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About  M&T  Publishing 
and  Dr  Dobb’s  Journal 


M&T  Publishing,  Inc.,  was  founded  in  1981  as  the  American  subsidiary  of  Markt  & 
Technik  A.G.,  the  leading  German  publisher  of  computer  magazines,  books,  and 
software.  In  addition  to  its  active  role  in  the  international  microcomputer  marketplace, 
M&T  publishes  three  monthly  magazines:  Dr.  Dobb’s  Journal,  DBMS,  and  LAN 
Technology.  M&T  also  publishes  an  extensive  line  of  microcomputer  books  and 
software  under  the  imprint  M&T  Books. 

Since  its  first  issue  in  1976,  Dr  Dobb’s  Journal  has  maintained  a  unique  voice  among 
microcomputer  publications.  The  first  issue  was  published  to  provide  a  short-term 
distribution  of  the  newly  written  Tiny  BASIC  language.  Reader  response  was  so 
strong  that  it  immediately  went  into  monthly  production.  DDJ  has  led  the  way  since 
then  by  focusing  on  important  advances  in  microcomputers,  printing  public-domain 
software,  and  fostering  vital  reader  interaction  on  technical  matters. 

Today,  Dr  Dobb’s  Journal  remains  the  primary  source  of  information  and  software 
tools  for  advanced  programmers.  Its  early  issues  are  still  in  demand,  and  no  part  of  the 
editorial  content  of  DDJ  has  ever  gone  out  of  print.  Volumes  One  through  Fifteen  of 
this  series  contain  the  entire  editorial  content  of  DDJ’ s  first  fifteen  years  and  are 
available  through  M&T  Books. 

Through  Dr  Dobb’s  Journal  and  its  other  software  publications,  M&T  Publishing  is 
providing  microcomputer  professionals  and  enthusiasts  with  the  most  advanced  and 
useful  software  information  available. 
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Editor’s  Preface 

The  banner  on  the  January  1990  cover  of  Dr.  Dobb’s  Journal  sums  up  what’s  perhaps  our 
proudest  accomplishment — 15  Years  of  Power  Programming!  That’s  something  no  other 
magazine  devoted  exclusively  to  software  development  can  come  close  to  saying. 

Over  the  past  decade-and-a-half.  Dr.  Dobb’s  seems  to  have  come  a  long  way  from  the  days 
of  “computer  calisthenics  &  orthodontia.”  In  many  ways  we  have,  yet  in  others  Dr.  Dobb’s 
remains  unchanged.  Certainly  our  content  has  changed  as  new  languages,  innovative  CPUs, 
and  up-to-date  environments  have  come  on  the  scene.  However,  our  approach  to  these  topics — 
and  the  spirit  in  which  we  do  so — is  the  same.  From  Dennis  Allison’s  Tiny  BASIC  in  1976  to 
DDJ’s  senior  technical  editor  Michael  Floyd’s  implementation  of  an  object-oriented  Prolog  or 
Bill  Ive’s  homegrown  one-pass  assembler  (both  in  these  pages),  Dr.  Dobb’s  Journal’s  mission 
has  been  to  share  the  best  in  programming  tools  and  techniques. 

In  addition  to  Michael’s  “Object  Prolog”  in  the  November  issue,  1990  showcased  many 
other  important  projects.  In  June,  for  instance,  we  presented  the  DDJ  Hyertext  Project,  a  fully- 
hypertexted  electronic  version  of  the  issue  to  complement  the  paper  page.  The  project, 
developed  by  Scott  Johnson  (and  described  in  the  June  issue),  included  linked  text,  graphics, 
and  source  code  all  in  electronic  form  on  CompuServe  and  disk. 

A1  William’s  two-part  “roll-your-own”  DOS  Extender  article  in  October  and  November  was 
also  in  the  DDJ  tradition.  Not  only  did  A1  share  an  valuable  programming  tool,  but  in  this  and 
other  DDJ  articles  he  unraveled  many  of  the  twisted  knots  of  protected-  mode  programming. 

DOS  wasn’t  the  only  operating  environment  DDJ  covered.  UNIX,  embedded  systems,  the 
Mac  and  other  platforms  were  an  integral  part  of  this  year’s  lineup,  along  with  topics  like 
neural  nets,  image  processing,  ray  tracing,  and  communications. 

But  hard  code  and  soft  tools  weren’t  our  only  offerings  in  1990.  DDJ  published  one  of  the 
most  year’s  most  controversial  software-related  articles  with  the  November  presentation  of 
“Software  Patents,”  a  position  paper  written  by  the  League  for  Programming  Freedom.  It  can 
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be  argued  that  software  patents  are  the  most  ruinous  or  beneficial  developments  in  the 
programming  arena — depending,  of  course,  on  which  side  of  the  patent  fence  you  sit. 

In  September,  contributing  editors  Andrew  Schulman  and  Ray  Duncan  launched  the 
“Programmer’s  Bookshelf,”  a  monthly  book  review  column.  And  1990  brought  into  the 
limelight  topics  like  windowing  environments  (particularly  Windows  3),  80386 
protected  mode,  and  object-oriented  programming,  all  of  which  were  extensively 
covered  in  Dr.  Dobb’s. 

All  in  all,  the  reference  volume  you  hold  in  your  hands  contains  all  of  this  and  more. 
A  simple  perusal  of  this  volume’s  Table  of  Contents  will  fire  your  interest.  You’ll  then 
find  yourself  coming  back  to  this  book  many  times  over  in  the  coming  years. 

Now  we  can  get  on  with  the  next  15  years. 


Jonathan  Erickson 
editor-in-chief 
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EDITORIAL 

Running  Light, 
And  Still  Without 
Overbyte 


Although  it  doesn’t  seem  that  long  ago,  it’s  15  years  ago  this  month  that  Patty  Hearst 
went  on  trial  for  terrorist-induced  bank  robbery,  Gerald  Ford  dodged  golf  balls  while  living 
at  the  White  House,  and  Terry  Bradshaw  lead  the  Steelers  to  a  Super  Bowl  victory  over  the 
Dallas  Cowboys.  (And  if  you  can  remember  when  Bradshaw  had  hair,  not  to  mention  when  the 
Cowboys  could  make  it  to  the  Super  Bowl  on  a  regular  basis,  you’re  showing  your  age,  just  like  the 
rest  of  us.) 

At  the  same  time,  the  plum  orchards  of  California’s  Santa  Clara  Valley  were  giving  way  to  Silicon 
Valley’s  R&D  labs  and  the  crew  at  an  outfit  called  the  “People’s  Computer  Company”  were  putting 
together  a  “reference  journal.”  Dennis  Allison  contributed  the  “D”  from  his  name,  Bob  Albrecht 
handed  over  “ob”  from  his  and  the  publication  was  christened  Dr.  Dobb’s  Journal  of  Computer 
Calisthenics  &  Orthodontia:  Running  Light  Without  Overbyte.  Admittedly,  the  first  DDJ  had  limited 
goals:  To  provide  a  minimal  Basic-like  programming  language  for  writing  simple  programs.  From 
the  outset,  the  undertaking  was  a  “participatory  design  project”  in  which  readers  were  asked  to 
share  information  and  articles  that  made  up  the  magazine.  After  the  initial  issue,  Jim  Warren  came 
aboard  as  editor  (for  the  princely  salary  of  $350/month),  and  stayed  around  to  guide  DDJfor  the 
next  couple  or  so  years. 

Since  those  early  days,  many  of  the  pioneers  of  the  computing  revolution  have  participated  in 
the  DDJ  experience,  leading  us  to  this  issue,  which  kicks  off  the  15th  year  of  publication  for  the 
Doctor.  Not  only  has  DDJ  survived,  but  it  has  grown,  become  established,  and  is  lauded  (most 
recently  by  CompuServe’s  Online  Today  magazine)  as  the  “granddaddy  of  all  programmers’ 
magazines.” 

As  I’ve  said  before,  there  aren’t  many  magazines,  computer-related  or  not,  that  manage  to  stick 
it  out  for  15  years.  Byte  is  still  there,  also  proudly  proclaiming  its  15th  year  of  publication,  and  I 
feel  particularly  lucky  to  have  been  associated  with  both  DDJ  and  Byte. 

This  past  week,  I  called  Dennis,  Bob,  and  Jim,  and  all  three  were  a  little  surprised  to  realize  that 
the  magazine  was  moving  into  its  15th  year.  It’s  not  that  they  didn’t  expect  DDJ  to  be  around  that 
long  but,  as  Jim  said,  “we  never  really  thought  about  any  future  for  DDJ.  Things  were  so  chaotic 
back  then  and  moving  so  fast  that  our  focus  was  on  the  here  and  now.”  Bob  added  that  “DDJ was 
supposed  to  be  a  four-issue,  forty  page  project,  and  then  self-destruct.  But  it’s  apparent  that  even 
back  then,  DDJ  filled  a  need  that  people  wanted.”  Dennis  concurs:  “DDJjusl  grew.  We  started  it 
as  a  newsletter  because  there  was  nothing  out  there  like  it.  And  there  still  isn’t.  It  stands  almost 
alone  among  technical  personal  computing  magazines.  We  xeroxed  some  flyers,  then  all  of  a 
sudden  we  had  400  or  500  subscribers  within  the  first  two  weeks.  It  looked  like  there  was  an 
audience.”  Both  Bob  and  Dennis  agree  that  much  of  DDJ s  early  success  rests  on  Jim’s  shoulders. 
“A  lot  of  the  flavor  of  DDJ  came  from  Jim,"  said  Dennis,  with  Bob  simply  adding  that  “Jim  did  a 
hell  of  a  job.” 

But  editors  move  on  to  other  things,  paradigms  come  into  and  go  out  of  vogue,  and  languages 
take  on  new  forms.  More  so  than  anything  else,  DDJs  one  constant  over  the  years  —  the  real  key 
to  its  success  —  has  been  the  desire  and  openness  of  DDJ  readers  to  share  programming 
information  and  techniques  with  each  other.  Even  before  I  joined  the  DDJ  staff,  Ray  Duncan 
underscored  this  when  he  said  that  DDJs  greatest  strength  was  its  core  of  faithful  readers.  But,  as 
Dennis  points  out,  that’s  nothing  new.  “From  the  very  start,”  he  says,  “DDJs  loyal  following  has 
made  it  special.” 

It  comes  as  no  surprise  that  Dennis,  Bob,  and  Jim  are  still  involved  with  computers  and 
programming  in  one  way  or  another.  Dennis  continues  his  lectures  on  computer  science  at  Stanford, 
and  consults  the  rest  of  the  time  (“You  have  a  computer  you  want  built,  I’ll  build  it.”).  Bob  writes 
books  on  and  teaches  about  programming  (he’s  still  a  believer  in  Basic),  and  Jim’s  just  completed 
a  four-year  stint  as  a  community  college  trustee  and  is  resharpening  his  programming  skills. 

The  only  thing  I’d  like  to  add  is  a  simple  thanks  to  Dennis,  Bob,  and  Jim,  and  all  you  readers 
who  have  stuck  with  DDJ  over  years. 


On  another  subject,  you’ll  notice  that  this  month’s  issue  inaugurates  the  “Programmer’s 
Workbench.”  This  new  monthly  section  focuses  on  developer’s  tools  and  how  they  interact  in  a 
complete  environment  for  developing  a  given  application.  The  types  of  tools  we’ll  cover  range  from 
prototyping  tools  and  code  generators  that  support  the  API  of  a  complex  GUI  to  add-in  libraries 
that  make  it  possible  for  you  not  to  continually  reinvent  the  wheel.  Rather  than  simply  present  a 
shopping  list  of  tools  and  a  discussion  of  how  they  interact,  the  Programmer’s  Workbench 
orchestrates  the  tools  on  the  workbench  to  develop  something  real.  And  in  the  process,  the 
strengths  and  weaknesses  of  each  tool  are  revealed.  Ultimately,  you’ll  walk  away  with  a  sense  that 
you  actually  used  those  tools,  and  you’ll  have  the  code  to  experiment  further. 

Contributing  editor  Andrew  Schulman  leads  off  with  a  two-part  article,  exploring  the  problem 
of  general  protection  faults.  If  you  have  ideas  for  similar  Workbench  topics  and  tools,  we’d  like  to 
hear  from  you  and  spread  your  tools  out  across  the  workbench  as  well. 


Jonathan  Erickson 
editor-in-chief 
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Stymied  by  C 

Dear  DDJ, 

I  thoroughly  enjoy  Jeff  Duntemann’s 
‘Structured  Programming”  column  in 
DDJ.  It’s  always  easy  to  enjoy  someone 
I  agree  with!  Besides  having  a  fond¬ 
ness  for  structured  programming  and 
Turbo  Pascal,  I  also  share  his  coolness 
towards  C.  Which  brings  me  to  the 
main  reason  for  this  letter.  I  have  a 
software  project  where  I  must  use  some 
C  routines  provided  for  me  in  .LIB  files. 
I  have  Microsoft  QuickC  out  of  neces¬ 
sity,  and  Turbo  Assembler/Turbo  Pas¬ 
cal  5.5  out  of  preference.  What  I  would 
like  to  do  is  somehow  hook  the  canned 
C  routines  from  Turbo  Pascal.  The  kind 
of  applications  I’ll  be  working  on  lend 
themselves  well  to  objects,  as  does  my 
way  of  thinking.  My  hope  is  that  there 
is  some  way  to  build  a  TP  unit  that  has 
TP  procedures/functions  that  actually 
are  calling  the  C  functions.  Once  this 
unit  is  established  I  could  happily  turn 
my  back  once  again  on  C.  What  I’d 
have  is  a  reusable  unit  with  the  C  hid¬ 
den  an  arm’s  length  away. 

Is  a  hook  like  this  possible?  Perhaps 
some  assembly  interface  calling  the  C 
and  in  turn  being  called  by  the  TP 
code?  I  don’t  have  access  to  the  C  li¬ 
brary  source  code  itself  but  maybe  I 
could  write  enough  C  code  to  call  the 
canned  functions  with  built-in  hooks? 
I’ve  done  more  in  TP  than  either  C  or 
assembly  but  have  dabbled  in  both.  I 
have  worked  with  externals  written  in 
assembly  and  called  from  Turbo  Pas¬ 
cal,  modifying  already  written  code, 
but  need  a  little  hand  holding  if  this  is 
the  route  to  go  with  this  problem.  I’d 
really  appreciate  any  help  Jeff  could 
offer. 

Dale  Lucas 

Cedar  Rapids,  Iowa 

Jeff  responds:  Without  being  able  to 
modify  and  recompile  your  C  libraries, 
you  ’re  stuck.  It ’s  a  matter  of  who  cleans 
up  whose  messes.  When  C  code  calls  a 


C  function,  the  caller  sets  up  the  stack 
frame,  calls  the  function,  and  then 
(when  the  function  returns  control  to 
the  caller)  the  caller  cleans  up  the  stack 
by  removing  parameters. 

Pascal,  on  the  other  hand,  requires 
that  the  function  (or  procedure)  clean 
up  the  stack  before  returning  control 
to  the  caller.  The  caller  assumes  that  it 
receives  a  clean  stack  after  each  call. 
The  two  systems  are  completely  incom¬ 
patible,  although,  some  C  compilers, 
including  Microsoft’s,  allow  you  to  spec¬ 
ify  Pascal  calling  conventions  as  an 
option.  If  you  could  recompile  your  C 
code,  you  could  invoke  this  option  and 
make  the  two  worlds  coexist  peaceably. 

C  does  what  it  does  to  allow  the  num¬ 
ber  of parameters  passed  to  a  function 
to  vary  from  one  call  to  the  next.  To 
each  his  own;  some  people  eat  fugu 
and  deserve  whatever  they  get.  I  take 
some  comfort  in  noting  that  operating 
system  API  calls  use  the  Pascal  calling 
conventions;  evidently  OS  architects 
draw  the  line  at  risking  the  system’s 
neck  for  this  kind  of  silliness. 

But  that  doesn ’t  solve  your  problem . 
If  you  only  have  .LIBs,  well,  shucks,  you 
have  two  choices: 

•  Become  a  sadomasochist,  embrace 
the  C  language,  and  work  twice  as 
hard  as  you  need  to  in  order  to  get 
your  work  done  for  the  rest  of  your 
career.  On  the  plus  side,  this  entitles 
you  to  wear  a  T-shirt  reading,  "Look 
what  a  big  tough  macho  hacker  I  am!’’ 

•  Give  your  gracious  benefactor  his  C 
code  back  and  recode  the  routines from 
the  interface  spec  in  Pascal.  Dimes  to 
donuts  you  ’ll  spend  less  time  recoding 
the  C  routines  in  Pascal  than  you  would 
recoding  your  app  in  C. 

Maybe  I’m  only  half-a-hacker ...  7 
like  to  take  a  little  time  now  and  then 
to  neck  with  my  wife,  build  radios,  and 
throw  the  rag  for  Mr.  Byte.  I  get  my  C 
in  orange  juice.  I’d  advise  you  to  do  the 
same. 

DDJ  Passes  the  Acid  Test 

Dear  DDJ, 

Many  times  during  the  last  year  I  was 
on  the  verge  of  deciding  to  let  my 
subscription  to  DDJ  lapse,  as  it  had 
apparently  turned  into  a  fanzine  for 
386  and  DOS  groupies.  One  more  arti¬ 
cle  on  cute  tricks  in  C,  how  to  write 
TSRs,  and  the  640K  barrier  would  have 
done  it. 

Then  Michael  Swaine’s  interview  with 
Hal  Hardenbergh  made  me  give  it  one 
more  month.  The  September  issue  made 
me  give  it  another  year,  and  I  have 
sent  in  my  renewal.  Five  out  of  six 
articles  were  of  interest  to  non-DOS, 
non-PC  programmers! 


For  1990,  please  make  at  least  half 
the  articles  in  any  issue  independent 
of  platform  and  language,  i.e.,  of  inter¬ 
est  and  value  to  programmers  on  any 
machine  using  any  language. 

If  you  wonder  where  I  am  coming 
from,  I  am  a  chemist;  I  write  about 
10,000  lines  of  code  a  year  for  my  re¬ 
search,  in  Pascal  (by  preference),  C  (by 
necessity),  and  (ugh!)  Fortran.  I  use  a 
VAX  station  and  a  networked  VAX  clus¬ 
ter  for  programming,  PCs  for  docu¬ 
ment  processing,  and  Macintoshes  for 
making  slides  and  figures.  I  am  cur¬ 
rently  using  neural  nets  and  simulated 
annealing.  I  am  sure  you  have  many 
readers  who,  like  me,  do  no  program¬ 
ming  on  PCs,  but  who  are  always  on 
the  lookout  for  new  programming  tech¬ 
niques  and  useful  algorithms. 

Ernest  W.  Robb 

Glen  Rock,  New  Jersey 

DDJ  responds:  You’ve  hit  on  what  DDJ 
is  really  all  about,  Ernest — sharing 
new  programming  techniques  and 
handy  algorithms —  and  we’d  like  to 
hear  from  anyone  who  has  some  to 
share. 

DFS  At  Work 

Dear  DDJ, 

I  read  Rabindra  Kar’s  article  “Data- 
Flow  Multitasking”  in  the  November 
1989  issue  of  Dr.  Dobb’s  Journal  and 
enjoyed  it  very  much.  The  title  of  the 
article  attracted  my  attention  first  be¬ 
cause,  as  part  of  my  job  for  the  past 
three  years,  I  designed  and  was  princi¬ 
pal  developer  of  a  data  analysis  system 
based  on  what  he  termed  data-flow 
multitasking  (I’ve  been  calling  it  data¬ 
flow  processing).  Currently  this  system 
consists  of  58  fittings  (programs  which 
tap  into  a  data  flow)  with  support  li¬ 
braries  consisting  of  264  functions.  Fit¬ 
tings  may  be  written  in  either  C  or 
Fortran,  and  the  system  runs  under  Unix 
and  VMS. 

This  system  (which  I  call  the  Data- 
Flow  System  or  DFS)  takes  a  slightly 
different  approach  to  establishing  the 
aggregate  task.  Instead  of  making  each 
processing  element  of  the  task  a  func¬ 
tion  in  an  application,  each  element  is 
itself  an  application  which  can  be  “con¬ 
nected”  to  any  other  element.  The  main 
reason  for  this  approach  was  to  make 
it  easier  for  the  user  to  construct  aggre¬ 
gate  tasks  without  the  need  to  deal 
with  a  programming  language.  This  ap¬ 
proach  also  allows  fittings  to  be  written 
in  the  programming  language  which 
best  implements  the  task. 

The  variety  of  fittings  in  this  system 
is  quite  broad.  There  are  fittings  for 
reading  and  writing  data,  analysis,  data- 
(continued  on  page  12) 
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(continued  from  page  8) 
flow  management,  and  data  visualiza¬ 
tion.  It  is  also  easy  for  a  user  to  develop 
a  new  fitting  to  match  any  special  needs. 
The  DFS  also  has  several  different  in¬ 
terfaces;  they  include  a  batch  type  in¬ 
terface,  an  interpreter,  and  a  fully  menu- 
driven  interface.  We  have  also  devel¬ 
oped  a  specialized  interface  which  a 
user  can  navigate  through  and  create 
an  SQL  query.  This  query  is  then  inte¬ 
grated  into  an  aggregate  task,  which 
extracts  the  data  from  one  or  more  data 
nodes  in  a  network  (a  distributed  data 
base)  and  then  presents  the  data  lo¬ 
cally  for  viewing. 

The  system  I’ve  described  is  in  use 
where  I  work  (The  Institute  of  Geo¬ 
physics  and  Planetary  Physics  at  UCLA) 
and  at  several  other  locations  which 
are  involved  with  space  physics  re¬ 
search.  I’d  be  happy  to  supply  more 
information  if  anyone’s  interested.  I  must 
compliment  Robin  on  the  clarity  of  his 
presentation  and  the  succinct  way  in 
which  he  described  the  concept.  It  was 
a  very  good  article. 

Todd  King 

Los  Angeles,  California 

C  Dynamic  Strings 

Dear  DDJ 

Just  finished  A1  Stevens’s  column  in  the 
October  issue,  with  special  interest  in 
his  item  on  dynamic  strings  in  C.  The 
ease  of  string  manipulation  in  Basic  is 
one  of  the  reasons  I  keep  using  it  and 
haven’t  switched  entirely  to  C  (besides 
the  fact  that  I  still  have  to  keep  the  old 
Z80  Radio  Shack  alive  for  my  wife). 

A  few  years  ago  I  picked  up  Alcor  C 
for  the  R/S.  Never  did  anything  big 
with  it  because  I  couldn’t  fit  much  into 
a  30K  workspace  anyway  ....  When  I 
saw  Al’s  item  on  strings  I  dug  up  the 
old  manual  because  I  remembered  that 
Alcor  had  dynamic  strings  in  those  old 
days  using  a  structure  defined  in  stdio, 
along  with  a  couple  of  conversion  func¬ 
tions  and  extensions  of  print/ and  scanf. 
Their  implementation  was  a  simple  struc¬ 
ture  with  a  length  byte  and  a  char  ar¬ 
ray,  but  it  worked. 

Alcor  C  is  still  around.  I  think  it’s  MIX 
C  now;  at  least  the  company  is  in  the 
same  town  and  still  lowballs  every¬ 
body  on  price.  It  was  available  back 
then  for  Apple  II,  CP/M,  and  Radio 
Shack  machines.  I  got  it  originally  as  a 
learning  tool,  which  it  served  well  as. 
It  was  not  industrial  strength;  any  word 
on  the  condition  if  MIX  these  days?  At 
the  price  ($19  95  last  I  saw)  it  must  be 
worth  something. 

Al,  keep  up  the  good  writing.  By  the 
way,  this  comes  via  US  Mule  because  I 
couldn’t  find  a  CompuServe  address 
for  you  or  DDJ.  I  did  find  the  DDJ 


Forum,  but  no  listing  for  Al  to  send  a 
message. 

Michael  Brady 

Fresno,  California 

Thanks,  Michael.  Al’s  CIS  address  is 
71 101, 1262;  DDJ’s  is  76704,50. 

And  NewWave  Begat. . . . 

Dear  DDJ, 

In  regard  to  Michael  Swaine’s  column 
titled  “Unbundled  Integration,”  in  the 
August  1989  issue  of  Dr.  Dobb’s  Jour¬ 
nal,  I  would  like  to  make  the  following 
observations.  The  “most  interesting”  fea¬ 
ture  of  the  Apple  System  Version  7.0 
release,  the  Inter  Application  Commu¬ 
nications  architecture  (IAC)  is  indeed 
an  interesting  development.  Over  a  year 
ago,  Hewlett-Packard  demonstrated  this 
capability  as  a  feature  of  its  NewWave 
environment.  (I  guess  imitation  really 
is  the  sincerest  form  of  flattery,  espe¬ 
cially  when  the  imitator  has  pending 
legal  action  against  the  imitatee  for  imi¬ 
tating  the  imitator!)  NewWave  is  part 
of  the  user  interface  proposed  by  the 
Open  Software  Foundation  as  Motif. 

HP’s  term  for  dynamic  cut-and-paste 
is  “shared  links.”  With  NewWave,  a 
user  “shares"  and  “establishes  a  view 
to”  data,  while  an  IAC  user  “publishes” 
and  “subscribes  to”  data.  It  probably 
makes  little  difference  to  a  user  which 
set  of  new  terms  must  be  learned  to  use 
this  feature,  but  I  think  I’d  prefer  al¬ 
most  any  set  of  terms  that  doesn’t  re¬ 
mind  me  of  the  recent  spate  of  renewal 
notices  I  seem  to  keep  getting  from 
computer  industry  publications,  in  di¬ 
rect  proportion  to  the  number  of  years 
for  which  I’ve  renewed  my  subscrip¬ 
tions  to  them!  The  important  thing  to 
remember  is  that  it  looks  like  the  folks 
responsible  for  these  windowing  envi¬ 
ronments  are  making  good  on  yet  an¬ 
other  implied  promise  —  software  that 
remains  integrated  even  after  one  pro¬ 
gram  changes.  More  power  to  them  all 
and  the  Flames  of  Swaine! 

Lawrence  T.  Prevatte,  III 

Cape  Canaveral,  Florida 

Finite  State’s  Rights 

Dear  DDJ, 

Donald  Smith’s  article  (October  1989), 
“Finite  State  Machines  for  XModem,” 
was  a  timely  help.  I  recently  proposed 
an  FSM  design  to  a  client  who  had  not 
heard  of  FSM.  Donald’s  article  added 
credibility  to  my  proposal. 

I  have  used  FSMs  to  manage  com¬ 
munication  protocols,  to  manage  user 
interfaces,  and  to  implement  control 
logic.  Using  FSMs  often,  I  implemented 
a  translator  and  C  library  called  “The 
State  Machine,”  which  is  just  what 
Donald  suggested  as  a  coding  tech¬ 


nique.  Interestingly,  the  code  that  this 
translator  generates  looks  remarkably 
similar  to  Donald’s  hand-coded  state 
machine.  I  have  developed  an  exam¬ 
ple,  “MENUS,”  which  uses  an  FSM  to 
control  the  navigation  about  a  menu- 
driven  user  interface.  The  state  dia¬ 
gram  that  was  the  original  design  docu¬ 
ment  for  this  example  was  directly  en¬ 
coded  into  a  language  called  “State 
Transition  Description  Language” 
(STDL).  The  state  machine  has  a  num¬ 
ber  of  unique  features:  It  aids  memory 
reduction  and  improved  productivity 
by  supporting  encapsulation  with  both 
macros  and  callable  substates.  The  ca¬ 
pability  to  call  substates  is  very  useful 
when  implementing  user  interfaces  with 
submenus.  Debugging  is  simplified  by 
a  trace  option  which  can  generate  a  log 
of  all  state  transitions  that  occur  during 
execution.  This  option  can  be  turned 
off  to  minimize  memory  requirements. 
Actions  are  C  functions  which  can  have 
any  number  of  arguments.  An  event 
or  stimulus  is  defined  by  a  Boolean  C 
function.  The  state  machine  comes  with 
several  predefined  action  and  event  func¬ 
tions. 

There  are  many  parallels  between 
the  implementation  philosophy  of  the 
state  machine  and  the  mini-interpreters 
described  by  Abrash  and  Illowsky  in 
their  article  (September  1989),  “Roll 
Your  Own  Minilanguages  with  Mini- 
Interpreters.” 

For  those  with  a  champagne  budget, 
there  is  a  sophisticated  CASE  tool  avail¬ 
able  from  i-Logix  called  “Statemate.”  It 
has  several  powerful  features:  Statemate 
is  a  graphic  tool.  State  diagrams  are 
drawn  interactively.  The  tool  integrates 
a  data  base  and  an  interpreter  that  sup¬ 
ports  complex  events  and  actions.  Docu¬ 
mentation  can  be  generated  automati¬ 
cally  from  the  data  base.  State  diagrams 
can  be  executed  using  Statemate’s  simu¬ 
lator  or  they  can  be  executed  from  C 
or  Ada  code  generated  by  Statemate’s 
prototyper.  FSMs  defined  by  Statemate 
can  be  decomposed.  This  capability  is 
based  upon  a  rigorous  mathematical 
theory  developed  by  David  Harel.  It  is 
important  for  complex  systems  which 
would  otherwise  explode  into  hundreds 
of  states. 

Rob  Buck 

Aerosoft 

Fairfield,  Iowa 

Graphics  For  the  Rest  of  Us 

Dear  DDJ, 

I  found  the  interview  with  David  Parker 
in  Michael  Swaine’s  column  entitled 
“Parker’s  Perceptions”  in  the  October, 
1989  DDJ  especially  interesting  since 
I’m  a  very  satisfied  user  of  his  “Ac- 
(continued  on  page  14) 
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(continued  from  page  12) 

roSpin”  graphics  software.  I’d  known 

nothing  about  the  person  behind  it! 

Swaine  says  “it  [Acrobits]  seems  to 
have  a  good  product,”  and  I  can  testify 
that  it  does  indeed.  My  colleagues  and 
I  need  to  do  3-D  graphics  in  a  variety 
of  languages,  on  a  number  of  different 
IBM  PC  compatible  machines.  We  also 
cannot  afford  fancy  hardware;  my  own 
machine  doesn’t  even  have  a  hard  drive. 

AcroSpin  is  the  only  product  I’ve 
seen  that  does  the  things  I  need  on  the 
hardware  I’ve  got.  On  all  our  PCs  at 
this  institution,  I’ve  yet  to  encounter 
one  that  has  some  kind  of  graphics  and 
cannot  run  AcroSpin.  It’s  clean,  simple, 
and  does  exactly  what  the  manual  says 
it’ll  do. 

Matthew  D.  Healy 
Zoology  graduate  student 
Duke  University,  North  Carolina 

Down  Those  Hallowed  Halls 

Dear  DDf 

Funny  how  time  alters  everything.  When 
Jeff  Duntemann  opened  his  September 
1989  “Structured  Programming”  column 
with  a  mention  of  his  high  school  days, 
I  had  to  pull  out  my  copy  of  the  Lane 
Arrowhead  70  and  look  him  up.  If  he 
still  has  his  copy,  he  can  find  me  on 
pages  27  and  126.  He  must  have  picked 
up  on  computers  in  college. 

OOPs,  it  still  leaves  me  in  the  dark. 
I  guess  for  my  PUNishment,  I  will  have 
to  rewrite  Fortran  into  Basic.  I  enjoyed 
his  column.  Take  care. 

Thomas  Kocourek 
Carrollton,  Georgia 

Magnitude,  Made  to  Order 

Dear  DDJ , 

In  Michael  Swaine’s  November  edito¬ 
rial  on  innumeracy,  his  accusation  of 
an  error  in  John  A.  Paulos’s  book,  In¬ 
numeracy,  is  based  on  a  misunderstand¬ 
ing  of  the  term  “order  of  magnitude.” 
He  starts  off  okay,  by  stating  his  deduc¬ 
tion  that  Paulos  uses  the  expression 
“order  of  magnitude”  to  mean  “a  power 
of  ten.”  He  goofs  when  he  asserts  that 
magnitude  (plural)  means  “powers  of 
one  hundred.”  This  is  wrong.  Any  sci¬ 
entist  will  tell  you  that  scientists  use  the 
term  “orders  of  magnitude”  to  mean 
“powers  of  ten,”  for  example: 

If  quantity  A  is  ten  times  greater  than 
quantity  B,  then  A  is  said  to  be  one 
order  of  magnitude  greater  than  B.  If 
A  is  one  hundred  times  greater  than  B, 
then  A  is  said  to  be  two  orders  of 
magnitude  greater  than  B. 

Getting  back  to  the  example  of  the 
malaria  safety  index  that  Swaine  cited, 
for  the  malaria  index  to  be  “orders”  of 
magnitude  lower  in  most  of  the  world 
than  in  the  United  States  merely  means 


that  the  actual  risk  of  malaria  (defined 
as  the  total  population  count  divided 
by  the  number  of  people  in  that  popu¬ 
lation  who  catch  malaria)  is  at  least  one 
hundred  times  higher  (i.e.  at  least  two 
orders  of  magnitude  higher)  than  in 
the  United  States.  (Remember  that  on 
Paulos’s  scale,  the  lower  the  index  num¬ 
ber,  the  greater  the  risk.)  By  using  the 
correct  definition  of  “orders  of  magni¬ 
tude”  we  see  that  Paulos’s  assertion  is 
indeed  within  the  realm  of  plausibility. 

Swaine’s  misunderstanding  of  the 
term  “order  of  magnitude”  is  under¬ 
standable,  because  written  definitions 
of  this  term  in  dictionaries  (even  scien¬ 
tific  ones)  are  hard  to  come  by.  The  use 
of  orders  of  magnitude  in  calculations 
has  been  spread  by  word-of-mouth 
among  scientists  and  has  not  been  ex¬ 
posed  to  the  general  public  (except 
by  Carl  Sagan  in  his  Cosmos  series). 
Despite  the  mistake,  I  thank  Mr.  Swaine 
for  addressing  the  issue  of  innumeracy 
in  his  editorials. 

Gregory  B.  Goslen 

Research  Triangle  Park,  N.  Carolina 

Zortech  Heard  From . . . 

Dear  DDJ, 

We  read  with  interest  Al  Stevens’s  col¬ 
umn  on  C++  in  the  October  issue  of 
DDJ.  Imagine  our  surprise,  when  on 
pg.  128  we  read  the  statement:  “  .  .  .  not 
until  Borland  and  Microsoft  introduce 
C++  compilers,  complete  with  integrated 
development  environments  and  hot- 
shot  debuggers,  can  PC  developers  get 
serious  about  it.” 

Are  you  actually  saying  that  only  a 
couple  of  vendors  are  allowed  to  pro¬ 
duce  a  C++  system  for  MS-DOS?  That 
sort  of  statement  belongs  in  company 
marketing  literature,  not  in  a  well-re¬ 
spected  publication  like  DDJ,  where 
developers  look  for  impartial  editorial 
content. 

Zortech  has  over  50,000  users  now, 
including  virtually  every  major  corpo¬ 
ration.  Many  are  switching  to  the 
Zortech  C++  compiler  as  their  preferred 
development  tool.  How  much  more 
serious  can  developers  get  than  to 
switch  from  C  to  C++  for  their  next 
generation  products?  This  is  happen¬ 
ing  now,  and  we  would  be  delighted 
to  provide  Al  with  a  list  of  major  corpo¬ 
rations  who  are  developing  with  Zortech 
C++. 

Incidently,  the  “integrated  environ¬ 
ment  and  hot-shot  debugger”  requested 
by  Al  is  now  available  with  the  release 
of  Zortech  C++  V2.0  Developer’s  Edi¬ 
tion.  It  is  a  full-blown  development 
system  including  the  world’s  first  MS- 
DOS  C++  Source-Level  Debugger,  AT&T 
C++  V2.0  compatibility,  and  many  other 
enhancements.  Our  entire  company  is 


focused  on  C++.  It  isn’t  a  sideline  for 
us  and  doesn’t  play  second  fiddle  to 
other  languages,  wordprocessors,  spread¬ 
sheets,  or  database  packages. 

Walter  Bright 
Director  of  Technologies 
Zortech  Inc. 

The  Foot  Bone’s  Connected  to  the 
Head  Bone 

Dear  DDJ, 

The  correct  answer  to  the  question 
posed  to  Michael  Swaine  in  New  Or¬ 
leans  (December  1989  DDJ),  “Where 
you  got  your  shoes?”  is  “You  got  your 
shoes  on  your  feet!” 

I  had  to  tell  you  .  .  . 

Harold  O.  Koenig 
Scottsville,  Virginia 

Disrobing  the  Emporer 

Dear  DDJ, 

Thank  you  for  publishing  Mr.  Guth- 
ery’s  informative  article,  “Are  the  Em- 
porer’s  New  Clothes  Object-Oriented?” 
in  the  December  1989  issue.  Amidst  all 
of  the  hype,  it’s  good  to  see  some  rea¬ 
son  appear.  Now,  I  can  say:  “OOPS! 
Did  they  really  do  that?”  Rather  than 
being  an  advance,  object-oriented  pro¬ 
gramming  seems  to  be  regressive. 

Regressive?  Yes,  it’s  a  return  to  “spa¬ 
ghetti  code”  and  violates  the  basic  ten¬ 
ets  of  writing  well-structured  programs. 
It  was  this  type  of  violation  by  the 
excessive  use  of  GOTOs  that  led  to 
Dykstra’s  letter  to  the  ACM  in  1969  and 
the  ensuing  interest  in  structured  pro¬ 
gramming. 

In  well-structured  programs,  the  struc¬ 
ture  is  a  tree  whose  nodes  are  the  pro¬ 
gram  modules.  Each  node  in  a  tree  may 
have  one  and  only  one  father,  but,  of 
course,  may  have  has  many  children 
as  necessary  to  do  the  job.  As  defined 
in  the  literature,  an  object  is  a  module 
that  may  receive  a  message  (be  called) 
from  any  number  of  sources  and  may 
send  messages  to  (call)  other  objects. 
Thus,  an  object  is  a  structural  node  that 
may  have  more  than  one  father  —  a 
rather  unnatural  situation!  Can  you  imag¬ 
ine  the  difficulties  when  trying  to  de¬ 
bug  a  module  entered  from  who-knows- 
where? 

Instead  of  coming  up  with  new  buzz 
words  like  OOP,  the  language  of  de¬ 
velopers  should  heed  our  desires  for 
more  granularity  in  the  libraries  associ¬ 
ated  with  various  compilers.  This  was 
pointed  out  admirably  by  Bruce  W. 
Tonkin  in  his  “Examining  Room”  col¬ 
umn  on  PDQ  in  the  same  issue. 

If  you  keep  coming  up  with  articles 
like  the  two  I’ve  mentioned,  I’m  afraid 
I’ll  have  to  subscribe  to  DDJ.  Thanks. 
Dan  W.  Crockett 
Queen  Valley,  Arizona 
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Real-Time 

Animation 


Presenting  a  sprite  driver  for  EGA 


Rahner  James 


“ The  distinction  between  a  toy  and  a  game  is  that  the  game 
has  a  goal;  therefore,  life  is  not  a  game ,  it  is  a  toy.  ”  —  GOK 

As  a  child,  1  could  not  differentiate  between  Bugs 
Bunny  and  Walter  Cronkite.  This  is  not  to  say  that 
the  man  America  most  trusted  had  dental  problems, 
but  that  the  child  did  not  have  the  experience  to  see 
the  cartoon  for  what  it  was  —  a  stream  of  individu¬ 
ally  drawn  pictures.  Skilled  professional  help  was  required 
to  deal  with  the  trauma  caused  by  the  revealed  truth.  Even 
after  the  psychological  defects  were  converted  to  scars,  I 
had  to  wait  until  I  could  create  two-dimensional  life  for 
myself. 

The  Time  Has  Come 

Animation  is  achieved  by  showing  a  series  of  incrementally 
changing  images.  Depending  on  the  duration  of  time  that  a 
single  image  is  shown  and  the  time  it  takes  to  switch  to  the 
next  image  increment,  the  viewer’s  visual  persistence  smooths 
out  the  image’s  transition.  Anyone  with  a  compiler  and  a 
graphics  library  can  put  a  series  of  images  on  a  computer 
display.  But  in  order  to  create  smooth,  non-flickering,  real¬ 
time  animation,  a  fair  amount  of  thought  is  necessary. 

To  support  reasonable  animation,  the  algorithm  must 
conform  to  the  following  rules: 

Coordinate  Movement  —  The  routines  must  allow  indi¬ 
vidual  objects  to  be  moved  around  on  the  screen  and  placed 
on  any  pixel  boundary. 

Independent  Motion  —  Each  object  in  the  image  should 


Rahner  is  an  independent  consultant  living  near  Sacra¬ 
mento,  Calif.  He  can  be  reached  by  phone  at  916-722-1939 
or  through  CompuServe  at  71450,  757. 


be  able  to  show  a  chain  of  sequences  independent  of  its 
coordinate  movement. 

Smooth  Transitions  —  The  transition  between  image  frames 
should  have  no  intermediate  stages.  This  means  that  the 
viewer  should  see  only  complete  images,  not  images  that 
are  half  the  first  image  and  half  the  second  image.  These 
half-and-half  images  are  perceived  as  a  flicker  and  are 
distracting. 

Regular  Transitions  —  All  image  transitions  should  occur 
at  regular  intervals.  If  this  does  not  happen,  the  sequence 
will  appear  to  jerk  as  if  shown  on  an  old  projector. 

Sprites  —  If  an  object  has  a  hole,  any  objects  that  are 
behind  it  should  show  through.  Poorly  done  animation  will 
not  allow  the  viewer  to  see  through  a  gap  in  an  object. 
Realistic  Objects  —  There  is  a  difference  between  what  is 
shown  on  the  screen  and  what  is  perceived  by  the  observer. 
Up  to  a  point,  jagged  lines  will  be  smoothed,  imperfect 
colors  accepted,  and  stairstep  corners  rounded.  This  point, 
the  point  of  realism,  is  subjective  and  entirely  dependent 
on  the  target  audience.  Below  this  point,  other  unrelated 
flaws  can  be  magnified;  above  this  point,  the  overall  percep¬ 
tion  of  the  product  is  enhanced. 

The  elements  of  this  list  are  all  mutable  by  targeted 
hardware  limitations.  Accurate  shading  may  be  difficult  on 
an  AT-class  machine.  Absolute  realism  for  anything  but  the 
simplest  geometric  shapes  is  impossible  on  CGA  or  EGA. 
The  finished  product’s  design  constraints  may  adjust  the 
significance  of  one  element  over  the  others.  These  are 
Rahner  rules  —  they  may  be  burnt,  bent,  or  beatified. 

Zippy  Tries  His  Hand  at  CGA  Animation 

When  I  first  saw  reasonable  animated  images  on  a  CGA 
adapter,  I  was  intrigued.  It  was  a  simple  CGA  sprite  demo  — 


16 


Dr.  Dobb’s Journal,  January  1990 

21 


several  helicopters  flying  aimlessly  around  the  display.  Be¬ 
cause  the  demo  allowed  the  helicopters  to  start  only  on  a 
byte  boundary  (four  pixels  per  byte)  and  did  not  allow  them 
to  exit  smoothly  from  the  side  of  the  screen,  I  decided  to  try 
my  hand  at  writing  the  ultimate  animation  driver  for  CGA. 

After  a  lazy  Sunday’s  work,  the  driver  was  finished.  Given 
CGA’s  limitations  (four  colors  and  320  X  200  resolution), 
ultimate  is  probably  too  strong  a  word.  It  was  about  the 
same  as  tying  the  ultimate  shoelace  or  throwing  the  ultimate 
dirt  clod.  Anticlimactic  would  be  the  correct  word  for  polite 
company. 

Because  the  initial  attempt  was  an  unplanned,  seat-of-the- 
pants,  I’ve-got-Fritos-diet-Coke-and-plenty-of-time  effort,  my 
trial  and  error  path  would  best  illustrate  some  animation 
rudiments. 

The  first  attempt  was  to  whip  a  series  of  changing  pictures 
past  the  monitor.  This  involved  copying  virtual  screens, 
which  I  had  prearranged,  onto  the  CGA  video  RAM.  This 
had  the  interesting  effect  of  flickering  the  screen  with  seem¬ 
ingly  random  images  caught  in  a  blizzard. 

The  flicker  and  snowstorm  were  due  to  not  waiting  for 
the  vertical  retrace  before  displaying  the  next  image.  What 
is  vertical  retrace?  A  good  question,  because  it  is  important 
later.  The  CRT  monitor  etches  its  pictures  in  the  orbitals  of 
fluorescent  compounds  with  a  single  beam  of  electrons. 
This  beam  sweeps  horizontally  back  and  forth  across  the 
screen.  In  either  direction  —  back  or  forth  —  the  beam  has 
to  turn  off,  otherwise  it  looks  funny.  The  off  direction  is 
called  the  horizontal  retrace.  The  beam  winds  its  way  down 
the  screen  in  this  back  and  forth  manner.  When  it  reaches 


the  bottom,  it  turns  off  and  returns  to  the  top  of  the  screen: 
This  off  time  is  called  the  “vertical  retrace.”  On  the  standard 
EGA  setup,  this  vertical  retrace  occurs  60  times  a  second. 

The  standard  CGA  adapter  has  a  bit  that  indicates  when 
the  horizontal  refresh  is  occurring  and  another  to  show 
when  the  vertical  refresh  is  occurring.  It  was  a  simple  task 
to  change  the  program  so  that  it  waited  for  the  vertical 
retrace  before  blasting  out  the  next  virtual  screen.  —  I  saw 
a  series  of  pictures  endlessly  circling,  but  without  snow  or 
flicker. 

Next  I  noticed  that  most  of  the  screen  was  stationary  and 
only  a  small  fraction  of  the  image  moved  at  any  one  time. 
In  fact,  most  of  the  things  that  did  move  were  sets  of  pixels 
that  did  not  reposition  themselves  with  respect  to  one 
another,  only  with  respect  to  the  rest  of  the  picture.  After 
much  deliberation  (and  lunch),  I  named  these  sets  “sprites.” 
Later  I  found  that  these  sets  had  been  noticed  by  others 
before  and  they  had  used  my  name  for  them.  Rather  than 
risking  a  protracted  legal  battle,  I  swallowed  my  pride  and 
have  allowed  the  others  to  take  the  credit. 

The  basic  concept  behind  the  sprite  is  simple.  Cut  a 
rectangular  section  out  of  the  screen  and  store  it.  Then  take 
the  set  of  pixels  that  comprise  the  sprite  and  replace  the 
cutout  section  with  them. 

Armed  with  my  “new”  creation,  I  reduced  the  series  of 
virtual  screens  to  a  simple  background  and  a  few  sprites. 
The  background  was  displayed  first,  then  the  sprites  were 
moved  into  position  before  the  finish  of  the  vertical  retrace. 
Now  I  had  the  same  cinematograph  that  I  had  before,  but 
the  program  was  more  efficient  and  the  storage  require- 
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ments  were  reduced.  Before  I  got  bored  with  this  endless 
video  cycle,  I  noticed  that  when  my  sprites  went  in  front  of 
something,  the  background  was  completely  covered,  even 
in  places  that  I  should  have  been  able  to  see  through. 

This  meant  another  change.  Instead  of  just  storing  the 
background,  I  masked  off  the  solid  areas  of  the  sprite  body. 
Instead  of  replacing  the  cutout,  I  ORed  the  sprite  onto  the 
masked  background,  then  replaced  the  cutout  around  the 
finished  product.  This  allowed  me  to  have  “holes”  in  the 
sprites,  for  increased  realism. 

Absolute  realism  for  anything 
but  the  simplest  geometric  shapes 
is  impossible  on  CGA  or  EGA. 

The  finished  product's  design  constraints 
may  adjust  the  significance  of  one 
element  over  the  others.  These  are 
Rahner  rules -they  may  be  burnt, 
bent,  or  beatified 


With  the  inclusion  of  holes  in  the  sprites,  I  had  my 
ultimate  CGA  sprite  routine.  All  the  little  fishes  were  swim¬ 
ming  around  in  my  video  aquarium  without  the  need  for 
food.  I  was  satisfied  and  went  to  bed. 

You  may  be  asking,  “What  does  this  have  to  do  with 
EGA?”  You  may  be  getting  sleepy  and  ready  to  close  the 
magazine.  You  may  just  be  hunting  for  good  prices  on 
software.  Well,  to  the  shopping  sportsman,  there  are  no 
good  prices  in  this  article;  to  the  somnolent  peruser,  good 
night;  and  to  the  inquisitor  in  the  back  with  his  hand  up, 
Everything! 

The  EGA  and  I 

In  its  640  X  350-pixel  color  graphics  mode,  an  EGA  adapter 
with  256K  of  RAM  is  set  up  as  four  planes  of  28,000  bytes 
each.  It  also  has  two  pages,  one  that  is  being  viewed  on  the 
monitor  and  one  that  is  in  the  ether.  Both  pages  can  be 
addressed  directly  by  the  CPU.  The  first  page  starts  at 
memory  address  AOOO.OOOOh  and  the  second  page  starts  at 
A000:8000b.  Each  byte  of  EGA  memory  represents  eight 
pixels  with  the  most  significant  bit  (MSB)  being  shown  as 
the  leftmost  pixel.  A  byte  or  bit  of  any  combination  of  the 
planes  may  be  addressed  depending  on  how  the  EGA 
registers  have  been  set. 

Superficially,  there  seemed  to  be  little  difference  between 
a  sprite  driver  for  the  CGA  and  EGA  adapters.  It  seemed  to 
be  just  another  block  of  RAM  that  I  needed  to  jam  out  bytes. 
Following  that  line  of  thought,  the  first  code  translation  from 
CGA  was  conceptually  simple.  The  sprites  were  placed  on 
the  visual  page,  a  plane  at  a  time.  When  I  looked  at  the 
result  for  the  first  time,  I  found  myself  almost  back  to  square 
one.  No  matter  how  efficiently  I  wrote  the  driver,  there  was 
a  constant  flicker.  I  ran  to  the  bookstore,  hoping  for  a  tome 
of  enlightenment.  My  hope  was  dashed  by  a  limited  selec¬ 
tion.  But  a  quick  reread  of  the  IBM  EGA  Technical  Reference 
manual  provided  me  with  the  answers:  The  EGA  adapter  can 
generate  an  interrupt  and  the  visual  page  can  be  switched 
during  the  vertical  retrace. 
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Writing  a  Bit  Map  to  EGA  Memory 

The  EGA  adapter  has  a  fair  number  of  features.  All  the 
features  and  the  way  the  board  reacts  to  CPU  memory 
manipulations  are  determined  by  the  configuration  regis¬ 
ters.  Most  of  the  registers  are  set  up  in  pairs.  The  first  register 
accepts  an  index  value  that  determines  the  functionality  of 
the  second  register.  The  major  register  pairs  that  we  need 
to  concern  ourselves  with  are  the  Sequencer  registers  and 
the  Graphics  1  &  2  Address  registers.  Another  register  that 
is  important  for  this  discussion  is  Input  Status  Register  One. 

The  Sequencer  register  is  located  at  3C4h  with  its  index 
register  at  3C5h.  It  has  five  indexed  registers:  Reset  (0), 
Clocking  Mode  (1),  Map  Mask  (2),  Character  Map  Select  (3), 
and  Memory  Mode  (4).  To  access  an  indexed  register,  the 
index’s  number  is  output  to  the  Sequencer  register  followed 
by  the  value  for  that  index  output  to  the  index  port.  For 
example,  if  you  want  to  place  a  5  in  the  Clocking  Mode 
index  register,  which  is  index  number  1,  the  assembly  code 
in  Example  1  would  do.  Because  all  the  register  pairs  are 
one  right  after  the  other,  this  code  segment  could  be  re¬ 
placed  by  that  in  Example  2.  This  replacement  is  usually 
valid,  except  when  slow  ports  cause  timing  difficulties. 

The  important  Sequencer  index  register,  with  respect  to 
our  driver,  is  the  Map  Mask  Register  (index  2).  This  register 
enables  planes  so  that  the  CPU  can  write  to  them.  Setting  bit 
0  enables  plane  0,  bit  1  enables  plane  1,  and  so  on.  Because 
there  are  only  four  planes,  the  four  MSBs  are  not  used  and 
are  ignored.  If  you  wanted  to  write  the  same  information  to 
multiple  planes,  multiple  bits  could  be  set.  No  easy  assump¬ 
tions  can  be  made  about  the  sprite  data,  so  we  can’t  really 
take  advantage  of  this  feature. 

The  Graphics  1  &  2  register  set  deals  with  colors,  pixel 
masks,  and  the  Boolean  graphic  operations  the  EGA  can 
perform.  This  register  is  configured  the  same  as  the  Se¬ 
quencer  register,  with  nine  indexed  registers:  Set/Reset  (0), 
Enable  Set/Reset  (1),  Color  Compare  (2),  Data  Rotate  (3), 
Read  Map  Select  (4),  Mode  Register  (5),  Miscellaneous  (6), 
Color  Don’t  Care  (7),  and  Bit  Mask  (8).  The  index  registers 
of  concern  are  the  Data  Rotate  register  and  the  Read  Map 
Select  register. 

The  Data  Rotate  register  has  two  controls.  Bits  0-2  repre¬ 
sent  the  Rotate  Count.  The  Rotate  Count  is  a  binary  encoded 
number  that  represents  the  bit  positions  to  shift  any  data 
written  to  a  video  plane.  Because  all  our  data  will  be 
unshifted  at  the  hardware  level,  this  value  should  be  0.  Bits 
3-4  represent  the  Function  Select.  The  Function  Select 
indicates  which  Boolean-type  operation  is  desired  for  pixels 


MOV 

MOV 

OUT 

INC 

MOV 

OUT 

DX,  3C4h 

AL,  1 

DX,  AL 

DX 

AL,  5 

DX,  AL 

;  DX  ->  Sequencer  register 
;  AL  =  index  1,  Clocking  Mode 

;  DX  ->  Sequencer  index  port 
;  AL  =  to  put  in  Clocking  Mode 

Example  1:  Sample  code  for  writing  bit  map  to  EGA 
memory 

MOV 

DX,  3C4h 

;  DX  ->  Sequencer  reg.  pair 

MOV 

AX,  501h 

;  AL  =  index  1,  AH  =  value  5 

OUT 

DX,  AX 

;  Puts  AL  out  3C4h,  then 
;  AH  out  3C5h 

Example  2:  Replacing  the  code  in  Example  1 
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written  to  display  memory.  Table  1  shows  the  available 
functions. 

To  diverge  for  a  moment,  a  definition  for  “latched  data” 
is  in  order.  No  matter  how  it  appears,  the  video  memory  on 
the  EGA  adapter  is  never  directly  connected  to  the  PC  bus. 
When  the  registers  are  set  properly,  the  program  addresses 
the  video  memory  in  exactly  the  same  manner  it  would  any 
other  portion  of  main  memory.  The  memory  can  be  ac¬ 
cessed  as  a  byte  or  a  word,  but  those  accesses  are  processed 
through  the  EGA’s  circuitry.  The  circuitry  performs  some 
gyrations  on  the  data,  then  passes  it  on.  In  order  to  properly 
swing  the  binary  song,  that  gyrating  EGA  circuitry  latches 
the  byte  or  word  in  its  internal  read/ write  buffer.  A  read  of 
EGA  memory  will  put  that  byte  of  pixels  in  the  latch,  which 
can  then  be  operated  on  by  some  future  operation.  Because 
each  plane  has  a  separate  latch  buffer,  if  all  four  planes  have 
been  enabled,  32  bits  at  a  time  can  be  latched  (read), 
operated  on,  and  then  rewritten  to  EGA  memory  with  a 
single  8086  instruction. 

Give  me  an  inch  and  I’ll  take  a  while,  diverging  on  to  the 
8086  instructions.  When  dealing  with  this  aspect  of  the  EGA 
adapter,  a  close  look  at  how  some  8086  instructions  actually 
work  would  be  in  order.  Let’s  start  with  the  instruction: 

OR  [DI],  AL 

When  the  8086  sees  this  instruction,  it  loads  the  value 
pointed  at  by  the  register  DI  into  the  8086  internal  register, 
ORs  the  value  in  register  AL  onto  that  internal  register,  then 
writes  the  result  back  out  to  the  location  pointed  to  by  DI. 
If  DI  happened  to  point  to  EGA  memory,  this  would  latch 
up  a  number  of  pixels,  add  in  pixels,  then  write  the  latch 
data  back  out  to  video  memory  — all  in  a  single  instruction. 
If  an  additional  EGA  function,  such  as  a  bit  rotate,  were 
added  to  the  previous  example,  some  interesting  and  possi¬ 
bly  useful  results  could  be  achieved.  I  don’t  use  this  in  my 
routine,  but,  by  jingo,  it’s  just  too  nifty  to  be  ignored! 

The  last  register  of  importance  is  Input  Status  Register 
One.  It  has  a  few  informative  bits,  but  we  will  be  concerned 
with  only  the  Vertical  Retrace  bit  (3).  As  the  name  implies, 
this  bit  is  set  to  1  when  the  display  is  in  a  vertical  retrace 
time.  As  I  stated  before,  this  was  the  time  to  write  to  the 
video  memory  with  the  CGA  adapter.  It  has  approximately 
the  same  value  with  the  EGA  adapter,  but  not  exactly. 

When  Blazing  Fast  Is  Not  Fast  Enough  to  Start  a  Fire 

When  I  converted  my  CGA  animation  routines  to  work  with 
the  EGA,  there  was  an  unexpected  problem.  I  found  that 
no  matter  how  fast  I  blasted  my  sprites  out  to  video  memory, 
the  raster  line  (another  name  for  that  beam  of  electrons 
described  earlier)  would  catch  up  to  where  I  was  writing 
pixels.  When  the  raster  caught  up,  the  screen  would  flicker 
annoyingly.  Having  to  deal  with  four  planes  and  EGA’s 
higher  resolution  just  took  too  much  time.  I  made  my  code 
the  most  efficient  assembly  routines  I  could.  I  made  assump¬ 
tions  about  the  data  I  was  displaying  in  order  to  cut  corners. 
I  got  a  25-MHz  386  system.  Nothing  worked.  I  felt  like  a 
laundry  soap  commercial.  I  went  back  to  the  EGA  Technical 
Reference  manual. 


Value 

Description 

00 

Written  data  is  not  modified 

0  1 

Written  data  is  ANDed  with  latched  data 

1  0 

Written  data  is  ORed  with  latched  data 

1 1 

Written  data  is  XORed  with  latched  data 

Table  1:  Available  functions 


Almost  immediately  the  answer,  written  by  the  IBM  an¬ 
cients,  made  me  question  what  I  had  been  thinking  about 
in  the  first  place.  The  standard  EGA  has  256K  of  RAM  — 
enough  for  two  pages  of  display  memory.  I  could  write  to 
one  page,  wait  for  the  next  vertical  retrace,  then  swap  pages. 
I  rewrote  everything. 

Planning  ahead,  I  continued  reading  the  Technical  Refer¬ 
ence  manual.  The  EGA  can  generate  an  interrupt  request  2. 
If  the  driver  could  just  swap  pages  whenever  the  video 

To  become  animated  objects,  sprites 
must  have  four  basic  degrees  of 
freedom:  Coordinate  Motion,  Self¬ 
relative  Motion,  Rotation,  and 
Perceived  Distance 


went  into  vertical  retrace,  then  I  wouldn’t  have  to  waste  time 
polling.  I  rewrote  it,  again. 

Animation  Structures 

To  become  animated  objects,  sprites  must  have  four  basic 
degrees  of  freedom:  Coordinate  Motion,  Self-relative  Mo¬ 
tion,  Rotation,  and  Perceived  Distance.  Coordinate  Motion 
is  simply  the  movement  from  one  point  on  the  screen  to 
another.  Self-relative  Motion  is  the  movement  that  the  sprite 
could  make  without  moving  to  a  new  coordinate  location. 
Rotation  is  rotation  of  the  sprite  around  some  center  point 
in  its  body.  Perceived  Distance  is  basically  sizing  the  sprite 
according  to  its  apparent  distance  from  the  viewer. 

The  increment  resolution  of  each  degree  of  freedom  is 
independent  of  the  others.  A  sprite  picture  of  a  person  may 
be  pumping  its  arm  up  and  down  a  pixel  at  a  time  and 
traversing  the  screen  five  pixels  at  time.  Given  a  monitor/ 
graphics  adapter  combination  that  refreshed  the  screen  an 
infinite  number  of  times,  the  smaller  the  movement  incre¬ 
ment,  the  more  realistic  its  action  would  be.  Because  the 
standard  EGA  board  refreshes  the  screen  at  60  Hz  (60  times 
a  second),  the  movement  increment  should  be  judged  rela¬ 
tive  to  the  apparent  velocity  of  the  sprite,  the  display  resolu¬ 
tion,  and  the  level  of  the  art.  Because  I  can  draw  only  crude 
stick  figures,  my  resolution  granularity  can  be  boulder-size. 

Two  of  the  four  degrees  of  freedom  (Rotation  and  Per¬ 
ceived  Distance)  should  not  be  a  function  of  a  sprite  driver. 
A  good,  general-purpose  rotation  algorithm  requires  fairly 
heavy  calculations.  These  calculations  are  burdensome  enough 
to  detract  from  the  real-time  nature  of  the  animation  driver. 
Although  Perceived  Distance  does  not  need  as  much  time 
from  the  CPU,  it  should  be  done  at  a  higher  level  than  the 
driver.  Perceived  Distance  requires  the  sprite  to  be  resized 
larger  as  it  gets  closer  to  the  viewer  and  smaller  as  it  gets 
farther  away.  As  the  size  of  the  sprite  approaches  the  mini¬ 
mum  resolution  of  the  monitor,  details  disappear.  No  al¬ 
gorithm  can  make  perfect  decisions  about  which  features  of 
an  object  are  important  to  the  visual  integrity  of  that  object. 

Self-relative  Motion  deals  with  the  movement  of  each  of 
the  individual  pixels  of  the  sprite  with  respect  to  each  other, 
but  not  straying  outside  the  boundary  of  the  sprite.  To 
illustrate  Self-relative  Motion  without  any  other  component, 
I  have  included  a  sprite  of  a  flame.  Each  of  the  pixel  groups 
that  represent  small  flamelets  rises  to  the  top  of  the  fire.  The 
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(continued  from  page  20) 

pixel  groups  that  represent  the  edges  of  the  flame  billow  in 
the  updraft  caused  by  the  heated  air.  In  my  routine,  the 
effect  of  the  motion  is  created  by  a  linked  list  of  sprite 
frames.  In  the  example,  each  successive  frame  shows  the 
flame  in  the  next  point  of  time  (without  regard  to  mathe¬ 
matical  proofs,  in  animation  there  is  a  quantum  of  time). 
Because  motion  in  most  biological  or  mechanical  systems 
is  cyclical,  I  join  the  terminal  points  of  this  linked  list  into  a 
sprite  circle.  Each  sprite  can  proceed  through  a  cycle  of 
self-relative  motions  whose  complexity  is  determined  by  the 
circumference  of  the  sprite  circle. 

Coordinate  Motion  involves  moving  the  sprite  circle  from 
one  point  to  another  on  the  screen  at  some  regular  velocity. 
The  sprite  velocity  is  determined  by  the  number  of  pixels 
that  the  sprite  circle  will  move  divided  by  the  number  of 
times  per  second  the  visual  image  will  be  changed.  Say  we 
make  a  sprite  representation  of  a  five-meter-long  car  that  is 
drawn  32  pixels  in  length.  To  move  that  car  from  the  right 
side  of  the  screen  to  the  center  at  an  apparent  velocity  of 
20  km/hour,  the  sprite  would  have  to  move  to  the  left  176 
pixels  per  second  if  everything  is  kept  to  scale.  If  our  visual 
page  changes  come  at  20  per  second,  the  sprite  would  have 
to  be  moved  nine  pixels  to  the  left  for  every  page  change. 

How  the  Routines  Work 

The  sprite  routines  are  broken  down  into  two  parts.  The 
portion  that  deals  with  the  EGA  ports,  memory  and  interrupt 
service  is  written  in  8086  assembly  language.  Listing  One 
(page  82)  shows  the  EGA  sprite  drivers  and  Listing  Two 
(page  88),  the  sprite  circle  handler.  The  higher-level  sprite 
circle  and  list  managers  are  written  in  Microsoft  C.  Listing 
Three  (page  92),  SPRITES. C,  displays  a  sprite  file  on  an  EGA 


screen,  and  Listing  Four  (page  93)  is  the  make  file. 

Some  assumptions  were  made  about  the  nature  of  the 
sprites  and  the  background.  The  sprite  driver  is  written  for 
sprites  of  any  dimension,  but  the  driver  is  optimized  for  a 
sprite  that  is  32  bits  across.  In  my  application,  it  was  as¬ 
sumed  that  the  observer  could  pan  or  tilt  the  viewing  per¬ 
spective.  Because  the  perspective  can  be  changing  in  smooth 
real  time,  the  background  is  not  a  set  quantity  —  it  is  being 
regenerated  in  every  visual  frame.  Additionally,  because  the 
8086  family  drops  at  least  eight  clock  ticks  every  time  it 
makes  a  JMP  or  CALL ,  the  code  favors  execution  speed  (that 
is,  very  few  jumps,  calls,  or  loops)  over  program  size. 

The  basic  algorithm  is  simple.  Before  any  operations  can 
be  performed,  the  sprite  driver  needs  to  be  installed  using 
the  function  EGA_LNSTALL(  ).  This  preps  the  adapter,  initial¬ 
izes  some  variables,  and  installs  the  interrupt  vector.  The 
first  sprite  of  a  sprite  circle  is  inserted  into  the  linked  list  of 
circles  by  calling  the  function  LNSERT_SPRLTE  (START_X, 
START_Y,  END_X ,  END_Y,  SPEED JX,  SPEED _Y,  DEPTH , 
SPRLTE_  CIRCLE)-  where  START _X  and  STARTJY  are  the 
starting  X,  Fcoordinates  of  the  sprite,  END_Xand  END_Y  are 
the  ending  X,  Y  coordinates  of  the  sprite,  SPEED_X  and 
SPEED_Y are  the  amounts  that  the  .A and  Fcoordinates  will 
change  per  visual  frame,  DEPTH  is  the  perceived  distance 
from  the  observer,  and  SPRITEjCIRCLE  is  a  pointer  to  the 
first  entry  of  the  sprite  circle.  Additional  sprites  can  be  added 
to  the  circumference  of  a  sprite  circle  with  the  function 
ADD_SPRILE.  Once  all  the  sprite  circles  have  been  figured 
out  and  inserted  into  the  sprite  list,  call  DO_SPRLTE_  LISTO 
whenever  it  is  appropriate.  DO_SPRLTE_  LISTC  )  figures  out 
the  new  sprite  positions  and  places  them  on  the  nonvisual 
page.  When  it  has  placed  all  the  sprites,  it  sets  the  flag 
DO_PAGE_  FLIP ,  clears  DONE_PA GE_  FLIP,  and  returns. 


The  main  program  body  is  then  free  to  do  anything  with  the 
sprite  structures.  At  some  time  in  the  future,  the  EGA’s 
vertical  interrupts  and  the  interrupt  service  routine  decides 
whether  to  swap  pages  or  not.  If  it  does  swap  the  pages,  it 
clears  DO_PAGE_FLIP and  sets  DONE_PAGE_  FLIP.  Although 
the  routines  are  not  completely  reentrant,  they  are  fairly 
immune  to  interrupts;  they  can  be  called  from  other  inter¬ 
rupt  service  routines  such  as  the  timer  tick  or  a  mouse  driver. 

Animation  is  achieved  by  showing 
a  series  of  incrementally 
changing  images 


With  regard  to  visual  timing,  movies  project  24  frames  per 
second  on  the  silver  screen.  To  decrease  the  cost  of  anima¬ 
tion,  some  cartoon  manufacturers  will  keep  the  same  pic¬ 
ture  on  the  screen  for  more  than  one  frame.  The  interrupt 
service  routine  has  a  counter  that  can  be  used  to  allow  it  to 
skip  any  number  of  vertical  retraces  between  page  changes. 
If  your  CPU  is  slow  or  the  main  body  of  your  program  needs 
more  time  to  do  its  work,  altering  the  skip  count  has  the 
effect  of  smoothing  out  the  movement  of  the  sprites.  To 
counteract  the  slowing  effect  that  increasing  the  skip  count 
would  have,  you  must  increase  the  velocity  of  any  coordi¬ 
nate  motion  proportionately. 


Finishing  Thoughts 

So  much  can  be  written  about  real-time  animation  that  a 
conclusion  at  any  point  leaves  us  feeling  a  lot  was  left  out. 
The  scope  of  this  article  does  not  allow  me  to  explore  all  the 
avenues  with  the  depth  they  deserve.  Maybe  you  can  use 
the  routines  that  have  been  provided  with  this  article  as 
learning  aids  to  go  beyond  what  has  been  written.  Anima¬ 
tion  is  a  form  for  the  presentation  of  ideas.  Seminars,  prod¬ 
uct  demonstrations,  and  computer  modeling  programs  can 
all  be  enhanced  by  the  addition  of  animation  graphics.  Of 
course,  the  most  obvious  use  only  enhances  what  I  have 
always  said:  The  only  useful  thing  someone  can  do  with  a 
computer  is  play  a  game  on  it. 

Availability 

All  source  code  is  available  on  a  single  disk  and  online.  To 
order  the  disk,  send  $14.95  (Calif,  residents  add  sales  tax) 
to  Dr.  Dobb's  Journal,  501  Galveston  Dr.,  Redwood  City, 
CA  94063,  or  call  800-356-2002  (from  inside  Calif.)  or  800-533- 
4372  (from  outside  Calif.).  Please  specify  the  issue  number 
and  format  (MS-DOS,  Macintosh,  Kaypro).  Source  code  is 
also  available  online  through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing  Service  (603-882- 
1599)  supports  300/1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the  system  answers,  type: 
listings  (lowercase)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  82.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  1. 
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Real-Time 
Data  Acquisition 

UsingDMA 

Here  are  all  the  tools  —  hardware  and  software  —  you  need 
for  your  own  data  acquisition  system 


Tom  Nolan 


In  this  article  I  describe  hardware 
and  software  that  I  designed  for 
an  IBM  PC-compatible  computer 
to  acquire  real-time  data  from  an 
external  source  in  a  way  that  still 
permits  the  PC  to  perform  analysis  and 
display  of  the  data  as  it  is  acquired.  A 
286-based  PC-compatible  is  an  attrac¬ 
tive  workstation  for  this  kind  of  devel¬ 
opment  because  it  is  relatively  inex¬ 
pensive,  portable,  easy  to  program,  and 
add-on  interface  hardware  can  easily 
be  designed  for  it. 

The  first  problem  in  a  data  acquisi¬ 
tion  system  is  how  to  actually  acquire 
the  data.  Direct  memory  access  (DMA) 
provides  a  simple  solution  from  a  hard¬ 
ware  design  standpoint.  With  DMA,  the 
data  from  some  external  device  is  stuffed 
directly  into  the  PC  memory  a  byte  or 
a  word  at  a  time,  without  processor 
intervention.  DMA  can  also  be  made 
to  work  in  the  other  direction:  From 
the  PC  memory  to  an  external  device 
or  even  from  one  area  of  memory  to 
another.  While  the  transfer  of  data  is 
taking  place,  the  CPU  is  free  to  perform 


Tom  is  an  associate  scientist  for  Ap¬ 
plied  Research  Corporation,  specializ¬ 
ing  in  real-time  data  acquisition  and 
control  and  is  currently  working  un¬ 
der  contract  with  the  Laboratory  for 
High  Energy  Astrophysics  at  NASA ’s  God¬ 
dard  Space  Flight  Center.  He  can  be 
reached  at  NASA/Goddard  Space  Flight 
Center,  Code  664,  Greenbelt,  MD 20771. 


any  other  tasks  it  wants  to.  Its  speed 
will  be  somewhat  degraded  because 
the  DMA  operation  is  stealing  cycles, 
holding  off  the  processor  for  just  long 
enough  to  transfer  the  next  byte  or 
word.  This  feature  of  leaving  the  proces¬ 
sor  free  allows  us  to  think  of  this  opera¬ 
tion  as  a  primitive  kind  of  multitasking: 
The  DMA  transfer  takes  place  in  the 
foreground,  in  real  time,  while  the  analy¬ 
sis  and  display  of  data  takes  place  in 
the  background,  using  whatever  pro¬ 
cessor  time  is  left  over. 


PC  DMA  Architecture 

In  an  IBM  PC  or  compatible,  most  of 
the  hardware  and  control  signals  nec¬ 
essary  to  carry  out  a  DMA  transfer  are 
present  on  the  system  board  and  I/O 
bus.  To  take  advantage  of  these  “built- 
in"  facilities,  you  must  build  a  small 
amount  of  handshaking  circuitry  on 
an  interface  card  that  plugs  into  the 
PC  backplane,  then  route  the  data  from 
its  external  source  to  this  interface  card. 
In  keeping  with  its  “open  system”  phi¬ 
losophy,  IBM  makes  public  all  the  in¬ 
formation  you  need  to  understand  and 
work  with  the  signals  present  on  its 
I/O  bus  (see  the  References). 

On  a  PC  system  board,  there  is  a 
DMA  controller,  which  is  an  Intel  8237A 
integrated  circuit.  A  single  8237  con¬ 
trols  four  separate  DMA  “channels,” 
numbered  0  through  3.  Each  can  be 
individually  programmed,  and  all  four 
can  be  active  simultaneously.  On  a  PC, 
channel  0  is  used  for  refreshing  the 
dynamic  memory,  and  its  control  sig¬ 
nals  are  not  even  present  on  the  system 
bus.  Channel  2  is  used  by  the  floppy 
disk,  and  channel  3  is  used  by  the  hard 
disk,  leaving  channel  1  available  as  a 
spare.  Channel  1  can  be  somewhat  over¬ 
subscribed,  because  many  add-on  pe¬ 
ripherals  (such  as  network  adapters  and 
tape  backup  systems)  use  it. 

On  an  AT,  two  8237  chips  are  pre¬ 
sent,  relieving  some  of  the  congestion. 
The  control  signals  for  the  additional 
channels  are  present  only  on  the  ex- 
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(continued  from  page  28) 
tended  AT  I/O  bus  (the  short  connec¬ 
tor  in  the  backplane  in  front  of  the 
longer,  standard  PC  connector).  Most 
commercial  add-on  boards  that  use 
DMA  are  equipped  with  switches  al¬ 
lowing  the  selection  of  a  non-interfer¬ 
ing  channel.  However,  cards  that  have 
only  the  standard  PC  connector  cannot 
take  advantage  of  the  AT’s  extra  chan¬ 
nels.  On  an  AT,  channel  2  is  used  for 
the  floppy,  and  channel  4  is  used  for 
cascading  the  two  controllers.  Memory 
refresh  and  hard  disk  transfers  are  per¬ 
formed  without  DMA.  That  leaves  chan¬ 
nels  0,  1,  3,  and  5-7  available  for 
add-on  use. 

The  8237  DMA  controller  is  a  com¬ 
plex  chip,  occupying  a  block  of  16 
addresses  in  the  PC’s  I/O  space.  The 
base  address  of  the  primary  controller  is 
0,  so  I/O  ports  0  to  F  (hex)  are  used  to 
address  it.  The  secondary  (AT  only)  con¬ 
troller’s  base  address  is  CO,  but  it  deals 
in  words  instead  of  bytes,  and  so  is 
addressed  on  the  even-numbered  ports 
in  the  range  CO-DE.  Figure  1  shows  the 
I/O  port  assignments  of  the  8237  chips. 

The  following  is  the  sequence  of 


operations  involved  in  setting  up  and 
carrying  out  a  DMA  transfer.  A  channel 
must  be  selected  for  use  and  the  hard¬ 
ware  and  software  must  both  agree  on 

The  software  operates 
on  a  “Ping-Pong” 
buffer  principle 


it.  The  software  (writing  to  the  DMA 
controller)  programs  the  transfer  mode 
(read  or  write),  the  starting  address  of 
the  area  in  memory  to  which  or  from 
which  the  data  will  be  transferred,  the 
number  of  bytes  (words,  in  the  case  of 
the  secondary  controller)  to  be  trans¬ 
ferred,  and  then  clears  the  channel  mask 
bit,  enabling  the  hardware  to  begin 
transferring  data.  The  hardware  requests 
a  DMA  cycle  by  raising  the  DMA  re¬ 
quest  line  (DRQ)  for  the  particular  chan¬ 


nel  to  a  high  level.  The  DMA  controller 
responds  by  lowering  the  DMA  acknowl¬ 
edge  line  (DACK),  which  is  normally 
high,  for  that  channel.  This  signals  that 
the  next  bus  cycle  can  be  used  by  the 
hardware  to  transfer  a  byte  or  word  of 
data.  If  the  controller  is  programmed 
for  a  write  transfer,  when  DACK  goes 
low  the  hardware  may  place  the  next 
value  on  the  data  lines.  In  a  read  trans¬ 
fer,  the  I/O  bus  data  lines  contain  the 
next  value  in  memory.  The  controller 
takes  care  of  everything  else:  Incre¬ 
menting  the  memory  location,  driving 
the  address  lines,  and  handling  the  CPU 
control  lines.  From  a  hardware  design 
standpoint,  this  is  a  simple  interface. 

Things  become  somewhat  more  com¬ 
plicated  if  the  program  desires  notifica¬ 
tion  when  the  DMA  transfer  is  com¬ 
plete.  The  DMA  controller  raises  a  total 
count  signal  (TC)  along  with  the  last 
DACK  when  the  programmed  count 
expires.  The  TC  line  is  available  on  the 
I/O  bus,  and  can  be  wired  to  one  of  the 
interrupt  request  (IRQ)  lines  to  cause 
a  CPU  interrupt  when  the  transfer  is 
complete.  The  interrupt  service  routine 
in  software  can  then  program  the  DMA 
controller  to  set  up  the  next  transfer, 
closing  the  loop  and  creating  a  fore¬ 
ground  task  that  will  run  indefinitely. 

Building  a  DMA  Interface  Circuit 

Figure  2  depicts  a  circuit  that  performs 
all  the  DMA  handshaking  described  ear¬ 
lier.  Together  with  the  software  sup¬ 
plied  in  the  accompanying  listings,  it 
forms  the  nucleus  of  a  real-time  data 
acquisition  system.  It  was  designed  to 
accept  data  from  a  D/PAD  (a  commer¬ 
cial  telemetry  receiver),  but  it  will  work 
with  any  data  source  that  can  provide 
a  byte  at  a  time  and  a  clock  signal 
when  each  byte  is  ready. 

At  the  heart  of  the  circuit  is  the  FIFO 
(U1  in  Figure  2),  a  chip  that  imple¬ 
ments  in  hardware  the  first-in,  first-out 
data  structure  familiar  to  most  program¬ 
mers.  There  are  eight  parallel  data  lines 
coming  in  to  the  FIFO,  and  eight  going 
out.  The  incoming  bytes  are  written 
into  the  FIFO  memory  by  strobing  the 
write  clock,  and  the  bytes  are  read  out 
in  the  same  order  as  they  were  written 
by  strobing  the  read  clock.  Both  of  the 
strobes  are  active-low  pulses.  The  FIFO 
acts  as  an  elastic  buffer  between  the 
data  source  and  the  computer:  If  the 
computer  is  busy  for  some  period  of 
time  (servicing  another  interrupt  for 
example),  incoming  data  just  gradually 
fill  up  the  FIFO  until  the  computer  gets 
around  to  taking  them  out.  If  the  FIFO 
ever  overflows,  data  are  lost.  The  depth 
of  the  FIFO  and  the  incoming  data  rate 
determine  the  maximum  tolerable  soft¬ 
ware  delay.  The  FIFO  I  used  has  a 
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AT 

ctrir 

address 


CO 


C2 


C4 


C6 


C8 


CA 


CC 


CE 


DO 


D2 


D4 


D6 


D8 


DA 


DC 


DE 


Description  of  register  contents 


Channel  0  base  address  (write  2  bytes,  LSB  first). 


Channel  0  count  (write  2  bytes,  LSB  first). 


Channel  1  base  address 


Channel  1  count 


Channel  2  base  address 


Channel  2  count 


Channel  3  base  address 


Channel  3  count 


Command/status  register  (not  used  in  this  application) 


Request  register  (not  used) 


Single  mask  register  (write  only) 


76  5  4  3  21  0 


( channel  select  (0-3) 
■  mask  bit  value  (0-1) 


Mode  register  (write  only) 


76  5  4  3  21  0 


channel  select  (0-3) 

01=write,  10=read 

0=disab!e  autoinitialization,  1  =enab!e 
0=disable  autoinitiali2ation,  1=decrement 

,  01  =single  transfer  mode 


Clear  byte  pointer  dtp-flop  (write  only) 


Master  clear  (not  used) 


Clear  mask  register  (not  used) 


Write  all  mask  registers  (not  used) 


Figure  1:  8237 DMA  controller  I/O  port  assignments 
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(continued  from  page  30) 
capacity  of  1024  bytes. 

The  FIFO  provides  an  “empty”  flag, 
a  signal  that  is  low  when  the  FIFO  is 
empty  and  high  when  it  contains  data. 
This  signal  is  used  directly  to  drive  the 
channel  1  DMA  request  line,  DRQ1. 
This  means  that  as  long  as  there  is 
something  in  the  FIFO,  there  will  be  a 
request  to  transfer  data.  In  single-trans¬ 
fer  mode,  the  DMA  controller  guaran¬ 
tees  that  even  when  DRQ  is  asserted 
continuously,  the  CPU  will  get  every 
other  bus  cycle.  In  other  words,  we 
can’t  shut  out  the  CPU  by  holding  up 
the  request  line  like  this.  Assuming  that 
the  DMA  controller  has  been  correctly 
programmed  by  the  software,  there  will 
be  DMA  acknowledge  signals  returned 
on  DACK1.  Each  DACK,  an  active-low 
signal,  strobes  the  read  clock  on  the 
FIFO,  which  causes  the  next  byte  to 
appear  on  the  FIFO  output  lines.  The 
DACK  also  gates  the  next  chip  in  line, 
which  is  a  “tri-state”  buffer  (U2)  whose 
output  is  connected  to  the  PC  data 
bus.  When  the  buffer  is  not  enabled 
(DACK  signal  high),  its  output  lines  are 
inactive  and  do  not  interfere  with  the 
PC  bus  operation.  When  DACK  is  low, 
the  buffer  drives  its  8  bits  onto  the  PC 
bus,  where  they  are  picked  up  and 
deposited  in  memory  as  directed  by 
the  DMA  controller. 

The  number  of  bytes  that  are  trans¬ 
ferred  in  this  manner  is  dependent  on 
the  count  programmed  into  the  DMA 
controller  by  the  software.  On  the  last 
transfer  the  DMA  controller  asserts  the 


TC  signal,  driving  it  high.  There  is  only 
one  TC  for  all  the  DMA  channels,  so 
in  order  to  distinguish  it  from  other 
DMA  operations  that  may  be  going  on, 
it  is  ANDed  with  the  negated  DACK 

The  first  problem  in  a 
data  acquisition  system 
is  how  to  actually 
acquire  the  data.  Direct 
memory  access  provides 
a  simple  solution  from 
a  hardware  design 
standpoint 


signal.  The  conjunction  of  these  two 
sets  a  flip-flop  (U3B),  whose  output 
goes  directly  to  IRQ3  on  the  PC  bus, 
causing  an  interrupt  in  the  CPU.  This 
is  the  same  interrupt  used  by  COM2  if 
one  is  present,  so  another  interrupt 
must  be  used  in  case  of  conflict.  To 
make  sure  the  interrupt  is  recognized, 
the  interrupt  line  must  be  held  high 


until  the  CPU  transfers  control  to  the 
interrupt  service  routine.  Unfortunately, 
there  is  no  way  to  determine  automati¬ 
cally  that  the  ISR  is  executing,  so  the 
software  must  explicitly  notify  the  hard¬ 
ware  when  it  is  safe  to  lower  the  IRQ. 
This  is  done  by  creating  an  I/O  port. 

When  the  software  reads  or  writes 
from  an  I/O  port,  the  CPU  places  the 
I/O  port  address  on  the  PC  address 
bus,  together  with  an  “address  enable” 
(AEN)  strobe  and  either  an  IOR  or  an 
IOW  signal,  depending  on  whether  the 
I/O  port  was  read  or  written.  Normally, 
any  device  recognizing  its  own  I/O 
address  uses  the  next  bus  cycle  to  trans¬ 
fer  a  byte  of  data,  either  to  or  from  the 
CPU,  thus  satisfying  the  program’s  read 
or  write.  However,  it  is  not  actually 
necessary  for  any  data  to  be  transferred. 
The  circuit  takes  advantage  of  this  by 
using  just  the  fact  that  an  I/O  read  has 
occurred  on  its  own  address  to  clear 
the  interrupt  request. 

The  address  comparator  at  U4  raises 
its  output  line  whenever  its  hard-wired 
address  appears  on  the  PC  bus  in  con¬ 
junction  with  AEN.  For  simplicity’s  sake, 
the  address  is  only  partially  decoded, 
that  is,  whenever  bits  9  -  2  of  the  ad¬ 
dress  are  “11101000”  regardless  of  the 
rest,  the  decoder  output  goes  high.  Bi¬ 
nary  11101000XX  is  hex  3A0-3A3,  so 
any  of  these  addresses  will  work.  (So 
will  7 A0  -  7 A3,  BA0  -  BA3,  and  FA0  - 
FA3.)  Normally,  these  addresses  are  un¬ 
used  in  a  PC,  any  other  address  range 
can  be  selected  by  wiring  the  appropri¬ 
ate  combination  of  pins  to  +5V  and 
ground.  To  finally  turn  off  the  flip-flop 
driving  the  IRQ,  the  decoder  output  is 
ANDed  with  IOR.  The  end  result  is  that 
the  program  can  read  I/O  port  3A0  (or 
any  of  its  equivalents)  to  clear  the  inter¬ 
rupt  request. 

One  final  bit  of  logic  is  used  to  reset 
the  FIFO  to  its  empty  state.  This  reset 
is  done  at  the  start  of  data  acquisition 
to  clear  out  any  old  data  and  to  start 
filling  the  FIFO  on  a  “frame”  boundary, 
which  marks  the  beginning  of  a  new 
block  of  data.  The  same  I/O  port  ad¬ 
dress  decode  is  used  in  conjunction 
with  IOW  this  time,  to  set  the  flip-flop 
at  U3A,  lowering  the  active-low  “reset” 
signal  on  the  FIFO.  The  software  can 
thus  cause  the  reset  to  happen  by  writ¬ 
ing  to  I/O  port  3 A0.  The  flip-flop  is 
cleared  at  the  next  “frame  sync”  pulse 
from  the  data  source,  bringing  the  FIFO 
out  of  reset  and  allowing  it  to  begin  to 
fill.  The  software  must  immediately  pro¬ 
gram  the  DMA  controller  to  begin  a 
transfer  —  before  the  FIFO  overflows  — 
to  avoid  losing  data. 

Programming  the  DMA  Interface 

Now  let’s  turn  to  the  software  that  makes 


Figure  2:  A  circuit  that  performs  DMA  handshaking 
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(continued from,  page  32) 
this  system  run.  It  is  contained  in  two 
files,  dma.c  (Listing  One,  page  94)  and 
test.c  (Listing  Two,  page  96).  The  first 
file  is  a  subroutine  package  containing 
all  of  the  subroutines  to  set  up  and  run 
the  DMA  hardware,  and  the  second  file 
is  a  sample  main  program  to  show  how 
the  subroutines  are  called. 

The  software  operates  on  a  “Ping- 
Pong”  buffer  principle.  Two  buffers  are 
allocated  at  run  time.  While  one  buffer 
is  being  filled  by  DMA,  the  other  buffer’s 
contents  are  available  to  the  program 
for  whatever  data  processing  is  desired. 
When  the  transfer  into  the  first  buffer 
is  complete,  the  buffers  are  swapped 
and  a  new  transfer  is  started.  The  size 
of  the  buffers  is  chosen  so  that  there  is 
enough  time  for  the  program  to  do  all 
the  processing  it  needs  to  do  in  be¬ 
tween  buffer  swaps.  At  a  medium  data 
rate  of  say,  64K  bits  per  second,  there 
are  eight  seconds  of  data  in  a  64K  byte 
buffer. 

Although  a  lot  of  processing  can  be 
done  in  eight  seconds,  it  is  not  an  infi¬ 
nite  amount  of  time.  If  a  program  needs 
to  do  some  heavy  data  crunching,  its 
first  action,  when  buffers  are  swapped, 
should  be  to  copy  some  or  all  of  the 
new  buffers  into  a  spare  area  in  mem¬ 
ory  and  work  on  it  there.  The  data 
acquisition  is  entirely  interrupt-driven, 
and  once  started,  it  runs  by  itself,  alter¬ 
nately  filling  and  swapping  buffers  like 
clockwork.  It  can  be  thought  of  as  the 
higher  priority  “foreground”  task,  with 
the  data  processing  filling  up  the  time 
as  the  “background”  task. 

The  main  program  calls  alloc_  dma_ 
buf( )  to  allocate  the  Ping-Pong  buff¬ 
ers.  The  buffer  size,  in  bytes,  is  speci¬ 
fied  in  the  global  variable  buf_size.  Be¬ 
cause  of  the  way  the  DMA  controller 
works,  neither  buffer  is  allowed  to  strad- 
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Figure  3 :  DMA  page  register 
assignments 


die  a  physical  64K  byte  “page”  bound¬ 
ary  in  memory.  Another  way  to  say  this 
is  that  each  DMA  buffer  must  lie  en¬ 
tirely  within  the  range  X0000-XFFFF 
(hex)  where  X  identifies  one  of  the  ten 

I  designed  a  more 
complex  software 
package  to  receive 
telemetry  from  a  NASA 
experiment  flown  on  a 
sounding  rocket  from 
Woomera,  Australia  in 
March  1988 


64K  pages  in  the  640K  base  memory 
of  the  PC.  This  requirement  is  difficult 
to  meet  and  alloc_dma_buf( )  does  it 
by  using  the  DOS  memory  allocation 
functions  to  grab  all  available  memory, 
then  fitting  the  two  buffers  into  the  first 
pages  large  enough  to  contain  them.  Of 
course,  the  maximum-length  DMA  trans¬ 
fer  this  scheme  can  handle  is  64K  bytes. 

The  program  then  calls  dma_setup( ) 
to  prepare  the  DMA  controller  and  en¬ 
able  the  interrupt  service  routine.  The 
channel  number  to  be  used  by  the  hard¬ 
ware  (channel  1  in  the  example)  is 
specified  in  the  global  variable  dma_ 
chan,  and  the  interrupt  number  in  dma_ 
irq.  dma_setup( )  locates  a  number  of 
registers  (port  addresses)  that  will  be 
used  later  on.  A  single  DMA  controller 
can  only  handle  data  in  64K  chunks 
(bytes  or  words,  depending  on  which 
controller).  To  gain  access  to  the  full 
640K  address  space,  the  upper  4  bits 
of  the  transfer  address  will  be  placed 
in  a  page  register.  There  is  one  page 
register  for  each  DMA  channel,  allo¬ 
cated  as  shown  in  Figure  3.  The  correct 
page  register  address  is  selected  by 
dma_setup( ),  as  well  as  the  base,  count, 
mask,  and  mode  register  addresses  from 
Figure  1. 

The  next  step  uses  an  undocumented 
feature  of  DOS.  Because  DOS  is  not 
reentrant,  care  must  be  taken  in  calling 
DOS  functions  from  an  interrupt  ser¬ 
vice  routine  (it  may  have  interrupted  a 
DOS  operation  in  progress).  The  un¬ 
documented  DOS  function  34  (hex) 
returns  in  the  register  pair  ES:BX,  the 
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(continued  from  page  34) 
address  of  its  critical  section  flag.  When 
the  byte  at  this  address  is  zero,  it  is  safe 
to  call  any  DOS  function.  When  the 
byte  is  non-zero,  DOS  is  executing  a 
critical  section  of  code  and  may  not 
be  reentered.  Function  34  works  in  DOS, 
Versions  2  and  3;  I  have  not  tested  it 
in  Version  4.  In  dma_setup(  ),  the  ad¬ 
dress  of  this  flag  is  found  and  saved  for 
later  use. 

The  final  step  in  dma_setup(  )  is  to 
place  the  address  of  the  interrupt  ser¬ 
vice  routine  dma_isr(  ),  in  the  speci¬ 
fied  vector,  and  enable  the  interrupt 
by  clearing  the  corresponding  mask  bit 
in  the  interrupt  controller. 

Starting  the  Data  Acquisition  Process 

To  start  up  the  data  acquisition,  the 
program  calls  start_dma(  ).  Two  argu¬ 
ments  are  passed:  The  buffer  address 
and  the  number  of  bytes  to  transfer. 
start_dma(  )  programs  the  DMA  con¬ 
troller  with  the  buffer  address  and  count, 
using  the  register  addresses  computed 
above  in  dma_setup(  ).  The  8237  is 
programmed  1  byte  at  a  time,  the  least 
significant  byte  first.  To  ensure  the  cor¬ 
rect  order,  a  register  on  the  8237  resets 
its  internal  byte  flip-flop  to  its  initial 
state,  but  it  is  a  safe  assumption  that  in 
a  PC  this  flip-flop  is  already  clear  so  the 
LSB  can  be  written  first. 

First,  the  mask  bit  on  the  8237  for  the 
selected  channel  is  set,  disabling  DMA 
on  this  channel  while  the  8237  is  being 
programmed.  Next,  the  buffer  address 
is  split  into  3  bytes  by  one  of  two 
methods,  as  illustrated  in  Figure  4.  The 
method  used  depends  on  whether  the 
channel  number  is  located  on  the  byte- 


oriented  or  the  word-oriented  control¬ 
ler.  The  lower  8  bits  and  the  middle  8 
bits  are  written  to  the  8237's  base  ad¬ 
dress  register  in  two  successive  opera¬ 
tions.  The  high  bits  are  written  to  the 
page  register.  Next,  the  byte  count  is 
divided  by  two  for  word-oriented  chan¬ 
nels,  then  decremented  and  output  to 
the  8237’s  count  register  in  two  writes. 
The  reason  it  is  decremented  is  that  the 
terminal  count  is  reached  when  the 
count  remaining  goes  from  0  to  FFFF. 
Finally,  the  channel  mask  bit  is  cleared, 
allowing  DMA  to  begin. 

When  the  last  byte  or  word  is  trans¬ 
ferred,  the  interface  card  causes  a  CPU 
interrupt.  Because  the  address  of 
dma_isH  )  was  placed  in  the  corre¬ 
sponding  interrupt  vector,  this  routine 
is  entered  as  soon  as  the  interrupt  oc¬ 
curs.  By  declaring  the  function  with 
type  interrupt,  the  usual  C  entry  code 
is  replaced  by  interrupt  entry  code:  The 
registers  are  saved  and  the  correct  data 
segment  is  loaded.  The  function  re¬ 
turns  by  restoring  the  registers  and  is¬ 
suing  an  IRET  instruction.  The  stack 
segment  may  not  be  the  same  as  the 
data  segment  as  would  be  usual  in 
small  model  code,  so  pointers  to  local 
variables  are  not  allowed  in  an  inter¬ 
rupt  context. 

In  dma_isr(  )  the  variable  curr_buf 
is  set  to  point  to  the  buffer  that  was  just 
filled.  The  main  program  can  use  this 
address  to  gain  access  to  the  data.  The 
buffer  index  is  toggled  to  swap  buffers 
and  start_dma(  )  is  called,  passing  the 
address  of  the  next  buffer.  Thus, 
dma_isr(  )  propagates  its  own  execu¬ 
tion  because  when  the  next  buffer  fills, 
the  interrupt  will  occur  and  dma_isr(  ) 


20-bit  DMA  Transfer  Address,  Byte-Orientated  Channels  0-3 
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will  get  called  again.  Before  exiting, 
the  interrupt  service  routine  clears  its 
own  interrupt  request  and  outputs  the 
end-of-interrupt  signal  to  the  interrupt 
controller.  I  declared  the  function  re- 
set_irq(  )  in  the  calling  program  rather 
than  here  because  it  is  hardware  de¬ 
pendent  —  the  functions  in  dma.c  work 
for  any  hardware  configuration. 

If  the  variable  file_bandle  is  non¬ 
zero,  it  is  assumed  that  filejhandle  was 
assigned  to  a  file  via  a  C  open(  )  call. 
write_buf(  )  is  then  called  to  write  the 
just  filled  buffer  to  the  disk  file  that 
filejhandle  represents.  This  is  where 
the  DOS  critical  section  flag  comes  in 
handy.  If  the  interrupt  service  routine 
happened  to  interrupt  DOS  at  a  critical 
location,  the  disk  write  is  skipped  and 
the  buffer  is  lost.  This  will  never  occur 
if  the  background  program  does  not 
make  use  of  DOS  calls,  but  it  provides 
a  simple  semaphore  when  the  program 
must  (such  as  during  the  opening  and 
closing  of  files). 

Real-Time  Applications 

I  built  the  circuit  using  wire-wrap  com¬ 
ponents  on  a  PC  prototyping  board.  It 
requires  only  six  chips  in  all,  but  the 
FIFO,  are  standard  LS-series  parts.  I 
tested  it  using  a  simple  program  on  a 
12-MHz  Compaq  286  computer.  The 
system  was  able  to  acquire  a  continu¬ 
ous  stream  of  data  from  the  D/PAD  at 
rates  up  to  100K  bytes  per  second, 
write  all  the  data  to  disk,  and  output 
the  results  of  a  minimal  error  checking 
algorithm  to  the  screen  without  drop¬ 
ping  any  data.  Of  course,  at  the  highest 
rate,  the  available  disk  storage  of  30 
Mbytes  or  so  is  exhausted  in  about  five 
minutes! 

I  designed  a  more  complex  software 
package  to  receive  telemetry  from  a 
NASA  experiment  flown  on  a  sounding 
rocket  from  Woomera,  Australia  in 
March  1988.  With  similar  DMA  inter¬ 
face  hardware,  the  Compaq  acquired 
the  telemetry  at  25K  bytes  per  second, 
recorded  the  full  flight’s  worth  of  data 
on  disk,  and  displayed  a  continuously 
updating  graphical  image  of  the  astro¬ 
nomical  target.  The  investment  in  soft¬ 
ware  and  hardware  development  was 
very  small  for  a  mission  of  its  type,  and 
it  has  served  as  a  template  for  future 
ground  support  systems  design. 
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All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
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1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
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case)  at  the  log-in  prompt. 
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ZEN  for 

Embedded  Systems 

What  you  see  is  what  you  get,  with  this  powerful 
implementation  of  Forth 


Martin  Tracy 


ZEN  is  a  tiny  Forth  with  a  big 
purpose:  It  is  a  model  Forth 
designed  for  readability.  Have 
you  ever  noticed  that  there  are 
no  intermediate  Forth  program¬ 
mers?  You  are  either  a  rank  beginner 
or  a  black-belt  guru.  Why?  My  guess  is 
that  after  reading  Leo  Brodie’s  Starting 
Forth  (or  my  own  Mastering  Forth), 
you  are  told  that  the  next  step  to  learn¬ 
ing  Forth  is  to  read  the  source  code  to 
the  language  itself.  This  sounds  like  a 
good  idea;  unfortunately,  the  source 
code  of  a  professional  Forth  system  is 
likely  to  be  tightly  packed,  handcoded, 
over-optimized,  and  generally  incom¬ 
prehensible.  If  you  can  make  it  through 
all  of  that,  you  are  in  a  good  position 
to  write  a  book  of  your  own. 

What  you  need  is  a  Forth  that  is 
written  mostly  in  .  .  .  you  guessed  it! 
Dr.  Dobb ’s  Journal  has  a  long  tradition 
of  publishing  personal  implementations 
of  computer  languages,  from  Tiny  Ba¬ 
sic  (January  1976  issue)  to  Small  C  (May 
1980  issue).  So  to  continue  the  tradi¬ 
tion,  we  are  proud  to  present  ZEN,  the 
tiny  Forth. 

Programs  written  in  ZEN  can  be  quite 
small,  about  half  the  size  of  programs 
written  in  C.  In  these  days  of  megabyte 
memory,  is  small  size  important?  Yes. 
Small  size  often  means  high  speed.  On- 
chip  memory  generally  runs  at  least 
twice  the  speed  of  off-chip  memory.  A 


Martin  is  a  DDJ  contributing  editor 
and  a  consultant.  He  can  be  reached 
at  281 9  Pinkard  Ave.,  Redondo  Beach, 
CA  90278. 


68HC1 1  has  only  8K  of  internal  masked 
ROM.  The  most  popular  DSP  chip,  the 
TMS32010,  has  only  4K.  Even  if  the 
density  of  on-chip  memory  doubles 
each  year,  three  years  from  now  micro¬ 
processors  will  support  only  64K  of 
internal  ROM. 

In  recognition  of  the  importance  of 
small  programs  in  embedded  applica¬ 
tions,  ZEN  is  inherently  ROMable  and 
easily  fits  in  an  8K  PROM.  Not  only 
that,  but  ZEN  is  extensible  in  ROM. 
How  can  a  program  grow  in  ROM? 
Assume  that  ZEN  is  resident  in  a  single¬ 
board  computer  (SBC)  and  is  talking 
to  a  host  computer  over  an  RS-232  se¬ 
rial  line.  Put  a  RAM  chip  in  an  empty 


ROM  socket,  and  then  send  source  code 
to  ZEN  with  instructions  to  compile  it 
to  the  address  occupied  by  the  RAM. 
ZEN  will  write  the  program  there  but 
will  assume  that  all  references  to  RAM 
point  to  a  separate  address  space,  nor¬ 
mally  the  on-chip  RAM. 

Test  the  program  interactively  and, 
once  it  works,  tell  ZEN  to  read  the  RAM 
image  and  burn  it  into  a  PROM.  Finally, 
remove  the  RAM  chip,  plug  in  the 
PROM,  and  you’re  done.  The  idea  of 
running  the  development  system  in  the 
target  hardware  may  seem  novel;  what 
it  means  is  that  all  testing  and  debug¬ 
ging  take  place  in  the  target  system. 
The  host  computer  is  used  only  as  a 
terminal  and  disk  server.  The  chances 
of  a  working  program  not  working 
when  you  burn  the  final  PROM  are 
utterly  remote. 

ZEN  Internals 

Before  you  study  the  ZEN  implementa¬ 
tion  (see  Listing  One,  page  98),  you 
must  have  a  fairly  good  understanding 
of  Forth.  For  example,  you  should  know 
that  the  body  of  a  CODE  definition 
contains  machine  code.  You  may  wish 
to  treat  the  80  or  so  CODE  words  in  the 
ZEN  kernel  as  black  boxes,  but  be  sure 
you  know  what  they’re  supposed  to 
do.  Otherwise,  be  aware  that  Forth  as¬ 
semblers  differ  somewhat  from  classi¬ 
cal  assemblers.  In  most  Forth  assem¬ 
blers,  operands  precede  operators. 

AL  0  [BX]  MOV 

instead  of 


38 

32 


Dr.  Dobb’s Journal,  January  1990 


(continued  from  page  38) 

MOV  [BX],AL 

Furthermore,  the  ZEN  assembler  uses 
numeric  local  labels 

DX  AX  OR 
1  L#  JZ 
AX  PUSH 
1  L:  BX  PUSH 

instead  of  using 

OR  AX,DX 
JZ  away 
PUSH  AX 
away  PUSH  BX 

ZEN  1.7  for  the  80x86-based  IBM 
PC  is  a  direct-threaded  Forth.  The  SI 
register  points  to  the  next  address  to 
execute  in  a  list  of  compiled  addresses. 
The  NEXT  interpreter  transfers  control 
to  the  machine  code  at  that  address, 
simultaneously  adjusting  SI  to  point  to 
the  next  address. 

NEXT  WORD  LODS  AXJMP  ; 

The  overhead  of  interpreting  a  list 
of  ZEN  words  is  therefore  two  instruc¬ 
tions  per  word.  A  list  of  addresses, 


NIP  and  TUCK,  they  are  equivalent  to 
the  phrases  SWAP  DROP  and  SWAP 
OVER,  respectively.  NIP  is  especially 
handy  and  is  a  single  instruction  on  the 
Harris  RTX  2000  Forth  Processor.  It  only 
takes  a  single  instruction  (plus  NEXT) 
on  the  80x86  as  well. 

The  single-precision  arithmetic  op¬ 
erators  form  this  set: 

+  -‘/MOD /MOD*/ 

1+  1/  2*  2/ 

NEGATE  ABS  MAX  MIN 

1+  and  1-  increment  and  decrement, 
respectively.  2*  and  2/  shift  once  right 
and  left,  arithmetically.  Notice  that  2+ 
is  not  available.  Use  CELL+  instead  to 
move  to  the  next  cell  in  an  array.  Use 
CELLS  instead  of  2*  to  change  cells  into 
bytes,  as  in: 

1024  CELLS  ALLOT. 

Many  single-precision  operators  have 
double-number  equivalents. 

D+  D-  D2*  D2/ 

DNEGATE  DABS  DMAX  DMIN 

Multiplication  and  division  generally 
mix  precisions  to  avoid  calculations  with 
unnecessary  accuracy. 


however,  takes  far  less  memory  than  a 
series  of  jumps  or  calls.  In  a  sense, 
threaded  Forths  trade  speed  for  mem¬ 
ory.  In  other  words,  threaded  Forths 
compile  tokens,  but  the  token  of  a 
word  is  simply  the  address  of  that  word. 
Microsoft’s  Compiled  Basic  and  mod¬ 
ern  “cddr-coded”  LISPs  have  recently 
copied  this  method. 

Assume  that  SI  points  into  a  Forth 
definition  at  a  point  where  it  executes 
DUP.  That  means  that  SI  points  to  the 
compiled  address  of  machine  code  that 
duplicates  the  item  on  top  of  the  stack. 

CODE  DUP  BX  PUSH  NEXT  C; 

The  C;  command  is  an  abbreviation  of 
END-CODE.  This  implementation  of 
ZEN  keeps  the  top  stack  item  in  the 
BX  register.  DUP  executes  in  only  three 
instructions  —  one  for  PUSH  and  two 
more  for  NEXT.  This  optimization  ap¬ 
plies  to  many  other  machine-coded  primi¬ 
tives,  such  as  DROP  and  @. 

CODE  DROP  BX  POP  NEXT  C; 
CODE  @  0  [BX]  BX  MOV  NEXT  C; 

ZEN  is  a  small  model  (64K)  Forth.  All 
four  segment  registers  contain  the  same 
segment  address.  The  origins  and  sizes 


UM*  UM/MOD  7MOD  M*  M/MOD 
M+  S>D  D>S 

A  full  complement  of  logical  and  com¬ 
parison  operators  exists. 

AND  OR  XOR  NOT 
0<0=0>  <  =  >  U<  WITHIN 
D0=  D<  D=  TRUE  0  1 

WITHIN  is  especially  powerful  because 
it  compares  within  in  a  circular  number 
space.  It  can  be  used  to  control  the 
■duration  of  an  event  by  comparing  the 
current  value  of  a  self-incrementing 
counter  to  some  future  value.  All  other 
comparison  operators  can  be  based  on 
WITHIN. 

These  are  the  memory  access  primi¬ 
tives: 


@  !  C@  C!  2@  2!  D@  D! 
CMOVE  CMOVE>  MOVE  +! 


D@  and  D!  are  equivalent  to  2@  and  2! 
except  that  the  order  of  cell  storage  is 
not  specified.  MOVE  is  a  smart  CMOVE 
that  moves  without  overlapping  bytes. 
It  cannot  be  used  to  fill  memory  with 
a  character. 

Here  are  the  flow-of-control  opera¬ 
tors: 


of  the  separate  RAM  and  ROM  address 
spaces  are  specified  on  block  1 . 

ZEN  Word  Set 

The  ANSI  Forth  standardization  effort 
is  well  under  way.  The  current  docu¬ 
ment,  ANS  X3J14  BASIS  9,  is  available 
for  $6  from  the  X3J14  Secretariat  (c/o 
FORTH,  Inc.,  Ill  N.  Sepulveda  Blvd., 
Manhattan  Beach,  CA  90266).  The  BA¬ 
SIS  is  modified  at  each  meeting  until  it 
becomes  the  draft  proposal  that,  after 
a  period  of  public  review  and  revision, 
becomes  the  ANSI  Forth  Standard.  ZEN 
1.7  is  an  unofficial  implementation  of 
BASIS  7  and  provides  all  required  words. 
It  supports  the  double  number,  file  ac¬ 
cess,  and  BLOCK  extensions. 

The  stack  manipulation  words  found 
in  ZEN  are: 

DUP  DROP  SWAP  OVER 

ROT  ?DUP 

2DUP  2DROP  2SWAP  20VER  2ROT 
>R  R@  R>  2>R  2R> 

NIP  TUCK  PICK  ROLL 

ROLL  is  defined  in  high-level  because 
it  cannot  be  efficiently  mapped  into 
machine  code.  You  will  find  that  2>R 
and  2R>  obviate  almost  any  need  for 
ROLL.  In  case  you  are  not  familiar  with 


BEGIN  WHILE  REPEAT  UNTIL  AGAIN 
IF  ELSE  THEN  DO  LOOP  +LOOP 
IJ  LEAVE  UNDO  EXIT 
EXECUTE  @ EXECUTE 

UNDO  removes  one  level  of  DO  .  .  . 
LOOP  support  from  the  return  stack, 
allowing  EXIT  to  execute  within  the 
loop.  UNDO  EXIT  is  the  preferred 
method  for  leaving  a  word  from  inside 
a  loop.  @EXECUTE  is  exactly  equiva¬ 
lent  to  @  EXECUTE,  but  is  much  faster. 

These  are  the  number  conversion 
and  formatting  commands: 

BASE  DECIMAL  HEX 
CONVERT  VAL?  PAD 
<#  #  #S  SIGN  HOLD  #> 

.  U.  D.  D.  R 

Output  conversion  and  formatting  takes 
place  at  PAD  1-  and  downwards,  leav¬ 
ing  PAD  itself  free  for  applications.  VAL? 
converts  strings  to  numbers,  and  BASIS 
6  defines  numeric,  string,  and  charac¬ 
ter  literals. 

[ASCII]  ASCII  “ccc”  LITERAL 

ZEN  adds  DLITERAL,  the  double-num¬ 
ber  equivalent  of  LITERAL.  ASCII  and 
[ASCII]  make  the  following  character 
into  an  ASCII  literal  inside  and  outside 
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(continued  from  page  42) 
a  definition,  respectively.  The  string 
literal  operator  "  (quote)  works  only 
inside  a  definition  and  accepts  the  fol¬ 
lowing  string  of  characters,  up  to  the 
next ",  as  a  string  literal. 

COUNT  SKIP  SCAN  /STRING 
FILL  BLANK  ERASE  -TRAILING 
STRING  .’’EVALUATE 

SKIP  SCAN  and  /STRING  are  natural 
factors  of  WORD.  SKIP  and  SCAN 
closely  map  the  80x86  string  operator 
SCAS.  /STRING  is  a  generic  substring 
operator;  it  can  be  used  to  select  any 
part  of  a  string.  STRING  is  the  funda¬ 
mental  string  compiler  and  is  used  by 
the  “and  .”  commands. 

EVALUATE  is  the  most  powerful 
string  operator:  It  interprets  any  string. 
EVALUATE  is  used  for  forward  refer¬ 
encing,  macro  definition,  and  any  other 
instance  of  late  binding.  For  example, 
coldstart  uses  the  phrase  READY  EVALU¬ 
ATE  for  device  initialization.  Suppose 
you  add  a  device  that  requires  its  own 
initialization: 

:  READY  (  new  initialization)  READY; 

READY  is  redefined  to  include  the  new 
initialization.  READY  EVALUATE  exe¬ 
cutes  this  new  version,  which  in  turn 
executes  the  previous  version. 

The  interpreter  level  uses  these  words: 

BLK  >IN  TIB  #TIB  SPAN  STATE 
FORTH  CONTEXT  ’  FIND  WORD 
CR  TYPE  EXPECT  KEYS  KEY? 

KEY  EMIT  PAGE  MARK  TAB 
BL  SPACE  SPACES  .( (  DEPTH 

Most  Forths  have  words  such  as  KEY?, 
which  is  true  if  a  key  is  available;  PAGE, 
which  clears  a  screen  or  page;  MARK, 
which  TYPEs  in  emphasized  mode;  and 
TAB,  which  repositions  the  cursor  to  a 
given  X  Y  coordinate.  None  of  these 
words  have  been  standardized.  In  addi¬ 
tion,  ZEN  supports  KEYS,  which  ac¬ 
cepts  characters  without  echoing  or  ed¬ 
iting.  In  general,  if  the  input  stream  is 
coming  from  a  human  being,  use  EX¬ 
PECT;  otherwise,  use  KEYS. 

The  compiler  layer  adds  these  words: 

CURRENT  DEFINITIONS  [][’],  C, 
COMPILE  [COMPILE]  IMMEDIATE 
RECURSE 

RECURSE  allows  a  definition  to  refer¬ 
ence  itself.  Remember,  though,  that  the 
size  of  the  return  stack  is  likely  to  be 
limited.  The  following  . defining  words 
are  provided: 


ZEN 


CREATE  VARIABLE  CONSTANT  :  ; 

2VARIABLE  2CONSTANT 

VOCABULARY 

Two  other  defining  words  are  used 
to  build  ZEN:  USER  and  XFER.  USER 
creates  a  user  variable,  whose  address 
is  based  on  its  offset  from  the  address 
in  the  pseudoregister  u.  A  user  variable 
is  private  to  each  task  in  a  multitasking 
environment.  XFER  creates  a  transfer 
command,  whose  action  is  specified 
by  its  offset  in  an  execution  vector 
pointed  to  by  the  user  variable  x.  By 
changing  this  execution  vector,  input 
and  output  can  be  redirected  to  differ¬ 
ent  devices  or  files.  Because  xis  a  user 
variable,  each  device  can  be  controlled 
by  a  different  task,  so  a  background 
task  can  spool  text  to  the  printer  while 
a  foreground  task  paints  graphics  on  a 
screen. 

RAM  vs.  ROM 

The  RAM  and  ROM  address  spaces  in 
ZEN  are  kept  entirely  separate.  The 
dictionary,  machine  code,  and  tables 
are  built  in  ROM,  and  the  data  fields 
of  variables  and  arrays  are  built  in  RAM. 
Each  word  that  refers  explicitly  to  RAM 
has  an  equivalent  that  refers  instead  to 
ROM. 

RAM  ROM 


CREATE  VARIABLE 

C,  .ALLOT 

HERETHERE 

DOES>  GOES> 

>BODY  >DATA 

Let’s  say  you  want  to  make  a  table  of 
powers  of  ten: 

CREATE  TENS 
1  ,  10  ,  100 , 1000 , 10000  , 

The  TENS  table  will  be  built  in  ROM. 
Suppose  you  want  an  array  of  seven 
cells: 

VARIABLE  DAYS  6  CELLS  ALLOT 

The  DAYS  array  will  be  built  in  RAM. 
Notice  that  VARIABLE  allocates  the  first 
cell.  It  is  not  possible  to  initialize  DAYS 
because  anything  stored  in  RAM  disap¬ 
pears  when  the  power  is  turned  off. 
You  can  use  GAP  to  allocate  uninitial¬ 
ized  cells  in  ROM,  but  you  will  rarely 
need  to  do  so. 

DOES>  refers  to  the  body  of  a  de¬ 
fined  word  in  ROM. 

:  COLOR  \  set  CREG  to  the  value  n. 
CREATE  (  n)  ,  DOES>  @  CREG  !  ; 

8  COLOR  RED  12  COLOR  GREEN 


Executing  RED  will  store  8  into  CREG. 
DOES>DATA  to  the  data  field  of  a  de¬ 
fined  word  in  RAM. 

:  KOUNTER  \  self-incrementing  object. 
VARIABLE  DOES>  DATA  1  SWAP  +!  ; 

KOUNTER  ALPHA  KOUNTER  BETA 

Each  execution  of  ALPHA  will  incre¬ 
ment  its  value.  To  read  this  value,  you 
must  be  able  to  recover  the  data  field 
address. 

’  ALPHA  >DATA  ?  (  prints  value) 

Use  >BODY  to  recover  the  parameter 
field  address  of  an  object  in 

ROM:  '  RED  >BODY  ?  (  prints  8) 

Restart  and  Error  Handling 

The  restart  and  error-handling  mecha¬ 
nism,  designed  by  Wil  Baden,  was  pub¬ 
lished  in  FORML  1987.  The  Forth  com¬ 
mand-line  interpreter  is  QUIT;  it  is  the 
default  Forth  application. 

:  QUIT  RESET 

BEGIN  CR  QUERY  interpret  OK? 
AGAIN  ; 

When  Forth  begins  executing,  it  goes 
to  ABORT  and  from  there  to  QUIT.  The 
function  of  ABORT  will  be  performed 
by  every  error  recovery  sequence. 
ABORT  is  the  default  Forth  error  restart 
sequence. 

:  ABORT 

BEGIN  PRESET  QUIT  GRIPE  AGAIN; 

In  QUIT,  the  work  of  clearing  the 
data  stack  is  factored  into  RESET.  The 
data  stack,  however,  is  not  completely 
cleared;  one  item  is  left,  but  this  has 
no  impact  on  existing  programs.  In 
ABORT,  PRESET  clears  both  stacks  all 
the  way  to  the  bottom. 

You  now  have  a  way  to  customize 
the  error  recovery  sequence.  In  addi¬ 
tion,  ABORT  shows  the  pattern  for  dedi¬ 
cating  an  application:  The  default  ap¬ 
plication  is  QUIT,  and  the  default  error 
recovery  sequence  is  GRIPE.  GRIPE 
sounds  like  TYPE  and  takes  the  same 
parameters,  address,  and  length.  It  dis¬ 
plays  the  error  message  provided  by 
ABORT.  It  may  also  attempt  to  display 
the  name  of  the  word  being  interpreted. 

PRESET  leaves  both  stacks  empty. 
Invoking  the  next  word  will  put  the 
address  of  the  return  point  on  the  re¬ 
turn  stack.  RESET  leaves  that  address 
alone.  A  word  can  get  back  to  that 
location  by  RESET  EXIT.  On  the  return, 
the  parameters  for  an  error  message 
string  are  assumed. 
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(continued  from  page  44) 

The  default  application  and  default 
error  recovery  sequence  can  be 
changed,  and  ABORT"  will  still  work 
with  them. 

:  err  RESET ; 

:  ABORT"  [COMPILE]  IF  [COMPILE]" 

COMPILE  err  [COMPILE]  THEN  ; 

IMMEDIATE 

err  in  the  definition  of  ABORT"  cannot 
be  replaced  with  RESET,  but  you  can 
build  a  variable  error  message  string 
and  follow  it  with  RESET  EXIT  or  RE¬ 
SET  ;  to  emulate  ABORT". 

The  following  trivial  example  changes 
the  default  application  to  indent  three 
spaces  for  every  value  on  the  stack 
before  receiving  new  input.  This  pro¬ 
cess  is  preventative  debugging:  If  you 
are  surprised  by  the  indentation  then 
you  are  in  trouble.  Also,  the  example 
demonstrates  logical  structure  as  you 
compile  a  definition  from  the  keyboard. 

The  error  recovery  message  is 
changed  as  well. 

:  OLD-ABORT  ABORT  ; 

:  INDENT  DEPTH  STATE  @  -3  ‘SPACES; 


tion  in  the  file  to  and  from  a  buffer  in 
memory.  SEEK-FILE  and  FILEPOS 
change  the  position  of  a  file,  and  FILE- 
SIZE  returns  its  size.  READ-LINE  reads 
a  line  of  text,  and  WRITE-CR  writes  an 
end-of-line  terminator.  To  write  a  line 
of  text,  use  WRITE-FILE  followed  by 
WRITE-CR.  All  file  primitives  work  with 
a  file  identifier  returned  by  CREATE- 
FILE  or  OPEN-FILE,  so  multiple  files 
are  supported.  Error  codes,  if  any,  are 
returned  in  IO-RESULT. 

The  BLOCK  support  includes  these 
words: 

BLOCK  BUFFER  UPDATE 

SAVE-BUFFERS  FLUSH  LOAD 

Running  ZEN 

You  can  find  the  source  code  and  execut¬ 
able  image  of  ZEN  in  the  file 
ZEN190.ARC  on  CompuServe  in  the 
DDJ  Forum.  ZEN  is  also  available  on 
the  GENIE,  ECFB,  and  BIX  bulletin 
boards.  Execute  the  file  ZEN.COM  and 
press  <RETURN>.  You  should  see  the 
OK  message.  ZEN  has  a  small  set  of 
debugging  words  you  can  use  to  look 
around: 

WORDS  .S  ?  DUMP 


:  SHELL 

BEGIN  CR  INDENT 
QUERY  interpret  OK? 
AGAIN  ; 

:  ABORT 

BEGIN  PRESET  SHELL 
CR  ."  Abort: "  GRIPE 
AGAIN  ; 


ABORT  installs  a  new  application  and 
error  handler.  OLD-ABORT  reinstalls 
old  application  and  error  handler. 

With  PRESET  and  RESET  you  can 
establish  intricate  error  recovery  and 
restart  networks.  The  following  generic 
QUIT  can  be  used  to  restart  the  default 
application  in  most  implementations. 
The  idea  is  to  return  to  the  position  just 
before  you  invoke  your  dedefault  appli¬ 
cation. 

:  QUIT  RESET  R>  CELL  -  >R  ; 


Mass  Storage 

ZEN  supports  both  text  files  and  tradi¬ 
tional  Forth  BLOCKS.  The  text  file  sup¬ 
port  includes  these  words: 


CREATE-FILE 

FILE 

DELETE-FILE 

READ-FILE 

SEEK-FILE 

READ-LINE 

IO-RESULT 


OPEN-FILE  CLOSE- 

RENAME-FILE 
WRITE-FILE 
FILESIZE  FILEPOS 
WRITE-CR 


READ-FILE  and  WRITE-FILE  read  a  se¬ 
quence  of  bytes  from  the  current  posi¬ 


You  can  compile  and  test  definitions 
from  the  keyboard,  or  type  GO  to 
compile  the  text  file  KERNEL.SRC.  Use 
any  text  editor  to  edit  this  file.  I  use  the 
Sidekick  pop-up  editor. 

Use  GUARD  to  protect  all  words  in 
the  dictionary  from  FORGET.  EMPTY 
restores  the  dictionary  to  the  previous 
GUARDed  word  set. 

I  hope  you  enjoy  ZEN  and  find  it 
useful.  Please  send  all  comments  and 
criticisms  to  me. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listing  begins  on  page  98.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  3. 
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Error  Message 
Management 

Automating  error  message  documentation 

Rohan  T.  Douglas 


ne  of  the  more  overlooked 
problems  programmers  face 
during  the  software  develop¬ 
ment  life  cycle  is  error  mes¬ 
sage  management.  For  one 
thing,  a  list  of  error  messages  must 
usually  be  provided  in  the  user  man¬ 
ual,  along  with  detailed  descriptions. 
At  one  stage  or  another,  many  of  us 
may  have  resorted  to  a  combination  of 
grep  and  our  favorite  text  editor  to  pro¬ 
duce  such  a  list.  For  larger  projects, 
however,  this  approach  becomes  un¬ 
manageable. 

The  purpose  of  this  article  is  to  pre¬ 
sent  an  approach  which  is  simple  to 
implement  and  use.  It  offers  some  sig¬ 
nificant  advantages  over  more  tradi¬ 
tional  approaches  to  the  problem.  In 
particular,  this  approach  automates  the 
error  message  documentation  process, 
guaranteeing  consistency  between  the 
product  and  documentation,  and  adds 
the  ability  to  generate  error  messages 
in  one  of  several  written  languages.  For 
that  matter,  there’s  no  reason  this  scheme 
couldn’t  be  adapted  for  on-screen 
menus,  prompts,  and  dialog  boxes. 


Rohan  Douglas  is  an  associate  director 
of  Giltnet  Limited  and  has  been  an 
architect  of  a  number  of  real-time  ana¬ 
lytic  products  for  the  global fixed  inter¬ 
est  markets  including  the  product  Tac¬ 
tician.  Rohan  can  be  reached  at  G.P.O. 
Box  2424,  Sydney,  N.S.W.  2001,  Aus¬ 
tralia  or  by  FAX  (2J-262-535 7 (A  ustra- 
lia). 


An  Error  Message  Data  Base 

One  traditional  approach  to  the  prob¬ 
lem  of  error  message  management  is 
to  maintain  a  separate  data  base  of 
error  messages  which  are  referenced 
within  the  source  code  by  calling  some 
function  with  an  identifying  index.  This 
approach,  however,  presents  several 
problems. 

For  readability,  a  description  of  each 
error  must  also  be  included  in  the 
source.  The  problems  of  maintaining 
two  copies  of  the  same  information 
quickly  become  apparent.  Cross-check¬ 
ing  the  source  against  the  error  mes¬ 
sage  data  base  is  a  problem  to  be 
avoided. 

Maintaining  a  distinct  error  message 
data  base  is  also  fairly  cumbersome. 
In  the  worst  case,  having  come  across 
an  error  condition  while  editing  source 
code,  we  have  to  exit  the  source  editor 
to  call  up  our  error  message  data  base 
editor.  Other  issues  to  consider  involve 
multiple  write  access  to  this  error  mes¬ 
sage  data  base  not  necessary. 

The  Solution 

A  more  natural  approach  is  to  retain 
the  error  messages  within  the  source 
code.  This  avoids  the  problems  listed 
above,  but  how  do  we  generate  a  de¬ 
tailed  listing  of  error  messages  along 
with  descriptions?  The  solution  takes 
the  form  of  a  source  processor. 

The  source  processor  takes  a  com¬ 
pleted  source  program  and  scans  for 
error  messages.  By  embedding  a  full 


description  of  each  error  message  within 
the  source  code,  we  can  automatically 
generate  a  list  of  error  messages  along 
with  descriptions  suitable  for  inclusion 
in  a  user  manual. 

If  we  extend  this  concept  further, 
we  can  combine  the  facilities  of  the  C 
preprocessor  with  the  source  proces¬ 
sor,  allowing  us  to  automatically  gen¬ 
erate  an  external  data  base  of  error 
messages.  This  allows  not  only  conver¬ 
sion  to  foreign  languages  but  also  such 
final  touches  as  a  spell-check  for  the 
production  version  of  the  product. 

The  source  processor  approach  can 
encourage  more  readable  code  by  docu¬ 
menting  error  messages  thoroughly 
within  the  source  code,  automating  the 
generation  of  error  message  descrip¬ 
tions,  allowing  fine-tuning  of  the  error 
messages  for  the  production  version 
without  touching  the  source  code,  and 
allowing  multi-language  error  messages 
using  the  same  program  executable. 
Another  advantage  is  that  the  source 
processor  approach  does  not  impede 
the  flow  of  the  development  process. 
The  source  processor  need  only  be  run 
on  the  production  version  of  the  source. 

I  have  used  the  source  processor 
approach  on  a  number  of  real-time  fi¬ 
nancial  systems,  each  around  300,000 
lines  of  C,  and  it  has  proven  both  flex¬ 
ible  and  practical. 

Implementation 

The  implementation  essentially  consists 
(continued  on  page  51) 
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(continued  from  page  48) 
of  two  components.  The  first  is  a  macro, 
errorf ),  which  replaces  the  error  mes¬ 
sage  in  the  source  with  a  call  to  an 
error-handling  function  _error( ).  This 
error-handling  function  is  passed  the 
file  name  and  line  number  which  are 
used  to  look  up  an  error  data  base  file. 
The  definition  for  the  error  macro  is 
shown  in  Listing  One,  page  108,  and 
the  definition  of  the  error-handling  func¬ 
tion  is  shown  in  Listing  Two,  page  108. 

The  implementation  shown  is  fairly 
simple.  More  than  likely  you  will  want 
the  error-handling  function  to  pop  up 
some  window  rather  than  use  printfO. 
The  ability  to  pass  additional  informa¬ 
tion  to  the  error  function  may  also  be 
required.  These  are  fairly  straightfor¬ 
ward  extensions. 

The  second  component  of  the  error 
handling  system  is  the  source  proces- 


#include  <stdio.h> 

#include  "error.h" 

main(int  argc,  char  *argv[  ]) 

f 

if  (argc  ==  1 ) 

errorfMissing  parameters"); 

/*  No  parameters  have  been  passed 

*  to  this  test  program.  This  error  message 

*  will  be  displayed  as  an  example  if  no 

*  parameters  are  passed  to  this  test 

*  program. 

7 

exit(O); 

1 


Figure  1:  Sample  source  file  with  em¬ 
bedded  error  message  and  description 


Missing  parameters: 

No  parameters  have  been  passed 
to  this  test  program.  This  error  mes¬ 
sage  will  be  displayed  as  an  ex¬ 
ample  if  no  parameters  are  passed 
to  this  test  program. 


Figure  2:  The  user  manual  list 
resulting  from  Figure  1 


test:8  Missing  parameters 


Figure  3 The  message  data 
base  resulting  from  Figure  1 


Missing  parameters  [test:8] 


Figure  4:  The  results  of  the  sample 
program 


sor.  The  function  of  the  source  proces¬ 
sor  is  to  scan  through  the  source  and 
extract  error  messages  and  accompa¬ 
nying  descriptions.  The  file  and  line 
numbers  of  each  error  message  are 
noted  and  two  files  are  produced.  The 
first  is  a  listing  of  the  error  messages 
with  descriptions  suitable  for  inclusion 
in  a  user  manual.  The  second  is  a  data 
base  of  error  messages  indexed  by  their 
respective  file  and  line  numbers.  Fig¬ 
ure  1  shows  a  sample  source  file  with 
an  embedded  error  message  and  de¬ 
scription.  Figure  2  shows  the  resulting 
description  for  the  user  manual  while 
Figure  3  shows  the  message  data  base. 
Figure  4  shows  the  results  of  the  sam¬ 
ple  program. 

An  AWK  listing  of  the  source  proces¬ 
sor  is  shown  in  Listing  Three,  page 
108.  Some  assumptions  have  been  made 
about  the  format  of  the  embedded  er¬ 
ror  message  comments.  This  listing  is 
intended  as  a  starting  point  rather  than 
a  definitive  implementation. 

Conclusion 

An  error  message  source  processor  pro¬ 
vides  a  flexible  and  effective  mecha¬ 
nism  for  controlling  error  messages. 
Embedded  error  messages  along  with 
descriptions  are  extracted  from  the 
source  code  to  create  an  external  error 
message  data  base  for  a  production 
version  of  the  product  and  error  mes¬ 
sage  listing  suitable  for  inclusion  in  a 
user  manual.  The  benefits  of  retaining 
the  error  messages  within  the  source 
code  are  maintained  while  the  benefits 
of  an  external  error  message  data  base 
are  obtained  for  the  production  ver¬ 
sion  of  the  product. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  108.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  4. 
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Data  Encryption 


A  secure  encryption  method  need  not  be 
computationally  intensive 


Robert  B.  Stout 


Although  not  a  new  topic,  sur¬ 
prisingly  little  has  been  done 
to  secure  data  in  the  micro¬ 
computer  world.  The  problem 
is  that  most  encryption  systems 
were  developed  for  high-powered  main¬ 
frame  and  super  computers  that  can 
handle  the  computationally  intensive 
calculations  required  for  such  encryp¬ 
tion  schemes.  Most  small  computers, 
on  the  other  hand,  cannot  reasonably 
implement  algorithms  set  forth  by  agen¬ 
cies  such  as  the  U.S.  National  Bureau 
of  Standards. 

On  the  upside,  however,  most  small 
computer  users  don’t  need  the  heavy 
security  required  by  such  government 
agencies.  And  while  simple  encryption 
schemes  can  be  easily  broken,  there  is 
a  way  to  get  the  best  of  both  worlds. 
This  article  presents  a  new  algorithm 
to  ease  the  production  of  secure  data 
systems.  Although  written  in  ANSI  C, 
the  algorithm  as  presented  is  adaptable 
to  most  high-level  languages,  assem¬ 
bly,  and  even  hardware  implementa¬ 
tions.  Although  usable  “as-is,”  it  can 
also  be  used  as  a  building  block  for 
enhanced  security  applications. 


Bob  is  the  president  of  MicroFirm,  a 
company  specializing  in  utilities  for 
small  computers.  He  can  be  reached 
at  P.O.  Box  428,  Alief  TX  77411. 


A  Quick  Tour 

A  typical  data  encryption  system  con¬ 
sists  of  three  basic  elements:  The  unen¬ 
crypted  data,  referred  to  as  the  “plain¬ 
text;”  an  encryption  key;  and  an  en¬ 
cryption  method  (the  encryption  en¬ 
gine). 

The  output  of  the  encryption  process 
is  called  the  “ciphertext.”  Decryption 
uses  three  corresponding  elements,  ex¬ 
cept  that  the  input  is  the  ciphertext  and 
the  output  is  the  reconstructed  plaintext. 

“Cryptanalysis”  is  the  science  of  break¬ 
ing  ciphers  based  on  searching  for  spe¬ 
cific  patterns  in  the  ciphertext.  If  the 
plaintext  is  unknown,  the  patterns  rep¬ 
resent  a  best  guess  as  to  the  partial 
contents  of  the  plaintext.  Even  better 
is  a  known  plaintext  attack  where  a 


known  message  has  been  encrypted 
so  both  the  plaintext  and  the  ciphertext 
are  known. 

Most  common  small  computer  data 
encryption  schemes  are  based  on  either 
the  exclusive  ORing  of  a  given  text 
string  key  with  the  plaintext  (a  polyal- 
phabetic  substitution  cipher  as  shown 
in  Figure  1),  or  a  software  implementa¬ 
tion  of  the  Data  Encryption  Standard 
(DES)  as  published  by  the  U.S.  Na¬ 
tional  Bureau  of  Standards.  The  former 
is  not  particularly  secure,  while  the  DES 
is  computationally  intensive.  The  ex¬ 
clusive  OR  method  would  be  perfectly 
secure  if  the  key  were  longer  than  the 
plaintext  (called  a  “one-time”  key)  and 
if  the  key  were  perfectly  random. 

Despite  the  high-tech  appeal  of  DES 


^*  ********* **************** ************************* ********************************** 


/*  Simple  encrypt/decrypt  function  using  exclusive-ORing  7 

/*  NOTE:  This  is  included  for  demonstration  only!  Data  encrypted  7 

/*  with  this  code  will  be  subject  to  simple  cryptanalysis.  7 

jit**** ******************************************************************************* *  j 

char  *cryptext;  /*  The  encryption/decryption  key  7 

void  crypt(char  *buf) 

{ 


int  cryptjotr  =  0;  /*  Circular  pointer  to  elements  of  key  7 
*buf  A=  cryptext[crypt_ptr] ; 
if  (++crypt_ptr  >=  strlen(cryptext)) 
crypt_ptr  =  0; 

} 


Figure  1:  A  poly  alphabetic  substitution  cipher 
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(continued  from  page  52) 
and  public  key  encryption  systems, 
these  systems  were  developed  both  in 
response  to,  and  dependent  upon,  the 
general  availability  of  powerful  spe¬ 
cialized  hardware.  Keys  are  typically 
large  numbers  and  are  difficult  to  memo¬ 
rize.  DES  requires  16  iterations  of  nested 
substitution  and  permutation  ciphers. 
RSA  public  key  systems  involve  raising 
200  digit  numbers  to  200  digit  powers. 
Most  PC  users  simply  want  a  secure 
means  of  quickly  making  files  unread¬ 
able  by  unauthorized  personnel. 

The  S-CODER  Engine 

The  S-CODER  algorithm  is  the  core  of 
an  encryption  “engine”  (an  S-Box,  or 
substitution  cipher  module),  which  is 
a  variant  of  the  exclusive  OR  method. 
It  differs  primarily  in  that  it  “scrambles” 
the  key  on-the-fly  (characteristic  of  a 
stream  cipher)  to  approach  the  security 
level  of  using  a  one-time  random  key. 
The  complete  algorithm  is  implemented 
in  Figure  2. 

To  remain  secure  from  known  plain¬ 
text  attacks  and  minimize  the  impact 
of  poorly  selected  keys,  the  exclusive 
OR  product  is  sufficiently  complex  to 


thoroughly  hide  the  encryption  key, 
even  when  encrypting  strings  of  identi¬ 
cal  characters.  By  modifying  the  key 
according  to  known  rules,  the  key  ef¬ 
fectively  becomes  an  array  of  seed  val¬ 
ues  for  a  complex  random  number  gen¬ 
erator.  It  is  these  random  numbers, 
rather  than  the  key  text  itself,  which  are 
exclusive  ORed  with  the  plaintext. 

Key  distribution  is  a 
historical  problem  for 
any  encryption  scheme 


S-CODER  requires  that  three  global 
variables  are  set  up  by  the  calling  pro¬ 
gram.  The  encryption  key  goes  in 
cryptext,  an  index  into  the  key  goes 
into  crypt _f>tr ,  and  the  length  of  the 
key  is  set  in  crypt_length.  Although 
crypt __ptr  is  usually  set  to  point  to  the 
first  character  of  the  key,  this  may  be 
changed  in  more  secure  S-CODER  ap¬ 
plications.  The  only  reason  for  passing 
crypt_length  in  a  variable  is  to  avoid 


l**+*1,i 

r 

***************************************************************** *** 

S-CODER  — Encrypt/decrypt  data 

**7 

7 

r 

Copyright  1987  -  1989  by  Robert  B.  Stout  dba  MicroFirm 

7 

T 

Originally  written  by  Bob  Stout  with  modifications 

7 

r 

suggested  by  Mike  Smedley. 

7 

/* 

This  code  may  be  used  freely  in  any  program  for  any 

7 

/* 

application,  personal  or  commercial. 

7 

/* 

Current  commercial  availability: 

7 

/* 

1 .  MicroFirm  Toolkit  ver  3.00:  LYNX  and  CRYPT  utilities 

7 

/* 

2.  CXL  libraries  (MSC.TC,  ZTC/C++,  PC):fcrypt( ) 

7 

/* 

dedicated  file  encryption  function 

7 

r 

1 ****** 

3.  SMTC  &  MFLZ  libraries:  cryptf )  function 
******************************************************************** 

7 

.... 

char  'cryptext;  /*  The  actual  encryption/decryption  key  7 
int  crypt_ptr  =  0;  T  Circular  pointer  to  elements  of  key  7 
int  cryptjength;  /*  Set  externally  to  strlen(cryptext)  * 

T  NOTES:  cryptext  should  be  set  and  qualified  (to  something  over  5-6  chars,  minimum) 
by  the  calling  program,  which  should  also  set  cryptjctr  in  the  range  of  0  to 
strlen(cryptext)  before  each  use.  If  crypt( )  is  used  to  encrypt  several  buffers, 
cryptext  should  be  reloaded  and  crypt_ptr  reset  before  each  buffer  is  en¬ 
crypted.  The  encryption  is  both  reversible  — to  decrypt  data,  pass  it  back 
through  cryptf )  using  the  original  key  and  original  initial  value  of  crypt_ptr  — 
and  multiple  passes  are  commutative.  7 

/****  Encrypt/decrypt  buffer  datum  ******************************/ 
void  crypt(char  *buf) 

{ 

*buf  A=  cryptext[crypt_ptr]  A  (cryptext[0]  *  crypt_ptr); 
cryptext[crypt_ptr]  +=  ((crypt_ptr  <  (cryptjength  - 1 ))  ? 

cryptext[crypt_ptr  +  1] :  cryptext[0]); 
if  (!cryptext[cryptjctr]) 
cryptext[crypt_ptr]  +=  1 ; 
if  (++crypt_ptr  >=  cryptjength) 
crypt_ptr  =  0; 

} 


Figure  2:  The  S-CODER  algorithm 
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( continued  from  page  54) 
repetitively  calling  the  strlen( )  library 
function.  An  important  point  to  note  is 
that  because  the  key  is  scrambled  dur¬ 
ing  encryption,  to  encrypt  multiple  texts 
using  the  same  key  requires  the  unal¬ 
tered  key  to  be  reloaded  into  cryptext 
before  each  use,  and  that  crypt Jotr  be 
preset  to  its  initial  value. 

In  examining  the  S-CODER  code, 
note  that  both  the  plaintext  and  the  key 
are  masked  by  including  the  exclusive 
OR  of  the  product  of  crypt _jrtr(c hanges 
each  character)  with  the  first  character 
of  the  key  (changes  each  pass).  Be- 

Despite  the  high-tech 
appeal  ofDES  and 
public-key  encryption 
systems,  these  systems 
were  developed  both  in 
response  to,  and 
dependent  upon,  the 
general  availability  of 
powerful  specialized 
hardware 


cause  the  length  of  the  key  is  unknown 
and  the  product  is  implicitly  modulo 
256,  this  simple  scheme  renders  crypt¬ 
analysis  extremely  difficult  by  search¬ 
ing  for  key-length  cycles.  This  is  espe¬ 
cially  true  if  we  further  assume  that 
crypt _ptr  may  be  preset  to  some  ran¬ 
dom  starting  point  within  the  key. 

As  each  character  of  the  key  is  used, 
it  is  modified  by  summing  it  with  the 
character,  which  is  logically  to  its  right, 
thus  treating  the  key  data  as  a  circular 
buffer.  Again,  this  is  implicitly  a  modulo 
256  operation.  Because  the  unique  char¬ 
acter  zero  or  NULL  is  reserved  in  C  to 
denote  the  end  of  a  string,  zeros  are 
converted  to  ones  to  preserve  the  key 
string  length  and  to  save  the  degenera¬ 
tive  effects  of  zero  propagation  through 
the  mathematical  operations  on  the  key. 

S-CODER  Applications 

Listing  One  (page  110)  implements  a 
simple,  single  file  encryption  utility  us¬ 
ing  the  S-CODER  algorithm.  For  sim¬ 
plicity,  crypt _ptr  is  initialized  to  zero, 
and  no  key  qualification  or  validation 


is  performed.  Even  this  simple  applica¬ 
tion  has  proven  resistant  to  unknown 
plaintext  attacks. 

Listing  Two  (page  110)  demonstrates 
the  use  of  the  S-CODER  algorithm  as  a 
stream  ( stdin  to  stdout)  encryptor.  It 
includes  a  call  to  a  setraw( )  function, 
which  will  be  different  for  different 
compilers.  This  is  necessary  to  force 
the  stdin  and  stdout  streams  into  “raw” 
or  binary  mode  for  the  duration  of  the 
program’s  execution.  Listing  Three 
(page  110)  demonstrates  a  simple  set- 
raw( )  function  for  the  Zortech  C  and 
C++  compilers.  Microsoft  and  Turbo  C 
users  may  use  the  setraw( )  function 
in  their  compilers. 

Listing  Four  (page  110)  demonstrates 
a  more  secure  implementation  and  in¬ 
troduces  a  cryptqual( )  function  to  as¬ 
sure  that  the  encryption  key  contains 
at  least  six  distinct  characters.  The  S- 
CODER  engine  is  embedded  in  an  en¬ 
cryption  algorithm,  where  data  are  read 
into  and  out  of  a  16K  data  buffer  as 
linear  arrays  but  encrypted  as  two- 
dimensional  128  x  128  columnar  char¬ 
acter  arrays  with  random  padding  of 
the  final  buffer  (a  modified  16K  block 
transposition  cipher). 

Also  note  that  crypt _ptr  is  preset  to 
a  computed  value  rather  than  the  de¬ 
fault  of  zero.  This  computed  value  in¬ 
cludes  the  length  of  the  encrypted  file, 
which  is  written  along  with  the  ci¬ 
phertext.  Although  the  S-CODER  algo¬ 
rithm  effectively  masks  the  key  length, 
these  techniques  serve  to  eliminate  re¬ 
sidual  weaknesses  when  faced  with  a 
known  plaintext  attack.  Using  the  ba¬ 
sic  S-CODER  engine  as  a  building  block, 
this  example  suggests  some  ways  to 
build  more  secure  specific  applications. 

Listing  Five  (page  111)  shows  a  sim¬ 
ple  test  program  to  calculate  statistics 
on  test  files.  The  coefficient  of  vari¬ 
ation  of  these  examples  asymptotically 
approaches  zero  as  the  size  of  the  file 
increases.  For  100K  test  files,  it  has  typi¬ 
cally  been  down  around  five  percent. 

Summary 

There  are  several  important  issues  that 
S-CODER  doesn’t  address.  Key  distri¬ 
bution  is  a  historical  problem  for  any 
encryption  scheme.  Public  key  encryp¬ 
tion  and  key-sharing  schemes  address 
this  issue,  but  at  the  expense  of  hard 
to  memorize  keys,  authentication  prob¬ 
lems,  and  computational  complexity. 
S-CODER’s  operation  is  symmetrical  and 
also  commutative  when  used  with  mul¬ 
tiple  keys.  For  example,  if  data  are 
doubly  encrypted  with  separate  keys, 
the  resulting  ciphertext  may  be  de¬ 
crypted  by  passing  it  through  an  S- 
CODER  engine  using  the  original  keys 
in  any  order.  This  suggests  the  use  of 
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(continued  from  page  56) 
a  hierarchical  key  distribution  scheme. 

No  data  encryption  system  is  un¬ 
breakable.  But  it’s  important  to  remem¬ 
ber  that,  for  hundreds  of  years,  there 
have  existed  relatively  simple  ciphers, 
which  couldn’t  routinely  be  broken  be¬ 
fore  the  invention  of  supercomputers. 
If  your  adversaries  can’t  afford  any¬ 
thing  more  powerful  than  a  80386- 
based  PC,  your  data  would  probably 
be  safe  with  any  of  these  methods. 
Also,  in  the  world  of  industrial  espio¬ 
nage,  it’s  usually  cheaper  for  an  adver¬ 
sary  to  buy  your  employees  than  the 
computing  power  to  crack  your  data 
when  encrypted  with  tools  such  as  S- 
CODER. 

The  real  purpose  of  encryption  is  to 
make  cryptanalysis  prohibitively  expen¬ 
sive,  either  in  terms  of  cost  or  time.  A 
further  fact  of  life  is  that  any  encryption 
process  that  runs  acceptably  fast  on  a 
small  computer  is  vulnerable  to  crypt¬ 
analysis  on  much  larger  and  faster  ma¬ 
chines.  The  S-CODER  algorithm  is  an 
effective  compromise  —  easy  to  use, 
reasonably  fast  on  small  machines,  yet 
offering  effective  levels  of  data  security. 

Notes 

Computer  Networks  by  Andrew  S.  Tan- 
nenbaum,  ISBN  0-13-162959-X,  Pren¬ 
tice  Hall. 

An  Introduction  to  Cryptology  by 
Henk  C.A.  van  Tilborg,  ISBN  0-89838- 
271-8,  Kluwer  Academic  Publishers. 

Security  in  Computing  by  Charles 
P.  Pfleeger,  ISBN  0-13-798943-1,  Pren¬ 
tice  Hall. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  110.) 


Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  6. 
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Parametric 

Circles 


Faster  circle  drawing  algorithms  can  produce  time  savings 
that  are  an  order  of  magnitude  faster 


As  graphical  PCs  become  increas¬ 
ingly  popular,  end-users  con¬ 
tinue  to  demand  faster  response 
rates  until  their  problem  can 
be  modeled  interactively  in  real 
time.  The  obvious  solution  to  the  prob¬ 
lem  of  minimizing  calculation  and  re¬ 
generation  time  is  faster  hardware,  but 
this  is  the  brute  force  solution.  Let's 
instead  look  at  producing  better  soft¬ 
ware  through  clever  algorithms.  This 
solution  can  produce  time  savings  that 
are  an  order  of  magnitude  faster.  This 
article  describes  an  algorithm  for  effi¬ 
cient  circle  generation  and  shows  how 
this  is  achievable  through  a  modest 
amount  of  mental  gymnastics. 

In  computer  graphics,  circle  (and  el¬ 
lipse)  generation  is  an  operation  as 
fundamental  as  line  drawing  and  point 
plotting.  The  obvious  approach  to  gen¬ 
erating  the  (Xk,Yk)  pairs  needed  to  de¬ 
scribe  the  circumference  of  the  circle 
is  shown  in  the  equation  in  Figure  1. 
However,  this  implicit  nonparametric 
representation  of  the  circle  has  three 
problems. 

First,  a  circle  has  multiple  Y  values 
for  a  given  X  value.  This  necessitates 
solving  the  equation  in  Figure  1  for  Yk 
to  produce  the  equation  in  Figure  2. 
Because  the  goal  is  to  produce  a  fast 
algorithm,  it  is  best  to  avoid  the  extrac¬ 
tion  of  the  roots.  The  second  problem 
deals  primarily  with  the  aesthetics  of 
the  curve.  When  the  Xks  are  evenly 
spaced,  the  results  are  poor  due  to  the 
uneven  distribution  of  points  along  the 
length  of  the  curve  in  Figure  3- 


Robert  is  a  senior  software  engineer  for 
International  Laser  Machines  and  can 
be  reached  at  4645  Orlando  Ct.,  Indi¬ 
anapolis,  IN  46208. 


Robert  Zigon 

Finally,  implicit  nonparametric  curves 
are  axis-dependent.  The  implication 
here  is  that  the  choice  of  coordinate 
systems  can  affect  the  ease  of  calcula¬ 
tion.  This  becomes  especially  apparent 
when  the  end  point  of  a  curve  has  a 
vertical  slope  relative  to  the  chosen 
coordinate  system.  These  problems  are 
why  we  will  switch  to  parametric  rep¬ 
resentations. 

The  parametric  form  of  each  point 
on  the  circumference  of  the  circle  can 
be  represented  as  two  functions  of  one 
variable.  There  are  many  possible 
choices  for  the  functions  and  parame¬ 
ters.  The  equation  representing  Figure 
3  can  be  converted  to  its  normalized 
parametric  equivalent  according  to  the 
equation  in  Figure  4.  However,  as  pre¬ 
viously  mentioned,  Figure  3  was  an 
example  of  a  computationally  ineffi¬ 
cient  and  aesthetically  displeasing  por¬ 
tion  of  a  circle.  This  leads  us  to  search 
for  a  different  parameter.  As  such,  we 
will  look  to  polar  representations  with 


X2^  =  R2 


Figure  1:  Equation  to  generate  pairs 
that  describe  a  circle 


Yk=V  R2-X2 


Figure  2:  To  solve  the  equation  in 
Figure  1,  it's  necessary  to  extract 
the  roots 


the  parameter  0.  Figure  5  describes  our 
new  parametric  form  of  a  circle. 

At  first  glance,  Figure  5  might  not 
seem  like  much  of  an  improvement 
over  the  equation  in  Figures  2  or  4.  The 
evaluation  of  the  sine  and  cosine  func¬ 
tions  can  be  just  as  costly  from  a  com¬ 
putational  standpoint  as  the  extraction 
of  the  square  root.  We  could  precom¬ 
pute  a  table  of  sine  values,  but  this 
would  limit  us  to  a  fixed  number  of 
points.  The  way  to  calculate  the  (Xk,Yk) 
pairs  is  by  rearranging  the  equation  in 
Figure  5.  Observe  that  0ks  used  in  Fig¬ 
ure  5  can  be  generated  from  the  previ¬ 
ous  value  via  the  relation  0k+1  =  0k  + 


Dotted  radial  lines  emphasize  unequal 


Figure  3 ■’  A  portion  of  a  circle 


Figure  4:  The  normalized  parametric 
equivalent  of  the  circle  in  Figure  3 
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A0.  If  we  take  the  cosine  of  both  sides 
of  the  previous  equation,  we  have 
cos(0k+1)  =  cos(0k  +  A0).  The  right  side 
of  this  equation  can  be  expanded  by 
using  the  trigonometric  identity  for  the 
cosine  of  an  angle  0  and  some  A0.  The 
identity  is  shown  in  Figure  6. 

If  you  now  multiply  by  R,  the  radius 
of  the  circle,  you  will  essentially  have 
the  equation  in  Figure  5.  However,  be¬ 
cause  the  right  side  has  been  expanded, 
according  to  the  equation  in  Figure  6, 
what  you  will  actually  be  left  with  is 
the  equation  in  Figure  7.  The  signifi¬ 
cance  of  this  expansion  can  be  found 
in  the  third  line  of  the  equation  for 
both  Xk+1  and  Yk+r  The  use  of  the  trig 
identity  shows  that  Xk+1  is  partially  de¬ 
scribed  in  terms  of  Xk  and  Yk,  leaving 
us  with  a  recurrence  relation.  Notice 
that  the  Xk  and  Yk  values  are  multiplied 
by  the  sine  and  cosine  of  A0,  a  numeric 
constant!  The  implication  of  these  alge¬ 
braic  gyrations  is  that  the  calculation  of 
the  equation  in  Figure  7  is  simply  the  sum 
of  the  product  of  two  sets  of  numbers. 

Please  note  that  Figure  7  will  gener¬ 
ate  the  points  on  the  circumference  of 
a  circle  centered  at  the  origin.  In  gen¬ 
eral,  if  the  circle  is  centered  at  the  point 
(a,b),  then  the  equation  in  Figure  8  will 
be  of  greater  interest. 


Xk  =  Rcos(0k)  e  2sk  k  =  0...N-1 
Yk  =  Rsin(6k)  N 


Figure  5:  Polar  representation  of  a 
parametric  form 


cos(9+A0)  =  cos0  cosA0  -  sin0  sinA0 
sin(0+A0)  =  cos0  sinA0  +  sin0  cosA0 


Figure  6:  The  trigonometric  identity 
for  the  cosine  of  an  angle  0  and 
some  A0 


Xk+i  =  Rcos(0k+A0) 

=  Rcos0k  cosA0  -  Rsin0k  sinA0 
=  Xk  COSA0  -  Yk  sinA0 
Yk+i  =  Rsin(0k+A0) 

=  Rcos0k  sinA0  +  Rsin0k  cosA0 
=  Xk  sinAO  +  Yk  cosA0 


Figure  7:  This  equation  will  generate 

the  points  on  the  circumference 

of  a  circle  when  centered  on  the  origin 


Xk+i=  a  +  (Xk-a)cos0A  -  (Yk-b)sinA0 
Yk+i=  b  +  (Xk-a)sin  A0+ (Yk-b)cosA0 


Figure  8:  This  equation  will  generate  the  points  on  the  circumference  of  a 
circle  when  the  circle  is  centered  on  point  (a,  b) 


My  answer  to  the  problem  of  circle 
generation  begins  with  the  obvious 
mathematical  solution.  From  there,  crea¬ 
tive  exploration  of  the  solution  space 
starts  with  trigonometric  representations 
that  are  not  well-suited  for  computers. 
However,  the  application  of  an  identity 
leaves  us  with  a  solution  using  opera¬ 


tions  that  are  an  intrinsic  part  of  any 
computational  unit.  I’ve  taken  this  as 
far  as  I  can  go  and  look  forward  to 
your  improvements. 

DDJ 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  14. 
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Examining  Zortech 

C++  2.0 

Putting  C++  to  the  challenge  of 
fractal  geometry . .  .and  more! 


Scott  Robert  Ladd 


In  mid-1988,  Zortech  released  its 
native  code  C++  compiler  for  the 
IBM  PC  and  compatibles.  Zortech 
C++,  Version  1.0,  was  based  on 
the  prevailing  standard  of  the 
time  —  AT&T’s  C++  1.x.  As  a  bonus, 
Zortech  C++  was  one  of  the  first  true 
source-to-object  code  C++  compilers 
in  existence.  This  first  version  was  a 
very  good  package,  and  it  boosted  the 
use  of  C++  on  MS-DOS  computers.  It 
was  with  this  compiler  that  I  began 
seriously  studying  and  using  C++. 

Recently,  Zortech  released  Version 
2.0  of  its  C++  compiler.  It  was  a  gigan¬ 
tic  step  forward,  being  the  first  im¬ 
plementation  of  the  AT&T  2.0  version 
of  C++  for  MS-DOS.  At  the  same  time, 
Zortech  released  the  first  source-level 
debugger  for  an  MS-DOS  C++,  improved 
the  programming  tools,  and  enhanced 
the  documentation  significantly. 

I’ve  been  using  this  compiler  in  my 
work  (book  and  article  writing)  as  well 
as  my  research  into  fractal  geometry 
and  chaos  theory.  This  article  discusses 
how  the  product  has  performed  in  my 
C++  projects.  Along  the  way,  I’ll  cover 
the  workings  of  the  compiler  and  its 
tools,  and  the  way  in  which  it  imple¬ 
ments  the  C++  language. 


Scott  is  a  free-lance  writer  and  soft¬ 
ware  developer;  he  has  over  15  years 
experience  in  a  variety  of  program¬ 
ming  languages.  Scott  can  be  reached 
either  at  705  W.  Virginia,  Gunnison, 
CO  81230,  or  via  MCI  Mail  369-4376. 
Scott  also  operates  a  BBS  devoted  to 
computer  programming,  outdoor  ac¬ 
tivities,  and  science,  at  303-641-5125. 


Fractal  Geometry 

Chaos  science,  of  which  fractal  geome¬ 
try  is  a  part,  combines  mathematics 
and  physics  to  describe  systems  which 
are  not  understandable  by  traditional 
methods.  Fractal  geometry  differs  from 
regular,  or  Euclidian,  geometry  in  many 
ways.  Euclidian  shapes,  such  as  squares 
and  spheres,  can  be  generated  and  mea¬ 
sured  using  simple  formulas.  Fractal 
shapes,  however,  are  created  from  iter¬ 
ated  (and  often  recursive)  algorithms. 
This  is  why  computers  are  an  integral 
part  of  fractal  geometry  research.  In 
fact,  most  fractal  shapes  were  not  dis¬ 
covered  until  computers  became  avail¬ 
able  for  mathematical  research. 

One  of  my  C++  projects  involved  writ¬ 
ing  a  program  to  display  a  set  of  frac¬ 
tals  similar  to  the  Mandelbrot  set.  Using 
a  variation  of  the  same  recursive  algo¬ 
rithm,  it  is  possible  to  find  shapes  in 
the  complex  plane  that  closely  resemble 
single-celled  life  forms.  These  so-called 
“biomorphs”  can  be  used  to  show  the 
dynamics  of  complex  numbers  as  well 
as  the  application  of  fractal  images  to 
modeling  microscopic  creatures. 

In  order  to  develop  a  C++  program 
for  generating  pictures  of  fractal  bio¬ 
morphs,  I  needed  to  have  a  complex 
number  library.  Usually,  programs  of 
this  type  are  written  in  Fortran,  which 
directly  supports  complex  numbers.  For¬ 
tran,  in  fact,  is  very  efficient  in  handling 
complex  number  arithmetic.  Is  it  possi¬ 
ble  to  create  an  efficient  complex  num¬ 
ber  class  with  Zortech  C++  2.0? 

The  result  is  shown  in  Listings  One 
and  Two.  Listing  One  (COMPLEX.HPP, 
page  112)  shows  the  header  files  for 


the  class  Complex,  and  Listing  Two 
(COMPLEX. CPP,  page  114)  is  the  im¬ 
plementation  of  the  non  inline  meth¬ 
ods.  To  make  the  class  efficient,  all  meth¬ 
ods  are  defined  as  inline  in  Listing  One, 
except  those  methods  that  do  division, 
power  calculations,  and  stream  I/O. 
The  latter  are  defined  in  Listing  Two. 

Inline  methods  make  complex  ob¬ 
ject  calculations  quicker  than  if  those 
methods  were  actual  functions.  How¬ 
ever,  my  preliminary  results  showed 
that  the  objects  were  still  50  percent 
slower  than  the  equivalent  Fortran  pro¬ 
gram.  The  standard  compile  options 
make  floating-point  calculations  use  a 
combined  coprocessor/emulator  library, 
which,  according  to  my  tests,  is  10  to 
20  percent  slower  than  equivalent  float¬ 
ing-point  libraries  provided  with  Mi¬ 
crosoft’s  and  Borland’s  C  compilers. 

I  solved  that  problem  by  using  the 
^option  when  compiling  with  Zortech 
C++;  that  option  tells  the  compiler  to 
generate  inline  numeric  coprocessor 
instructions.  This  is  both  faster  and 
smaller  than  the  standard  method  of 
making  calls  to  floating-point  emulator 
routines  (which  do  use  the  coproces¬ 
sor,  if  present).  The  disadvantage  is 
that  a  program  compiled  with  ^/will 
run  only  on  a  computer  that  contains 
or  emulates  a  math  coprocessor. 

This  is  a  good  place  to  point  out  that 
Zortech  C++  is  a  globally-optimizing 
compiler.  A  section  in  the  reference 
manual  describes  how  the  optional- 
optimizer  pass  works.  The  compiler 
has  three  passes.  The  first  pass  gener¬ 
ates  intermediate  code,  and  the  third 
pass  converts  intermediate  code  to  na- 
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(continued  from  page  64) 
tive-code  form.  The  optimizer  is  an  op¬ 
tional  second  pass,  which  optimizes 
the  intermediate  code.  This  approach 
is  terrific.  During  development,  you  can 
leave  out  the  optimizer  pass  to  get  fast 
compile  times.  Then,  on  your  final  com¬ 
pile,  you  run  the  optimizer  to  generate 
fast,  tight  code.  My  experiments  have 
shown  that  Zortech  C++  2.0  is  competi¬ 
tive  with  other  optimizing  compilers 
such  as  Microsoft  and  Watcom. 

Integrated  Environment 

Zortech  C++  2.0  comes  with  a  set  of 
integrated  tools.  You  can  edit,  com¬ 
pile,  and  debug  your  programs  in  a 
single  environment  by  using  the  Zortech 

This  debugger  has  an 
amazing  number  of 
features,  including  the 
ability  to  provide  a 
profile  of  program 
execution 


Editor  (ZED)  to  control  both  the  com¬ 
piler  and  debugger.  While  this  system 
is  not  as  smooth  or  quick  as  the  envi¬ 
ronment  provided  by  other  compilers, 
it  offers  the  advantage  of  more  power¬ 
ful  tools.  In  a  completely  integrated 
environment,  such  as  those  that  come 
with  Microsoft  QuickC  and  Borland 
Turbo  C,  all  of  the  environment’s  appli¬ 
cations  are  built  into  one  executable 
file.  Thus,  you  have  an  editor,  debug¬ 
ger,  and  compiler  all  in  one  large  .EXE 
file.  This  uses  a  lot  of  memory  and  puts 
restrictions  on  the  power  of  the  indi¬ 
vidual  applications.  Many  professional 
programmers  disdain  integrated  envi¬ 
ronments  because  of  the  large  memory 
requirements  and  limited  capabilities 
of  the  built-in  tools. 

Zortech’s  approach  exchanges  some 
speed  and  flashiness  in  order  to  integrate 
full-featured  applications  development 
tools.  The  ZED  is  much  improved  over 
its  predecessor,  and  supports  multiple 
file  buffers,  simple  macros,  and  numer¬ 
ous  other  features  expected  of  an  editor 
by  professional  programmers.  Instead  of 
building  a  compiler  into  the  editor,  ZED 
simply  calls  the  command-line  com¬ 
piler  and  traps  the  error  messages.  This 
isn’t  as  fast  or  slick  as  a  Turbo  Pascal, 
but  it  does  provide  you  with  the  power 


of  a  real  programmer’s  editor  at  a  mini¬ 
mal  cost. 

Debugging 

The  Zortech  debugger  (ZDB)  is  also 
much  improved  over  the  previous  ver¬ 
sion.  The  interface  is  easier  to  use,  the 
mouse  support  works  better  than  you 
would  expect,  and  C++  is  fully  sup¬ 
ported.  In  fact,  this  is  the  first  source- 
level  C++  debugger  for  MS-DOS.  It  man¬ 
ages  to  handle  the  infamous  C++  “name 
mangling”  (a  process  whereby  C++  in¬ 
ternally  changes  the  names  of  func¬ 
tions  and  objects  to  differentiate  among 
overloaded  names).  ZDB  allows  you 
to  examine  and  manipulate  identifiers, 
using  the  same  names  you  used  in 
your  program. 

ZDB  is  a  capable  debugger;  it  uses 
a  set  of  overlapping  windows  to  show 
everything  from  source  code  to  regis¬ 
ters  to  local  and  global  variables  and 
constants.  One  item  I  didn’t  like  about 
the  debugger  was  its  tendency  to  “for¬ 
get”  things.  If  I  set  up  the  local’s  win¬ 
dow  to  expand  certain  variables,  those 
expansions  would  be  forgotten  by  ZDB 
if  I  stepped  into  a  function  call  and  back. 

Another  debugger  problem  occurred 
when  I  was  debugging  the  Complex 
class.  Because  inline  methods  actually 
do  not  exist  as  functions,  there  is  no 
way  to  trace  them  in  the  debugger. 
That’s  fine  and  logical.  To  get  around 
this  problem,  Zortech  provided  a  com¬ 
piler  switch  (-c),  which  explicitly  turns 
all  inline  methods  into  actual  functions. 
This  would  allow  the  debugging  of 
these  methods.  Alas,  while  the  com¬ 
piler  correctly  generates  the  inline  meth¬ 
ods  as  functions,  it  fails  to  create  de¬ 
bugging  information  for  those  func¬ 
tions.  Thus,  while  the  functions  exist, 
the  debugger  had  no  information  to 
trace  into  them.  This  is  a  minor  bug  in 
the  compiler,  not  the  debugger. 

This  debugger  has  an  amazing  num¬ 
ber  of  features,  including  the  ability  to 
provide  a  profile  of  program  execu¬ 
tion.  During  months  of  use  both  the 
beta  and  release  versions  of  the  debug¬ 
ger  were  able  to  handle  everything  not 
mentioned  before.  An  additional  bo¬ 
nus  is  that  ZDB  is  CodeView  compat¬ 
ible,  and  it  can  debug  C  and  assembly 
language  programs  alongside  C++. 

Is  It  "Real"  C++? 

When  building  the  Complex  class,  I 
realized  the  need  to  have  input  and 
output  routines  for  Complex  objects. 
The  obvious  approach  (and  the  one  I 
used)  is  to  create  functions  that  use  the 
«  and  »  operators  and  the  streams 
class.  Zortech  supports  an  enhanced 
version  of  the  original  streams  classes 
as  defined  in  Stroustrup’s  book,  The 
(continued  on  page  69) 
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(continued  from  page  66) 

C++  Programming  Language.  AT&T 
has  since  enhanced  this  library  itself, 
but  Zortech  does  not  yet  support  the 
new  AT&T  additions  (called  “io- 
streams”),  saying  that  AT&T  has  not 
made  a  complete  specification  avail¬ 
able. 

The  Biomorph  program  shown  in 
Listing  Three,  page  119,  required  a  graph¬ 
ics  module.  Rather  than  use  the  Flash 
Graphics  library  included  with  Zortech 
C++,  I  linked  in  the  low-level  routines 
from  my  own  C  and  C++  graphics  li¬ 
brary.  Because  of  space  considerations, 
the  graphics  library  source  code 
( zg_lwlvl.h  and  zgjtwlvl.c)  is  not  in¬ 
cluded  with  this  article.  However,  the 
code  is  available  through  the  DDJ  Fo¬ 
rum  of  CompuServe,  through  the  DDJ 
Listing  Service,  through  my  BBS,  or 
directly  from  DDJ  (see  information  at 
the  end  of  this  article). 

To  link  these  C-language  functions 
with  a  C++  program  required  the  use 
of  type-safe  linkage,  one  of  the  more 
important  additions  AT&T  made  to  C++ 
2.0.  Type-safe  linkage  allows  object  mod¬ 
ules  from  other  languages  to  be  linked 
with  C++  safely.  By  declaring  the  native 
language  of  a  module,  the  C++  linker 
knows  how  names  are  to  be  resolved. 
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This  lets  C++  do  whatever  it  wants  with 
the  names  in  C++  modules,  while  al¬ 
lowing  other  languages  to  do  their  own 
thing.  In  addition  to  the  C  and  C++ 
types  of  linkage,  Zortech  C++  supports 
Pascal-style  linkage.  This  is  a  big  plus 
for  those  people  writing  C++  programs 
for  OS/2  and  Microsoft  Windows. 

Did  I  say  Windows?  Yes,  indeed, 
Zortech  C++  supports  Microsoft  Win¬ 
dows  programming.  Zortech  does  not 
provide  a  library  of  classes  or  interface 
routines  related  to  Windows  program¬ 
ming.  However,  the  compiler  is  capa¬ 
ble  of  being  used  with  the  Microsoft 
Windows  Software  Development  Kit 
(SDK),  and  documentation  is  provided 
that  explains  how  to  use  the  Zortech 
compiler  with  the  SDK.  Because  Micro¬ 
soft  C  is  not  too  strict  about  prototypes 
and  other  things,  from  an  ANSI  stand¬ 
point  most  Windows  programs  are  slop¬ 
pily  written.  Zortech  is  stricter,  and  you 
may  have  to  make  minor  changes  to 
get  Windows  programs  to  compile.  How¬ 
ever,  I  was  able  to  take  several  Win¬ 
dows  applications,  including  some  from 
the  SDK,  and  make  them  compile  with 
Zortech  C  and  C++.  While  the  OS/2 
compiler  is  an  extra  cost  option,  the 
addition  of  Microsoft  Windows  com¬ 
patibility  to  the  MS-DOS  compiler  will 


provide  the  first  true  C++  compiler  for 
Windows  developers. 

AT&T  Compatibility 

Zortech  C++  2.0  is  close  to  the  AT&T 
standard.  Zortech  does  not  support  point¬ 
ers  to  members,  the  obscure  asm( ) 
pseudo-function,  or  fine-grained  over¬ 
load  resolution.  All  of  this  is  docu¬ 
mented  in  the  READ. ME  file,  along  with 
a  list  of  known  bugs  in  the  compiler. 
If  only  other  companies  were  so  hon¬ 
est;  most  manufacturers  seem  to  make 
an  art  of  trying  to  hide  the  bugs  in  their 
products.  All  compilers  have  bugs; 
Zortech  is  the  only  one  willing  to  admit 
to  them  so  they  don’t  sneak  up  on  you. 
As  it  is,  the  bugs  in  Zortech  C++  are 
relatively  trivial,  and  workarounds  are 
provided  when  possible. 

Zortech  C++  does  support  multiple 
inheritance,  virtual  and  abstract  base 
classes,  anonymous  unions,  scope  reso¬ 
lution,  and  just  about  everything  else 
you’d  care  to  throw  at  it  from  the  AT&T 
2.0  Reference.  I’ve  put  some  pretty 
messy  code  through  the  Zortech  com¬ 
piler,  and  it  hasn’t  even  blinked. 

It  is  interesting  to  note  that  cfront , 
AT&T’s  own  C++,  is  not  entirely  com¬ 
patible  with  the  language  as  described 
in  the  AT&T  C++  2.0  Reference  Man- 
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(continued  from  page  69  ) 
ual.  For  instance,  cfront  does  not  sup¬ 
port  the  volatile  keyword,  which 
Zortech  does.  While  the  Zortech  prod¬ 
uct  is  not  a  perfect  implementation  of 
the  language  described  in  the  AT&T 
standard,  it’s  close.  Zortech  people  have 
said  they  will  be  adding  the  missing  2.0 
features  in  a  subsequent  release. 

The  Goodies 

For  those  of  us  who  have  used  the 
Zortech  1  .x  product,  documentation  has 
always  been  a  sore  point.  To  put  it 
bluntly,  the  documentation  with  Zortech 
C++  1.0  was  terrible.  That  isn’t  true  of 
the  documents  that  come  with  Zortech 
C++  2.0:  These  manuals,  aside  from 
minor  spelling  errors,  are  simply  great. 
The  C++  Compiler  Reference  is  well- 
organized  and  clearly  written.  It  con¬ 
tains  a  good,  if  short,  C++  tutorial,  along 
with  lots  of  “extra”  information  on  sub¬ 
jects  such  as  the  global  optimizer  and 
the  proper  use  of  C++.  The  C++  Func¬ 
tion  Reference,  C++  Tools,  and  C++ 
Debugger  manuals  are  complete  and 
thorough,  including  many  examples. 

In  the  past,  Zortech  C++  has  been 
criticized  for  not  being  as  “fancy”  as 
other  compilers.  Borland  and  Micro¬ 
soft  include  a  number  of  functions  in 


their  C  libraries  that  Zortech  did  not 
support.  That  complaint  can  now  be 
dropped;  Zortech  has  added  a  number 
of  functions  to  its  library.  Not  only  have 
a  number  of  functions  been  added  to 

My  experiments  have 
shown  that  Zortech  C++ 
2.0  is  competitive  with 
other  optimizing 
compilers  such  as 
Microsoft  and  Watcom 


increase  compatibility  with  the  Micro¬ 
soft  C  library,  there  are  new  functions 
to  handle  expanded  memory  and  TSRs. 
Library  functions  carried  over  from  the 
previous  version  support  graphics,  di¬ 
rect-video  displays,  mouse  routines,  in¬ 
terrupt  trapping,  and  the  PC  speaker. 

The  compiler  has  been  extended  to 


support  a  new  pointer  type,  known  as 
a  “handle.”  A  handle  pointer  can  be 
used  to  access  virtual  or  expanded  mem¬ 
ory,  a  major  plus  for  memory-hungry 
applications.  If  you  don’t  want  to  use 
a  language  extension,  a  library  of  ex¬ 
panded  memory  functions  is  also  in¬ 
cluded. 

The  C++  Tools  package  is  included 
with  the  Developer’s  Edition  of  the  com¬ 
piler,  and  is  also  available  separately. 
Unlike  Zortech’s,  most  C++  products 
fail  to  provide  a  significant  library  of 
classes.  C++  Tools  has  classes  for  vari¬ 
ous  kinds  of  lists,  dynamic  and  virtual 
arrays,  binary  trees,  hashed  tables,  BCD 
math,  time  and  date  handling,  interrupt 
handlers,  string  and  text  editing,  event 
queues,  windows,  and  money.  While 
some  of  the  classes  are  not  implemented 
as  well  as  they  could  be,  this  is  an 
excellent  starting  point  for  those  peo¬ 
ple  who  do  not  want  to  spend  time 
developing  their  own  basic  classes. 

A  “disk  13  of  12”  contains  a  number 
of  other  goodies.  These  include  a  C++ 
overlay  for  the  graphics  library,  an  ex¬ 
ample  C++  application,  and  a  library 
of  interesting  C  routines.  While  the  C++ 
graphics  library  is  weak,  the  Doodle 
program  is  a  good  example  of  C++ 
program  design. 
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Back  to  the  Biomorphs 

The  Biomorph  program  works  great. 
Zortech  C++  compiles  the  program  so 
that  it  runs  at  the  same  speed  as  the 
Fortran  version.  If  you  have  any  inter¬ 
est  at  all  in  the  new  science  of  chaos, 
or  just  like  to  generate  interesting  pic¬ 
tures  on  your  PC,  this  program  is  a 
great  opportunity  to  experiment.  One 
word  of  warning:  The  program  per¬ 
forms  millions  of  floating-point  opera¬ 
tions  to  generate  an  image.  A  PC  with¬ 
out  a  math  coprocessor  will  run 
Biomorph  very  slowly;  the  program  is 
totally  unusable  on  an  8088/86-based 
PC.  It  works  well  on  my  20MHz  80386 
with  16-bit  VGA.  Take  heart,  though  — 
the  real  researchers  on  this  subject  use 
supercomputers  to  generate  this  stuff. 

Summing  Up 

The  Zortech  C++  compiler  has  become 
an  intimate  part  of  the  work  I  do.  From 
articles  and  books  on  C++  to  personal 
research  projects  and  consulting  work, 
Zortech  C++  has  had  more  mileage  put 
on  it  in  the  last  year  than  any  other 
compiler  in  the  house.  The  new  2.0 
compiler  has  improved  the  product  from 
good  to  excellent.  While  it’s  not  per¬ 
fect,  Zortech  C++  is  one  of  the  best 
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1165  Massachusetts  Ave. 
Arlington,  MA  02174 
800-848-8408 

Developer’s  Edition  (includes 

compiler,  debugger,  tools,  and 

library  source)  $450 

C++  compiler  $199.95 

C++  debugger  $149.95 

C++  tools  $149.95 

OS/2  compiler  upgrade  $149.95 


MS-DOS  products  I’ve  had  the  luck  to 
use.  If  you  want  to  work  with  C++  2.0 
on  an  MS-DOS  computer,  I  can  highly 
recommend  the  Zortech  2.0  release. 

Currently,  Version  2.0  of  the  Zortech 
C++  compiler  (by  itself)  costs  $200, 
and  the  Developer’s  Edition  (including 
library  source  code,  a  C++  class  library, 
and  the  debugger)  costs  $450.  Consid¬ 
ering  what  this  package  offers,  I’d  opt 
for  the  more  complete  Developer’s  Edi¬ 
tion. 
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All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 
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“All protection  violations  that  do  not 
cause  another  exception  cause  a 
general  protection  exception.’’ 

—  Intel  80386  Programmer’s  Reference 

Manual 

"  ‘Good’  exceptions  are  the  ones  you 
expect  to  occur.  ” 

—  Edmund  Strauss,  Inside  the  80286 


In  porting  applications  to  the  Pro¬ 
tected  Virtual  Address  Mode  (pro¬ 
tected  mode  for  short)  of  Intel’s 
286  and  386  processors,  many  de¬ 
velopers  have  become  familiar  with 
the  General  Protection  (GP)  fault. 

The  code  in  Example  1  causes  a  GP 
fault  in  protected  mode.  When  the  In¬ 
tel  processor  detects  a  protection  viola¬ 
tion  (writing  into  a  code  segment,  peek¬ 
ing  past  the  end  of  a  segment,  trying 
to  execute  data,  or  using  an  illegal  seg¬ 
ment  selector),  it  raises  an  exception.  A 
protected-mode  operating  environment 
such  as  OS/2  or  a  DOS  extender  catches 
this  exception  and,  almost  always,  ter¬ 
minates  the  offending  application. 

In  contrast  to  real  mode,  which  al¬ 
lows  a  program  such  as  this  to  execute, 
protected  mode  makes  it  possible  for 
an  operating  system  to  halt  buggy  ap¬ 
plications.  Whereas  the  real-mode  ver¬ 
sion  of  this  program  behaves  nonde- 
terministically  (or  would,  if  the  random 
number  generator  were  initialized),  the 


Andrew  is  a  software  engineer  in  Cam¬ 
bridge,  Mass.,  where  he  is  writing  a 
network  CD-ROM  server.  Andrew  can 
be  reached  at  32  Andrew  (really!)  St., 
Cambridge,  MA  02139. 
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Stalking  GP  Faults: 
Part  I 

Catching  general  protection  faults  when  using 
protected-mode  tools 

Andrew  Schulman 


protected-mode  version  behaves  the 
same  every  time.  This  makes  protected 
mode  terrific  for  software  development. 

But,  what  if  a  protected-mode  envi¬ 
ronment  catches  a  GP  fault  from  the 
program  in  Example  2?  That  would  not 
be  an  application  problem,  but  a  prob¬ 
lem  in  user  input.  This  program  is  an 
interpreter  of  sorts,  and  if  it  GP  faults, 
it’s  because  of  an  error  by  the  user,  not 
by  the  application  itself. 

Now  isn’t  this  rather  silly  program 
responsible  for  verifying  its  input?  Per¬ 
haps,  but  these  two  lines  of  code  rep¬ 
resent  a  large  class  of  programs  that 
allow  address  manipulation  by  the  user, 
and  in  many  such  extensible  systems, 
it  will  not  be  possible  to  completely 
verify  “user  code.”  It’s  often  better  to 
let  the  Intel  processor  handle  the  verifi¬ 
cation;  your  application  is  then  respon¬ 
sible  for  catching  the  GP  fault  signals 
that  the  CPU  sends. 

The  GP  fault  is  just  an  interrupt:  INT 
0D,  in  fact.  Normally,  the  operating 
system  installs  an  interrupt  handler  for 
GP  faults;  this  handler  halts  buggy  pro¬ 
grams.  Clearly,  this  is  not  the  proper 
response  when  the  GP  fault  lies  in  the 
user’s  input  rather  than  your  code. 

In  these  cases  —  when  it’s  not  your 
fault  —  your  application  needs  to  in¬ 
stall  its  own  GP  fault  handler.  Depend¬ 
ing  on  the  system,  catching  GP  faults 
may  be  no  more  difficult  than  catching 
AC  signals,  or  may  be  as  complicated 
as  running  oneself  under  a  pseudo¬ 
debug  process. 

Catching  and  recovering  from  GP 
faults  is  important  to  a  far  wider  class 
of  applications  than  one  might  guess. 
Aside  from  the  programmer’s  interpret¬ 


ers  and  debuggers,  more  and  more  ap¬ 
plications  include  some  form  of  em¬ 
bedded  language  that  allows  the  user 
(or,  more  likely,  a  consultant)  to  cus¬ 
tomize  the  application.  When  ported 
to  protected  mode,  these  applications 
will  have  to  recover  gracefully  from 
GP  faults.  This  means  building  soft¬ 
ware  that  is  fault-tolerant. 

This  two-part  article  discusses  catch¬ 
ing  GP  faults  in  several  different  286 
and  386  protected-mode  DOS  exten¬ 
ders  and  in  OS/2.  Part  I  explains  why 
you  would  want  your  protected-mode 
programs  to  catch  GP  faults,  and  then 
shows  how  to  do  so  using  a  286-based 
DOS  extender.  Part  II,  scheduled  to 
run  in  the  next  issue  of  DDJ ,  shows 
how  to  catch  GP  faults  in  Phar  Lap’s 
386-based  DOS  extender,  and  in  IBM 
and  Microsoft’s  16-bit  OS/2  operating 
system.  Catching  GP  faults  is  more  diffi¬ 
cult  in  OS/2  than  in  the  other  protected- 
mode  environments,  and  requires  use 


Example  2:  If  this  program  GP  faults, 
it’s  because  of  an  error  by  the  user,  not 
by  the  application  itself 
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of  the  interesting  DosPTrace( )  debug¬ 
ging  function. 

To  a  programmer  familiar  with  the 
ANSI  C  standard  library  or  with  the  Unix 
operating  system,  all  of  this  will  at  first 
seem  to  be  much  ado  about  nothing, 
because  the  solution  is  “obviously”  to 
install  a  SIGSEGV  (segmentation  viola¬ 
tion)  handler  with  signal/ ).  But  none 
of  these  environments  turns  an  INT  OD 
into  a  SIGSEGV  signal.  For  portability 
with  Unix,  we  could  write  a  SIGSEGV 
signal  handler,  and  then  make  our  INT 
OD  interrupt  handler  raise  (SIGSEGV), 
but  that  still  leaves  the  question  of  how 
to  catch  INT  OD  in  the  first  place. 
Because  this  article  focuses  on  writing 
code  in  C  to  catch  GP  faults,  it  also 
discusses  general  issues  involved  with 
writing  interrupt  handlers  in  C,  and 
with  the  setjmpC )  and  signal( )  facili¬ 
ties.  And,  while  focusing  on  one  seem¬ 
ingly  obscure  aspect  of  286/386  pro¬ 
gramming,  this  article  also  looks  at  a 
lot  of  different  protected-mode  tools. 

The  Protected-Mode  PEEK/POKE 
Problem 

“A  GP  fault  is  evidence  that  the  pro¬ 
gram  's  logic  is  incorrect,  and  therefore 
it  cannot  be  expected  to  fix  itself  or 
trusted  to  notify  the  user  of  its  ill  health .” 

Gordon  Letwin 
Inside  OS/2,  1988 


Similar  statements  can  be  found  in  the 
documentation  for  almost  any  system 
based  on  protected  mode,  but  Letwin 
is  wrong. 

How  could  it  be  otherwise?  Are  there 
any  real  programs  for  which  a  GP  fault 
is  not  indicative  of  the  program’s  ill 
health?  How  can  a  program  violate  the 
protection  model  and  still  deserve  to 
continue  executing? 

Take  the  example  of  Digitalk’s  su¬ 
perb  Smalltalk/V286,  which  runs  in  pro¬ 
tected  mode.  Normally  Smalltalk/V286 
is  quite  resilient  to  user  errors.  But  type 
in  this  line  of  code:  Dos  new peekFrom: 
0  @  0.  Select  it  and  evaluate  it  by  choos¬ 
ing  “Show  It”  from  the  menu.  (0  @  0 is 
a  point  in  two-dimensional  memory 
space.)  The  result  is  that  Smalltalk  bombs 
back  out  to  DOS  with  the  message: 

Exception  OD:  General  protection  fault 

Error  code/selector:  0000 

All  we  did  was  ask  to  peek  at  mem¬ 
ory  location  0000:0000.  We  weren’t  even 
trying  to  change  it!  How  could  peeking 
at  it  cause  Smalltalk  to  crash?  Still  crazy 
after  all  those  years  of  real-mode  pro¬ 
gramming,  we  expected  that  0000:0000 
would  point  to  the  address  of  the  divide- 
by-zero  interrupt  vector.  In  fact,  in  pro¬ 
tected  mode  dereferencing  the  address 
0000:0000  is  guaranteed  to  be  illegal. 


Okay,  so  we’re  not  allowed  to  peek 
at  0:0  in  protected  mode.  But  the  bug 
was  in  our  code,  not  in  the  Smalltalk 
interpreter.  The  interpreter  was  shut 
down  because  of  a  bug  in  our  code? 
This  doesn’t  sound  very  protected.  In 
this  case,  the  assumption  “a  program 
that  GP  faults  should  be  terminated” 
was  wrong.  It’s  our  “user  code”  that 
should  be  squelched,  not  the  Smalltalk 
interpreter  itself. 

To  see  that  this  problem  is  not  inher¬ 
ent  in  protected  mode,  let’s  execute  the 
same  instruction  using  another  great 
protected-mode  product,  Laboratory  Mi¬ 
crosystems’s  UR/Forth  386,  a  32-bit  Forth 
that  runs  under  Phar  Lap’s  386  !  DOS- 
Extender  and  virtual-memory  manager. 

When  we  execute  this  Forth  state¬ 
ment  00c@L  (fetch  from  0:0)  and  then 
continue  on  with  the  Forth  interpreter 
itself  responds  with  the  message:  Gen¬ 
eral  protection  fault!  This  is  what  Small- 
talk/V286  should  have  done.  Instead 
of  crashing  back  out  to  DOS,  the  inter¬ 
preter  stays  in  control. 

That  this  is  easier  said  than  done, 
though,  becomes  clear  if  we  lastly  look 
at  the  OS/2  version  of  UR/Forth.  True, 
this  isn’t  supposed  to  be  identical  to 
UR/F  386,  because  that’s  a  completely 
32-bit  application  while  the  OS/2  ver¬ 
sion  remains,  alas,  16-bit.  But  if  we 
evaluate  the  same  line  of  code:  0  0 
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(continued  from  page  75) 

C@L  which,  again,  means  “peek  at 
0000:0000,”  OS/2  halts  the  Forth  inter¬ 
preter  and  displays  a  GP  fault  dump 
as  shown  in  Figure  1. 

Now,  unless  we’re  writing  a  32-bit 
protected-mode  HastyBasic,  few  of  us 
care  about  PEEK  and  POKE  as  such. 
But  any  other  form  of  memory  access 
can  be  reduced  to  PEEK  and  POKE. 
The  question  when  writing  a  protected 
mode  interpreter  is  what  do  PEEK  and 
POKE  mean  in  the  context  of  protected 
mode? 

The  answer  is  simple:  The  user  must 
be  allowed  to  execute  any  command 
without  fear  of  killing  the  interpreter. 
If  the  Intel  processor  detects  a  GP  fault, 
the  interpreter  should  handle  it  by  print¬ 
ing  out  a  message  such  as  “Illegal  se¬ 
lector”  or  “Can’t  write  to  code  seg¬ 
ment”  or  “Peeking  past  end  of  seg¬ 
ment,”  or  perhaps  simply  “General  pro¬ 
tection  fault!”  The  interpreter  should 
then  return  to  its  top-level  input  loop. 

The  Real-Mode  GP  Fault 

Actually,  this  isn’t  purely  a  protected- 
mode  problem.  There  is  also  a  limited 
form  of  GP  fault  in  real  mode  on  286 
and  386  machines.  Attempt  to  derefer¬ 
ence  more  than  one  byte  from  offset 
FFFF: 

int  *p  =  (int  *)  -1; 

printf("%d  \  n",  *p); 

This  is  an  excellent  way  to  crash  an 
IBM  AT.  The  CPU  generates  an  INT 
0D,  but  it  isn’t  caught  properly.  On  an 
AT,  the  real-mode  GP  fault  (segment 
overrun)  is  treated  as  though  it  were  a 
hardware  interrupt  coming  in  on  IRQ5. 
IRQ5  can  be  used  by  anything  from 
LPT2  to  the  Novell  network  to  an  inter¬ 
rupt-driven  SCSI  board,  so  exactly  what 
this  code  will  do  depends  on  your  setup. 

FFFF.C  (Listing  One,  page  120)  is  a 
program  that  generates  this  real-mode 
GP  fault  on  286  and  386  machines.  But 
it  also  includes  a  handler  for  INT  0D. 
The  listing  shows  how  easy  it  is  to 
write  a  real-mode  interrupt  handler  in 
C.  The  only  difficulty  is  that,  while  both 
Turbo  C  and  Microsoft  C  push  all  regis¬ 
ters  to  a  function  defined  with  the  in- 


Session  title:  UR/Forth 

SYS1943:  A  program  caused  a  protection  violation. 
TRAP  000 D 

AX=2092  BX=0000  CX=FFFFDX=3FC2  BP=FFFA 
SI=05EA  DI=05E4  DS=00C7ES=00C>0  FLG=2206 
CS=0227  IP=2093  SS=00C7SP=FBFC  MSW=FFED 
CSLIM=FFFE  SSLIM=FFFF  DSLIM=FFFF  ESLIM=**** 
CSACC=DF  SSACC=F3  DSACC=F3  ESACC=** 
ERRCD=0000  ERLIM=****  ERACC=” 

End  the  program 


Figure  1:  A  GP  fault  dump 


terrupt  keyword,  they  differ  in  the  or¬ 
der  in  which  the  registers  are  pushed. 

FFFF.C  uses  a  REG_P ARAMS  struc¬ 
ture  in  which  the  fields  appear  in  a 
different  order  depending  on  the  com¬ 
piler  used.  REG_PARAMS  is  defined  in 
GPFAULT.H  (Listing  Two,  page  120). 
The  interrupt  handler  expects  one  of 
these  structures  (not  a  pointer  to  it!)  to 
be  on  the  stack.  Using  286  instructions, 
the  Microsoft  C  compiler  does  a  PUSHA; 
Turbo  C  pushes  each  register  individu¬ 
ally.  The  processor  itself  pushes  FLAGS 
and  CS:IP  before  calling  the  interrupt 
handler.  In  addition  to  distinguishing 
between  the  Borland  and  Microsoft  com¬ 
pilers,  REG_PARAMS  also  handles  the 
extra  parameter  that  is  pushed  on  the 
stack  of  protected-mode  handlers  for 
INT  08-0D,  and  the  extra  FS  and  GS 
registers  on  the  386.  GPFAULT.H  is 
#include d  by  most  of  the  programs  in 
this  article. 

The  real-mode  GP  fault  handler  is 
installed  using  MS-DOS  function  25, 
just  like  any  other  interrupt  handler. 

How  does  the  INT  OD  handler  know 
whether  it’s  been  invoked  because  of 
a  GP  fault  or  because  of  a  hardware 
interrupt  on  IRQ5?  An  INT  0D  handler 
can  check  whether  the  CS:IP  pushed 
on  its  stack  corresponds  to  any  of  the 
known  places  in  the  program  where  a 
GP  fault  is  expected  or  allowed  to  oc¬ 
cur.  If  it  doesn’t,  the  handler  can  just 
pass  the  interrupt  along  using  the  MSC 
5.1  chain_intr( )  function. 

This  program  will  not  work  properly 
on  a  386  machine  running  in  Virtual 
86  mode,  however.  If  you  run  Qualitas’ 
386  A  Max,  for  example,  it’s  as  if  you 
hadn’t  installed  the  interrupt  handler 
at  all: 

A  Privileged  operation  exception  at  ad¬ 
dress  0ED3-003A. 

Press  any  key  to  restart  your  computer. 

(In  fact,  pressing  any  key  has  no  effect, 
and  you  have  to  reach  around  the  back 
for  the  power  switch.) 

Running  FFFF.EXE  under  Windows/ 
386  doesn’t  hang  your  machine  like 
386  A  Max,  but  it  does  terminate  the 
application,  and  the  message  box  it 
displays  sounds  ominous  for  a  pro¬ 
gram  that  simply  wants  to  peek  at  two 
bytes  starting  at  offset  FFFF  (on  an 
8088,  memory  would  wrap  around): 

This  application  has  violated  system 
integrity  and  will  be  terminated.  This 
may  result  in  the  system  becoming  un¬ 
stable.  It  is  strongly  recommended  that 
you  close  all  applications,  exit  Win¬ 
dows,  and  then  reboot  your  machine. 

Our  exception  handler  is  ignored  in 


Dr.  Dobb’s Journal,  January  1990 

50 


PROGRAMMER'S  WORKBENCH 


Virtual  86  mode  because  exceptions 
in  V86  mode  are  vectored  through  the 
protected-mode  interrupt  descriptor  ta¬ 
ble  (IDT),  not  through  the  8086-style 
interrupt  vector  table  at  memory  loca¬ 
tion  zero.  In  fact,  it  is  important  that 
Virtual  86  control  programs  keep  con¬ 
trol  over  INT  OD,  because  GP  fault  is 
precisely  the  mechanism  that  programs 
such  as  Windows/386  use  to  virtualize 
I/O.  It  would  be  nice,  though,  if  V86 
control  programs  would  not  scare  us 
with  dire  warnings  of  hellfire,  brim¬ 
stone,  and  data  loss. 

Protected-Mode  MS-DOS 

Stalking  the  real-mode  GP  fault  is  a 
good  introduction  to  handling  GP  faults 
in  programs  running  under  a  DOS  ex¬ 
tender.  DOS  extenders  run  in  protected 
mode,  but  switch  into  real  mode  to  use 
the  INT  21  facilities  provided  by  MS- 
DOS,  to  use  other  INT  facilities  (for 
example,  the  mouse  or  NetBIOS),  or 
to  call  functions  in  real  mode  (for  exam¬ 
ple,  some  graphics  libraries). 

Installing  a  GP  fault  handler  in  a 
DOS  extender  is  similar  to  using  the 
MS-DOS  Set  Vector  function,  and  most 
DOS  extenders  use  the  same  INT  21 
function  25h  interface  as  real-mode  MS- 
DOS.  But,  as  in  V86  mode,  Set  Vector 
for  protected  mode  manipulates  the 
protected-mode  IDT  rather  than  the  low- 
memory  interrupt  vector  table.  Also, 
Set  Vector  in  protected  mode  must  be 
able  to  install  interrupt  handlers  lo¬ 
cated  in  high  memory  (above  one 
Mbyte).  Set  Vector  for  a  32-bit  environ¬ 
ment  such  as  Phar  Lap’s  386 1 DOS- 
Extender  must  be  able  to  use  32-bit 
offsets  (which,  added  to  1 6-bit  seg¬ 
ment  selectors,  make  for  48-bit  far  ad¬ 
dresses).  And,  finally,  because  these 
environments  switch  back  into  real 
mode,  DOS  extenders  also  must  pro¬ 
vide  a  way  to  install  real-mode  inter¬ 
rupt  handlers. 

GPFAULT.C  (Listing  Three,  page  120) 
is  a  program  that  runs  under  two  286- 
based  DOS  extenders:  DOS/16M  from 
Rational  Systems,  and  OS/286  from 
Eclipse  Computing  (formerly  AI  Archi¬ 
tects).  The  phrase  286-based  means  that 
these  DOS  extenders  can  run  on  any 
IBM-compatible  equipped  with  an  In¬ 
tel  80286  and  up.  Developers  will  pre¬ 
sumably  be  using  a  386,  but  aren’t  fro¬ 
zen  out  of  the  much  larger  AT  market. 
This  1 6-bit  program  can  be  compiled 
with  Microsoft  C  5.1,  and  then  run 
through  a  post-processor  (DOS/16M 
MAKEPM  or  OS/286  EXPRESS).  The 
resulting  program,  GPFAULT.EXP,  can 
then  be  spliced  with  a  protected-mode 
loader  to  form  GPFAULT.EXE. 

The  GPFAULT  program  is  a  mock 
interpreter  that  allows  the  user  to  try 


to  poke  at  arbitrary  locations  in  mem¬ 
ory,  as  shown  in  Figure  2,  the  session 
with  the  DOS/16M  version. 

It  is  interesting  that  while  poking  at 
1234:5678,  0088:00CB,  and  0000:0000, 
all  caused  GP  faults  that  happened  in 
different  ways.  In  fact,  we  can  see  why 
this  is  called  the  general  protection  fault: 
It  is  a  catchall  for  everything  that  doesn’t 
fit  into  some  other  exception. 

In  the  example  session,  1234:5678 
was  a  completely  bogus  pointer,  and 
the  processor  refused  even  to  load  1234 
into  a  segment  register  (note  that  ES 
still  contains  the  selector  00 A0).  We 
didn’t  get  anywhere  near  trying  to  poke 
this  address:  There  was  no  such  ad¬ 
dress  in  this  session.  In  contrast  to  real 
mode,  in  which  every  segment:offset 
combo  points  somewhere  ( in  this  sense, 
real  mode  is  magic),  memory  in  pro¬ 
tected  mode  is  a  sparse  matrix:  Most 
addresses  you  can  form  don’t  point 
anywhere. 

Because  the  processor  refuses  to  load 
the  number,  the  GP  fault  handler  can’t 
find  it  in  the  registers  and,  consequently, 
has  no  way  of  knowing  what  caused 
the  fault,  unless  the  processor  also  gives 
it  some  additional  information. 

Fortunately,  the  Intel  processor  pro¬ 
vides  this  information  by  passing  an 
extra  parameter  on  the  stack  of  a  GP 
fault  handler.  When  GPFAULT.H  is  in¬ 
cluded  in  a  protected-mode  program, 
the  REG_PARAMS  structure  contains  a 
field  for  this  error  code.  In  a  C  interrupt 
handler,  this  extra  parameter  goes  be¬ 
tween  the  CS:IP  and  FLAGS  pushed 


Figure  2:  A  GPFAULT.EXP  session 


by  the  processor  and  the  PUSHA  sup¬ 
plied  by  the  C  compiler. 

The  handler  could  use  the  Intel  LAR 
and  LSL  instructions  to  figure  out  why 
a  GP  fault  took  place  (did  we  try  to 
write  into  code,  did  the  offset  overrun 
the  segment  limit,  and  so  on),  so  that 
it  could  provide  the  user  with  a  more 
informative  message  or  perhaps  cor¬ 
rect  the  error. 

Trying  to  poke  0088:00C5  did  not 
produce  an  error  code  (the  processor 
just  pushes  a  0  on  the  handler’s  stack). 
This  is  because  0088  was  a  valid  seg¬ 
ment  selector;  in  fact,  it  was  GPFAULT 
.EXP’s  code  segment.  This  means  that 
loading  it  into  ES  was  a  legal  operation 
(as  we  can  see  from  the  register  dump), 
but  trying  to  poke  it  caused  a  GP  fault. 

This  explains  why  the  CS:IP  where 
the  fault  took  place  was  a  few  bytes 
further  down  from  where  we  tried  pok¬ 
ing  the  totally  bogus  address.  In 
GPFAULT.C,  the  crucial  line  of  code 

*fp  =  data; 

becomes  three  instructions: 

les  bx,  dword  ptr  _fp 
mov  ax,  word  ptr  _data 
mov  word  ptr  es:[bx],  ax 

Loading  a  bogus  segment  selector  faults 
on  the  first  instruction,  whereas  doing 
something  illegal  with  a  genuine  seg¬ 
ment  selector  faults  on  the  third. 

Trying  to  poke  memory  location  zero 
is  a  special  case.  While  segment  selec- 


C:\DOS1 6M>gpfault 

DOS/1 6M  Protected  Mode  Run-Time  Version  3.25 
Copyright  (C)  1987,1988,1989  by  Rational  Systems,  Inc. 

’Q’  to  quit,  ’!’  to  reinstall  default  GP  fault  handler 
00A0:04C6  is  a  legal  address  to  poke 
00A0:04C4  is  not  a  legal  address  to  poke 
$  1234:5678  666 
Protection  violation  at  0088:0005! 

Error  code  1 234 

<ES  00A0>  <DS  00A0>  <DI  1  AC0>  <SI0082> 

<AX  001 5>  <BX  0BF8>  <CX  001 5>  <DX  0000> 

$  OOAO:04C4  666 

poked  00A0:04C4  with  666 

$  0OAO:O4C2  1 

poked  00A0:04C2  with  1 

$  0088:0005  666 

Protection  violation  at  0088:00CB! 

<ES  0088>  <DS  00A0>  <DI  1  AC0>  <SI  0082> 

<AX  029A>  <BX  00CB>  <CX  0015>  <DX  0000> 

$0:0  0 

Protection  violation  at  0088:00CB! 

<ES  0000>  <DS  00A0>  <DI  1  AC0>  <SI  0082> 

<AX  0000>  <BX  0000>  <CX  001 5>  <DX  0000>  $  ! 

$! 

$0:0  0 

DOS/16M:  Unexpected  lnterrupt=000D  at0088:00CB 
code=0000  ss=00A0  ds=00A0  es=0000 

ax=0000  bx=0000  cx=0015  dx=0000  sp=1982  bp=1A92  si=0082  di=1AC0 
C:\DOS1 6M> 
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tor  0  is  bogus  in  the  sense  that  it  is 
guaranteed  not  to  correspond  to  an 
actual  segment  descriptor,  loading  0 
into  a  segment  register  is  not  illegal:  It’s 
using  any  resulting  pointer  that’s  ille¬ 
gal.  In  this  way,  the  Intel  processor  in 
protected  mode  lends  support  to  high- 
level  languages  that  treat  memory  loca¬ 
tion  zero  as  the  NIL  pointer. 

While  on  the  subject  of  0:0,  remem¬ 
ber  that  even  trying  to  peek  at  this 
location  caused  Smalltalk/V286  and  UR/ 
Forth  OS/2  to  blow  up.  Here  we  tried 
to  poke  it,  but  because  we  installed  an 
INT  0D  handler,  the  mock-interpreter 
stayed  in  control.  At  the  end  of  the 
session,  I  told  GPFAULT  to  reinstall 
DOS/l6M’s  default  GP  fault  handler, 
and  then  did  another  POKE  0:0  0.  The 
result  this  time  was  that  DOS/16M 
spewed  out  some  diagnostics  and  the 
interpreter  halted.  This  is  the  sort  of 
behavior  we’ve  avoided  by  installing 
our  own  handler. 

The  IRQ5  Problem 

Microsoft  C  5.1  provides  the  function 
dos_setvect( )  to  install  an  interrupt  han¬ 
dler.  Turbo  C  provides  setvectC).  These 
functions  merely  call  INT  21  function 
25.  Can  these  functions  be  used  from 
a  protected-mode  DOS  extender  to  in¬ 
stall  a  GP  fault  handler? 

All  DOS  extenders  provide  an  INT 
21  interface  for  protected-mode  pro¬ 
grams  (that,  in  fact,  is  a  pretty  good 
definition  of  a  DOS  extender),  and  that 
includes  INT  21  function  25.  This  means 
that  a  lot  of  even  low-level  code,  in¬ 
cluding  a  call  to  _dos_setvect( ),  works 
transparently  under  a  DOS  extender. 

However,  the  GP  fault  is  a  little  un¬ 
usual.  INT  OD  lies  in  the  range  of  Intel 
processor  exceptions  that  are  also  IBM 
AT-compatible  hardware  interrupts.  On 
the  286  and  above,  Intel  reserved  INT 
0D  and  other  slots  for  processor  excep¬ 
tions  like  the  GP  fault,  but  IBM  wasn’t 
thinking  about  protected  mode  at  the 
time  and  overloaded  INT  08  through  OF 
for  use  by  the  AT  hardware  interrupts 
IRQ0  through  IRQ7.  Thus,  INT  0D  is 
multiplexed  between  the  GP  fault  and 
IRQ5  (which,  in  turn,  may  be  used  by 
LPT2  or  by  an  Ethernet  board  or  by  an 
interrupt-driven  SCSI  board  or  by  ...  ). 

The  386-based  DOS  extender  from 
Phar  Lap  and  Quarterdeck’s  DESQview 
386  both  solve  this  problem  by  recon¬ 
figuring  the  8259  programmable  inter¬ 
rupt  controller  (PIC)  so  that  IRQ0 
through  IRQ7  are  relocated  to  INT  78 
through  7F  (see  Ray  Duncan,  “Power 
Programming,”  PC  Magazine,  October 
17,  1989). 

But  286-based  DOS  extenders  hap¬ 
pen  not  to  reprogram  the  8259  PIC.  So, 
when  you  install  an  INT  0D  handler 


with  INT  21  function  25,  are  you  in¬ 
stalling  a  protected-mode  GP  fault  han¬ 
dler  or  a  real-mode  IRQ5  handler?  The 
286-based  DOS  extenders  try  to  “Do 
the  Right  Thing”  (to  trivialize  the  title 
of  a  recent  movie).  And  alternatives  to 
INT  21  function  25  are  provided  when 
the  extender’s  default  behavior  isn’t 
what  you  need. 

Returning  to  GPFAULT.C  in  Listing 
Three,  for  DOS/16M,  I  used  the  func¬ 
tions  Dl6pmlnstall(  )3.ndDl6pmGetVec- 
toii ).  The  “pm”  in  the  function  names 
stands  for  protected  mode.  These  func¬ 
tions,  along  with  many  other  C  inter¬ 
face  routines  for  protected-mode  pro¬ 
gramming,  appear  in  the  file  DOS- 


16LIB.C  that  comes  with  DOS/16M  and 
with  Rational  Systems’s  protected-mode 
development  environment,  Instant-C. 

The  Limits  of  Protection 

In  addition  to  illustrating  how  to  catch 
the  GP  fault,  Listing  Three  also  shows 
its  limitations.  Having  committed  one 
GP  fault  and  seeing  the  register  dump, 
the  user  now  knows  the  selector  num¬ 
ber  for  DS,  and  an  error  prone  or  mali¬ 
cious  user  can  freely  poke  at  the  pro¬ 
gram’s  internal  data. 

Doing  so  doesn’t  cause  a  GP  fault. 
Instead,  the  more  places  the  user  clob¬ 
bers,  the  more  erratically  the  program 
behaves.  Generally,  the  interpreter’s 
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PROGRAMMER'S  W  0  R  K  B  E  N  C  H 


strings  are  clobbered  first.  Because  they 
take  up  more  room  in  memory  than 
other  variables,  there’s  a  good  chance 
that  random  pokes  will  first  hit  strings. 
Soon,  crucial  program  data  is  poked, 
and  the  program  itself  causes  a  GP 
fault.  This  is  somewhat  like  the  game 
Core  Wars  (which  first  appeared  in  the 
“Computer  Recreations”  column  of  Sci¬ 
entific  American ),  in  which  two  as¬ 
sembly-language  programs  try  to  make 
each  other  execute  an  illegal  opcode. 

A  GP  fault  handler  must  be  able  to 
distinguish  its  own  “internal”  GP  faults 
from  those  caused  directly  by  user  code. 
GPFAULT.C  keeps  a  “whereami”  flag. 
The  GP  fault  handler  checks  whether 
(whereami  ==  IN_USER_CODE)  which 
indicates  whether  INT  OD  occurred  in 
any  known  places  in  the  code  where 
a  GP  fault  is  expected  or  allowed  to 
occur.  If  it  didn’t,  then  the  INT  OD  was 
caused  by  an  internal  error  (or  by  a 
real  mode  IRQ5,  though  in  that  case 
the  processor  won’t  have  pushed  the 
additional  error  code,  and  our  inter¬ 
rupt  handler  expecting  a  REG_PARAMS 
on  the  stack  will  view  CS  and  IP  as 
garbage).  If  the  fault  took  place  while 
directly  executing  code  on  behalf  of 
the  user,  then  we  print  out  some  diag¬ 
nostics  and  longjmp( )  back  to  the  in¬ 
terpreter’s  main  input  loop.  longjmp( ) 


is  a  non-local  goto.  The  jmp_buf  holds 
the  state  of  the  program’s  registers  at 
the  time  we  called  setjmp( ),  and  call- 

While  this  article  focuses 
on  writing  code  in  C 
to  catch  GP  faults,  it 
also  discusses  general 
issues  involved  with 
writing  interrupt 
handlers  in  C,  and  with 
the  setjmpO  and 
signalO  facilities 


ing  longjmp( )  restores  this  state.  The 
program’s  thread  of  execution  resur¬ 
faces  as  if  it  had  just  “returned”  from 
setjmp(  ). 

Signal  handlers  that  execute  long- 


jmp( )  are  notoriously  unreliable.  So 
you  might  have  some  doubts  about 
taking  a  longjmp(  )  from  within  an  in¬ 
terrupt  handler.  For  example,  what 
about  all  the  junk  that  was  pushed  on 
the  stack  at  entry  to  the  interrupt  han¬ 
dler?  If  we  longjmp(  )  out  of  the  inter¬ 
rupt  handler,  we  never  execute  the  IRET 
instruction  and,  it  seems,  we  never  clean 
up  the  stack.  The  jmp_buf  however, 
includes  the  stack  pointer  from  when 
setjmp(  9  was  first  called,  so  longjmp(  ), 
by  loading  this  saved  stack  pointer  into 
SP,  will  effectively  cut  back  the  stack. 

There’s  still  a  problem  with  an  inter¬ 
rupt  handler  that  doesn’t  return:  It  can 
leave  the  program  in  an  incomplete 
state.  By  itself,  longjmp( )  is  insuffi¬ 
cient  for  true  exception  handling.  In  a 
real  program,  the  jmp_buf  should  prob¬ 
ably  be  enclosed  within  a  larger  appli¬ 
cation-defined  structure  that  includes 
other  fields  necessary  for  cleanup  (such 
as  open  file  handles,  data  base  indexes, 
and  so  on).  For  a  good  discussion  of 
longjmp(  )'s  problems  as  an  exception¬ 
handling  mechanism,  see  William  M. 
Miller’s  paper,  “Exception  Handling  with¬ 
out  Language  Extensions,”  Usenix  Pro¬ 
ceedings  C++  Conference ,  Denver, 
Colo.,  17  -  21  October,  1988. 

What  does  the  fault  handler  do  if  the 
flag  indicates  the  program  wasn’t  in 
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user  code?  The  GP  fault  must  then  have 
been  caused  by  our  own  code  (per¬ 
haps  because  the  user  tromped  on  some 
of  our  data,  including  possibly  the 
whereami  flag  itself).  In  this  program, 
I  print  out  a  message  and  then  use 
chain_intr( )  to  call  the  default  GP  fault 
handler,  which  terminates  the  applica¬ 
tion.  In  a  real  program,  you  might  want 
to  try  to  give  users  a  chance  to  save  their 
work,  perhaps  by  disabling  all  menu 
items  except  “File  Save.  .  .”  and  dis¬ 
playing  a  “The  End  Is  Near”  message. 

Because  the  whereami  flag  itself  is 
so  easy  to  tromp  on,  it  holds  “magic” 
numbers  rather  than  simple  enum  val¬ 
ues.  And  because  the  jmp_buf  top  level 
is  so  crucial,  the  program  maintains 
two  of  them.  In  a  real  program,  you 
might  want  to  make  such  essentials 
read  only  while  executing  user  code. 
Even  better,  you  might  want  to  try  to 
run  user  code  using  a  different  local 
descriptor  table  (LDT)  from  the  one 
you  use  for  the  interpreter  itself. 

Any  protection  scheme  has  similar 
limitations.  Who  protects  the  protec¬ 
tor?  Another  protector,  of  course,  al¬ 
most  (but  not  quite)  as  vulnerable.  Ulti¬ 
mately,  the  protection  problem  is  the 
same  as  the  halting  problem. 

This  concludes  Part  I  of  the  epic 
saga,  “Stalking  GP  Faults.”  Tune  in  again 
next  month,  when  our  hero  gets  caught 
inside  32-bit  code  running  under  a  386- 
based  DOS  extender,  and  inside  16-bit 
code  running  under  the  OS/2  operat¬ 
ing  system.  Until  then,  remember:  To 
commit  a  GP  fault  is  human,  but  to 
catch  it  and  recover,  divine. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  120.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  8. 
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REAL-TIME  ANIMATION 


Listing  One  (Text  begins  on  page  16 J 


.model  small,  c 

.286  /  This  directive  can  be  used  to  optimize  procedure  entry 

/  but  not  much  else.  I  avoided  all  non-8088  commands 
comment  \ 

EGA  Sprite  Drivers  for  C 

Copyright  (c)  February  1989,  Ryu  Consulting,  Inc. 

(916)  722  -  1939  anytime 

Written  by  Rahner  James,  CS 

This  is  a  full  functioning  sprite  driver  for  EGA  graphics  adaptors.  The 
sprite  are  given  to  the  routines  as  a  linked  list  of  sprite  structures.  All 
the  function  are  re-entrant  and  can  be  part  of  a  multi-tasking  system.  The 
sprite  structures  are  intended  to  reside  in  far  memory.  The  sprite  can 
exist  on  any  pixel  boundary.  These  were  intended  to  be  called  from  some  C 
program,  but  probably  can  be  modified  for  some  other  language.  This  must  be 
assembled  with  Microsoft  MASM  version  5.0  or  later  since  I  make  use  of  local 
variables,  forward/backward  jumps  and  models.  Expect  to  get  some  incorrect 
size  warnings  because  MASM  doesn't  seem  to  recognize  its  own  "byte  ptr"  and 
"word  ptr"  operators  when  used  with  words  and  dwords.  \ 


EOI  equ 

EOI_PORT  equ 

CRT_MODE  equ 

EGA  ADDRESS  equ 

EGA_P I XE LS_WORD  equ 
EGA_PIXELS_BYTE  equ 
NUMBER_OF_P LANES  equ 

EGA_RETRACE_STATUS 
RETRACE_BIT 
SEQUENCE_REG 
GRAPHICS_12 
MAP_MASK_REG 
DATA_ROTATE_REG  equ 
DATA_0R  equ 

DATA  MOVE 


;  End  Of  Interrupt  signal 
;  Port  to  output  the  EOI 


;  Number  of  pixels  per  word 
;  Number  of  pixels  per  byte 
;  Number  of  EGA  color  planes 

3dah  /  EGA  retrace  status  register 

1  shl  3  ;  Bit  set  to  signal  a  vertical  retrace 

3c4h  /  Sequencer  register 

3ceh  ;  Graphics  1  &  2  register 

2  ;  Map  mask  Indexed  register 
;  Data  Rotate  Indexed  register 

z  Set  to  OR  data  on  the  EGA 
0  ;  Write  data  unmodified  onto  EGA 


;  EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE 
;  EGA  sprite  related  routines  below  this  line 
;  void  EGA_CONVERT(  dest_ptr,  sourceptr  ) 

/  Converts  long  storage  format  sprite  into  EGA  structure  sprite 
;  Given: 

;  dest_ptr  far  ->  EGA  sprite  buffer  ready  to  go 

;  source_ptr  far  ->  disk  sprite  structure  to  convert 

/  Returns : 

;  EGA  sprite  buffer  set  up  accordingly 

ega_convert  proc  near  uses  di  si  ds,  destrdword,  sourcerdword 
local  store_width: word,  store_height : word 
local  source_width:word 
local  plane_size:word 
cld 

Ids  si,  source  ;  DS:SI  ->  source  sprite 

les  di,  dest  ;  ES:DI  ->  CGA  sprite  buffer 


es: [di] ,  di 
es:[di+2],  es 
di,  E_WIDTH 


source_width,  ax 

ax,  EGA_P IXELS_WORD- 1 

cl,  4 

ax,  cl 

bx,  ax 


store_height,  ax 


ax,  ax 

plane_size,  ax 


Make  the  animate  ptr  point  to  itself 


Get  width  in  byte  pixels 

Want  to  include  those  border  pixels 
Divide  by  sixteen  to  convert  one  byte 
.per  pixel  to  16  pixels/word  for  EGA 
Use  this  as  our  width  count 
Store  as  words/pixels 
Get  height 

Move  height  straight  across 

AX  =  Body  size  in  mask/sprite  entries 

AX  =  body  size  in  words 

AX  =  plane  size  in  bytes 

Save  as  our  plane  index 

Swap  DS:SI  and  ES:DI 


BOTTOM_LINE 
RIGHT  SIDE 


;  Lowest  pixel  line  to  allow  a  sprite 
/  Right-most  visual  pixel  allowed 


;  All  sprites  are  stored  on  disk  using  the  same  internal  format.  The  first  word 
;  is  the  width  of  the  sprites  in  bytes  and  the  second  word  is  the  height  of  the 
;  sprite  in  widths.  Each  byte  represents  ;  one  pixel's  worth  of  information. 

;  Bit  7  of  the  byte  is  the  intensity  bit,  0=off.  This  allows  for  128  colors, 

;  black  will  be  0  or  80h.  The  intensity  bit  set  indicates  an  opaque  black 
;  surface.  All  color  translations  are  table  driven. 


sub 

next_row: 

mov 

next_word: 

add 


internal_sprite_structure 
int_width  dw  ? 
int_height  dw  ? 
int_body  db  ? 
internal_sprite_structure 


struc  /  Storage  structure  used  for  sprites 
;  Width  in  bytes  for  the  sprite 
;  Height  in  widths  of  the  sprite 
;  Start  of  the  sprite's  body 

ends 


ega_sprite_structure 
e_animate_ptr  dw 
e_width  dw  ? 

e_height  dw 

e_body  dw 


ega_sprite_structure 

style_structure  struc 
style_width  dw 

style_height  dw 

style_body  db 

style_structure  ends 


struc  ;  Internal  EGA  sprite  structure 

0,0  ;  Far  ptr  to  next  sprite  struct  in  animation  seq. 

;  Width  of  the  sprite  in  words 

?  ;  Height  of  sprite  in  widths 

?  /  Beginning  of  body 

;.word  0:  mask,  word  1:  sprite 
throughout  the  body.  That  way  you  can  pull 
/.the  background  up,  mask  it,  OR  the  sprite, 
/.then  store  the  background 
;  The  body  is  organized  into  four  planes, 

/.termed  PLANEO  to  PLANE3 .  Each  represents  a 
/.different  color  in  the  EGA  spectrum,  except 
/.PLANEO  which  is  the  intensity  bit. 


/  Width  of  each  style  entry  in  bytes 
/  Height  of  each  style  entry  in  pixels 
/  Start  of  the  style  entries 


LOCAL  DATA  STORAGE  for  DS 


do_page_flip,  done_page_flip 


do_page_flip  db 

done_page_flip  db 

flip_turn  db 

old_irq_mask  db 

EGA_settings  db 


0  /  Set  to  -1  when  non-visual  page  is  completed 

-1  /  Set  to  -1  right  after  page  has  been  swapped 

4  /  #  of  interrupts  before  an  EGA  page  flip 

0  /  Old  IRQ  mask 

2bh, 2bh, 2bh, 2bh, 24h, 24h, 23h, 2eh 
0,0,0,0,0,24h,23h,2eh,2bh 


cx,  source_width 

si,  4 
dx,  -1 
ax,  ax 
[si],  dx 
[si+2],  ax 
bx,  plane_size 
[si+bx],  dx 
[si+bx+2],  ax 
bx,  plane_size 
[si+bx],  dx 
[si+bx+2],  ax 
bx,  plane_size 
[si+bx],  dx 
[si+bx+2],  ax 


mov  dx,  1  shl  7 

next_pixel_byte: 

jc  next_word 

mov  al,  es:[di] 

inc  di 

or  al,  al 

jz  end_pixel_byte 

xor  [si],  dx 

test  al,  1  shl  4 

jz  @F 

or  [si+2],  dx 

mov  bx,  plane_size 

xor  [si+bx],  dx 

test  al,  1  shl  7 

jz  @F 

or  [si+bx+2],  dx 

add  bx,  plane  size 

xor  [si+bx],  dx 

test  al,  1  shl  6 

jz  @F 

or  [si+bx+2],  dx 

add  bx,  plane_size 

xor  [si+bx],  dx 

test  al,  1  shl  5 

jz  end_pixel_byte 

or  [si+bx+2],  dx 


endjpixelbyte : 
shr 


even 

ega_base_port  dw 

default_retrace  label  word 
v_retrace_reg  db 

v  retrace  value  db  ? 


LOCAL  DATA  STORAGE  for  CS 


dl,  1 
dh,  1 

next_pixel_byte 

store_height 
next  row 


This  is  to  prep  for  the  next  INC 
Get  source  row  width 


SI  ->  next  word  in  line 
DX  -  the  destination  mask 

Set  the  mask  word 
Clear  the  sprite  word 
BX  offset  to  next  plane 
Set  the  mask  word 
Clear  the  sprite  word 
BX  offset  to  next  plane 
Set  the  mask  word 
Clear  the  sprite  word 
BX  offset  to  next  plane 
Set  the  mask  word 
Clear  the  sprite  word 

Start  at  MSB  which  is  pixel  LSB 

Only  be  set  by  pixel  shift  below 
Get  the  source  pixel  byte 
DI  ->  next  source  pixel  byte 
See  if  it's  anything  at  all 
Skip  all  the  checks 

Reset  the  mask  bit 

Check  bit  7 

Skip  if  nothing  here 

Place  the  sprite  bit 

BX  ->  plane  1  offset 

Clear  the  mask  bit 

Check  bit  6 

Skip  if  nothing  here 

Place  the  sprite  bit 

BX  ->  plane  2  offset 

Clear  the  mask  bit 

Check  bit  5 

Skip  if  nothing  here 

Place  the  sprite  bit 

BX  ->  plane  3  offset 

Clear  the  mask  bit 

Check  bit  4 

Skip  if  nothing  here 

Place  the  sprite  bit 

Move  pixel  bit  toward  MS  pixel  bit 

Loop  through  the  pixel  bytes 

One  less  row 


ega_segment  dw  0a800h  /  EGA  page  memory  segment  being  set  up 
old_vector  dw  0,0  /  Old  IRQ-2  vector  (as  Checkov  would  say  wecter) 


ret 

ega_convert  endp 

Z  EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE 
/  ui  EGA_CALCULATE (  source_ptr  ) 

/  Calculates  the  amount  of  storage  needed  for  an  unconverted  sprite 
/  Given : 

>  source_ptr  far  ->  disk  sprite  structure  to  convert  /  Returns: 

:  AX  =  number  of  bytes  needed  to  store  the  converted  sprite 

ega_calculate  proc  near  uses  si  ds,  source :dword 

Ids  si,  source  /  DS:SI  ->  sprite  structure  for  calculation 


0 continued  on  page  84) 
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listing  One  (Listing  continued,  text  begins  on  page  16.) 

mov 

ax,  [si]  ;  Get  the 

width  in  bytes 

short 

mask: 

add 

ax,  EGA  PIXELS  WORD-1 

Round  up  to  nearest  word 

jmp 

masked 

shr 

ax,  4  ; 

AX  =  number  of  words  for  stoarge 

add 

ax,  ax  ; 

AX  =  number  of  bytes  storage 

shifted: 

add 

ax,  ax  ; 

AX  =  number  of  globs  in  one  row 

mov 

plane  number,  NUMBER  OF 

PLANES-1 

add 

ax,  ax  ; 

AX  =  number  of  row/planes 

mov 

cl,  shift 

add 

ax,  ax 

mov 

bh,  -1 

mul 

word  ptr  [sij.int  height 

;  AX  =  bytes  per  row  *  number  of  rows 

shr 

bh,  cl 

add 

ax,  E  BODY 

AX  =  body  size  +  header  size 

next  shift_plane: 

ret 

mov 

dx,  GRAPHICS  12 

;  Talk  to  EGA  control  logic 

ega  calculate 

endp 

mov 

al,  4 

EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE 

mov 

ah,  plane  number 

void  PUT  SPRITE (  ui  X,  ui  Y,  ega  sprite 

structure  far  ‘SPRITE  PTR  ) 

out 

dx,  ax 

Maps  a  sprite  list  into  the  display  video  buffer 

Sprite  is  assumed  to  be  32-bits  wide 

mov 

dx,  SEQUENCE  REG 

;  Set  up  the  ports  for  writing  as  well 

Given : 

mov 

ax,  lOOh  +  MAP  MASK  REG 

X  =  X  pixel  location  of  sprite 

mov 

cl,  plane  number 

Y  =  Y  pixel  location  of  sprite 

shl 

ah,  cl 

SPRITE 

PTR  ->  sprite  structure  to  put  on  the  screen 

out 

dx,  ax 

Returns: 

The  sprite  is  mapped  onto  the  screen  buffer 

mov 

ch,  byte  ptr  number  of  rows 

put  sprite  proc  uses  di  si,  x:word,  y:word,  sprite  ptr: dword 

mov 

cl,  shift 

00: 

lodsw 

;  Get  the  sprite  mask 

local  mask  msw:word  ; 

OR'ed  with  the  mask  dword 

xchg 

ah,  al 

;  Switch  them  around 

local  mask  lsw: word 

ror 

ax,  cl 

local  or  msw 

word  ; 

AND' ed  with  the  sprite  dword 

mov 

bl,  ah 

;  Top  CL  bits  are  ones  to  mask  3rd  byte 

local  or  lsw 

word 

not 

bh 

;  BH  =  ~BH 

local  start  di:word 

and 

bl,  bh 

local  start  sirword 

or 

ah,  bh 

;  Now  set  the  top  ones  of  source  byte 

local  sprite  plane  sizerword 

mov 

dx,  es: [di] 

;  Get  the  first  destination  word 

local  number 

of  rows: word 

xchg 

ah,  al 

;  Re-order  the  mask  bytes 

local  shift:byte 

and 

dx,  ax 

;  Mask  it 

local  plane  number: byte 

lodsw 

;  Get  the  sprite 

push 

ds 

xchg 

ah,  al 

cmp 

y,  200 

See  if  below  200 

ror 

ax,  cl 

jc 

0F 

or 

dh,  al 

OR  DH  w/  old  AH 

short  done: 

mov 

al,  ah 

Save  the  upper  bits 

jmp 

done 

and 

ah,  bh 

Mask  off  other  bits 

@0:  cmp 

x,  640 

not 

bh 

BH  =  BH 

jnc 

short  done 

and 

al,  bh 

Cut  out  the  rotunds 

or 

dl,  al 

OR  least  sig.  bytes 

cld 

mov 

es:[di],  dx 

Save  that  first  word,  whew! 

mov 

es,  ega  segment 

Ids 

si,  sprite_ptr  ; 

DS:SI  ->  sprite  to  be  driven 

mov 

dl,  ah 

DL  *  pushed  up  sprite  bits 

mov 

ax,  80  ; 

Calculate  the  offset 

lodsw 

Get  the  next  sprite  mask 

mul 

y 

xchg 

ah,  al 

Switch  them  around 

mov 

CX,  X 

ror 

ax,  cl 

mov 

di,  cx 

mov 

dh,  ah 

DH  =  MS  shifted  mask  bits 

and 

cl,  7 

CL  ■  shift  value 

and 

ah,  bh 

Get  rid  of  shifted  bits 

mov 

shift,  cl 

or 

ah,  bl 

OR  with  shifted  mask,  previous  byte 

shr 

di,  3 

or 

dh,  bh 

Add  on  the  mask 

add 

di,  ax  ; 

DI  ->  byte  offset 

xchg 

ah,  al 

AH:AL  back  to  normal 

mov 

start_di,  di 

and 

es:[di+4],  dh 

Easy  way  to  get  rid  of  DH 

mov 

bl,  dl 

BL  =  previous  sprite  bits 

mov 

ax,  [si].e  height  ; 

AX  =  height  of  the  sprite  in  rows 

mov 

dx,  es:[di+2] 

Get  the  destination  word 

mov 

number  of  rows,  ax  ; 

Save  for  later  use 

and 

dx,  ax 

Mask  it 

shl 

ax,  3  ; 

AX  *=  8,  to  get  size  of  1  sprite  plane 

lodsw 

Get  the  sprite 

mov 

sprite_plane_size,  ax 

xchg 

ah,  al 

ror 

ax,  cl 

mov 

ax,  number  of  rows  ; 

Let's  see  if  it  goes  too  low 

or 

dh,  al 

OR  DH  w/  old  AH 

add 

ax,  y 

mov 

al,  ah 

Save  the  upper  bits 

sub 

ax,  BOTTOM  LINE 

not 

bh 

BH  =  ~BH 

jbe 

0F 

Skip  if  it  doesn't 

and 

ah,  bh 

Mask  off  other  bits 

sub 

number  of  rows,  ax 

Update  the  number  of  rows 

not 

bh 

BH  =  BH 

and 

al,  bh 

Cut  out  the  rotunds 

@0:  add 

si,  E  BODY 

SI  ->  start  of  sprite  body 

or 

al,  bl 

mov 

start  si,  si 

or 

dl,  al 

OR  least  sig.  bytes 

mov 

es:[di+2],  dx 

Save  that  first  word,  whew! 

cmp 

x,  640-32 

See  if  we  are  going  to  be  right 

or 

es:[di+4],  ah 

ja 

short  mask  ; 

Skip  if  no  mask 

cmp 

shift,  0 

add 

di,  80 

jnz 

shifted 

dec 

ch 

mov 

bl,  NUMBER  OF  PLANES 

jnz 

@B 

next_plane: 

dec 

bl 

mov 

di,  start  di 

mov 

si,  start  si 

mov 

dx,  GRAPHICS  12 

Talk  to  EGA  control  logic 

add 

si,  sprite_plane  size 

mov 

al,  4 

mov 

start  si,  si 

mov 

ah,  bl 

sub 

plane  number,  1 

out 

dx,  ax 

jc 

0F 

mov 

dx,  SEQUENCE  REG 

Set  up  the  ports  for  writing  as  well 

jmp 

next  shift_plane 

mov 

ax,  lOOh  +  MAP  MASK  REG 

00: 

jmp 

done 

mov 

cl,  bl 

shl 

ah,  cl 

masked 

out 

dx,  ax 

xor 

ax,  ax 

Set  up  masks  and  ORs 

mov 

mask  lsw,  ax 

mov 

cx,  number  of  rows 

mov 

mask  msw,  ax 

00:  mov 

ax,  es:[di]  ; 

Get  the  background  dword 

dec 

ax 

mov 

dx,  es:[di+2] 

mov 

or  lsw,  ax 

and 

ax,  [si] 

Do  the  mask  dword 

mov 

or  msw,  ax 

and 

dx,  [si+4] 

or 

ax,  [si+2]  ; 

Bring  on  the  sprite 

cmp 

x,  640-24 

See  if  we  have  masked  it  already 

or 

dx,  [si+6] 

jc 

0F 

Skip  if  we  have 

mov 

es:[di],  ax  ; 

Replace  with  new  graphic  dword 

mov 

mask  msw,  OffOOh 

mov 

es:[di+2],  dx 

mov 

or  msw,  Offh 

add 

si,  8  ; 

Next  row  stuff 

add 

di,  80 

cmp 

x,  640-16 

loop 

@B 

jc 

0F 

mov 

mask  msw,  -1 

Make  sure  nothing  gets  masked 

mov 

di,  start  di 

mov 

or  msw,  0 

mov 

si,  start  si 

add 

si,  sprite  plane  size 

cmp 

x,  640-8 

See  if  that's  all 

mov 

start  si,  si 

jc 

0F 

or 

bl,  bl 

mov 

mask  lsw,  OffOOh 

jnz 

next_plane 

jmp 

done 

( continued  on  page  86) 
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REAL-TIME  ANIMATION 


Listing  One  (Listing  continued,  text  begins  on  page  16.) 


@@ :  mov 

next_mask_plane : 
mov 


plane_number,  NUMBER_OF_P LANES -1 

dx,  GRAPHICS_12  ;  Talk  to  EGA  control  logic 

al,  4 

ah,  plane_number 
dx,  ax 


mov 

dx,  SEQUENCE  REG 

;  Set  up  the  ports  for  writ 

mov 

ax,  10 Oh  +  MAP_MASK_REG 

mov 

cl,  plane_number 

shl 

ah,  cl 

out 

dx,  ax 

mov 

cx,  number  of  rows 

mov 

ax,  [si]  , 

;  Get  the  first  mask 

mov 

dx,  [si+4] 

:  Get  the  second  mask 

or 

ax,  mask  lsw 

or 

dx,  mask  msw 

and 

ax,  es:[di]  ; 

:  Get  the  background  dword 

and 

dx,  es:[di+2] 

mov 

bx,  or_lsw  ; 

:  Get  the  OR  lsw 

and 

bx,  [si+2]  ; 

:  Bring  on  the  sprite 

or 

ax,  bx 

mov 

bx,  orjnsw 

and 

bx,  [si+6] 

or 

dx,  bx 

mov 

es : [di] ,  ax  ; 

:  Replace  with  new  graphic 

mov 

es:[di+2],  dx 

add 

si,  8  ; 

'  Next  row  stuff 

add 

di,  80 

loop 

@B 

mov 

di,  start_di 

mov 

si,  start_si 

add 

si,  sprite_plane_size 

mov 

start_si,  si 

sub 

plane_number,  1 

jnc 

next_mask_plane 

jmp 

done 

add  di,  dx 

dec  bx 

jnz  @B 

done :  ret 

ega_clear_area  endp 

;  EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE 
;  void  EGA_INSTALL ( ) 

;  Installs  IRQ-2  vectors  for  EGA  card 
;  Given : 

;  nothing 

;  Returns : 

;  -1  if  neither  EGA  or  VGA  else 

;  EGA  interrupt  vector  installed  and  enabled 

public  ega_install 


ega_install  proc 


done:  pop  ds 

ret 

put_sprite  endp 

;  EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE 
;  void  EGA_CLEAR_AREA (  ui  XI,  ui  Yl,  ui  X2,  ui  Y2  ) 

;  Clears  an  area  on  the  EGA  display  to  black 
;  Given: 

;  XI, Yl  =  X, Y  pixel  coordinates  of  the  upper  left  corner 

;  X2,Y2  =  X, Y  pixel  coordinates  of  the  lower  right  corner 

;  Returns: 

;  Rectangular  area  from  XI, Yl  to  X2,Y2  (inclusive)  cleared  to  black 

public  ega_clear_area 

ega_clear_area  proc  uses  ds  si  di,  xl:word,  yliword,  x2:word,  y2:word 

local  height: word 

local  di_start :word 

local  word_columns:word 

local  di  offset: word 


See  if  too  far  to  the  right 


bx,  ax 
height,  ax 

ax,  yl 
cx,  80 

di  offset,  cx 


Check  out  number  of  rows 


See  if  jerk  put  them  in  backwards 


BX  =  number  of  rows 


Check  our  starting  offset 


See  where  we  start 


dx,  es: [EGA_ADDRESS] 
ega_base_port,  dx 


int 

lOh 

cmp 

al,  lah 

jne 

ega  adaptor 

cmp 

bl,  7 

je 

vga  adaptor 

cmp 

bl,  8 

je 

it: 

vga_adaptor 

mov 

ax,  -1 

jmp 

short  done 

;  ES  ->  video  BIOS  data  area 


;  DX  ->  CRTC  Address  port 
;  Save  the  port  address 


;  Read  display  combination 


;  See  if  VGA 


ega_adaptor: 

mov 

mov 

xlat 

jmp 

vga_adaptor : 
mov 
out 
inc 


al,  es: [CRT_MODE]  ;  AL  =  video  BIOS  mode  number 

bx,  offset  EGA_settings 


al,  v_retrace_reg 
dx,  al 
dx 

al,  dx 

v_retrace_value,  al 

done_page_f lip,  -1 
do_page_flip,  0 

ax,  ax 
es,  ax 
bx,  0ah*4 
dx,  cs 

ax,  offset  ega_interrupt 


es:[bx],  ax 
es : [bx+2] ,  dx 
old_vector,  ax 
old_vector+2,  dx 

al,  21h 

old_irq_mask,  al 
al,  11111011b 
21h,  al 

dx,  ega_base_port 
ax,  default_retrace 
ah,  11001111b 
dx,  ax 
short  $+2 
ah,  00010000b 
dx,  ax 


AL  =  Vertical  retrace  register 


;  ES  ->  base  page 
;  Vector  for  IRQ  2 


;  Get  present  mask 


done:  ret 

ega_install  endp 

;  EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE 
;  void  EGA_RIP_OUT ( ) 

;  Undoes  all  the  interrupt  processing  for  the  EGA 
;  Given: 

;  nothing 

;  Returns : 

;  EGA  interrupt  vector  removed 

public  ega_rip_out 
ega_rip_out  proc  uses  es 

mov  ax,  old_vector  ;  See  if  installed 

or  ax,  old_vector+2 

jz  done  ;  Return  if  not  installed 


word_columns,  ax 
ax,  ax 

di_offset,  ax 
es,  ega_segment 

dx,  SEQUENCE_REG 
ax,  0f00h+MAP_MASK_REG 
dx,  ax 

dx,  di_offset 
ax,  ax 
di_start,  di 
cx,  word_columns 
stosw 


Set  up  the  ports  for  writing 


ax,  ax 

es,  ax 

bx,  0ah*4 

ax,  old_vector 

dx,  old_vector+2 

old_vector,  0 

old_vector+2,  0 

es : [bx] ,  ax 
es:[bx+2],  dx 

al,  21h 

ah,  old_irq_mask 
ah,  1  shl  2 
al,  11111011b 
al,  ah 
21h,  al 


;  ES  ->  base  page 
;  Vector  for  IRQ  2 


Restore  old  interrupt  mask 


(continued  on  page  88) 
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REAL-TIME  ANIMATION 


Listing  One  (Listing  continued,  text  begins  on  page  16.) 


dx,  3d4h 
ax,  2bllh 
dx,  ax 


mov 
mov 
out 
sti 
done :  ret 

ega_rip_out  endp 

EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE 
void  EGA_INTERRUPT (  void  ) 

Handles  all  the  interrupt  processing  for  the  EGA  controller 
Given: 

This  is  run  at  every  IRQ-2  spike  (ie.  vertical  retrace) 

Returns: 

If  FLIP_TURN  is  brought  to  zero,  EGA  visual  pages  are  swapped 
If  swap  is  made,  DO_PAGE_FLIP  set  to  0,  DONE_PAGE_FLIP  set  to  -1 

ega_interrupt  proc  far 


DX  ->  I/O  port  for  input  status 
Interrupt  is  ours 


push 

ax 

push 

dx 

push 

ds 

mov 

ax,  @DATA 

mov 

ds,  ax 

mov 

dx,  3c2h  ;  1 

in 

al,  dx 

test 

al,  1  shl  7 

jnz 

@F  ;  : 

pushf 

call 

dword  ptr  [old_vector] 

jmp 

done 

mov 

dx,  ega_base_port  ;  1 

in 

al,  dx 

push 

ax 

mov 

ax,  default  retrace 

and 

ah,  11101111b 

out 

dx,  ax 

jmp 

short  $+2 

mov 

al,  EOI 

out 

EOI_PORT,  al 

jmp 

short  $+2 

sti 

dec 

flip  turn 

jnz 

0F 

mov 

flip_turn,  4 

cmp 

do  page  flip,  0  ;  : 

jz 

0F 

mov 

al,  Och  ;  : 

mov 

ah,  byte  ptr  ega  segment+1 

shl 

ah,  4 

out 

dx,  ax  ;  ( 

xor 

ega_segment,  800h  ;  1 

jmp 

short  $+2 

mov 

do_page_flip,  0 

mov 

done  page  flip,  -1 

cli 

mov 

ax,  default  retrace 

and 

ah,  11011111b 

or 

ah,  00010000b 

out 

dx,  ax 

jmp 

short  $+2 

pop 

ax 

out 

dx,  al 

pop 

ds 

pop 

dx 

pop 

ax 

iret 

;  DX  ->  EGA/ VGA  register  port 


;  See  if  we  need  to  do  this 


Select  register  for  page  MSB 


Output  the  most  significant  byte 
Swap  the  active  page 


ega_interrupt  endp 
end 


Listing  Two 


End  Listing  One 


comment  \ 

Sprite  Circle  Handler 

Copyright  (c)  February  1989,  Ryu  Consulting, 
(916)  722  -  1939  anytime 
Written  by  Rahner  James,  CS 


EQUATES 

MAX_SPRITES  equ 

STRUCTURES 

sprite_structure  struc 
animate_ptr  dw 

sprite_width  dw 

sprite_height  dw 

sprite_body  db 

sprite_structure  ends 
struc 

x  dw 


0,0 

0 

0 


Width  in  words 
Height  in  pixels 


y 

dw 

0 

depth 

dw 

0 

pre_x 

dw 

0 

pre_y 

dw 

0 

dest  x 

dw 

0 

dest  y 

dw 

0 

adder  x  dw 

0 

adder  y  dw 

0 

sprite  ptr 

dw 

0,( 

next_node 

dw 

0 

sprite  node 
.data 

ends 

.  **********, 

********** 

*  *  *  *  i 

;  DATA 

VARIABLES 

and 

extrn 

extrn 


done_page_f lip: by t e ,  do_page_f 1 ip : by t e 
min_x:word,  min_y:word,  max_y:word,  max_x:word 


first_sprite  dw  0 

public  sprite_list 
sprite_list  sprite_node 


MAX_SPRITES  dup (<>) 


pre_max_x 

pre_max_y 

pre_min_x 

pre_min_y 

.code 


dw 

dw 

dw 

dw 


639 

199 

0 

0 


ROUTINES  and  EXTERNAL  CODE  DEFINITIONS 
extrn  do_background:near,  put_sprite:near 


void  DO_SPRITE_LIST (  void  ) 

Sets  up  the  sprites  on  the  unviewed  back  page 
Given : 

A  sprite  list  has  been  created  and  is  stored  in  the  array  SPRITE_LIST 
Returns: 

If  DONE_PAGE_FLIP  is  0,  no  processing  is  done 

else  all  sprites  in  the  sprite  list  are  put  on  the  non-visual  page 
then  DONE  PAGE  FLIP  is  set  to  0  and  DO  PAGE  FLIP  is  set  to  -1 


do_sprite_list  proc  uses  si 


cmp 

jnz 

jmp 

@0:  call 


done_page_f lip,  0 
@F 

done 

do_background 


See  if  we  need  to  do  this 


mov 

ax,  pre  max  x 

mov 

max  x,  ax 

mov 

ax,  pre_max_y 

mov 

max  y,  ax 

mov 

ax,  pre  min  x 

mov 

min  x,  ax 

mov 

ax,  pre  min  y 

mov 

min  y,  ax 

xor 

ax,  ax 

mov 

pre  max_x,  ax 

mov 

pre  max  y,  ax 

dec 

ax 

mov 

pre_min_x,  ax 

mov 

pre_min_y,  ax 

mov 

si,  first  sprite 

3rite: 

or 

si,  si 

jnz 

@F 

jmp 

almost_done 

mov 

ax,  [si]  .x 

mov 

[si] .pre_x,  ax 

cmp 

[si] .dest_x,  ax 

je 

no_add  x 

mov 

cx,  [si] .dest  x 

sub 

cx,  [si] .x 

jnc 

@F 

neg 

cx 

add 

ax,  [si] .adder  x 

mov 

[si] .x,  ax 

sub 

ax,  [si] .dest  x 

jnc 

@F 

neg 

ax 

cmp 

cx,  ax 

jnc 

no_add  x 

mov 

ax,  [si] .dest_x 

mov 

[si] .x,  ax 

x: 

mov 

ax,  [si]  .y 

mov 

[si] .pre_y,  ax 

cmp 

[si] .dest_y,  ax 

je 

no_add_y 

mov 

cx,  [si].dest_y 

sub 

cx,  [si]  .y 

jnc 

@F 

neg 

cx 

add 

ax,  [si] . adder  y 

mov 

[si] .y,  ax 

sub 

ax,  [si] .dest  y 

jnc 

@F 

neg 

ax 

cmp 

cx,  ax 

jnc 

no_add_y 

mov 

ax,  [si].dest_y 

mov 

[si] .y,  ax 

T- 

cmp 

[si] .y,  200 

Clear  out  some  variables 


SI  ->  sprite  node  to  start  with 
See  if  this  is  a  NULL  pointer 


See  if  we  are  already  there 

Skip  if  we  are 

Get  our  absolute  value 


See  if  we  are  already  there 

Skip  if  we  are 

Get  our  absolute  value 


See  if  beyond  bottom  line 

(continued  on  page  90) 
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Listing  Two  (Listing  continued,  text  begins  on  page  16.) 


else  ! 0  if  there  is  no  room 


jnc 

pre  next  sprite 

mov 

ax,  [si] .x  ; 

See  if  we  need  to  update  some  things 

cmp 

ax,  640  ; 

See  if  beyond  right  column 

jnc 

pre  next  sprite 

cmp 

ax,  pre  min  x  ; 

See  if  pre  x  <  min  x 

jnc 

@F 

Skip  if  not 

mov 

pre_min_x,  ax  ; 

Update  with  new  MIN  X 

@0: 

mov 

ax,  [si] .y  ; 

See  if  need  to  update  min  y 

cmp 

ax,  pre  min  y 

jnc 

@F 

mov 

pre_min_y,  ax 

00: 

les 

bx,  dword  ptr  [si]. sprite 

_ptr  ;  ES:BX  ->  sprite  structure 

mov 

ax,  es: [bx] .sprite  width 

inc 

ax 

if 

(@Cpu  AND  2) 

shl 

ax,  4  ; 

AX  =  AX  *  16 

else 

rept 

4 

add 

ax,  ax 

endm 

endif 

add 

ax,  [si] .x 

cmp 

pre  max  x,  ax  ; 

See  if  >  max  x 

jnc 

@F 

Jump  if  not 

mov 

pre  max  X,  ax  ; 

Assume  we  are  going  to  save  it 

00: 

mov 

ax,  es: [bx] . sprite_height 

add 

ax,  [si] . y 

cmp 

pre  max  y,  ax  ; 

See  if  >  max_x 

jnc 

@F 

Jump  if  not 

mov 

pre_max_y,  ax  ; 

Assume  we  are  going  to  save  it 

00: 

push 

es  ; 

Set  up  for  call  to  put_sprite() 

push 

bx 

push 

[si] .y 

push 

[si] .x 

call 

put_sprite 

add 

sp,  4  ; 

Clear  the  stack 

pop 

bx  ; 

ES:BX  ->  sprite  pointer 

pop 

es 

les 

bx,  dword  ptr  es: [bx] .animate_ptr 

mov 

[si] .sprite_ptr,  bx 

mov 

[si] .sprite_ptr+2,  es 

pre_next_sprite : 

mov 

si,  [si] .next_node  ; 

SI  ->  next  sprite  node  in  line 

jmp 

next_sprite 

almost 

done : 

mov 

ax,  pre_max  x 

cmp 

ax,  640 

jb 

@F 

mov 

ax,  639 

mov 

pre_max_x,  ax 

00: 

cmp 

pre  min  x,  ax 

jb 

@F 

dec 

ax 

mov 

pre_min_x,  ax 

00: 

mov 

ax,  pre_max_y 

cmp 

ax,  200 

jb 

@F 

mov 

ax,  199 

mov 

pre_max_y,  ax 

00: 

cmp 

pre  min  y,  ax 

jb 

@F 

mov 

pre_min_y,  ax 

insert_sprite  proc  uses  si,  xl  .-word,  yl  .-word,  d_x : word,  d_y:  word,  \ 

plus_x:word,plus_y:word,  the_depth: word, \ 
sprite :dword 


mov 

cx,  MAX_SPRITES 

mov 

bx,  (offset  sprite  list 

@0:  add 

bx,  size  sprite  node 

mov 

ax,  [bx] .sprite_ptr 

or 

ax,  [bx] .sprite  ptr+2 

loopnz 

@B 

jnz 

done  bad 

les 

ax,  sprite 

mov 

[bx] .sprite  ptr,  ax 

mov 

[bx] .sprite_ptr+2,  es 

mov 

ax,  xl 

mov 

[bx] .x,  ax 

mov 

[bx] .pre_x,  ax 

mov 

ax,  yl 

mov 

[bx] .y,  ax 

mov 

[bx] .pre_y,  ax 

mov 

ax,  d  x 

mov 

[bx] .dest  x,  ax 

mov 

ax,  d  y 

mov 

[bx] .dest_y,  ax 

mov 

ax,  plus  x 

mov 

[bx]. adder  x,  ax 

mov 

ax,  plus_y 

mov 

[bx] .adder_y,  ax 

mov 

ax,  the_depth 

mov 

[bx]. depth,  ax 

mov 

dx,  bx 

mov 

si,  first_sprite 

mov 

bx,  offset  first  sprite 

mov 

cx,  MAX_SPRITES 

@0 :  or 

si,  si 

jz 

@F 

cmp 

ax,  [si] .depth 

jnc 

@F 

mov 

bx,  si 

mov 

si,  [si] .next  node 

loop 

done_bad : 

@B 

mov 

ax,  -1 

jmp 

short  done 

@0:  xchg 

si,  dx 

mov 

[si] .next_node,  dx 

cmp 

bx,  offset  first  sprite 

jne 

@F 

mov 

[bx],  si 

jmp 

short  done_good 

0  0 :  mov 

[bx] .next_node,  si 

done_good : 

xor 

done :  ret 

ax,  ax 

-  (size  sprite_node) 

;  See  if  this  has  been  set  yet 


;  ES:AX  ->  sprite  location 
;  Save  it 


;  Set  up  the  structure 


;  This  is  used  in  the  following  loop 
;  Save  this  sprite  entry  for  later 

;  SI  ->  sprite  furthest  from  the  viewer 
;  BX  ->  previous  sprite  entry 

;  See  if  it's  a  NULL  ptr 
;  Skip  out  if  it  is 
;  See  if  farther  from  observer 

;  BX  =  this  pointer 
;  SI  ->  next  sprite  node  in  line 


;  Indicate  we  had  a  problem 


;  SI  ->  sprite_list [i] 


insert_sprite  endp 

;  void  ADD_SPRITE (  sprite_structure  far  *DEST,  far  * SOURCE  ) 

;  Adds  a  self-relative  sprite  motion  to  the  end  of  a  sprite  circle 
;  Given: 

;  DEST  ->  sprite  circle  header 

;  SOURCE  ->  sprite  to  add  on 

;  Returns: 

;  SOURCE  is  added  to  the  end  of  the  sprite  linked  list  and  the 

;  circle  ends  are  rejoined,  may  the  circle  be  unbroken  (ie  Johnny  Cash) 


@0: 

mov 

done_page_flip,  i 

mov 

do_page_flip,  -1 

done: 

ret 

do_sprite_list  endp 

;  void  CLEAR_SPRITE_LIST (  void  ) 

;  Zeros  out  the  present  sprite  list 
;  Given: 

;  nothing 

;  Returns: 

;  FIRST_SPRITE  and  SPRITE_LIST  array  are  zeroed 

clear_sprite_list  proc  uses  di 
cld 

mov  di,  offset  sprite_list 

mov  ax,  ds 

mov  es,  ax 

xor  ax,  ax 

mov  first_sprite,  ax 

mov  cx,  (MAX_SPRITES  *  (size  sprite_node) ) /2 

rep  stosw 


add_sprite  proc  uses  si  di  ds,  dest:dword,  source :dword 


Ids 

les 

next_sprite: 

mov 

cmp 

jne 

mov 

cmp 

je 

@@:  ids 

jmp 


si,  dest 
di,  source 

ax,  [si] ,animate_ptr  ;  See  if  this  is  the  end  of  the  line 
ax,  word  ptr  dest 
@F 

ax,  [si] .animate_ptr+2 

ax,  word  ptr  dest+2 

got_the_end 

si,  [si] .animate_ptr 

next_sprite 


got_the_end : 

mov  [si] . animate_ptr,  di 

mov  [si] .animate_ptr+2,  es 

mov  ax,  word  ptr  dest 

mov  es : [di] .animate_ptr,  ax 

mov  ax,  word  ptr  dest+2 

mov  es: [di] .animate_ptr+2,  ax 


ret 

add_sprite  endp 


ret 

clear_sprite_list  endp 

;  int  INSERT_SPRITE (  ui  XI, ui  Yl,  ui  D_X,ui  D_Y,  ui  PLUS_X,ui  PLUS_Y, 

;  ui  THE_DEPTH,  sprite_structure  far  ‘SPRITE  ) 

;  Inserts  the  first  sprite  of  a  sprite  circle  into  the  linked  list  of  circles 
;  Given : 

;  XI, Yl  =  pixel  location  of  the  upper  left  corner  of  the  sprite 

;  D_X,D_Y  =  pixel  location  of  the  destination  of  the  sprite 

:  PLUS_X, PLUS_Y  =  pixels  the  sprite  moves  every  page  flip 

;  THE_DEPTH  =  apparent  distance  of  the  sprite  from  the  viewer 

;  SPRITE  ->  sprite  to  insert 

;  Returns : 

;  If  0,  sprite  pointer  was  inserted  in  the  array 


end 

End  Listing  Two 


( continued  on  page  92) 
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REAL-TIME  ANIMATION 


Listing  Three  (Listing  continued,  text  begins  on  page  16.) 


TITLE:  SPRITES. C 

Displays  a  sprite  file  on  an  EGA  screen 
Written  by:  Rahner  James,  CS 

of  Ryu  Consulting,  Inc. 


#include  <stdio.h> 
♦include  <dos.h> 
♦include  <fcntl.h> 


VARIOUS  DEFINITIONS 

♦pragma  pack(l) 

typedef  unsigned  char  uc. 

typedef  unsigned  int  ui, 

typedef  unsigned  long  ul, 

/*******************************************»******************************* 
EXTERNAL  DECLARATIONS 

**************************************************************************** 
extern  void  ega_convert 
0; 

extern  ui  ega_calculate (  uc  far  *  ); 
extern  void  ega_install {) ; 

extern  void  ega_clear_area (  ui,  ui,  ui,  ui  ); 
/**************«************************************************************ 
GLOBAL  DATA 

ui  min  x=0,  min  y=0,  max  x=639,  max  y=199; 
/*************************************************************************** 
long  READ_ALL_FILE (  uc  ‘FILENAME,  uc  huge  ‘BUFFER,  ul  BUFFER_SIZE  ) 
Opens  and  reads  an  entire  sprite  file 
Given: 

FILENAME  ->  name  of  sprite  file  to  read 
BUFFER  ->  buffer  to  read  the  sprite  file  into 
BUFFER_SIZE  =  number  of  bytes  the  buffer  can  hold 

Returns: 

File  is  opened,  read  and  closed 
Number  of  bytes  read,  if  all  went  well 
If  error,  returns  -1 

**************************************************************************** 
long  read_all_file (  uc  ‘filename,  uc  huge  ‘buffer,  ul  buffer_size  ) 

( 

long  rv  =  0; 

ui  handle,  dos_return,  amount_read; 

ui  amount_to_read; 

if  (  _dos_open(  filename,  0_RD0NLY,  Shandle  )  ) 
return  -1; 

while  (  buffer_size  ) 

{ 

amount  to  read  =  buffer  size<60000L  ?  buffer  size  :  60000L; 


if  (  _dos_read(  handle,  buffer+rv,  amount_to_read,  &amount_read  )  ) 


{ 


rv  =  -1; 
break; 


rv  +=  amount_read; 
if  (  amount_read  <  60000  ) 
break; 

buffer  size  -=  amount  read; 


_dos_close(  handle  ); 
return  rv; 

} 

/*********************************************************** 
void  DO_BACKGROUND (  void  ) 

Sets  up  the  background  for  the  sprite  visual  screen 
Given: 

nothing 

Returns : 

visual  sprite  screen  erased 

void  do_background (  void  ) 

{ 

ega_clear_area (  min_x,  min_y,  max_x,  max  y  ); 

uc  SET_MODE (  uc  MODE_NUMBER  ) 

Sets  the  video  mode 
Given: 

Mode  number  to  set  video  to 

Returns: 

Present  video  mode  number 

uc  set_mode (  uc  mode_number  ) 

{ 

uc  rv; 

union  REGS  regs; 

regs.h.ah  =  15; 

int86(  0x10,  &regs,  &regs  ); 

rv  =  regs.h.al; 

regs.h.ah  =  0; 
regs.h.al  =  mode_number; 
int86(  0x10,  &regs,  Sregs  ); 
return  rv; 


MAIN (  int  ARGC,  uc  *ARGV[]  ) 

Allocates  memory,  reads  in  a  sprite  file,  displays  the  sprites 
until  a  key  is  pressed,  frees  up  memory  and  interrupt  vectors 
Given: 

ARGC  =  number  of  command  line  values,  must  be  >  1 
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ARGV[1]  ->  file  name  of  the  sprite  file  to  display 

Returns : 

0  if  all  went  well,  otherwise  numbered  according  to  error 

main(  int  argc,  uc  *argv[]  ) 

{ 

ui  i,  x,  y; 

uc  far  *file_ptr,  huge  *sprite_start,  huge  *buffer_start; 

uc  huge  *sprite_ptr [20J ; 

uc  old_mode; 

ui  memory_segment ; 

ul  memory_size=0,  file_size; 

/*  Check  initial  values  and  allocate  memory  for  buffers  */ 
if  (  argc<2  ) 

{ 

printf(  "\nNo  file  name  has  been  given\n"  ); 
exit  (  1  ) ; 

) 


else 

filesize  =  0; 

#  } 

/  /*  Create  linked  list  of  sprite  circles  */ 

insert_sprite {  100,100,  100,100,  0,0,  7,  sprite_ptr [0]  ); 
for  (  x=l  ;  x<i  ;  ++x  ) 

add_sprite(  sprite_ptr [0] ,  sprite_ptr [x]  ); 

/*  Setup  the  EGA  screen  mode  and  interrupt  vector  */ 
old_mode  =  set_mode(  0x10  ); 
ega_install () ; 

/*  Process  the  sprite  list  until  someone  taps  a  key  */ 
while  (  ikbhitO  ) 

do_sprite_list  () ; 

/*  Restore  screen  and  allocated  memory  to  original  state  */ 
ega_rip_out ( ) ; 
set_mode (  old_mode  ) ; 

_dos_f reemem (  memory_segment  ); 
exit (  0  ) ; 


if  (  _dos_allocmem(  -1,  (ui  *) &memory_size  )  ) 

{ 

if  (  _dos_allocmem(  memory_size,  &memory_segment  )  ) 

{ 

printf(  "\nMemory  allocation  error\n"  ); 
exit  (  2  ) ; 

} 

) 

else 

( 

memory_segment  =  memory_size; 
memory_size  =  Oxffff; 

) 

memory_size  «=  4; 

buffer~start  =  (uc  huge  *) ( (ul)memory_segment  «  16L); 

/*  Read  in  the  sprite  file  and  then  convert  it  to  our  intenal  structure  */ 
file_ptr  =  buffer_start; 

if  (  (file_size=read_all_file(argv(l) , file_ptr,memory_size) )  ==  -1  ) 

I 

_dos_f reemem (  memory_segment  ); 

printf(  "\nGot  error  reading  %s.  Aborting. \n",  argvfl]  ); 
exit  (  3  ) ; 

) 

clear_sprite_list () ; 

sprite_start  =  file_ptr  +  file_size; 

for  (  i-0  ;  i<20  &&  file_size  ;  ++i  ) 

{ 

ega_convert (  sprite_ptr [i]=sprite_start,  file_ptr  ); 
x  =  ega_calculate (  file_ptr  ); 
sprite_start  +=  x; 

x  =  (ui) *file_ptr  *  (ui) * (file_ptr+2)  +  4; 

file_ptr  +=  x; 

if  (  file_size  >  (ul)x  ) 

file_size  -=  (ul)x; 


End  Listing  Three 


Listing  Four 


sprite. obj:  sprite. c 

cl  /c  sprite. c 


ega_drv.obj : 

masm 


ega_drv.asm 

ega_drv; 


gen_asm.obj : 

masm 


gen_asm.asm 

gen_asm; 


sprite.exe: 

link 


sprite. obj  ega_drv.obj  gen_asm.obj 
sprite+gen_asm+ega_drv; 


End  Listings 
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DMA 


Listing  One  ( Text  begins  on  page  28.) 


/*  dma.c  —  subroutines  for  dma  data  acquisition 

*  The  calling  routine  must  declare  the  variables  in  the  "extern"  list 

*  below,  and  the  reset_irq()  function.  Communication  from  the  main 

*  program  to  the  subroutines  is  mostly  through  these  global  variables. 

*  The  calling  routine  must  give  values  to  dma_chan,  dma_irq  and  buf_size, 

*  then  call  alloc_dma_buf () ,  dma_setup(),  and  start_dma().  As  each 

*  dma  buffer  fills  up,  the  interrupt  service  routine  calls  start_dma()  on 

*  the  next  buffer.  The  calling  routine  can  wait  for  buf_index  to 

*  change,  then  process  data  pointed  to  by  curr_buf.  Cleanup  is  done 

*  by  dma_finish () ,  which  is  called  automatically  when  the  program  exits. 

* 

*  Compiler:  Microsoft  C  Version  5.0 

*  Set  /Gs  switch  to  remove  stack  probes  (a  necessity  for  any 

*  function  called  at  interrupt  state!) 

*  Tom  Nolan  -  11/3/89 


♦pragma  check_stack (off ) 
# include  <dos.h> 


/*  DMA  Register  Definitions  */ 


♦define 

DMA0  BASE 

0x00 

/* 

address  of  dma  controller  (chan  0-3) 

♦define 

DMA1_BASE 

OxCO 

/* 

address  of  dma  controller  (chan  4-7) 

/*  Interrupt  Controller  Definitions 

*/ 

♦define 

INTA00 

0x20 

/* 

base  address  of  int  ctrlr  */ 

♦define 

INT A0 1 

0x21 

/* 

address  of  int  ctrlr  2nd  reg  */ 

♦define 

EOI 

0x20 

/* 

code  for  non-specific  end-of-int  */ 

/*  External  Variables  */ 


extern 

char 

far  *dma_buffers(] j 

:  /* 

array  containing  buffer  addresses  */ 

{ 

basereg 

, 

DMA0_BASE 

+ 

sel  1 

'  2; 

/* 

standard  dma  controller 

*/ 

extern 

int 

buf_index; 

/* 

index  of  current  buffer  in  array  */ 

cntreg 

= 

basereg  + 

1; 

/* 

note  that  this  controller 

*/ 

extern 

char 

far  *curr  buf; 

/* 

pointer  to  just-filled  buffer  */ 

maskreg 

= 

DMA0  BASE 

+ 

10; 

/* 

is  addressed  on  byte 

*/ 

extern 

unsigned  buf  size; 

/* 

size  of  buffers  in  bytes  */ 

modereg 

= 

DMA0_BASE 

+ 

11; 

/* 

boundaries 

*/ 

extern 
*  / 

int 

lost_buffers; 

/* 

count  of  buffers  unable  to  be  written 

) 

extern 

int 

dma  irq; 

/* 

h/w  interrupt  when  dma  complete  (0-7) 

else 

{ 

*/ 

basereg 

= 

DMA1_BASE 

+ 

sel  1 

'  4; 

/* 

alternate  dma  ctrlr  (AT  only) 

extern 

int 

dma_chan; 

/* 

channel  number  for  dma  operation  */ 

*/ 

extern 

int 

file  handle; 

/* 

handle  of  archive  file  (0=no  file)  */ 

cntreg 

= 

basereg  + 

2; 

/* 

note  that  this  controller 

extern 

void 

reset_irq() ; 

/* 

function  to  reset  interrupt  request  */ 

*/ 

*  / 

maskreg 

- 

DMA1_BASE 

+ 

20; 

/* 

is  addressed  on  word 

/*  local  variables  -  placed  in 

static  . 

storage  to 

/ 

modereg 

= 

DMA1_BASE 

+ 

22; 

/* 

boundaries 

*  avoid  excessive  stack  usage 

in  interrupt  routines  */ 

*/ 

static  union  REGS  r;  /* 

static  struct  SREGS  s;  /* 

static  int  sel;  /* 

static  int  basereg;  /* 

static  int  cntreg;  /* 

static  int  maskreg;  /* 

static  int  modereg;  /* 

static  int  pagereg;  /* 

static  int  page_tbl[]  =  /* 

(  0x87,  0x83,  0x81,  0x82,  /* 

0x8f ,  0x8b,  0x89,  0x8a  };  /* 

char  far  *dos_crit_addr;  /* 

static  void  /* 

(interrupt  far  *dma_int_save) () ; 


/*  macros  for  extracting  bytes  from  20-bit  addresses  */ 

♦define  LSB(x)  ‘((unsigned  char  *)  &x) 

♦define  MSB(x)  ‘(((unsigned  char  *)  &x)  +  1) 

♦define  PAGE(x)  ‘(((unsigned  char  *)  &x)  +2) 

/*  Function  Prototypes  */ 

void  dma_setup(void) ; 

void  dma_finish (void) ; 

int  alloc_dma_buf (void) ; 

void  start_dma(char  far  *,  unsigned); 

void  interrupt  far  dma_isr (void) ; 

int  write_buf(); 


general  registers  */ 

segment  registers  */ 

dma  channel  select  bits  */ 

dma  controller  base  address  register 

dma  controller  count  register  */ 

dma  controller  mask  register  */ 

dma  controller  mode  register  */ 

dma  page  address  register  */ 

table  of  page  register  addresses  */ 

for  dma  channels  0,  1,  2,  3  */ 

4,  5,  6,  7  */ 

address  of  DOS  critical  section  flag  : 
space  for  saved  int  vector  contents  *, 


int  alloc_dma_buf () 
{ 

unsigned  buf; 
unsigned  max; 
unsigned  seg; 
unsigned  size; 


/*  allocate  a  pair  of  dma  buffers  */ 

/*  temp  variables  for  various  */ 

/*  paragraph  addreses  */ 

/*  buffer  size  in  paragraphs  */ 


/*  This  routine  allocates  a  pair  of  buffers  that  can  be 

*  filled  by  dma.  The  buffers  are  guaranteed  to  be 

*  aligned  so  that  they  do  not  cross  physical  page  boundaries. 

*  Before  calling  this  routine,  set  the  value  of  buf_size  to 

*  the  required  number  of  bytes  in  each  buffer.  The  maximum 

*  buffer  size  is  64K  bytes,  which  can  be  allocated 

■  *  by  specifying  a  buf_size  of  zero.  The  byte  count  is  converted 

*  to  paragraphs,  which  are  the  units  the  DOS  memory  allocation 

*  functions  work  with.  Buffer  addresses  are  returned  in  dma_buf fers [0] 

*  and  dma_buffers [1] .  The  return  value  is  zero  if  the  allocation  suoceded, 
non-zero  (an  MS-DOS  error  code)  otherwise. 


*/ 


size  =  (buf_size  ==  0)  ?  /* 

0x1000  :  buf_size  »  4;  /* 
_dos_allocmem(0xffff,  &max);  /* 

_dos_allocmem(max,  &seg) ;  /* 


convert  bytes  to  paragraphs  */ 
..by  dividing  by  16  */ 
get  max  paragraphs  from  dos  */ 
now  grab  it  all  */ 


buf  =  seg; 

if (  ((buf  +  size  -  1)  &  OxfOOO) 

!=  (buf  &  OxfOOO)  ) 
buf  =  (buf  &  OxfOOO)  +  0x1000; 

dma_buf fers [0]  =  (char  far  *) 

((long)  buf  «  16); 

buf  +=  size; 

if(  ((buf  +  size  -  1)  &  OxfOOO) 

!=  (buf  &  OxfOOO)  ) 
buf  =  (buf  &  OxfOOO)  +  0x1000; 

dma_buffers [1]  =  (char  far  *) 

((long)  buf  «  16); 

size  =  buf  +  size  -  seg; 
return 

_dos_setblock (size,  seg,  &max), 


/*  initial  attempt  at  buffer  segment 

/*  if  buffer  crosses  */ 

/*  phys  page  bdry  */ 

/*  ...adjust  to  next  phys  page  */ 

/*  convert  buffer  segment  */ 

/*  ...  to  far  pointer  for  return  */ 

/*  initial  attempt  at  next  buffer  */ 


/*  adjust  if  it  crosses  page  bdry  */ 
/*  return  it  as  a  far  pointer  */ 


/*  compute  actual  size  needed  */ 

/*  free  unneeded  memory  and  */ 
/*  return  error  if  not  enough  */ 


void  dma_setup()  /*  set  up  for  dma  operations  */ 

{ 

/*  Before  calling  this  routine  set  the  following  variables: 

*  dma_chan  -  channel  number  (hardware  dependent) 

*  dma_irq  -  interrupt  request  number  0-7  (hardware  dependent) 


sel  =  dma_chan  &  3; 
pagereg  =  page_tbl [dma_chan] ; 


if (dma  chan  <  4) 


/*  isolate  channel  select  bits  */ 
/*  locate  corresponding  page  reg 


/*  setup  depends  on  chan  number  */ 


r.h.ah  =  0x34; 


/*  dos  "get  critical  flag  addr"  function 


intdosx(&r,  &r,  &s); 
dos_crit_addr  =  (char  far  *)  /* 

(((long)  s.es  «  16)  !  r.x.bx), 

if (dma_irq  <  0  ! !  dma_irq  >  7)  /* 

return; 

dma_int_save  =  /* 

_dos_getvect (dma_irq  +  8) ; 
_dos_setvect (dma_irq+8,  dma_isr) ; 


intmsk  =  inp(INTAOl);  /* 
intmsk  &=  “(1  «  dma_irq) ;  /* 
outp(INTA01,  intmsk);  /* 
atexit(dma  finish);  /* 


save  its  address  so  it  can  be  tested  */ 
/*  ...  as  a  far  pointer  */ 

validate  interrupt  number  */ 

save  current  contents  of  dma  int  vec  */ 

/*  set  up  new  int  service  routine  */ 

get  current  interrupt  enable  mask  */ 
clear  mask  bit  for  dma  interrupt  */ 
output  new  mask,  enabling  interrupt  */ 
register  exit  function  */ 


static  void  dma_finish{) 

( 

int  intmsk; 

intmsk  =  inp(INTAOl); 
intmsk  !=  (1  «  dma_irq) ; 
outp(INTA01,  intmsk); 


/*  called  via  atexitO  mechanism  */ 


/*  get  current  interrupt  enable  mask  */ 

/*  set  mask  bit  for  dma  interrupt  */ 

/*  output  new  mask,  disabling  interrupt  */ 


_dos_setvect (dma_irq+8,  dma_int_save) ;  /*  restore  old  vector  contents  */ 


void  start_dma (buf ,  count) 
char  far  *buf; 
unsigned  count; 


/*  start  a  dma  operation  */ 

/*  address  of  buffer  to  be  filled  */ 
/*  size  of  buffer  in  bytes  */ 


/*  20-bit  address  of  dma  buffer  */ 


int  page; 

unsigned  long  addr  = 

FP_OFF (buf)  + 

((long)  FP_SEG(buf )  «  4); 

/*  This  routine  starts  a  dma  operation.  It  needs  to  know: 

*  -  the  address  where  the  dma  buffer  starts; 

*  -  the  number  of  bytes  to  transfer; 

*  The  dma  buffer  address  is  supplied  in  segmented,  far-pointer 

*  form  (as  returned  by  alloc_dma_buf () ) .  In  this  routine  it  is 

*  converted  to  a  20-bit  address  by  combining  the  segment  and 

*  offset.  The  upper  four  bits  are  known  as  the  page  number,  and 

*  are  handled  separately  from  the  lower  16  bits.  The  transfer 

*  count  is  decremented  by  1  because  the  dma  controller  reaches 

*  terminal  count  when  the  count  rolls  over  from  0000  to  ffff. 

*  The  dma  transfer  stops  when  the  channel  reaches  terminal  count. 

(continued  on  page  96) 
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listing  One  (Listing  continued,  text  begins  on  page  28.) 


Listing  Two 


*  The  terminal  count  signal  is  turned  around  in  the  interface 

*  hardware  to  produce  an  interrupt  when  dma  is  complete. 

*  Channels  4-7  are  on  a  separate  dma  controller,  available  on 

*  the  PC-AT  only.  They  perform  16-bit  transfers  instead  of  8-bit 

*  transfers,  and  they  are  addressed  in  words  instead  of  bytes. 

*  This  routine  handles  the  addressing  requirements  based 

*  on  the  channel  number. 

*  dma_setup ( )  needs  to  be  called  before  start_dma()  in  order  to 

*  assign  values  to  maskreg,  modereg,  etc. 


page  =  PAGE (addr); 

if(dma_chan  >=  4) 

{ 

count  »=  1; 
addr  »=  1; 
page  &=  0x7e; 


count — ; 
outp (maskreg, 
outp (modereg, 
outp (basereg, 
outp (basereg, 
outp(pagereg, 
outp(cntreg, 
outp(cntreg, 
outp (maskreg, 


sel  !  0x04) 
sel  0x44) 
LSB(addr)  ) 
MSB (addr)  ) 
page  ) 
LSB (count) ) 
MSB (count)) 
sel  ) 


/*  extract  upper  bits  of  address  */ 

/*  for  word-oriented  channels...  */ 

/*  convert  count  to  words  */ 

/*  convert  address  to  words  */ 

/*  address  bit  16  is  now  in  'addr'  */ 


/*  compute  count-1  (xfr  stops  at  ffff)  */ 
/*  set  mask  bit  to  disable  dma  */ 

/*  xfr  mode  (sngl,  inc,  noinit,  write)  */ 
/*  output  base  address  lsb  */ 

/*  output  base  address  msb  */ 

/*  output  page  number  to  page  register  */ 
/*  output  count  lsb  */ 

/*  output  count  msb  */ 

/*  clear  mask  bit,  enabling  dma  */ 


/*  test.c  —  test  dma  data  acquisition 
* 

*  Compiler:  Microsoft  C  Version  5.0 

*  Compile  with  /Gs  option  (or  use  #pragma)  because 

*  reset_irq()  is  called  from  interrupt. 

*  Tom  Nolan  -  11/3/89 


♦include  <bios.h> 

int  far  *dma_buffers [2] ; 

int  far  *curr_buf; 

int  buf_size; 

int  buf_index; 

int  dma_irq  =  3; 

int  dma_chan  =1; 

int  file_handle  =  0; 

int  lost  buffers  =  0; 


/*  pointers  to  two  buffers  */ 

/*  pointer  to  current  buffer  */ 

/*  buffer  size  */ 

/*  index  of  current  buffer  */ 

/*  hardware  int  request  line  */ 

/*  hardware  dma  channel  number  */ 
/*  file  handle  */ 

/*  write  errors  */ 


/*  In  this  program,  each  dma  buffer  will  be  filled  with 

*  NUMFR  "frames",  each  of  size  FRSIZE  (in  words) .  The  second 

*  word  of  each  frame  is  a  frame  counter,  which  increments 

*  modulo  256.  The  program  checks  the  frame  counters  to  make 

*  sure  they  are  sequential  and  no  data  was  lost. 


♦define  FRSIZE  64 
♦define  NUMFR  8 


/*  words  per  frame  */ 

/*  frames  per  dma  buffer  */ 


ic  void  interrupt  far  dma_isr() 

/*  This  routine  is  entered  upon  completion  of  a  dma  operation. 

*  At  this  point  the  current  dma  buffer  is  full  and  we  can 

*  write  it  to  disk.  We  set  the  "available  data"  pointer 

*  to  point  to  the  just-filled  buffer,  and  start  the  next  dma 

*  operation  on  the  other  buffer.  At  the  conclusion  of 

*  operations,  we  output  a  non-specific  end-of-interrupt 

*  to  the  interrupt  controller. 

*  The  PC  bus  provides  no  mechanism  for  "unlatching"  an 

*  interrupt  request  once  it  has  been  serviced.  In  order  to 

*  enable  the  next  interrupt,  the  hardware  must  be  designed 

*  so  that  the  request  can  be  reset,  by  a  write  to  an  i/o 

*  port,  for  example.  The  external  routine  reset_irq() 

*  must  be  coded  to  perform  this  function. 

* 

*  Declaring  this  routine  as  type  'interrupt',  ensures 

*  that  all  registers  are  saved,  the  C  data  segment  is  set 

*  correctly,  and  that  the  routine  returns  with  an  IRET 

*  instruction.  Further  interrupts  are  disabled  during  the 

*  execution  of  this  routine. 


curr_buf  =  dma_buffers [buf_index) ; 
buf_index  A=  1; 

start_dma (dma_buf fers [buf_index] , 
buf_size) ; 
if (  file_handle  ) 
write_buf () ; 
reset_irq() ; 
outp (INTA00,  EOI) ; 


/*  post  just-filled  buf  address  */ 
/*  index  next  buffer  */ 

/*  start  dma  on  next  buffer  */ 

/*  if  disk  is  enabled. .  */ 

/*  write  buffer  to  disk  */ 

/*  do  hardware-specific  reset  */ 

/*  signal  end  of  int  */ 


static  int  write_buf() 
{  ■ 

if(  *dos  crit  addr 


/*  write  buffer  to  disk  file  */ 

/*  first  check  dos  critical  section  flag 


int  temp; 
int  i; 

unsigned  char  frame; 
int  far  *cp; 


reset_irq();  /*  clear  interrupt  request  */ 

buf_size  =  FRSIZE  *  NUMFR  *  sizeof(int);  /*  figure  out  buffer  size  */ 
alloc_dma_buf () ;  /*  allocate  buffers  */ 

printf("bufl  =  %p  buf2  =  %p\n",  /*  informational  output  */ 

dma_buffers [0] ,  dma_buffers[l) ) ; 

dma_setup();  /*  set  up  for  dma  operations  */ 

outp(0x3a0, 0) ;  /*  reset  fifo  on  hw  interface  */ 

start_dma (dma_buffers [0] ,  buf_size) ;  /*  start  up  the  data  acq  */ 

file_handle  =  creat ("tmp.dat") ;  /*  open  a  file  for  raw  data  */ 

temp  =  buf_index; 

while (  !_bios_keybrd(_KEYBRD_READY)  )  /*  quit  on  next  keystroke  */ 


if (temp  !=  buf_index) 

{ 

printf("%d:  ",temp); 


/*  wait  for  dma  complete  */ 
/*  print  buffer  index  */ 


for(i=0,  cp  =  curr_buf+l;  i<NUMFR;  i++,  cp  +=  FRSIZE) 


if (frame  !=  *cp)  printf{" 
else  printf("  "); 
printf ("%04x",  *cp) ; 
frame  =  *cp  +  1; 


);  /*  frame  counter  was  bad  */ 
/*  frame  counter  was  good  */ 

/*  print  frame  counter  */ 

/*  next  expected  counter  value 


printf ("  :  %d\n", lost_buffers) ;  /*  keep  track  of  lost  writes  */ 


temp  =  buf_index; 


close (file_handle) ; 
exit (0) ; 


/*  next  expected  buffer  number 


/*  close  data  file  */ 

/*  halt  dma  and  exit  */ 


lost_buffers++; 
return  0; 


r. x.dx  =  FP_OFF (curr_buf) ; 

s. ds  =  FP_SEG(curr_buf) ; 

r.x.bx  =  file_handle; 
r.x.cx  =  buf  size; 


/*  ..if  set,  skip  writing  this  buffer  */ 
/*  ..not  really  an  error  in  this  case  */ 


/*  ok  to  write  now,  set  address  in  */ 
/*  proper  registers  for  dos  call  */ 
/*  set  file  handle  to  write  to  */ 

/*  set  byte  count  for  write  */ 

/*  WARNING  -  can't  write  64K!  */ 

/*  dos  write-to-file-handle  function  * 


if (intdosx(&r,  &r,  &s)  ==  buf_size  /*  check  return  value  and.. 


&&  r.x.cflag  ==  0) 
return  0; 


/*  . .carry  flag  for  success  code  */ 
/*  return  success  */ 


♦pragma  check_stack (of f ) 


/* - 

*/ 

reset_irq() 


/*  clear  interrupt  request  in  hardware  */ 


lost_buffers++; 
return  1; 


/*  didn't  write  this  buffer  */ 
/*  return  failure  */ 


End  Listing  One 


End  Listings 
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ZEN 


Listing  One  (Text  begins  on  page  38.) 

\  EXIT  differs  from  semi  as  an  aid  to  decompilation. 

SCREEN  0 

\  nope  is  a  "no  operation"  word  used  for  initialization. 

\  ZEN,  Version  1.60 — a  simple  classical  Forth  ZEN  1.60  is  a  model  implementa¬ 
tion  of  the  unofficial  ANS  Forth  with  Double-Number,  File  Access,  and  BLOCK 

Standard  Extensions  (BASIS6) .  This  model  is  not  endorsed  by  the  ANS  X3J14  com- 

SCREEN  8 

mittee.  {  Comments  to  go  back  to  the  ANS  committee  look  like  this.}  ZEN  1.60 

\  Data  objects 

generates  an  IBM  PC  64K  small-model  ROM-able  nucleus.  BX  register  is  top-of- 

LABEL  addr  \  the  action  of  all  CREATES. 

stack.  DTC  with  JMP  code  field.  Assumes  segment  registers  CS  =  DS  =  ES  Thanks 
to  Wil  Baden  for  his  suggestions.  This  is  a  working  document.  No  guarantees 

BX  PUSH  3  #  AX  ADD  BX  AX  XCHG  NEXT 

are  made  to  its  accuracy  or  fitness.  While  this  is  a  working  document,  it  is 

LABEL  con  \  the  action  of  all  CONSTANTS  and  VARIABLES. 

copyrighted  1989  by  Martin  J.  Tracy.  All  rights  are  reserved. 

BX  PUSH  3  #  AX  ADD  BX  AX  XCHG  0  [BX]  BX  MOV  NEXT  C; 

SCREEN  1 

VARIABLE  u  (  Private}  \  USER  area  pointer. 

\  ZEN  nucleus 

LABEL  uvar  \  the  action  of  all  USER  variables. 

FORTH  DEFINITIONS  8  K-OF-ROM  !  "  KERNEL.COM"  MAKE-OBJECT 

BX  PUSH  3  #  AX  ADD  BX  AX  XCHG 

0  [BX]  BX  MOV  u  )  BX  ADD  NEXT 

32  CONSTANT  #Jot  (  number  conversion  area  in  bytes) 

128  CONSTANT  #Safe  {  CREATE  safety  area—  in  bytes) 

LABEL  (does)  BP  DEC  BP  DEC  SI  0  [BP]  MOV  \  run-time  DOES> 

128  CONSTANT  #User  (  total  user  area  size —  in  bytes) 

SI  POP  BX  PUSH  3  #  AX  ADD  BX  AX  XCHG  NEXT  C; 

HEX 

SCREEN  9 

0100  BFFF  2DUP  2CONSTANT  IROM  ROMORG  2!  (  start  &  end  of  ROM) 

\  Stack  manipulation 

C000  FFFF  2DUP  2CONSTANT  #RAM  RAMORG  2!  (  start  &  end  of  RAM) 

CODE  DUP  (  w  -  w  w)  BX  PUSH  NEXT  C; 

0000  #User  -  CONSTANT  #RP0  (  top  of  return  stack) 

#RP0  0080  -  CONSTANT  #SP0  (  top  of  data  stack) 

CODE  DROP  (  w)  BX  POP  NEXT  C; 

CODE  SWAP  (  w  w2  -  w2  w) 

START  DECIMAL  2  LOAD  FINIS 

SP  DI  MOV  BX  0  [DI]  XCHG  NEXT  C; 

CODE  OVER  (  w  w2  -  w  w2  w) 

SCREEN  2 

SP  DI  MOV  BX  PUSH  0  [DI]  BX  MOV  NEXT  C; 

\  Main  LOAD  screen 

HERE  EQU  Power  2  CELLS  (  power-up)  GAP  C  1989  by  M  Tracy" 

CODE  ROT  (  w  w2  w3  -  w2  w3  w) 

HERE  EQU  DO  #ROM  ,  ,  #RAM  ,  , 

HERE  EQU  HO  (  h)  0  ,  HERE  EQU  F0  0,0,  (  forth  vlink) 

DX  POP  AX  POP  DX  PUSH  BX  PUSH  AX  BX  MOV  NEXT  C; 

HERE  EQU  TO  (  r)  0  ,  HERE  EQU  SO  #SP0  , 

CODE  PICK  (  w[u]...w[l]  w[0]  u  -  w[u]...w[l]  w[0]  w[u]) 

\  copy  kth  item  to  top  of  stack. 

7  17  THRU  (  Kernel  primitives) 

BX  SHL  SP  BX  ADD  0  [BX]  BX  MOV  NEXT  C; 

19  27  THRU  (  Numbers  and  I/O) 

29  41  THRU  {  Interpreter) 

SCREEN  10 

43  69  THRU  (  Compiler) 

\  Memory  access 

71  75  THRU  (  Device  dependencies) 

CODE  @  (  a  -  w)  0  [BX]  BX  MOV  NEXT  C; 

81  86  THRU  {  Mass  storage  extension) 

77  79  THRU  (  Initialization) 

CODE  !  (  w  a)  0  [BX]  POP  BX  POP  NEXT  C; 

{  Application,  if  any) 

CODE  C@  (  a  -  b)  0  [BX]  BL  MOV  BH  BH  SUB  NEXT  C; 

CODE  C!  (  b  a)  AX  POP  AL  0  [BX]  MOV  BX  POP  NEXT  C; 

HERE  HO  !  THERE  TO  ! 

CODE  CMOVE  (  a  a2  u) 

SCREEN  3 

\  move  count  bytes  from  from  to  to,  leftmost  byte  first. 

\  Documentation  requirements 

BX  CX  MOV  SI  BX  MOV  DI  POP  SI  POP 

ZEN  1.60  supports  Double-Number,  File  Access,  and  BLOCK  Standard  Extensions. 

To  compile  the  BLOCK  extension,  load  the  two  screens  following  the  File  Access 

REP  BYTE  MOVS  BX  SI  MOV  BX  POP  NEXT  C; 

extension.  There  are  two  8-bit  bytes  per  cell.  Counted  strings  may  be  as  long 

SCREEN  11 

as  255  bytes.  Division  is  rounded-down.  To  change  to  floored  division,  load 

\  Math  operators 

two  screens  following  the  mixed-precision  rounded-down  operators.  The  system 

1  CODE  tic  NOP 

dictionary  is  approximately  7K  address  units  (au's)  leaving  56K  for  the  ap- 

1  CODE  lit  WORD  LODS  BX  PUSH  AX  BX  MOV  NEXT  C; 

plication.  {#RAM  &  #ROM  are  currently  set  for  40K  of  application  dictionary 
and  16K  of  RAM.)  (The  data  stack  grows  downwards  towards  the  bottom  of  RAM.} 

\  push  the  following  (in-line)  number  onto  the  stack. 

(The  return  stack  is  currently  set  for  128  au's  of  RAM.}  Only  dumb  (glass) 

CODE  +  (  n  n2  -  n3)  AX  POP  AX  BX  ADD  NEXT  C; 

terminals  are  supported.  {  How  are  minimum  facilities  to  be  specified?} 

CODE  -  (  n  n2  -  n3)  AX  POP  AX  BX  SUB  BX  NEG  NEXT  C; 

SCREEN  4 

CODE  NEGATE  (  n  -  n2)  BX  NEG  NEXT  C; 

\  Errors  and  exceptions 

CODE  ABS  (  n  -  +n2) 

If  the  input  stream  is  inadvertantly  exhausted:  ABORT"  ?" 

If  a  word  is  not  found:  ABORT"  ?" 

BX  BX  OR  1  L#  JNS  BX  NEG  1  L:  NEXT  C; 

If  control  structures  are  incorrectly  nested:  ABORT"  Unbalanced" 

If  insufficient  space  in  the  dictionary:  ABORT"  No  Room" 

If  insufficient  number  of  stack  entries:  ABORT"  Stack?" 

CODE  +!  (  n  a)  AX  POP  AX  0  [BX]  ADD  BX  POP  NEXT  C; 

\  increment  number  at  address  by  n. 

If  FORGETing  within  the  nucleus:  ABORT"  Can't" 

SCREEN  12 

\  Math  and  logical 

Division  by  zero  returns  a  quotient  of  zero  and  a  remainder  equal  to  the  divi- 

CODE  1+  (  n  -  n2)  BX  INC  NEXT  C; 

dend.  Data  and  return  stack  overflows  are  not  detected:  the  system  may  crash 
or  hang,  if  you  are  lucky.  Execution  of  compiler  words  while  interpreting  is 

CODE  1-  (  n  -  n2)  BX  DEC  NEXT  C; 

not  prevented;  the  result  of  such  execution  is  undefined.  Invalid  and  out-of- 

CODE  2*  (  n  -  n2)  BX  SHL  NEXT  C;  (  CONTROLLED)  {  Require?} 

range  arguments  are  not  checked:  the  result  of  using  such  arguments  is  very 
undefined. 

CODE  2/  (  n  -  n2)  BX  SAR  NEXT  C;  (  arithmetic) 

CODE  AND  (  m  m2  -  m3)  AX  POP  AX  BX  AND  NEXT  C; 

SCREEN  5 

CODE  OR  (  m  m2  -  m3)  AX  POP  AX  BX  OR  NEXT  C; 

\  Key  to  auxiliary  commands 

Several  words  used  by  the  metacompiler  are  described  here. 

CODE  XOR  (  m  m2  -  m3)  AX  POP  AX  BX  XOR  NEXT  C; 

CODE  NOT  (  w  -  w2)  BX  NOT  NEXT  C;  {  (  m  -  m2)  ?} 

<  make  the  next  word  headerless. 

ccc"  compile  the  characters  "ccc." 

SCREEN  13 

\  Comparisons 

a  ORG  reset  HERE  to  address  a. 

CODE  0  (  -  n)  BX  PUSH  BX  BX  SUB  NEXT  C;  {  Feature} 

n  EQU  <name>  equivalent  to  a  headerless  constant  with  value  n. 

CODE  1  (  -  n)  BX  PUSH  1  #  BX  MOV  NEXT  C;  {  Feature} 

LABEL  <name>  equivalent  to  HERE  EQU  <name>  but  also  activates 

CODE  TRUE  (  -  m)  BX  PUSH  -1  #  BX  MOV  NEXT  C;  [  Control?) 

the  CODE  assembler. 

CODE  <name>  begins  a  machine-code  definition,  usually  ended 

CODE  =  (  n  n2  -  f)  AX  POP  AX  BX  CMP 

by  END-CODE  or  C; 

TRUE  #  BX  MOV  1  L#  JZ  BX  INC  1  L:  NEXT  C; 

CODE  <  (  n  n2  -  f)  AX  POP  BX  AX  SUB 

I>  and  >1  like  R>  and  >R  when  used  to  get  return  addresses. 

TRUE  #  BX  MOV  1  L#  JL  BX  INC  1  L:  NEXT  C; 

CODE  U<  (  u  u2  -  f)  AX  POP  BX  AX  SUB 

BASE  is  returned  to  DECIMAL  after  each  block  is  LOADed. 

TRUE  #  BX  MOV  1  L#  JB  BX  INC  1  L:  NEXT  C; 

SCREEN  6 

:  >  (  n  n2  -  f)  SWAP  <  ; 

SCREEN  14 

!  Please  direct  all  comments  and  inquiries  to  Martin  Tracy  ! 

\  Comparisons  against  zero  and  CELL  operators 

CODE  0=  (  n  -  f) 

BX  BX  OR  TRUE  #  BX  MOV  1  L#  JZ  BX  INC  1  L:  NEXT  C; 

CODE  0<  (  n  -  f) 

BX  BX  OR  TRUE  #  BX  MOV  1  L#  JS  BX  INC  1  L:  NEXT  C; 

SCREEN  7 

\  -  Kernel  primitives  - 

LABEL  colon  BP  DEC  BP  DEC  SI  0  [BP]  MOV  SI  POP  NEXT 

:  0>  (  n  -  f)  0  >  ; 

\  save  I  register  on  return  stack  and  set  it  to  new  position. 

\  This  is  the  action  of  the  code  field  in  all  colon  definitions. 

2  CONSTANT  CELL  {  Feature} 

CODE  EXIT  NOP 

CODE  CELL+  (  a  -  a2)  BX  INC  BX  INC  NEXT  C; 

1  CODE  semi  0  [BP]  SI  MOV  BP  INC  BP  INC 

CODE  CELLS  (  a  -  a2)  BX  SHL  NEXT  C; 

!  CODE  nope  NEXT  C; 

\  semi  is  the  action  of  the  semicolon  in  all  colon  definitions. 

(continued  on  page  100) 
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listing  One  (Listing  continued,  text  begins  on  page  38.) 

SCREEN  15 

\  Branches  and  loops 

!  CODE  branch  \  unconditional  branch. 

0  [SI]  SI  MOV  NEXT  C; 

!  CODE  ?branch  {  f)  \  branch  if  zero. 

BX  BX  OR  BX  POP  '  branch  JZ  2  #  SI  ADD  NEXT  C; 

!  CODE  (do)  (  n  n2)  \  begin  DO... LOOP  structure. 

4  #  BP  SUB  AX  POP  HEX  8000  DECIMAL  #  AX  ADD 

AX  2  [BP]  MOV  AX  BX  SUB  BX  0  [BP]  MOV  BX  POP  NEXT  C; 

!  CODE  (loop)  \  terminate  DO... LOOP  structure. 

WORD  0  [BP]  INC  '  branch  JNO 
LABEL  >loop  2  #  SI  ADD 
I  CODE  >undo  4  #  BP  ADD  NEXT 

!  CODE  (+loop)  (  n)  \  terminate  DO...+LOOP  structure. 

BX  0  [BP]  ADD  BX  POP  '  branch  JNO  >loop  JO  NEXT  C; 

SCREEN  16 

\  Return  stack 

CODE  >R  (  w)  BP  DEC  BP  DEC  BX  0  [BP]  MOV  BX  POP  NEXT  C; 


CODE  R@  (  -  w) 
CODE  I  (  -  n) 
CODE  J  (  -  n) 
CODE  R>  (  -  w) 


BX  PUSH  0  [BP] 
BX  PUSH  0  [BP] 
BX  PUSH  4  [BP] 
BX  PUSH  0  [BP] 


BX  MOV  NEXT  < 
BX  MOV  2  [BP] 
BX  MOV  6  [BP] 
BX  MOV  BP  INC 


BX  ADD  NEXT  C; 

BX  ADD  NEXT  C; 

BP  INC  NEXT  C; 


CODE  2>R  (  w  w2) 

\  push  w  and  w2  to  the  return  stack,  w2  on  top. 

4  #  BP  SUB  BX  0  [BP]  MOV  2  [BP]  POP  BX  POP  NEXT  C; 


CODE  2R>  (  -  w  w2) 

\  pop  w  and  w2  from  the  return  stack. 

BX  PUSH  2  [BP]  PUSH  0  [BP]  BX  MOV  4  #  BP  ADD  NEXT  C; 
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\  Optimizations  and  EXECUTE 

CODE  NIP  (  w  w2  -  w2)  {  CONTROLLED]  AX  POP  NEXT  C; 

CODE  TUCK  (  w  w2  -  w2  w  w2)  {  CONTROLLED]  AX  POP 

BX  PUSH  AX  PUSH  NEXT  C; 


CODE  ?DUP  (  w  -  w  w  I  0-0) 

BX  BX  OR  1  L#  JZ  BX  PUSH  1  L:  NEXT  C; 
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\  Input  number  conversion 
ASCII  A  ASCII  9  1+  -  EQU  A-10 

!  :  digit  (  c  base  -  n  t  !  ?  0) 

\  true  if  the  char  c  is  a  valid  digit  in  the  given  base. 
SWAP  [ASCII]  0-9  OVER  <  DUP 
IF  DROP  A-10  -  10  THEN 

>R  DUP  R@  -  ROT  R>  -  U<  ; 

:  CONVERT  (  +d  a  -  +d2  a2) 

\  convert  the  char  sequence  at  a+1  and  accumulate  it  in  +d. 
\  a2  is  the  address  of  the  first  non-convertable  digit. 
BEGIN  1+  DUP  >R  C@  BASE  @  digit 

WHILE  SWAP  BASE  0  UM*  DROP  ROT  BASE  0  UM*  D+  R> 
REPEAT  DROP  R>  ; 
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\  Output  number  conversion 
:  <#  PAD  hid  !  ; 

:  #>  (  wd  -  a  u)  2DROP  hid  @  PAD  OVER  -  ; 

:  HOLD  (  c)  TRUE  hid  +!  hid  @  C!  ; 

\  add  character  c  to  output  string. 

:  SIGN  (  n)  0<  IF  [ASCII]  -  HOLD  THEN  ; 

\  add  to  output  string  if  w  is  negative. 

:  #  (  ud  -  ud2) 

\  transfer  the  next  digit  of  ud  to  the  output  string. 
BASE  0  >R  0  R@  UM/MOD  R>  SWAP  >R  UM/MOD  R> 

ROT  9  OVER  <  IF  A-10  +  THEN  [ASCII]  0  +  HOLD  ; 

:  #S  (  ud  -  ud2)  BEGIN  #  2DUP  OR  0=  UNTIL  ; 

\  convert  all  remaining  digits  of  ud.  ud2  is  0  0  . 
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\  Transfers 

LABEL  xvar  \  the  action  of  all  transfers. 

u  )  DI  MOV  x  [DI]  DI  MOV  3  #  AX  ADD  DI  AX  XCHG 
0  [DI]  DI  MOV  AX  DI  ADD  0  [DI]  AX  MOV  AX  JMP  C; 


0  XFER  TYPE  (  a  u) 

XFER  KEYS  (  a  u)  {  Private) 
XFER  MARK  (  a  u)  {  Extend?) 
XFER  TAB  (  n  n2)  [  Extend?) 


XFER  CR 

XFER  KEY?  (  -  f)  {  Extend?) 
XFER  PAGE  {  Extend?) 

(  Reserved)  DROP 


CODE  EXECUTE  (  w)  BX  AX  XCHG  BX  POP  AX  JMP  C; 

CODE  ©EXECUTE  (  w)  {  Control?)  {  Why  w  and  not  a?) 

\  ©EXECUTE  is  equivalent  to  0  EXECUTE  but  is  much  faster. 
BX  DI  MOV  BX  POP  0  [DI]  AX  MOV  AX  JMP  C; 


\  KEYS  is  a  simple  unfiltered  EXPECT  which  doesn't  echo. 

\  KEY?  is  true  if  a  key  is  available. 

\  MARK  is  like  TYPE  but  highlights  if  possible. 

\  PAGE  clears  the  screen. 

\  TAB  moves  the  cursor  to  the  x  (n)  and  y  (n2)  coordinates 
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\  Print  spaces 

32  CONSTANT  BL  {  CONTROLLED)  \  ASCII  blank 
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\  -  Input/Output  - 

\  In  ZEN,  consecutive  headerless  variables  form  a  category 
\  which  can  be  extended  but  not  reduced  or  reordered. 

0  USER  entry  2  CELLS  +  (  skip  multitasking  hooks) 

USER  r  I  USER  SP0 

USER  x  \  XFER  vector  pointer. 

USER  BASE  1  USER  dpi  !  USER  hid  EQU  #1/0 

:  THERE  (  -  a)  r  0  ;  {  ROM) 

:  PAD  (  -  a)  r  0  [  IJot  ]  LITERAL  +  ;  {  CONTROLLED) 

{  pictured  number  staging  area  size  undefined?) 

:  DECIMAL  10  BASE  !  ; 

:  HEX  16  BASE  !  ;  {  CONTROLLED) 
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\  Double-value  data  stack  operators 
CODE  2DUP  (  w  w2  -  w  w2  w  w2)  SP  DI  MOV  BX  PUSH 
0  [DI]  PUSH  NEXT  C; 

CODE  2DROP  (  w  w2)  BX  POP  BX  POP  NEXT  C; 

CODE  2 SWAP  (  w  w2  w3  w4  -  w3  w4  w  w2)  AX  POP  CX  POP  DX  POP 

AX  PUSH  BX  PUSH  DX  PUSH  CX  BX  MOV  NEXT  C; 

:  2 OVER  (  d  d2  -  d  d2  d)  2>R  2DUP  2R>  2 SWAP  ; 

:  2 ROT  (  d  d2  d3  -  d2  d3  d)  2R>  2 SWAP  2R>  2 SWAP  ; 

{  CONTROLLED)  {  Require?) 

CODE  20  (  a  -  w  w2)  2  [BX]  PUSH  0  [BX]  BX  MOV  NEXT  C; 

CODE  2!  (  w  w2  a)  0  [BX]  POP  2  [BX]  POP  BX  POP  NEXT  C; 
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\  Numeric  conversion  math  support 
CODE  D+  (  d  d2  -  d3)  AX  POP  DX  POP  CX  POP 
AX  CX  ADD  CX  PUSH  DX  BX  ADC  NEXT  C; 

CODE  DNEGATE  (  d  -  d2)  AX  POP  AX  NEG  AX  PUSH 
0  #  BX  ADC  BX  NEG  NEXT  C; 


HERE  (  *)  BL  , 

:  SPACE  (  *)  LITERAL  1  TYPE  ; 

HERE  (  *  )  BL  C,  BL  C,  BL  C,  BL  C,  BL  C,  BL  C,  BL  C,  BL  C, 

:  SPACES  (  +n  )  \  output  w  spaces.  Optimized  for  TYPE. 

(  *  )  LITERAL  OVER  2/  2/  2/  ?DUP 

IF  0  DO  DUP  8  TYPE  LOOP  THEN  SWAP  7  AND  TYPE  ; 
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\  Print  numbers 

!  :  (d.)  (  d  -  a  u)  \  convert  a  double  number  to  a  string. 
TUCK  DUP  0<  IF  DNEGATE  THEN  <#  #S  ROT  SIGN  #>  ; 

:  D.  (  d)  (d.)  TYPE  SPACE  ; 

:  U.  (  u)  0  D.  ; 

:  .  (  n)  DUP  0<  D.  ; 
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\  -  Interpreter  - 

#1/0  (  continued  from  I/O  layer) 

USER  BLK  {  BLOCK)  {  Require?)  USER  >IN  \  keep  together. 
USER  #TIB  CELL+  \  #TIB  and  TIB'S  value. 

USER  SPAN 

USER  STATE  EQU  #Used 


VARIABLE  last 

CELL  ALLOT 

\ 

last 

lfa  and  cfa. 

I  VARIABLE  scr 

CELL  ALLOT 

\ 

last 

error  location 

I  VARIABLE  bal  ! 

VARIABLE  leaf 

\ 

see 

compiler. 

VARIABLE  CONTEXT 

(  CONTROLLED) 

VARIABLE  CURRENT 

{  CONTROLLED) 

:  TIB  (  -  a)  #TIB  CELL+  @  ; 
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\  Automatic  variables 

\  These  variables  are  automatically  initialized;  see  COLD. 
VARIABLE  h  !  VARIABLE  f  CELL  (  ie  vlink)  ALLOT 


:  MAX  (  n  n2  -  n3)  2DUP  <  IF  SWAP  THEN  DROP  ; 

:  MIN  (  n  n2  -  n3)  2DUP  <  0=  IF  SWAP  THEN  DROP  ; 
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\  Numeric  conversion  math  support 
CODE  UM*  (  u  u2  -  ud) 

AX  POP  BX  MUL  AX  PUSH  DX  BX  MOV  NEXT  C; 


VARIABLE 

'pause 

\  multitasking  hook. 

VARIABLE 

' expect 

\ 

deferred  EXPECT 

VARIABLE 

' source 

\ 

deferred  input  stream. 

VARIABLE 

'  warn 

\ 

redefinition  warning. 

VARIABLE 

'  loc 

\ 

source  location  field. 

VARIABLE 

'  val? 

\ 

string  to  number  conversion. 

VARIABLE 

key'  CELL  ALLOT  \  one-key  look-ahead  buffer 

CODE  UM/MOD  (  ud  u  -  u2  u3) 

\  return  rem  u2  and  quot  u3  of  unsigned  ud  divided  by  u. 

\  On  zero-divide,  return  quot=0  and  rem=low-word-of-ud. 
DX  POP  AX  AX  SUB  BX  DX  CMP  1  L#  JAE 
AX  POP  BX  DIV  DX  PUSH  1  L:  AX  BX  MOV  NEXT  C; 


:  HERE  (  -  a)  h  0  ; 
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(  String  operators —  high-level  definitions  )  EXIT 
:  COUNT  (  a  -  a2  u)  DUP  C@  SWAP  1+  ; 
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\  transform  counted  string  into  text  string. 

:  /STRING  (  a  u  n  -  a2  u2)  {  Control?}  ROT  OVER  +  ROT  ROT  -  ; 

\  truncate  leftmost  n  chars  of  string,  n  may  be  negative. 

:  SKIP  (  a  u  b  -  a2  u2)  {  Control?} 

\  return  shorter  string  from  first  position  unequal  to  byte. 

>R  BEGIN  DUP 

WHILE  OVER  C@  R@  -  IF  R>  DROP  EXIT  THEN  1  /STRING 
REPEAT  R>  DROP  ; 

:  SCAN  (  a  u  b  -  a2  u2)  {  Control?} 

\  return  shorter  string  from  first  position  equal  to  byte. 

>R  BEGIN  DUP 

WHILE  OVER  C@  R@  =  IF  R>  DROP  EXIT  THEN  1  /STRING 
REPEAT  R>  DROP  ; 
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(  String  operators —  low-level  definitions  ) 

CODE  COUNT  (  a  -  a2  u)  BX  AX  MOV  AX  INC 
\  transform  counted  string  into  text  string. 

0  [BX]  BL  MOV  BH  BH  SUB  AX  PUSH  NEXT  C; 

CODE  /STRING  (  a  u  n  -  a2  u2)  {  Control?}  CX  POP  AX  POP 

\  truncate  leftmost  n  chars  of  string,  n  may  be  negative. 

BX  AX  ADD  BX  CX  SUB  CX  BX  MOV  AX  PUSH  NEXT  C; 

CODE  SKIP  (  a  u  b  -  a2  u2)  (  Contr?}  BX  AX  MOV  CX  POP  DI  POP 
\  return  shorter  string  from  first  position  unequal  to  byte. 

1  L#  JCXZ  REPE  BYTE  SCAS  1  L#  JZ  CX  INC  DI  DEC 

1  L:  DI  PUSH  CX  BX  MOV  NEXT  C; 

CODE  SCAN  (  a  1  b  -  a2  u2)  {  Contr?}  BX  AX  MOV  CX  POP  DI  POP 
\  return  shorter  string  from  first  position  equal  to  byte. 

1  L#  JCXZ  REPNE  BYTE  SCAS  1  L#  JNZ  CX  INC  DI  DEC 

1  L:  DI  PUSH  CX  BX  MOV  NEXT  C; 
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\  More  string  operators 

CODE  FILL  (  a  u  b)  \  store  u  b's,  starting  at  addr  a. 

BX  AX  MOV  CX  POP  DI  POP  REP  BYTE  STOS  BX  POP  NEXT  C; 

:  -TRAILING  (  a  +n  -  a2  +n2)  2DUP 
\  alter  string  to  suppress  trailing  blanks. 

BEGIN  2DUP  BL  SKIP  DUP 

WHILE  2 SWAP  2 DROP  BL  SCAN  REPEAT  2 DROP  NIP  -  ; 

EXIT 

:  FILL  (  a  u  b)  \  store  u  b's,  starting  at  addr  a. 

SWAP  ?DUP  0=  IF  2 DROP  EXIT  THEN 
>R  OVER  C!  DUP  1+  R>  1-  CMOVE  ; 
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\  Input  stream  operators 

!  :  source  (  -  a  u)  #TIB  2@  ;  \  input  stream  source. 

:  /source  (  -  a  u)  'source  0EXECUTE  >IN  @  /STRING  ; 

I  :  accept  (  n  f)  IF  1+  THEN  >IN  +!  ; 

\  accept  characters  by  incrementing  >IN. 

:  parse  (  c  -  a  u)  \  parse  a  character-delimited  string. 

>R  /source  OVER  SWAP  R>  SCAN  >R  OVER  -  DUP  R>  accept  ; 

:  WORD  {  c  -  a)  \  parse  a  character-delimited  string; 

\  leading  delimiters  are  accepted  and  skipped; 

\  the  string  is  counted  and  followed  by  a  blank  (not  counted) . 

>R  /source  OVER  R>  2>R  R@  SKIP  OVER  SWAP  R>  SCAN 
OVER  R>  -  SWAP  accept  OVER  -  31  MIN  THERE  DUP  >R 
2DUP  C!  1+  SWAP  CMOVE  BL  R@  COUNT  +  C!  R>  ; 
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\  Dictionary  search 

CODE  thread  (  a  w  -  a  0  ,  cfa  -1  ,  cfa  1) 

\  search  vocabulary  for  a  match  with  the  packed  name  at  a  . 

DX  POP  SI  PUSH 

1  L:  0  [BX}  BX  MOV  (  chain  thru  dictionary  ) 

BX  BX  OR  5  L#  JZ  (  jump  if  end  of  thread  ) 

DX  DI  MOV  (  'string)  BX  SI  MOV  2  #  SI  ADD  (  SI=nfa) 

0  [SI]  CL  MOV  31  #  CX  AND  0  [DI]  CL  CMP  (  count  =  ?) 

1  L#  JNZ  (  lengths  <>)  DI  INC  SI  INC  (  to  body  of  'string) 

REPE  BYTE  CMPS  (  names  =?)  1  L#  JNZ  (  jump  not  matched) 

CX  POP  SI  PUSH  (  cfa  )' 

CX  SI  MOV  BYTE  32  #  2  [BX]  TEST  (  immediate  bit  ) 

TRUE  #  BX  MOV  4  L#  JZ  BX  NEG  4  L:  NEXT 
5  L:  SI  POP  DX  PUSH  (  'str)  (  BX  =  0)  NEXT  C; 
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\  FIND  [  and  ] 

:  FIND  (a-aO!a-w-l!a-wl) 

\  search  dictionary  for  a  match  with  the  packed  name  at  a  . 

\  Return  execution  address  and  -1  or  1  (  IMMEDIATE)  if  found; 

\  [']  EXIT  1  if  a  has  zero  length;  a  0  if  not  found. 

DUP  C@  (  a  1)  DUP 

IF  31  MIN  OVER  C!  (a)  CONTEXT  @  thread  (  a  -1/0/1)  DUP 
IF  EXIT  THEN  CONTEXT  @  f  - 

IF  DROP  f  thread  THEN  EXIT 
THEN  (  a  0)  2DROP  [']  EXIT  1  ; 

:  ]  TRUE  STATE  !  ;  \  stop  interpreting;  start  compiling. 

:  [  0  STATE  !  ;  \  stop  compiling;  start  interpreting. 

IMMEDIATE 
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\  Data  and  return  stack 

\  Set  data  and  return  stack  pointers,  respectively: 

I  CODE  sp!  (a)  BX  SP  MOV  BX  POP  NEXT  C; 

1  CODE  rp!  (a)  BX  BP  MOV  BX  POP  NEXT  C; 

:  RESET  (  Feature}  \  reset  return  stack  for  error  recovery. 

I>  entry  CELL  -  rp!  >1  ; 

:  PRESET  {  Feature}  \  empty  both  stacks  and  prepare  system. 

SPO  0  sp!  I>  entry  rp!  >1  SPO  0  0  #TIB  2!  0  STATE  !  ; 

:  :  err  RESET  ; 

(continued  on  page  102) 
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Listing  One  (Listing  continued,  text  begins  on  page  38.) 

CODE  DEPTH  (  -  n)  \  #  items  on  stack  before  DEPTH  is  executed. 

BX  PUSH  u  )  BX  MOV  SPO  [BX]  BX  MOV  SP  BX  SUB  BX  SAR 

NEXT  C; 
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{  Memory  management —  high-level  definitions)  EXIT 
:  ALLOT  (  n)  r  +!  ;  \  allocate  n  RAM  data  bytes. 

:  GAP  (  nj  h  +!  ;  \  allocate  n  dictionary  bytes.  {  ROM) 

:  C,  (  w)  h  @  C!  1  h  +!  /  \  ie  HERE  C!  1  GAP  ; 

\  append  low  byte  of  w  onto  the  dictionary. 

:  ,  {  w)  h  @  !  CELL  h  +!  ;  \  ie  HERE  !  CELL  GAP  / 

\  append  w  onto  the  dictionary. 

EXIT  (  In  an  all-RAM  system:} 

:  GAP  ALLOT  ;  :  THERE  HERE  ;  :  >DATA  >BODY  ; 

:  GOES>  [COMPILE)  DOES>  ;  IMMEDIATE 
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(  Memory  management —  low-level  definitions) 

CODE  ALLOT  (  n)  \  allocate  n  RAM  data  bytes. 

r  #  DI  MOV  u  )  DI  ADD  BX  0  [DI]  ADD  BX  POP  NEXT  C; 

CODE  GAP  (  n)  \  allocate  n  dictionary  bytes.  (  ROM) 
h  #  DI  MOV  BX  0  [DI]  ADD  BX  POP  NEXT  C; 

CODE  C,  (  w)  h  #  DI  MOV  0  [DI]  DI  MOV 
\  append  low  byte  of  w  onto  the  dictionary. 

BL  0  [DI]  MOV  1  #  BX  MOV  '  GAP  JU 
CODE  ,  (  w)  h  #  DI  MOV  0  [DI]  DI  MOV 
\  append  w  onto  the  dictionary. 

BX  0  [DI]  MOV  2  #  BX  MOV  '  GAP  JU  FORTH 
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\  Code  and  data  fields 
:  >BODY  (  w  -  a)  3  +  / 

:  >DATA  (  w  -  a)  3  +  0  /  {  ROM] 

:  >code  (  cfa  -  'code)  1+  DUP  @  CELL+  +  ; 

\  finds  code  address  associated  with  cfa. 

!  :  alter  (  'code  cfa)  1+  TUCK  CELL+  -  SWAP  !  / 

\  point  the  cf  to  the  given  code  addr.  Skip  the  CALL  byte. 

:  :  nest,  (  'code  )  HERE  232  (  CALL)  C,  CELL  GAP  alter  ; 

\  create  the  code  field  for  colon  words,  DOES>  and  GOES> 

:  :  code,  (  'code  )  HERE  233  (  JMP  )  C,  CELL  GAP  alter  ; 

\  create  the  code  field  for  data  words. 

:  patch  (  'code  cfa)  233  (  JMP  )  OVER  C!  alter  ; 

\  make  'code  the  new  action  of  the  cf.  Used  by  (/code). 
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\  Alignment,  string  and  error  primitives 
\  :  ALIGN  HERE  1  AND  GAP  ;  [  ALIGN) 

\  force  dictionary  to  the  next  even  address. 

\  :  REALIGN  (  a  -  a2)  DUP  1  AND  +  /  [  ALIGN) 

\  force  address  to  the  next  even  address. 

a  1)  I>  COUNT  2DUP  +  (  REALIGN)  >1  ; 

\  leave  the  address  and  length  of  an  in-line  string. 

:  :  huh?  (  w)  0=  ABORT"  ?"  ; 

\  error  action  of  several  words. 

:  '  (  -  w)  BL  WORD  DUP  C@  huh?  FIND  huh?  ; 

\  :  I>  [COMPILE]  R>  ;  IMMEDIATE  (  ALIGN) 

\  :  >1  [COMPILE]  >R  ;  IMMEDIATE  [  ALIGN) 
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\  -  Compiler  - 

:  COMPILE  I>  DUP  CELL+  >1  @  ,  / 

\  compile  the  word  that  follows  in  the  definition. 

:  header  \  create  link  and  name  fields. 

(  ALIGN)  ' loc  @ EXECUTE  (  extra  fields  ) 

BL  WORD  DUP  C@  huh?  'warn  0EXECUTE  (  redefinition?) 

HERE  last  !  HERE  CURRENT  @  DUP  @  ,  !  (  link  field) 

HERE  OVER  C@  1+  CMOVE  (  name  field) 

HERE  C@  DUP  128  OR  C,  GAP  HERE  last  CELL+  !  ; 
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\  Defining  words 
:  CREATE  (  -  a) 

header  [  addr  ]  LITERAL  code,  ; 

:  VARIABLE  (  -  a) 

header  [  con  ]  LITERAL  code,  THERE  , 

0  THERE  !  (  courtesy  )  CELL  ALLOT  ; 

:  CONSTANT  (  -  w) 

header  [  con  ]  LITERAL  code,  ,  ; 
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\  DOES>  and  GOES> 

!  :  (/code)  I>  last  CELL+  @  patch  / 

\  the  code  field  of  (/code)  is  at  '  DOES>  >BODY  CELL+ 


:  DOES>  COMPILE  (/code)  [  (does)  ]  LITERAL  nest,  /  IMMEDIATE 
\  eg  :  KONST  CREATE  ,  DOES>  0  / 

:  GOES>  (  ROM)  [COMPILE]  DOES>  COMPILE  @  /  IMMEDIATE 
\  eg  :  VALUE  VARIABLE  GOES>  @  / 
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\  Literals 


:  LITERAL  (  -  w)  COMPILE  lit  ,  /  IMMEDIATE 
\  compile  w  as  a  literal. 

:  [']  (  -  w)  '  COMPILE  tic  ,  /  IMMEDIATE 

\  compile-form  of  '  ("tick"). 

:  ASCII  (  -  c)  BL  WORD  1+  C@  ;  \  return  value  of  next  char. 

:  [ASCII]  (  -  c)  \  compile  value  of  next  char. 

ASCII  [COMPILE]  LITERAL  ;  IMMEDIATE 

:  STRING  (  c)  (  Feature)  \  string  compiler,  eg  32  STRING  ABC 
parse  DUP  C,  HERE  OVER  GAP  SWAP  CMOVE  {  ALIGN)  / 

:  "  (  -  a  u)  \  string  literal,  eg  "  cccc" 

COMPILE  (")  [ASCII]  "  STRING  ;  IMMEDIATE 
:  ."  [COMPILE]  "  COMPILE  TYPE  /  IMMEDIATE 
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\  Flow  of  control 

!  :  ?bal  DUP  bal  0  <  huh?  PICK  @  0=  huh?  / 

1  :  -bal  bal  0  huh?  TRUE  bal  +!  DUP  0  huh?  / 

:  BEGIN  HERE  1  bal  +!  /  IMMEDIATE 

:  IF  COMPILE  ?branch  [COMPILE]  BEGIN  0  ,  /  IMMEDIATE 

:  THEN  0  ?bal  TRUE  bal  +!  HERE  SWAP  !  /  IMMEDIATE 

:  ELSE  0  ?bal  COMPILE  branch  [COMPILE]  BEGIN  0  , 

SWAP  [COMPILE]  THEN  /  IMMEDIATE 

:  UNTIL  -bal  COMPILE  ?branch  ,  /  IMMEDIATE 

:  AGAIN  -bal  COMPILE  branch  ,  /  {  Control?)  IMMEDIATE 

:  WHILE  bal  0  huh?  [COMPILE]  IF  SWAP  ;  IMMEDIATE 

:  REPEAT  1  ?bal  [COMPILE]  AGAIN  [COMPILE]  THEN  /  IMMEDIATE 
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\  Definite  loops 

:  DO  COMPILE  (do)  [COMPILE]  BEGIN  /  IMMEDIATE 

:  LEAVE  COMPILE  >undo  COMPILE  branch 

HERE  leaf  0  ,  leaf  !  /  IMMEDIATE 

!  :  rake,  \  gathers  leaf's.  Courtesy  of  Wil  Baden. 

DUP  ,  leaf  0 

BEGIN  2DUP  U<  WHILE  DUP  0  HERE  ROT  !  REPEAT 
leaf  !  DROP  / 

:  LOOP  -bal  COMPILE  (loop)  rake,  /  IMMEDIATE 
:  +LOOP  -bal  COMPILE  (+loop)  rake,  ;  IMMEDIATE 

:  UNDO  COMPILE  >undo  /  IMMEDIATE 
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\  Colon  definitions 

:  :  \  create  a  word  and  enter  the  compiling  loop. 

CURRENT  @  CONTEXT  ! 

header  [  colon  ]  LITERAL  nest, 

last  @  @  CONTEXT  0  !  0  0  bal  2!  ]  / 

:  /  \  terminate  a  definition, 

bal  2@  OR  ABORT"  Unbalanced" 
last  0  CURRENT  @  ! 

COMPILE  semi  [COMPILE]  (  ;  IMMEDIATE 
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\  Vocabularies 
:  FORTH  f  CONTEXT  !  / 

:  DEFINITIONS  CONTEXT  0  CURRENT  !  / 

\  new  definitions  will  be  into  the  CURRENT  vocabulary. 

:  VOCABULARY 

\  when  executed,  a  vocabulary  becomes  first  in  the  search  order. 

VARIABLE  HERE  f  CELL+  (  ie  vlink)  DUP  0  ,  ! 

CELL  GAP  (  value  for  automatic  initialization) 

GOES>  CONTEXT  !  / 
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\  Misc.  compiler  support 

:  IMMEDIATE  last  0  CELL+  DUP  C@  BL  (  ie  32)  OR  SWAP  C!  / 

:  [COMPILE]  '  ,  ;  IMMEDIATE 

\  force  compilation  of  an  otherwise  immediate  word. 

:  (  [ASCII]  )  parse  2 DROP  /  IMMEDIATE  (  comments) 

:  .(  [ASCII]  )  parse  TYPE  /  IMMEDIATE  \  messages. 

:  RECURSE  last  CELL+  0  ,  ;  IMMEDIATE  \  self-reference. 
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(  Hall  of  fame —  high-level)  EXIT 

:  M+  (  d  n  -  d2)  {  Control?)  S>D  D+  /  \  add  n  to  d. 

:  x  (  u  -  u2)  {  Control?)  DUP  255  AND  SWAP  256  *  OR  / 

\  reverse  the  bytes  within  a  cell. 

:  WITHIN  (  u  n  n2  -  f)  {  Control?)  OVER  -  >R  -  R>  U<  / 

\  true  if  n  <=  u  <  n2  given  circular  comparison. 

:  ERASE  (  a  u)  0  FILL  ;  {  CONTROLLED) 

:  BLANK  (  a  u)  BL  FILL  /  (  CONTROLLED) 
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(  Hall  of  fame —  low-level) 

CODE  M+  (  d  n  -  d2)  (  Control?)  \  add  n  to  d. 

BX  AX  XCHG  CWD  BX  POP  CX  POP  AX  CX  ADD  CX  PUSH 

DX  BX  ADC  NEXT  C/ 

CODE  X  (  u  -  u2)  {  Control?)  BL  BH  XCHG  NEXT  C/ 

\  reverse  the  bytes  within  a  word. 

:  WITHIN  (  u  n  n2  -  f)  (  Control?)  OVER  -  >R  -  R>  U<  / 

\  true  if  n  <=  u  <  n2  given  circular  comparison. 

:  ERASE  [  a  u)  0  FILL  ;  (  CONTROLLED)  (cOUtmUed  OH  page  104) 
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ZEN 


Listing  One  (Listing  continued,  text  begins  on  page  38.) 

:  BLANK  (  a  u)  BL  FILL  ;  {  CONTROLLED} 
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\  Byte  move  operators 
:  CMOVE>  (  a  a2  u)  {  CONTROLLED} 

\  move  u  bytes  from  a  to  a2,  rightmost  byte  first. 

DUP  DUP  >R  D+  R>  ?DUP 

IF  0  DO  1-  SWAP  1-  TUCK  C@  OVER  C!  LOOP  THEN  2 DROP  ; 

:  MOVE  (  a  a2  u)  \  move  u  bytes  from  a  to  a2  without  overlap. 

>R  2DUP  U<  IF  R>  CMOVE>  ELSE  R>  CMOVE  THEN  ; 

:  ROLL  (  w[u]  w[u-l] . . . w [0]  u  -  w[u-l] . . . w [0]  w[u]) 

\  rotate  kth  item  to  top  of  stack.  {  Delete?} 

DUP  BEGIN  ?DUP  WHILE  ROT  >R  1-  REPEAT 

BEGIN  ?DUP  WHILE  R>  ROT  ROT  1-  REPEAT  ; 
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{  Double-number  math —  high-level)  EXIT 
:  S>D  (  n  -  d)  DUP  0<  ;  \  extend  n  to  d. 

:  D>S  (  d  -  n)  DROP  ;  (  DOUBLE}  \  truncate  d  to  n. 

(  Require?} 

:  D-  (  d  d2  -  d')  DNEGATE  D+  ;  {  DOUBLE} 

:  D2*  (  d  -  d*2)  2DUP  D+  ; 

:  D2/  (  d  -  d/2)  SWAP  2/  32767  AND  (  DOUBLE} 

OVER  1  AND  IF  32768  OR  THEN  SWAP  2/  ;  {  Require?} 
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(  Double-number  math —  low-level) 

CODE  S>D  (  n  -  d)  \  extend  n  to  d. 

BX  AX  XCHG  CWD  AX  PUSH  BX  DX  XCHG  NEXT  C; 

CODE  D>S  (  d  -  n)  BX  POP  NEXT  C;  {  Req?}  \  truncate  d  to  n. 

CODE  D-  (  d  d2  -  d3)  BX  DX  MOV  AX  POP  BX  POP  CX  POP 

AX  CX  SUB  CX  PUSH  DX  BX  SBB  NEXT  C;  {  DOUBLE) 

CODE  D2*  (  d  -  d2) 

AX  POP  AX  SHL  BX  RCL  AX  PUSH  NEXT  C; 

CODE  D2/  (  d  -  d2)  {  DOUBLE)  {  Require?} 

AX  POP  BX  SAR  AX  RCR  AX  PUSH  NEXT  C; 
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\  More  Double-number  math 
:  D<  (  d  d2  -  f) 

ROT  2DUP  =  IF  2 DROP  U<  EXIT  THEN  2 SWAP  2 DROP  >  ; 

:  D0=  {  d  -  f)  OR  0=  ;  {  DOUBLE) 

:  D=  (  d  d2  -  f)  D-  OR  0=  ;  {  DOUBLE} 

:  DABS  (  d  -  ud)  DUP  0<  IF  DNEGATE  THEN  ;  {  Double?} 

:  DMAX  {  d  d2  -  dmax)  {  DOUBLE} 

20VER  2 OVER  D<  IF  2 SWAP  THEN  2 DROP  ; 

:  DMIN  (  d  d2  -  dmin)  {  DOUBLE} 

20VER  20VER  D<  NOT  IF  2 SWAP  THEN  2 DROP  ; 
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\  Double-number  operators 
:  2CONSTANT  (  -  w)  CREATE  ,  ,  DOES>  2@  ; 

\  create  a  double  constant.  {  DOUBLE) 

:  2 VARIABLE  (  -  a)  VARIABLE  0  THERE  !  CELL  ALLOT  ; 

\  create  a  double  variable.  {  DOUBLE} 

:  D@  (  a  -  d)  2@  ;  {  DOUBLE} 

:  D!  (  d  a  )  2!  ;  {  DOUBLE} 

:  DLITERAL  (  d  )  (  -  d)  {  Double?}  \  compile  d  as  a  literal. 

SWAP  [COMPILE]  LITERAL  [COMPILE]  LITERAL  ;  IMMEDIATE 

:  D.R  (  d  n)  f  DOUBLE} 

\  print  d  right- justified  in  field  of  width  n. 

>R  TUCK  DABS  <#  #S  ROT  SIGN  #> 

R>  OVER  -  0  MAX  SPACES  TYPE  ; 
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{  Mixed-precision  multiply  and  divide--  high-level)  EXIT 
:  M*  (  n  n2  -  d)  {  Control?) 

\  signed  mixed-precision  multiply. 

2DUP  XOR  >R  ABS  SWAP  ABS  UM*  R>  0<  IF  NEGATE  THEN  ; 

:  M/MOD  (  d  n  -  rem  quot)  [  Control?} 

\  signed  rounded-down  mixed-precision  divide. 

2 DUP  XOR  >R  OVER  >R  ABS  >R  DABS  R>  UM/MOD 
SWAP  R>  0<  IF  NEGATE  THEN 
SWAP  R>  0<  IF  NEGATE  THEN  ; 
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(  Mixed-precision  multiply  and  divide —  low-level) 

CODE  M*  (  n  n2  -  d)  {  Control?} 

\  signed  mixed-precision  multiply. 

BX  AX  XCHG  DX  POP  DX  IMUL  AX  PUSH  DX  BX  MOV  NEXT  C; 

CODE  M/MOD  (  d  n  -  rem  quot)  {  Control?}  DX  POP  AX  POP 
\  signed  rounded-down  mixed-precision  divide. 

BX  BX  OR  5  L#  JZ  (  divide  by  zero?) 

BX  IDIV  AX  BX  MOV  DX  PUSH  NEXT 

5  L:  AX  DX  MOV  0  #  BX  MOV  DX  PUSH  NEXT  C; 
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(  Mixed-precision  multiply  and  divide —  floored)  EXIT 
CODE  M*  (  n  n2  -  d)  {  Control?) 

\  signed  mixed-precision  multiply. 

BX  AX  XCHG  DX  POP  DX  IMUL  AX  PUSH  DX  BX  MOV  NEXT  C; 

:  M/MOD  {  d  n  -  rem  quot)  {  Control?) 

\  signed  floored  mixed-precision  divide. 

DUP  >R  2 DUP  XOR  >R  DUP  >R  ABS  >R  DABS  R>  UM/MOD 
SWAP  R>  0<  IF  NEGATE  THEN 

SWAP  R>  0<  IF  NEGATE  OVER  IF  R@  ROT  -  SWAP  1-  THEN  THEN 


R>  DROP  ; 
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\  Multiply  and  divide 

:  /MOD  (  n  n2  -  n3  n4)  >R  DUP  0<  R>  M/MOD  ; 

:  /  (  n  n2  -  n3)  /MOD  NIP  ; 

:  MOD  (  n  n2  -  n3)  /MOD  DROP  ; 

\  Intermediate  product  is  32  bits: 

:  */MOD  (  n  n2  n3  -  n4  n5)  >R  M*  R>  M/MOD  ; 

:  */  (  n  n2  n3  -  n4)  >R  M*  R>  M/MOD  NIP  ; 

CODE  *  (  n  n2  -  n3)  AX  POP  BX  IMUL  AX  BX  MOV  NEXT  C; 

EXIT 

:  *  (  n  n2  -  n3)  UM*  DROP  ; 
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\  Number  conversion  operator 
!  :  val?  (  a  u  -  d  2  ,  n  1  ,  0) 

\  string  to  number  conversion  primitive.  True  if  d  is  valid. 

\  Returns  d  if  number  ends  in  final  '.'  and  sets  dpi  =  0 

\  Returns  n  if  no  punctuation  present  and  sets  dpi  =  0< 

[  # Jot  1-  ]  LITERAL  MIN  PAD  1-  OVER  -  TUCK  >R  CMOVE 

BL  PAD  1-  DUP  dpi  !  C!  0  0  R> 

DUP  C@  [ASCII]  -  =  DUP  >R  -  1- 

BEGIN  CONVERT  DUP  C@  DUP  [ASCII]  :  = 

SWAP  [ASCII]  ,  [ASCII]  /  1+  WITHIN  OR 
WHILE  DUP  dpi  !  REPEAT  R>  SWAP  >R  IF  DNEGATE  THEN 
PAD  1-  dpi  @  -  1-  dpi  !  R>  PAD  1-  =  (  valid?) 

IF  dpi  0  0<  IF  DROP  1  ELSE  2  THEN  ELSE  2 DROP  0  THEN  ; 

:  VAL?  (  a  u  -  d  2  ,  nl,  0)  {  Feature}  'val?  @ EXECUTE  ; 
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\  Interpreter  proper 
!  :  val,  (  ...  w  ) 

\  compiles  the  top  w  stack  items  as  numeric  literals. 

DUP  BEGIN  ROT  >R  1-  ?DUP  0=  UNTIL 

BEGIN  R>  [COMPILE]  LITERAL  1-  ?DUP  0=  UNTIL  ; 

:  interpret  {  Feature}  \  the  text  compiler  loop. 

BEGIN  BL  WORD  FIND  ?DUP 

IF  STATE  @  =  (  Imm?)  IF  ,  ELSE  EXECUTE  THEN 

ELSE  COUNT  VAL?  DUP  huh? 

STATE  0  IF  val,  ELSE  DROP  THEN 

THEN 
AGAIN  ; 
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\  QUIT  support 

:  EVALUATE  (  a  u)  \  evaluate  a  string. 

#TIB  2@  2>R  #TIB  2!  BLK  2@  2>R  0  0  BLK  2 !  interpret 
2R>  BLK  2!  2R>  #TIB  2!  ; 

:  EXPECT  (  a  +n)  'expect  0EXECUTE  ; 

:  QUERY  {  CONTROLLED} 

\  fill  TIB  from  next  line  of  input  stream. 

0  0  BLK  2!  TIB  80  EXPECT  SPAN  0  #TIB  !  ; 

:  ok?  \  status  check. 

DO  @  [  #Safe  ]  LITERAL  -  HERE  U<  ABORT"  No  Room" 

DEPTH  0<  ABORT"  Stack?"  ; 

:  OK?  [  Feature)  ok?  STATE  @  0=  IF  ."  ok"  THEN  ; 
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\  QUIT  and  ABORT 

:  QUIT  \  default  main  program. 

RESET  BEGIN  CR  QUERY  SPACE  interpret  OK?  AGAIN  ; 

:  GRIPE  (  a  u)  {  Feature}  \  default  error  handler. 

BLK  @  IF  BLK  20  scr  2!  THEN 

THERE  COUNT  TYPE  SPACE  (  msg  )  TYPE  ; 

:  ABORT  BEGIN  PRESET  QUIT  GRIPE  AGAIN  ; 

\  default  main  program  and  error  handler,  courtesy  Wil  Baden. 

:  ABORT"  \  compile  error  handler  and  message. 

[COMPILE)  IF  [COMPILE]  "  COMPILE  err  [COMPILE]  THEN  ; 
IMMEDIATE 
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(  Debug —  EXIT  when  done) 

:  .S  {  Control?}  \  display  the  data  stack. 

DEPTH  0  MAX  ?DUP 

CR  IF  0  DO  DEPTH  I  -  1-  PICK  .  LOOP  THEN  ."  <-Top  "  ; 

:  DUMP  (  a  u)  (  RESERVED)  \  simple  dump. 

SPACE  0  DO  DUP  7  AND  0=  IF  SPACE  THEN  DUP  C@  .  1+  LOOP 

DROP  ; 

:  ?  (  a)  0  .  ;  {  Control?) 

:  WORDS  {  Control?}  \  simple  word  list. 

CONTEXT  @ 

BEGIN  @  ?DUP 

WHILE  DUP  CELL+  COUNT  31  AND  TYPE  SPACE  REPEAT  ; 
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\  FORGET  support 

!  :  clip  (  a  'lfa)  \  unlink  words  below  the  given  address. 
BEGIN  DUP  0 

WHILE  2 DUP  0  SWAP  U<  NOT  (  ie  U<=  ) 

IF  DUP  0  @  OVER  !  (  unlinks  it  )  ELSE  @  THEN 

REPEAT  2 DROP  ; 

:  crop  (  lfa) 

\  crop  dictionary  to  the  given  link  address. 
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f  CELL+  (  ie  vlink)  2DUP  clip 

BEGIN  @  ?DUP  WHILE  2DUP  CELL  -  0  (  ie  >RAM)  clip 
REPEAT  FORTH  DEFINITIONS  DUP  CURRENT  @  clip  h  !  ; 
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\  FORGET  and  variations 

:  GUARD  h  HO  3  CELLS  CMOVE  THERE  TO  !  ;  {  Feature) 

:  EMPTY  HO  h  3  CELLS  CMOVE  TO  0  r  !  ;  {  Feature) 

:  >link  (  cfa  -  lfa) 

BEGIN  1-  DUP  C0  128  AND  UNTIL  CELL  -  ; 

:  FORGET  \  forget  words  from  the  following  <name>. 
CURRENT  0  CONTEXT  !  '  >link 

DUP  HERE  HO  @  WITHIN  ABORT"  Can't"  crop  ; 

{  FORGET  cannot  recover  RAM  and  so  is  not  ROMable.) 

{  Delete?) 
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\  -  Device  drivers  - 

HEX 

:  CODE  (type)  (  a  u)  BX  CX  MOV  DX  POP  1  #  BX  MOV 
40  #  AH  MOV  21  INT  BX  POP  'pause  )  JMP  C; 

!  CODE  KDOS  (  -  key  -1  ,  ?  0) 

\  check  for  key  pressed. 

\  Special  keys  are  returned  in  high  byte  with  low  byte  zeroed. 
BX  PUSH  FF  #  DL  MOV  6  #  AH  MOV  21  INT 

0  #  BX  MOV  2  L#  JE  AH  AH  SUB  (  special  key?) 

AL  AL  OR  1  L#  JNZ  7  #  AH  MOV  21  INT 
AH  AH  SUB  AL  AH  XCHG 

1  L:  TRUE  #  BX  MOV  2  L:  AX  PUSH  'pause  )  JMP  C; 

SCREEN  72 

\  KEY  and  EMIT  actions 

13  EQU  #EOL  (  end-of-line)  10  EQU  #LF  (  line-feed) 

HERE  EQU  $Eol  #EOL  C,  #LF  C,  2  EQU  #Eol 

!  :  (cr)  $Eol  #Eol  (type)  ; 

!  :  (key?)  (  -  f)  \  true  if  key  pressed  since  last  KEY. 
key'  0  0=  IF  KDOS  key'  2!  THEN  key'  0  ; 

:  KEY  (  -  n)  BEGIN  (key?)  UNTIL  key'  CELL+  0  0  key'  !  ; 

:  EMIT  (  b)  hid  C!  hid  1  TYPE  ; 

SCREEN  73 

\  EXPECT  action 

08  EQU  #BSP  (  backspace)  127  EQU  #DEL  (  delete) 

27  EQU  #ESC  (  escape) 

HERE  EQU  $Bsp  (  *  )  3  C,  #BSP  C,  BL  C,  #BSP  C, 

I  :  expect  (  a  +n)  >R  0  (  a  o) 

\  read  upto  +n  chars  into  address;  stop  at  #EOL  or  #ESC 
BEGIN  DUP  R@  < 

WHILE  KEY  127  (  7-bit  ASCII)  AND 
DUP  #BSP  =  OVER  #DEL  =  OR 
IF  DROP  DUP  IF  1-  $Bsp  COUNT  TYPE  THEN 
ELSE  DUP  #EOL  =  OVER  #ESC  =  OR 

IF  DROP  SPAN  !  R>  2 DROP  EXIT  THEN 
(  otherwise)  BL  MAX  >R  2DUP  +  R>  OVER  C!  1  TYPE  1+ 
THEN 

REPEAT  SPAN  !  R>  2 DROP  ; 

SCREEN  74 

\  Dumb  terminal  actions 
!  :  (keys)  (  a  +n)  >R  0  (  a  o) 

\  read  upto  +n  chars  into  address  without  echo;  stop  at  #EOL 
BEGIN  DUP  R@  < 

WHILE  KEY  DUP  #EOL  = 

IF  R>  2 DROP  DUP  >R  (  early  out) 

ELSE  BL  MAX  >R  2DUP  +  R>  SWAP  C!  1+  THEN 
REPEAT  SPAN  !  R>  2 DROP  ; 

:  :  (mark)  (an)  ."  A"  TYPE  ; 

!  :  (page)  25  0  DO  CR  LOOP  ; 

!  :  (tab)  (  n  n2)  CR  DROP  SPACES  ; 

SCREEN  75 

\  Initialize  automatic  variables 
HERE  EQU  RAMs 

)  nope  expect  source  nope  nope  val?  ( 

(  key'  )  0  ,  0  , 

HERE  RAMS  -  EQU  #RAMs 


SCREEN  76 


SCREEN  77 

\  -  Initialization  - 

DO  CONSTANT  parms  \  System  parameter  table. 


CREATE  glass  \  Simple  transfer  table. 

]  (type)  (cr)  (keys)  (key?)  (mark)  (page)  (tab)  nope  [ 


:  READY  ."  Ready"  ; 
:  BYE  0  EXECUTE  ; 


{  Feature)  \  Initialize  application. 
{  Feature)  \  Shut  down  application. 


SCREEN  78 

\  Initialization —  high-level 

160  CONSTANT  VERSION  {  Feature)  \  ZEN  1.60 

!  :  vocabs  \  initialize  vocabularies, 
f  CELL+  (  ie  vlink) 

(continued  on  page  106) 


Dr.  Dobb’s Journal,  January  1990 


CIRCLE  NO.  69  ON  READER  SERVICE  CARD 


105 

69 


ZEN 


listing  One  (Listing  continued,  text  begins  on  page  38.) 

BEGIN  @  ?DUP 

WHILE  DUP  CELL+  @  OVER  CELL  -  @  (  ie  >RAM)  !  REPEAT  ; 

!  :  cold  \  high-level  coldstart  initialization. 

TRUE  (  wake)  entry  entry  2!  TO  20  r  2!  glass  x  ! 

RAMs  'pause  #RAMs  CMOVE 

EMPTY  vocabs  PRESET  FORTH  DEFINITIONS  DECIMAL 
"  READY"  EVALUATE  ABORT  ; 

\  If  all  definitions  are  headerless,  substitute:  READY  ABORT  ; 

SCREEN  79 

\  Initialization —  low-level 
HEX  HERE  (  *)  ,"  No  Room  $" 

!  CODE  Coldstart  \  low-level  initialization. 

1000  #  BX  MOV  4A  #  AH  MOV  21  INT  (  enough  room?) 

1  L#  JNC  (  No:) 

(  *)  1+  #  DX  MOV  9  #  AH  MOV  21  INT  0  #  JMP  (  Bye) 

1  L:  #SP0  #  SP  MOV  #RP0  #  BP  MOV  BP  u  )  MOV 

'  cold  >BODY  #  SI  MOV  (  I  register)  NEXT  C; 

HERE  (  *  )  Power  ORG  ASSEMBLER  '  Coldstart  #  JMP  C; 

(  *  )  ORG 


SCREEN  80 
SCREEN  81 

\ - FILE  extension - 

#Used  USER  IO-RESULT  DROP 

26  EQU  #EOF  \  .control-Z  marks  the  end  of  older  text  files. 

128  EQU  buff  \  MS-DOS  command  tail  and  default  fcb  buffer. 

192  EQU  name  \  RENAME-FILE  takes  two  names. 

256  buff  -  EQU  #buff  \  size  of  buffer  in  bytes. 

name  buff  -  EQU  #name  \  size  of  name  in  bytes  plus  zero. 

!  :  >fname  (  a  u  -  a2)  \  convert  string  to  ASCIIZ  file  name, 

buff  2DUP  2>R  SWAP  MOVE  R@  0  2R>  +  C!  ; 

SCREEN  82 

\  MS-DOS  interface 
HEX 

CODE  fdos  (  DX  CX  handle  function#  -  AX) 

\  generic  call  to  MS-DOS 

BX  AX  MOV  BX  POP  CX  POP  DX  POP  21  INT 
LABEL  return  AX  BX  MOV  1  L#  JB  AX  AX  SUB  2  L#  JZ 

1  L:  BX  BX  SUB  (  non-zero  retcode  forces  zero  result) 

2  L:  u  )  DI  MOV  AX  IO-RESULT  entry  -  [DI]  MOV  NEXT  C; 

!  CODE  rename  (  a  a2  function#  -  AX) 

BX  AX  MOV  DI  POP  DX  POP  21  INT  return  JU  C; 


:  CODE  seek  (  DX  CX  handle  function#  -  AX  DX) 

BX  AX  MOV  BX  POP  CX  POP  DX  POP  21  INT 
DX  PUSH  return  JU  C; 

SCREEN  83 

\  5  file  primitives 
HEX 

:  OPEN-FILE  (  a  u  -  w)  >fname  0  0  3D02  fdos  ; 

:  CREATE-FILE  (  a  u  -  w)  >fname  0  0  3C00  fdos  ; 

:  DELETE-FILE  (  a  u)  >fname  0  0  4100  fdos  DROP  ; 

:  CLOSE-FILE  (  w)  00  ROT  3E00  fdos  DROP  ; 

:  RENAME-FILE  {  a  u  a2  u2) 

>fname  name  #name  CMOVE> 

>fname  name  5600  rename  DROP  ; 

SCREEN  84 

\  Read,  write  and  seek  bytes 
HEX 

\  Read  or  write  u  bytes  to  or  from  address  a  to  file  w. 

:  READ-FILE  (  a  u  w  -  u2)  3F00  fdos  ; 

:  WRITE -FILE  (  a  u  w  -  u2)  4000  fdos  ; 

:  SEEK-FILE  (  doff  n  w  -  dpos)  \  add  an  offset  to  file  w. 

\  n  neg:  to  start;  n  pos:  to  end;  n  zero:  to  current. 

SWAP  DUP  IF  0<  CELLS  1+  THEN  4201  +  seek  ; 

\  Return  file  position  or  size. 

:  FILEPOS  (  w  -  d)  >R  0  0  0  R>  SEEK-FILE  ; 

:  FILESIZE  (  w  -  d)  >R  0  0  1  R>  SEEK-FILE  ; 

SCREEN  85 

\  Read  and  write  lines  of  text 

:  WRITE-CR  (  w)  $Eol  #Eol  ROT  WRITE-FILE  DROP  ; 

:  READ-LINE  (auw-00  !  u2t) 

{  Greater  performance  will  result  if  the  end-of-line  sequence  } 
{  is  read  into  the  address  and  the  size  u  adjusted  accordingly.) 
>R  buff  OVER  1+  #buff  MIN  R@  READ-FILE  (  a  u  u2) 

DUP  0=  IF  R>  2 DROP  2 DROP  0  0  EXIT  THEN  (  end  of  file) 
buff  OVER  #EOL  SCAN  NIP  (  a  u  u2  u3) 

?DUP  IF  #Eol  OVER  -  >R  - 

ELSE  2DUP  U<  >R  THEN  MIN  R>  (  a  u4  #seek) 

?DUP  IF  S>D  0  R@  SEEK-FILE  2 DROP  THEN 

buff  OVER  #EOF  SCAN  NIP  -  (  remove  if  no  control-Zs) 

R>  DROP  (  a  u4)  >R  buff  SWAP  R@  CMOVE>  R>  TRUE  ; 

SCREEN  86 

\  Load  and  save  files 

:  GO  (  a  u)  {  Feature)  \  evaluate  the  KERNEL. SRC  file. 

"  KERNEL. SRC"  OPEN-FILE  DUP  huh?  (  w)  >R 

BEGIN  buff  DUP  64  R@  READ-LINE 

WHILE  EVALUATE  REPEAT  2DROP  R>  CLOSE-FILE  ; 

:  SAVE-FILE  (  a  u)  {  Feature)  \  save  the  dictionary  by  name. 

CREATE-FILE  DUP  huh?  (  w)  >R 

'pause  RAMs  #RAMs  CMOVE  GUARD  f  CELL+  (  ie  vlink) 

BEGIN  0  ?DUP  (  save  vocabularies) 

WHILE  DUP  CELL  -  @  (  ie  >RAM)  0  OVER  CELL+  !  REPEAT 
256  HERE  OVER  -  R@  WRITE-FILE  DROP  R>  CLOSE-FILE  ; 

SCREEN  87 

\  BLOCK  word  set 

VARIABLE  system  VARIABLE  block#  VARIABLE  update 
VARIABLE  buffer  1024  CELL  -  ALLOT 

:  seek-block  (  u  w  -  a  n  w) 

>R  1024  UM*  TRUE  R@  SEEK-FILE  2 DROP  buffer  1024  R>  ; 

:  SAVE-BUFFERS  {  BLOCK)  system  @  0=  ABORT"  No  File" 
system  2@  seek-block  WRITE-FILE  DROP  ; 

:  BUFFER  {  u  -  a)  {  BLOCK)  >R  block#  2@  R@  -  AND 
IF  SAVE-BUFFERS  THEN  0  R>  block#  2!  buffer  ; 

:  BLOCK  (  u  -  a)  {  BLOCK) 

DUP  block#  @  =  IF  DROP  buffer  EXIT  THEN 

BUFFER  >R  system  2@  seek-block  READ-FILE  DROP  R>  ; 

SCREEN  88 

\  BLOCK  support 

:  EMPTY-BUFFERS  {  CONTROLLED)  0  TRUE  block#  2!  ; 

HEX 

:  UPDATE  {  BLOCK)  TRUE  update  !  ; 

:  FLUSH  {  BLOCK) 

SAVE-BUFFERS  0  0  system  0  4500  fdos  CLOSE-FILE  ; 

:  LOAD  (  u)  {  BLOCK) 

BLK  20  2>R  0  SWAP  BLK  2!  interpret  2R>  BLK  2!  ; 

:  block  BLK  @  ?DUP  IF  BLOCK  1024  ELSE  #TIB  2@  THEN  ; 

\  Use  this  definition  if  the  BLOCK  word  set  is  compiled: 

:  READY  ."  Ready!"  [')  block  'source  ! 

"  NEW. SCR"  OPEN-FILE  DUP  huh?  system  !  EMPTY-BUFFERS  ; 


End  Listing 
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ERROR  MESSAGE  MANAGEMENT 


listing  One  (Text  begins  on  page  48.) 

/*  Include  file  for  macros  replacement  of  error  function.  */ 

♦define  error (m)  _error( _ FILE _ ,  _ LINE _ ) 

extern  void  error(char  *,  int); 


Listing  Two 


/*  Definition  of  error  function.  */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦include  "error. h" 

static  int  get_err_msg (char  *,  char  *,  char  *); 
void 

_error(char  *fname,  int  lno) 

( 

char  ‘period;  /*  Pointer  for  file  extension  */ 
char  lstr[6];  /*  Temp  string  for  file  line  */ 
char  key (15);  /*  Message  key  (file:line)  */ 

char  msg(75);  /*  Error  message  from  file  */ 

/*  Strip  out  file  extension  from  file  name  */ 
if  ((period  =  strchr (fname,  !=  NULL) 

‘period  =  '\0'; 

/*  Create  f ile : linenumber  key  */ 
sprintf(key,  "%s:%s",  fname,  itoa(lno,  lstr, 

10) )  ; 

/*  Look  up  error  message  from  file  */ 
if  ( !get_err_msg( fname,  key,  msg) ) 

/*  Not  found  in  file,  just  print  out 
*  file:lineno. 

*/ 

printf ("Error  [%s]",  key); 

else 

printf ("%s  [%s]",  msg,  key) ; 
return; 

)  /*  error()  */ 
static  int 

get_err_msg (char  ‘fname,  char  ‘key,  char  *msg) 

I 

FILE  ‘fp;  /*  Error  message  file  pointer  */ 

char  msg_key (14) ;/*  Key  for  current  line  */ 

/*  Open  error  file  */ 
if  ( ! (fp  =  fopen ("error .dat",  "r"))) 
return  FALSE; 

/*  Scan  file  for  message  */ 
while  (!feof(fp))  { 

fscanf(fp,  "  %s  ",  msg_key) ; 
fgets(msg,  75,  fp) ; 
if  { Istrcmpi (key,  msg_key) ) 
break; 

) 

fclose (fp) ; 

/*  Return  false  if  message  not  found  */ 
if  (feof(fp)) 

return  FALSE; 

/*  Remove  CR  from  message  string  */ 
msg[strlen (msg) -1]  =  '\0'; 
return  TRUE; 

)  /*  get_err_msg ()  */ 


Listing  Three 

BEGIN  { 

FS  =  " \ " " ; 

printf {"")  >  "error.txt"; 
printf ("")  >  "error.dat"; 

) 

/  ‘error  *\ (/  ( 

printf ("%s  :\n",  $2)  »  "error.txt"; 
ind  =  substr (FILENAME,  0,  index (FILENAME,  ".") 
-  1); 

printf ("%s : %d\t%s\n",  ind,  NR,  $2)  » 
"error.dat"; 


get line () ; 
i  =  index ($0,  "/*  "); 
if  (i)  i++; 
while  (i)  { 

printf ("\t%s\n",  substr($0, 
"error.txt"; 
get line () ; 

if  (index ($0,  "*/"))  break; 
i  =  index ($0,  "*  ") ; 

} 


End  Listing  One 


End  Listing  Two 


End  Listings 
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S-CODER 


Listing  One  (Text  begins  on  page  52.) 


_iob[l] ._flag  i-  ~_IOTRAN; 


/*  Simple  S-CODER  file  encryptor/decryptor 


**/ 

*/ 

**/ 


Listing  Four 


End  Listing  Three 


♦include  <stdio.h> 
♦include  <string.h> 
♦include  <assert.h> 


/*  Enhanced  security  S-CODER  file  encryptor/decryptor 


**/ 

*/ 

**/ 


♦define  BUF_SIZ  32768 

extern  char  *cryptext; 
extern  int  crypt_length; 
void  crypt (char  *); 


♦include  <stdio.h> 
♦include  <stdlib.h> 
♦include  <string.h> 
♦include  <assert.h> 


main (int  argc,  char  *argv[]) 

( 

unsigned  i,  n; 
char  *buf,  *p; 

FILE  *infile,  *outfile; 

if  (4  >  argc) 

{ 

puts ("\aUsage:  CRYPT  input_file  output_file  key"); 
abort ( ) ; 

) 

assert (buf  =  (char  *)malloc (BUF_SIZ) ) ; 

assert (infile  =  fopen (argv(l] ,  "rb" )); 

assert (outfile  =  fopen (argv[2] ,  "wb")); 

cryptext  =  argv[3); 

crypt_length  =  strlen (cryptext) ; 

while  (n  =  fread(buf,  1,  BUF_SIZ,  infile)) 

{ 

p  =  buf; 

for  (i  =  0;  i  <  n;  ++i) 
crypt (p++) ; 

fwrite(buf,  1,  n,  outfile); 

1 

fclose (infile) ; 
fclose (outfile) ; 
exit (0) ; 

} 

End  Listing  One 


Listing  Two 


/**■ 

/* 

/**: 


Simple  S-CODER  stream  encryptor/decryptor 


♦include  <stdio.h> 
♦include  <string.h> 
♦include  <assert.h> 

extern  char  ‘cryptext; 
extern  int  crypt_length; 
void  crypt (char  *7; 


*/ 

“*/ 


main (int  argc,  char  *argv[]) 

( 

char  cch; 
int  ich; 

FILE  ‘infile; 
void  setraw(void) ; 

if  (2  >  argc) 

{ 

puts ("\aUsage:  SCRYPT  key"); 
puts ("encrypts  stdin  to  stdout"); 
abort () ; 

} 

cryptext  =  argv[l]; 
crypt_length  =  strlen (cryptext) ; 

setraw();  /*  NOTE:  setraw()  will  be  compiler-dependent.  It  is  used 
to  set  stdin  and  stdout  to  raw  binary  mode.  This  is 
necessary  to  avoid  CR/LF  translation  and  to  avoid 
sensing  Oxla  as  EOF  during  decryption.  */ 
while  (EOF  !=  (ich  =  getchar())) 

{ 

cch  =  (char) ich; 
crypt (&cch) ; 
fputc(cch,  stdout); 

} 

exit  (0) ; 

} 


End  Listing  Two 


Listing  Three 

/*  Zortech  C  routine  to  set  stin  and  stdout  to  binary  mode 


*/ 

*/ 

*/ 


♦include  <stdio.h> 
extern  FILE  _iob[_NFILE] ; 
void  setraw(void) 

{ 

_ i ob [ 0 ] ._flag  &=  ~_IOTRAN; 


♦define  MIN_KEYL  6 

extern  char  ‘cryptext; 
extern  int  crypt_length; 
void  crypt (char  *); 
int  cryptqual (void)  ; 
long  fsize; 

union  (  /*  Transposition  cipher  buffer  */ 

char  in [16384 J ; 
char  out [128] [128] ; 

}  buf; 

FILE  ‘infile,  ‘outfile; 

main (int  argc,  char  *argv[]) 

{ 

void  encrypt (void) ; 
void  decrypt (void) ; 

if  (5  >  argc  I!  NULL  ==  strchr ("EeDd",  a rg v [1] [0])) 

{ 

puts ("\aUsage:  HI-CRYPT  {  E  :  D  )  input_file  output_file  key"); 
puts ("where:  E  =  Encrypt"); 
puts("  D  =  Decrypt"); 

abort  () ; 

) 

assert (infile  =  fopen (argv[2] ,  "rb")); 
assert (outfile  =  fopen (argv[3] ,  "wb")); 
cryptext  =  argv[4]; 
crypt_length  =  strlen (cryptext) ; 
if  (cryptqual () ) 

I 

puts ("\aHI-CRYPT:  Key  is  not  sufficiently  complex"); 
abort () ; 

> 

if  (strchr ("Ee",  argv[l][0])) 
encrypt () ; 
else  decrypt (); 
fclose (infile) ; 
fclose (outfile) ; 
exit (0) ; 

) 

int  cryptqual (void) 

I 

int  i,  j  =  0; 

static  char  found [MIN_KEYL  +  1];  /*  Statics  initialized  to  zeros  */ 

if  (MIN_KEYL  >  crypt_length) 
return  -1; 

for  (i  =  0;  i  <  crypt_length;  ++i) 

{ 

if  (strchr (found,  cryptext [i] ) ) 
continue; 

found [j++]  =  cryptext [i]; 
if  ( (MIN_KEYL  -  1)  <  j) 
return  0; 

) 

return  -1; 

} 

void  encrypt (void) 

I 

unsigned  i,  j,  n; 

fseek (infile,  0L,  SEEK_END) ; 

fsize  =  ftell (infile) ;  /*  Save  size  */ 

rewind (infile) ; 

fwrite (Sfsize,  sizeof (long) ,  1,  outfile); 

srand( (unsigned) fsize) ; 

crypt_ptr  =  fsize  %  crypt_length; 

while  (n  =  fread (buf . in,  1,  16384,  infile)) 

{ 

while  (16384  >  n) 

buf.in[n++]  =  rand(); 
for  (i  =  0;  i  <  128;  ++i) 

for  (j  =  0;  j  <  128;  ++j) 

crypt (&buf .out [ j]  [i ] ) ; 
fwrite (buf .in,  1,  16384,  outfile); 

) 

) 

void  decrypt (void) 

I 

unsigned  i,  j,  n; 

fread(&fsize,  sizeof (long) ,  1,  infile); 
crypt_ptr  =  fsize  %  crypt_length; 

while  (n  =  fread (buf . in,  1,  16384,  infile))  /*  Read  size  */ 

{ 

for  (i  =  0;  i  <  128;  ++i) 

for  (j  =0;  j  <  128;  ++j) 

crypt ( &buf . out [ j ]  [ i ] ) ; 
if  (16384  <=  fsize) 

fwrite (buf .in,  1,  16384,  outfile); 
else  fwrite (buf .in,  1,  fsize,  outfile); 
fsize  -=  n; 

} 

) 

End  Listing  Foi 
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Listing  Five 


/*  Collect  file  statistics 

♦include  <stdio.h> 

♦include  <math.h> 

♦include  <assert.h> 

main(int  argc,  char  *argv[]) 

{ 

int  i,  ch,  hist  =  0; 
long  n  =  0L; 

double  mean  =0.,  stdev  =  0.,  ftmp; 
static  unsigned  bins [256]; 

FILE  *infile; 

assert (infile  =  fopen (argv[l] ,  "rb")); 
while  (! feof  (infile) ) 

{ 

if  (EOF  ==  (ch  =  fgetc (infile) ) ) 
break; 
bins[ch]  +=  1; 

++n; 

} 

fclose (infile) ; 

for  (i  =0;  i  <  256;  ++i) 

{ 

mean  +=  (double) (bins [i] ) ; 
if  (bins[i]J 

++hist; 

) 

mean  /=  256.; 

for  (i  =  0;  i  <  256;  ++i) 


**/ 

*/ 

**/ 


ftmp  =  (double) (bins [i] )  -  mean; 
stdev  +=  (ftmp  *  ftmp); 

) 

ftmp  =  stdev  /  255.; 

stdev  =  sqrt(ftmp); 

printf("%ld  Characters  were  read  from  %s\n" 

"There  are  an  average  of  %f  occurances  of  each  character\n" 
"%d  Characters  out  of  256  possible  were  used\n" 

"The  standard  deviation  is  %f\n" 

"The  coefficient  of  variation  is  %f%%\n", 

n,  argv[l],  mean,  hist,  stdev,  (100.  *  stdev)  /  mean); 


End  Listings 
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EXAMINING  ROOM 


Listing  One  (Listing  continued,  text  begins  on  page  64.) 

inline  Complex  polar (double  Radius,  double  Theta) 

( 

Complex  Result; 

Result. Real  =  Radius  *  cos (Theta); 

Result. Imag  =  Radius  *  sin (Theta); 
return  Result; 

} 

inline  Complex  con j (const  Complex  &  C) 

{ 

Complex  Result; 

Result. Real  =  C.Real; 

Result. Imag  =  -C.Imag; 
return  Result; 

} 

//  trigonometric  methods 

inline  Complex  cos (const  Complex  &  C) 

( 

Complex  Result; 

Result. Real  =  cos (C.Real)  *  cosh (C. Imag) ; 

Result. Imag  =  -sin (C.Real)  *  sinh (C. Imag) ; 
return  Result; 


} 

inline  Complex  sin (const  Complex  &  C) 

{ 

Complex  Result; 

Result. Real  =  sin (C.Real)  *  cosh (C. Imag) ; 
Result. Imag  =  cos (C.Real)  *  sinh (C. Imag) ; 
return  Result; 

) 

inline  Complex  tan (const  Complex  &  C) 

{ 

Complex  Result; 

Result  =  sin(C)  /  cos (C) ; 
return  Result; 

} 

inline  Complex  cosh (const  Complex  &  C) 

( 

Complex  Result; 

Result  =  cos (C.Imag)  *  cosh (C.Real) ; 
Result  =  sin (C.Imag)  *  sinh (C.Real) ; 
return  Result; 

} 

inline  Complex  sinh (const  Complex  &  C) 

I 

Complex  Result; 

Result. Real  =  cos (C.Imag)  *  sinh (C.Real) ; 
Result. Imag  =  sin (C.Imag)  *  cosh (C.Real) ; 
return  Result; 

} 

inline  Complex  tanh (const  Complex  &  C) 


{ 

Complex  Result; 

Result  =  sinh(C)  /  cosh(C); 
return  Result; 

) 

//  logarithmic  methods 

inline  Complex  exp (const  Complex  &  C) 

I 

Complex  Result; 
double  X  =  exp(C.Real); 

Result. Real  =  X  *  cos (C.Imag) ; 

Result. Imag  =  X  *  sin (C.Imag); 
return  Result; 

} 

inline  Complex  log (const  Complex  &  C) 

{ 

Complex  Result; 
double  Hypot  =  abs  (C) ; 
if  (Hypot  >  0.0) 

{ 

Result. Real  =  log (Hypot); 

Result. Imag  =  atan2 (C. Imag,  C.Real); 

} 

else 

Complex : : ErrorHandler ( ) ; 
return  Result; 

} 

#endif  //  _ Complex_HPP 


End  Listing  One 


Listing  Two 


Complex 

2.00  28-Oct-1989 

C++  2.0;  Environ:  Any;  Compilers:  Zortech  C++  2.01 

Provides  the  class  "Complex"  for  C++  programs.  The  majority 
of  the  class  is  implemented  inline  for  efficiency.  Only 
the  division,  power,  and  i/o  methods  are  actual  functions. 
Scott  Robert  Ladd,  705  West  Virginia,  Gunnison  CO  81230 
BBS  (303)641-6438;  FidoNet  1:104/708 

finclude  "math.h" 

♦include  "stdlib.h" 
finclude  "Complex. hpp" 
finclude  "stream. hpp" 

static  void  DefaultHandler () ; 

void  (*  Complex: : ErrorHandler) ()  =  DefaultHandler; 
static  void  DefaultHandler () 

( 

cout  «  "\aERROR  in  complex  object:  DIVIDE  BY  ZERO\n"; 
exit (1) ; 

} 

//  division  methods 

Complex  operator  /  (const  Complex  s  Cl,  const  Complex  s  C2) 

Complex  Result; 
double  Den; 

Den  =  norm(C2); 
if  (Den  !=  0.0) 

{ 

Result. Real  -  (Cl. Real  *  C2.Real  +  Cl. Imag  *  C2.Imag)  /  Den; 

Result. Imag  •  (Cl. Imag  *  C2.Real  -  Cl. Real  *  C2.Imag)  /  Den; 

else 

Complex : : ErrorHandler ( ) ; 
return  Result; 

} 

Complex  Complex: : operator  /=  (const  Complex  &  C) 

double  Den,  OldReal; 

Den  =  norm(C); 
if  (Den  !=  0.0) 

{ 

OldReal  =  Real; 

Real  =  (Real  *  C.Real  +  Imag  *  C.Imag)  /  Den; 

Imag  =  (Imag  *  C.Real  -  OldReal  *  C.Imag)  /  Den; 

else 

Complex: : ErrorHandler () ; 
return  *this; 

) 

//  "power"  methods 

Complex  pow (const  Complex  &  C,  const  Complex  &  Power) 

Complex  Result; 

if  (Power. Real  ==  0.0  &&  Power. Imag  ==  0.0) 

Result. Real  =  1.0; 

Result. Imag  =  0.0; 

} 

else 

{ 

if  (C.Real  ! =  0.0  II  C.Imag  !=  0.0) 

Result  =  exp ( log (C)  *  Power); 

else 

Complex: : ErrorHandler () ; 

) 

return  Result; 

} 

Complex  sqrt (const  Complex  &  C) 

( 


//  Module: 

//  Version: 

//  Language: 

//  Purpose: 

// 

// 

//  Written  by: 

// 


(continued  on  page  117) 
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Listing  Two  (Listing  continued,  text  begins  on  page  64.) 

Complex  Result; 

double  r,  i,  ratio,  w; 

if  (C.Real  !=  0.0  C.Imag  !=  0.0) 

{ 

r  =  C.Real  <  0.0  ?  -C.Real  :  C.Real; 
i  =  C.Imag  <  0.0  ?  -C.Imag  :  C.Imaq; 
if  (r  >  i) 

{ 

ratio  =  i  /  r; 

w  =  sqrt(r)  *  sqrt(0.5  *  (1.0  +  sqrt(1.0  +  ratio  *  ratio))); 

else 

{ 

ratio  =  r  /  i; 

w  =  sqrt(i)  *  sqrt (0 . 5  *  (ratio  +  sqrt(1.0  +  ratio  *  ratio))); 

if  (C.Real  >  0) 

( 

Result. Real  =  w; 

Result. Imag  =  C.Imag  /  (2.0  *  w) ; 

) 

else 

{ 

Result. Imag  =  (C.Imag  >0.0)  ?  w  :  -  w; 

Result. Real  =  C.Imag  /  (2.0  *  Result . Imag) ; 

} 

else 

Complex: rErrorHandler () ; 
return  Result; 

} 

//  output  method 

ostream  &  operator  «  (ostream  &  Output,  const  Complex  &  C) 

Output  «  form(" (%+lg%+lgi) ",  C.Real,  C.Imag)  ; 
return  Output; 

} 

istream  &  operator  »  (istream  &  Input,  Complex  &  C) 

char  Ch; 

C.Real  =  0.0; 

C.Imag  =  0.0; 

Input  »  Ch; 
if  (Ch  ==  '  (') 

{ 

Input  »  C.Real  »  Ch; 
if  (Ch  ==  ',') 

Input  »  C.Imag  »  Ch; 


if  (Ch  !=  ')') 

Input .clear (_bad) ; 

) 

else 

{ 

Input . putback (Ch) ; 

Input  »  C.Real; 

) 

return  Input; 

} 

End  Listing  Two 


Listing  Three 


//  Program:  Biomorph  (Generate  non-standard  fractals) 

//  Version:  1.01  31-Oct-1989 

//  Language:  C++  2.0;  Environ:  Any;  Compilers:  Zortech  C++  2.01 
//  Purpose:  Generates  fractals  based  on  complex  number  formula  iterations 

//  Written  by:  Scott  Robert  Ladd,  705  West  Virginia,  Gunnison  CO  81230 
//  BBS  (303)641-6438;  FidoNet  1:104/708 

finclude  "conio.h" 

#include  "zg_lwlvl .h" 
finclude  "complex. hpp" 

Complex  C,  Z,  Power; 

double  Range,  Xinc,  Yinc,  Xmax,  Ymax,  Xorig,  Yorig; 
int  X,  Y,  I,  Iterations,  Species; 

void  GetParamsO; 
int  main(); 

void  GetParamsO 

I 

cout  «  "Biomorph  1.01  —  a  complex-plane  fractal  generator\n"; 

cout  «  "  \ n " ; 

cout  «  "This  program  generates  these  species  of  biomorphs ... \n"; 

cout  «  "  Species  0:  Z-'X  +  C  Species  1:  sin(Z)  +  exp(Z)  +  C\n"; 

cout  «  "  Species  2:  ZAZ  +  ZAX  +  C  Species  3:  sin(Z)  +  ZAX  +  C\n\n"; 

do  ( 

cout  «  "What  species  of  biomorph  do  you  want  ( 0 . . 3 ) ?  "; 
cin  »  Species; 

i  ( continued  on  page  119) 
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EXAMINING  ROOM 


Listing  Three  (Listing  continued,  text  begins  on  page  64.) 

while  ((Species  <  0)  !!  (Species  >  3)); 

case  1: 

cout  «  "\we  need  one  or  two  complex  numbers.  These  can  be  entered\n"; 

Z  =  sin(Z)  +  exp(Z)  +  C; 

cout  «  "in  the  following  formats  (where  ' t'  indicates  a  floating-point\n"; 

break; 

cout  «  "value :\n"; 

case  2 : 

cout  «  "  f  -or-  (f)  (just  a  real  number) \n"; 

Z  =  pow(Z,Z)  +  pow(Z, Power)  +  C; 

cout  «  "  (f,f)  (entering  both  the  real  and  imaginary  parts) \n\n"; 

break; 

if  (Species  !=  1) 

case  3: 

{ 

Z  =  sin(Z)  +  pow(Z, Power)  +  C; 

cout  «  "Enter  the  complex  power  applied  to  Z: 

break; 

cin  »  Power; 

} 

} 

if  ( (abs (real  (Z) )  >=  10.0)  I!  (abs (imag (Z) )  >=  10.0) 

cout  «  "Enter  the  complex  constant  C:  "; 

1 1  (norm(Z)  >=  100.0) ) 

cin  »  C; 

break; 

cout  «  "\nNext  two  numbers  are  floating  point  values  representing  the\n"; 

1 

cout  «  "origin  point  on  the  complex  plane  of  the  area  being  viewed. \n\n"; 

if  ( (abs (real  (Z) )  <  10.0)  II  (abs (imag (Z) )  <  10.0)) 

cout  «  "Enter  the  X  location  of  the  center  of  the  picture:  "; 

ZG  PlotPixel (X, Y, 0) ; 

cin  »  Xorig; 

else 

cout  «  "Enter  the  Y  location  of  the  center  of  the  picture: 

ZG  PlotPixel (X, Y, ZG  Videoinfo. NoColors  -  1); 

cin  »  Yorig; 

if  (kbhitO)  break; 

cout  «  "\nNext  number  represents  the  distance  the  graph  extends  away\n"; 

) 

cout  «  "from  the  above  origin. \n\n"; 

if  (kbhitO)  break; 

cout  «  "Enter  the  range  of  the  graph:  "; 

) 

cin  »  Range; 

while  (! kbhitO)  ; 

cout  «  "\nFinally,  how  many  iterations  should  the  program  perform?  "; 

if  ( ! getch ( ) )  getch(); 

cin  »  Iterations; 

ZG  Done ( ) ; 

} 

return  0; 

int  main() 

GetParams () ; 

if  (ZG  InitO)  return  1; 

if  (ZG  SetMode (ZG  MOD  BESTRES))  return  2; 

Ymax  =  ZG  Videoinfo. Ylength; 

Xmax  =  Ymax  /  (1.33333333  *  Ymax  /  ZG  Videoinfo. Xwidth) ; 

Xinc  =  2.0  *  Range  /  Xmax; 

Yinc  =  2.0  *  Range  /  Ymax; 

Range  =  -Range; 

for  (X  =  0;  X  <  Xmax;  ++X) 

{ 

for  (Y  =  0;  Y  <  Ymax;  ++Y) 

End  Listings 

Z  =  Complex ( (Range+Xinc  *  X+Xorig) , (Range+Yinc  *  Y+  Yorig)); 

for  (I  =  0;  I  <  Iterations;  ++I) 

( 

switch  (Species) 

case  0  : 

Z  =  pow(Z, Power)  +  C; 

break; 
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PROGRAMMER'S  WORKBENCH 


Listing  One  (Text  begins  on  page  74.) 

/*  FFFF.C 

—  causes  GP  fault  in  real  mode  on  286/386,  and  in  Virtual  86  mode 

—  catch  it  in  real  mode 

—  can't  catch  it  in  Virtual  86  mode 

—  distinguishes  between  GP  fault  and  IRQ5 

*/ 

♦include  <stdio.h> 

♦include  <dos.h> 

♦include  "gpfault.h" 

void  (interrupt  far  *old)(); 
cdecl  main(); 


♦endif 

♦define  INT_GPFAULT  OxOD 

♦define  INT_IRQ5  OxOD 


/*  386  protected-mode :  far  pointer  is  48  bits;  near  pointer  is  32  bits  */ 
/*  thus,  386  pmode  near  pointer  can  hold  a  real-mode  far  pointer  */ 

♦ifdef  _ HIGHC _ 

♦define  real_far  _near 

♦define  prot_far  _far 

♦define  far  _far 

♦else 

♦if  defined ( _ WATCOMC _ )  &&  defined ( _ 386 _ ) 

♦define  real_far  near 

♦define  prot_far  far 

♦endif 
♦endif 


void  fini(char  *msg,  int  exit_code) 

( 

puts (msg) ; 

_dos_setvect (INT_GPFAULT,  old); 
exit (exit_code) ; 

} 

void  far  my_exit (void)  {  fini("Bye!",  1); 


typedef  unsigned  long  UL; 

typedef  void  far  *FP; 

typedef  enum  {  FALSE,  TRUE  }  BOOL; 

♦ifdef  _ HIGHC _ 

/*  use  overlay  struct;  no  High  C  support  for  48-bit  immediate  values  */ 
/*  remember  that  unsigned  is  32  bits,  short  is  16  bits  */ 
typedef  struct  {  unsigned  off;  short  seg;  )  overlay; 


/* 

In  this  tiny  program,  it  is  easy  to  determine  whether  an  INT  OD 
was  caused  by  GP  fault  or  by  IRQ5  —  just  see  if  CS  on  the 
interrupt  handler's  stack  corresponds  to  this  code  segment. 

A  real  program  would  need  to  do  a  more  thorough  check  to  see 
if  r.cs: r.ip  corresponded  to  any  known  places  in  the  code  where 
a  GP  fault  is  expected  or  allowed  to  occur,  then  the  handler 
could  pass  the  interrupt  along  using  _chain_intr (old) . 

V 

♦define  IS_GPFAULT (cs,  ip)  ((cs)  ==  FP_SEG(main) ) 

void  interrupt  far  handler (REG_P ARAMS  r) 

( 

if  (IS_GPFAULT (r . cs,  r.ip)) 

{ 

printf ("\nProtection  violation  at  %04X: %04X\n",  r.cs,  r.ip); 

/* 

Change  CS:IP  on  stack  so  control  is  "returned"  to  my_exit; 
this  is  an  alternative  to  using  longjmpO  . 

*/ 

r.cs  =  FP_SEG (my_exit) ; 
r.ip  =  FP_OFF (my_exit) ; 

} 

else 

{ 

/*  handle  IRQ5  --  unfortunately,  _chain_intr ()  not  in  Turbo  C  */ 
_chain_intr (old) ; 

) 

} 


♦define  FP_SEG(fp)  ((overlay  prot_far  *)  &(fp))->seg 

♦define  FP_OFF(fp)  ((overlay  prot_far  *)  &(fp))->off 

♦else 

♦if  (!(defined( _ WATCOMC _ )  &&  defined( _ 386 _ ))) 

/*  Microsoft  C  FP_SEG()  and  FP_OFF()  require  an  lvalue:  yuk!  */ 

♦ifdef  FP_SEG 

♦undef  FP_SEG 

♦undef  MK_FP 

♦undef  FP_OFF 

♦endif 

♦define  FP_SEG(fp)  ( ( (UL) ( (FP)  fp) )  »  16) 

♦define  MK_FP (seg, off)  ( (FP) (UL) ( ( (UL) (seg)  «  16)  !  (off))) 

♦define  FP_OFF(fp)  ( (unsigned) ( (FP)  fp) ) 

♦endif 

♦endif 


♦ifdef  _ HIGHC _ 

♦pragma  Calling_convention (C_interrupt  !  _FAR_CALL) ; 
typedef  void  ( * IPROC) ( ) ; 

♦pragma  Calling_convention ( ) ; 

♦else 

typedef  void  (interrupt  far  *IPROC){); 

♦endif 

Listing  Three 


End  Listing  Two 


/*  GPFAULT.C  --  for  Rational  Systems  DOS/16M  or  Eclipse  Computer  Solutions 
(formerly  AI  Architects)  OS/286 


cdecl  main() 

< 

int  *p  =  (int  *)  -1; 
old  =  _dos_getvect (INT_GPFAULT) ; 
♦ifndef  CRASH_AT 

_dos_setvect (INT_GPFAULT,  handler) ; 
♦endif 

printf ("int  at  %p  is  ",  p) ; 
printf ("%04X\n",  *p) ; 

/‘NOTREACHED  on  286/386  */ 
fini ("Done !  ",  0); 


Listing  Two 


End  Listing  One 


/*  GPFAULT.H 

—  REG_PARAM  structure  represents  stack  at  entry  to  interrupt  handler 
—  CPU  pushes  flags,  CS:IP,  and,  for  protected-mode  INT  08-0D, 
an  error  code 

—  Compiler  pushes  all  other  registers  at  entry  to  interrupt  function 
—  Turbo  C  pushes  registers  in  a  strange  order 

—  Watcom  C  386  7.0  also  pushes  FS  and  GS  registers  (unfortunately 
MetaWare  High  C  for  MS-DOS  386  1.5  does  not) 

--  replace  Microsoft  C  5.1  FP_SEG,  FP_OFF  macros  with  ones  that  don't 
requires  lvalues 

—  keep  Watcom  C  386  7.0  FP_SEG,  etc.  —  these  work  for  48-bit  pointers 

—  for  MetaWare  High  C  for  386  MS-DOS,  need  our  own  48-bit  FP_SEG,  etc. 

*/ 

♦ifdef  InstantC_16M 

/*  Rational  Systems  Instant-C/16M  protected-mode  C  interpreter  */ 

♦define  DOS16M 
♦define  PROT_MODE 
♦endif 

typedef  struct  { 

♦if  defined ( _ WATCOMC _ )  &&  defined! _ 386 _ ) 

unsigned  gs,fs; 

♦endif 

♦ifdef  _ TURBOC _ 

unsigned  bp, di,  si,  ds,  es, dx, cx, bx, ax; 

♦else 

unsigned  es,  ds,  di,  si,  bp,  sp,  bx,  dx,  cx,  ax; 

♦endif 

♦ifdef  PROT_MODE 

unsigned  err_code; 

♦endif 

unsigned  ip, cs, flags; 

}  REG_P ARAMS; 


/*  same  as  PUSHA  */ 

/*  for  pmode  INT  08-OD  */ 


for  DOS16M: 

if  not  exist  dosl61ib.obj  cl  -AL  -Ox  -Gs2  -c  source\dosl61ib. c 

cl  -AL  -Ox  -Gs2  -c  -DPROT_MODE  -DDOS16M  -Zi  gpfault.c 

link  /co  preload  crt0_16m  pml  gpfault  dosl61ib  /noe, gpfault; 

makepm  gpfault 

splice  gpfault  gpfault 

for  OS/286: 

if  not  exist  \os286\llibce . lib  call  patch  msc51e 

cl  -AL  -Ox  -Gs2  -c  -DPROT_MODE  gpfault.c 

link  gpfault, gpfault, gpfault/map, \os286\llibce; 

\os286\express  gpfault 

*/ 


♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <setjmp.h> 

♦include  <string.h> 

♦include  <dos.h> 

♦ifdef  DOS 16M 
♦include  "dosl6.h" 

♦endif 

♦include  "gpfault.h" 

♦define  IN_MY_CODE  11593 

♦define  IN_USER_CODE  16843 

♦define  IN_HANDLER  40311 

unsigned  whereami  -  IN_MY_CODE;  /* 

jmp_buf  toplevel; 

jmp_buf  toplevel_copy  =  (0);  /* 

unsigned  legal  =  0;  /* 

void  (interrupt  far  *old_intl3handler) 


need  our  own  protection  for  this  */ 

initialized,  in  a  different  segment*/ 
just  a  legal  address  to  bang  on  */ 


void  interrupt  far  int 1 3handler (REG_P ARAMS  r) ;  /* 

void  goto_toplevel (void) ;  /*  long jump  out  of 

void  revert (void) ;  /*  restore  default 

void  fail (char  *msg,  FP  fp) ;  /*  fail  by  calling 

main  (int  argc,  char  *argv[]) 

{ 

char  buf [255] ; 
unsigned  far  *fp; 
unsigned  data; 

old_intl3handler  =  _dos_getvect (INT_GPFAULT) ; 

_dos_setvect (INT_GPFAULT,  intl3handler) ; 

printf ("'Q'  to  quit,  '!'  to  reinstall  default  GP  Fault  handler\n") ; 
printf ("%Fp  is  a  legal  address  to  poke\n",  filegal) ; 

/*  next  line  helps  illustrate  limitations  of  protection  */ 
printf ("%Fp  is  not  a  legal  address  to  poke\n",  Slegal-1); 


GP  fault  handler  */ 
handler  */ 
handler  */ 
default  handler  */ 


♦ifdef  _ TURBOC _ 

♦define  _dos_setvect (x,y)  setvect(x,y) 

♦define  _dos_getvect (x)  getvect(x) 


set jmp (toplevel) ; 
whereami  =  IN_MY_CODE; 


(continued  on  page  122) 
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Listing  Three  (Listing  continued,  text  begins  on  page  74.) 

memcpy  ( topi eve l_copy,  toplevel,  sizeof  ( jmp_buf) ) ; 

for  (;;) 

{ 

printf  ("$  "); 

*buf  =  '  \  0 ' ; 
gets (buf ) ; 

if  (toupper (*buf)  ==  'Q' ) 
break; 

else  if  (*buf  ==  ' ! ' ) 

{ 

revert  () ; 
continue; 

} 

sscanf (buf ,  "%Fp  %u",  &fp,  sdata) ; 
whereami  =  IN_USER_CODE; 

*fp  =  data;  /*  the  crucial  line  of  code  */ 
printf ("poked  %Fp  with  %u\n",  fp,  *fp); 
whereami  =  IN_MY  CODE; 

} 

revert () ; 
puts ("Bye") ; 
return  0; 

} 

void  revert (void) 

( 

_dos_setvect (INT  GPFAULT,  old  intl3handler) ; 

} 

void  fail (char  *msg,  FP  fp) 

( 

(fp)  ?  printf (msg,  fp)  :  puts(msg); 
revert  ()  ; 

_chain  intr(old  intl3handler) ; 

) 

void  goto_toplevel (void) 

{ 

if  (memcmp (toplevel,  toplevel_copy,  sizeof (jmp_buf) )  ==  0) 
long jmp (toplevel,  -1); 

else 

fail ("Toplevel  context  has  been  trompled",  0); 

void  interrupt  far  intl3handler (REG  PARAMS  r) 

{ 

switch  (whereami) 

{ 

case  IN  HANDLER: 


fail ("\nDouble  fault  at  %Fp\n",  MK_FP(r.cs,  r.ip)); 

/‘NOTRE ACHED*/ 
case  IN_MY_CODE: 

/* 

In  a  program  that  had  to  look  out  for  IRQ5  in 
addition  to  GP  fault,  here  one  might  want  to 
_chain_intr (old_intl3handler)  and  then  recover. 

*/ 

fail ("\nlnternal  error  at  %Fp\n",  MK_FP(r.cs,  r.ip)); 

/‘NOTRE ACHED*/ 
case  IN_USER_CODE : 

whereami  =  IN_HANDLER; 

_enable();  /*  reenable  interrupts  */ 

/*  we  could  use  Intel  LAR  and  LSL  instructions  here  to 
figure  out  why  GP  fault  took  place:  did  we  try  to  write 
into  code?  or  did  offset  overrun  segment  limit?  */ 
printf ("\nProtection  violation  at  %04X: %04X\n",  r.cs,  r.ip); 
if  (r.err_code) 

printf ("Error  code  %04X\n",  r.err_code); 
printf ("<ES  %04X>  <DS  %04X>  <DI  %04X>  <SI  %04X>\n", 
r.es,  r.ds,  r.di,  r.si); 

printf ("<AX  %04X>  <BX  %04X>  <CX  %04X>  <DX  %04X>\n", 
r.ax,  r.bx,  r.cx,  r.dx); 
goto_toplevel () ; 

/‘NOTREACHED*/ 
default : 

whereami  =  IN_HANDLER; 

_enable ( ) ; 

puts ("whereami  flag  got  trompled"); 
goto_toplevel () ; 

/‘NOTREACHED*/ 

I 

} 

#ifdef  DOS16M 
/* 

NOTE!  For  capturing  most  interrupts  in  DOS/16M,  the  following  is 
_not_  necessary.  In  the  vast  majority  of  cases,  Microsoft's 
_dos_setvect ()  and  _dos_getvect ( )  will  "do  the  right  thing"  under 
DOS/16M.  But  capturing  INT  0D  to  get  at  protected-mode  GP  Faults 
(rather  than  getting  at  real-mode  IRQ5)  is  an  admittedly  uncommon 
case,  so  here  we  have  to  kick  down  and  use  the  DOS/16M  API. 

*/ 

void  _dos_setvect (unsigned  intno,  IPROC  isr) 

{ 

D16pmlnstall (intno,  FP_SEG(isr),  FP_OFF(isr),  NULL) ; 

} 

IPROC  _dos_getvect (unsigned  intno) 

{ 

IPROC  isr; 

D1 6pmGetVector ( intno,  (INTVECT  *)  &isr) ; 
return  isr; 

Ldif  End  Listings 
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A  locator  for  embedded  systems  programming 
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A  few  years  ago,  most  embed¬ 
ded  controllers  were  4-  or  8-bit 
microcontrollers  such  as  the 
8048,  8051,  68HC11,  or  COPS- 
400.  But  the  popularity  of  the 
PC  has  brought  the  8088  into  this  arena 
for  two  reasons.  First,  the  price  of  8088 
processors  and  support  chips  was  driven 
down  to  levels  where  they  can  com¬ 
pete  with  microcontrollers.  Second,  just 
as  important,  sophisticated  8088  soft¬ 
ware  development  tools  are  widely  avail¬ 
able  at  low  prices. 

For  example,  a  typical  price  for  an  8051 
compiler/linker/locator  package  can  eas¬ 
ily  run  over  $1000.  This  compares  with 
street  prices  of  under  $100  for  PC- 
based  C  compilers.  The  support  tools 
(CodeView  or  Turbo  Debugger,  for  in¬ 
stance)  for  the  PC-based  compilers  gen¬ 
erally  outperform  those  for  the  micro¬ 
controller  cross  compilers.  Even  more 
important,  there  exists  a  huge  group 
of  programmers  that  are  familiar  with 
the  PC-based  development  tools. 

But  just  because  you  have  a  copy  of 
Turbo  C  or  Microsoft  C  doesn’t  mean 
you  are  ready  to  go  out  and  start  devel¬ 
oping  code  to  run  an  atomic  toaster. 


Mark  is  a  programmer  for  Greenleaf 
Software,  Inc.,  Dallas,  Texas.  He  can 
be  reached  through  the  DDJ  office. 


There  is  still  one  key  ingredient  miss¬ 
ing  in  your  software  development  en¬ 
vironment.  The  missing  link  is  a  piece 
of  software  called  a  “Locator,”  which 
takes  the  output  from  the  linker  and 
moves  code  and  data  around  so  that 
they  match  up  with  the  RAM  and  ROM 
in  the  target  hardware. 

A  simple  8088-based  system  will  gen¬ 
erally  have  EPROM  in  high  memory 
and  RAM  in  low  memory.  This  mode 
of  operation  is  more  or  less  dictated 
by  the  architecture  of  the  processor. 
You  have  to  have  ROM  or  EPROM  in 
high  memory  because  that  is  where  the 
8088  begins  executing  code  when  it 
powers  up.  Because  the  interrupt  vec¬ 
tors  for  the  part  are  in  low  memory, 
hardware  designers  typically  place  the 
system  RAM  there.  So,  in  a  system  with 
64K  of  RAM  and  64K  of  EPROM,  the 
RAM  will  have  a  base  address  of 
0000:0000,  while  the  EPROM  will  have 
a  base  address  of  F000:0000. 

EXE  File  Structure 

Though  it  may  not  be  obvious,  MS- 
DOS  does,  in  fact,  provide  a  locator. 
When  COMMAND.COM  loads  an  EXE 
file,  it  needs  to  locate  the  file  at  the 
currently  available  location  in  the  RAM 
of  the  PC.  This  location  changes  up 
and  down  depending  on  many  factors 


(the  version  of  DOS,  whether  or  not 
TSRs  are  loaded  in,  and  so  on).  Thus, 
the  EXE  file  has  all  the  information  in 
it  necessary  to  inform  DOS  about  what 
it  needs  to  do  to  run  the  program  any¬ 
where  in  memory.  This  information  is 
stored  in  what  is  known  as  the  “header” 
of  the  file.  The  structure  of  the  EXE  file 
is  shown  in  Figure  1,  and  a  detail  of  the 
header  structure  is  shown  in  Figure  2. 

As  Figure  1  shows,  the  code  image 
is  just  one  of  four  sections  in  the  EXE 
file.  The  code  found  in  that  section  is 
ready  to  be  loaded  into  RAM  and  exe¬ 
cuted  with  no  changes,  provided  it  is 
loaded  starting  at  location  0000:0000. 

In  order  to  load  it  into  a  different 
section,  the  loader  needs  to  go  into  the 
code  image  and  adjust  any  segment 
references  upward  by  the  value  of  the 
load  segment. 

A  general  -  purpose  locator  should 
also  be  able  to  place  code  anywhere 
in  memory.  But  to  complicate  matters, 
it  needs  to  be  able  to  split  up  the  code 
and  data  sections  of  the  program,  lo¬ 
cating  them  in  arbitrarily  different  sec¬ 
tions  of  memory.  It  needs  to  be  able 
to  adjust  any  segment  references  in  the 
code  image.  The  locator  also  needs  to 
be  able  to  produce  a  located  output  file 
suitable  for  loading  into  an  embedded 
system  and  it  needs  to  provide  some 
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sort  of  initialization  so  that  our  soft¬ 
ware  in  the  target  will  begin  execution 
on  when  the  processor  is  reset. 

A  Locate  Program 

The  program  LOCATE  (see  Listing  One, 
page  152)  accomplishes  the  just  men¬ 
tioned  goals.  All  that  needs  to  be  done 
is  to  include  the  startup  module, 
START. ASM  (Listing  Two,  page  153), 
as  the  first  file  in  the  link.  The  file  can 
then  be  run  through  LOCATE.  This  pro¬ 
duces  a  HEX  output  file  suitable  for 
loading  into  an  embedded  system. 

The  first  thing  LOCATE  does  in  order 
to  produce  the  HEX  output  file  is  to 
read  in  the  header  of  the  EXE  file.  This 
is  done  in  the  module  read_header_ 
data().  The  header  is  read  into  the 
exe_header structure  defined  at  the  top 
of  the  file.  Once  the  header  is  read  in, 
most  of  the  information  needed  to  lo¬ 
cate  the  program  is  ready.  read_header_ 
data( )  also  makes  a  few  more  calcula¬ 
tions  before  exiting.  First,  it  computes 
the  offset  to  the  start  of  the  actual  code 
in  the  EXE  file.  The  header  contains  the 
offset  in  paragraphs,  which  just  has  to 
be  multiplied  by  16  to  create  an  offset 
in  bytes. 

Next,  LOCATE  calculates  the  size  of 
the  program.  This  is  somewhat  more 
complicated,  involving  three  different 
numbers  in  the  header.  Finally,  it  deter¬ 
mines  where  in  the  program  the  STACK 
segment  is  located.  This  point  will  mark 
the  line  of  demarcation  between  RAM 
and  ROM.  As  you  will  see  later,  the 
routine  START.ASM  orders  the  segments 
in  such  a  way  that  this  is  the  case. 

After  LOCATE  has  determined  where 
the  code  image  is,  and  how  long  it  is, 
it  calls  the  routine  read_input( ),  allo¬ 
cates  a  buffer,  then  loads  the  code  im¬ 
age  into  the  buffer.  This  code  image  is 
ready  to  run  as  is  on  an  8088  if  it  is 
loaded  in  at  address  0000:0000. 

After  reading  in  the  image,  all  that  is 
left  to  do  is  to  process  all  of  the  reloca¬ 
tion  table  entries.  The  header  has  two 
items  that  say  where  the  relocation  ta¬ 
ble  is  in  the  EXE  file,  and  how  many 
entries  are  in  it.  Each  entry  in  the  table 
is  just  a  segment:offset  pair,  specifying 
a  long  address  in  the  code  image  that 
needs  to  be  relocated. 

The  procedure  called  process_  relo- 
cation_table( )  is  a  loop  that  gets  each 
relocation  table  entry,  computes  where 
that  is  in  the  code  image,  then  modifies 
the  value  so  that  it  conforms  with  the 
target  hardware.  The  item  pointed  to 
by  the  relocation  table  entry  is  a  seg¬ 
ment  value  in  the  code  image.  For  ex¬ 
ample,  when  a  program  starts,  there  is 
often  a  statement  that  looks  like  this: 

MOV  AX,  XXXX 


MOV  DS,  AX 

The  relocation  table  points  to  the  XXXX 
value,  so  that  it  can  be  modified  to 
reflect  the  real  memory  address  that 
should  be  loaded  in.  The  MS-DOS 
loader  has  a  simple  job  here.  It  just 

A  general-purpose 
locator  should  also  be 
able  to  place  code 
anywhere  in  memory 


adds  the  base  segment  address  of  the 
program  to  the  segment  in  memory. 
For  example,  if  the  code  is  being  loaded 
in  at  2134:0000,  it  adds  2134  to  XXXX 
and  stores  the  new  value  in  the  code 
image. 

Our  locator  has  to  make  a  slightly 
more  complicated  decision.  It  needs 
to  look  at  the  value  of  the  segment  to 
be  relocated.  If  the  segment  value  is 
less  than  that  of  the  stack  segment,  it 
means  that  it  is  a  ROM  value,  and  should 
be  recalculated  to  go  into  high  mem¬ 
ory.  If  the  segment  value  is  greater 
than,  or  equal  to,  that  of  the  stack  seg¬ 
ment,  it  should  be  recalculated  to  go 
into  low  memory.  Remember,  that  the 
stack  segment  value  is  in  the  EXE 
header,  and  we  have  defined  our  seg¬ 
ments  so  that  all  code  is  below  the 
stack  segment  and  all  data  is  above  it. 

The  relocation  values  in  LOCATE  are 
hardcoded  as  F000H  for  the  program, 
and  40H for  the  data.  The  8088  has  256 
interrupt  vectors  that  go  from  address 
0  to  3FFH,  so  that  the  first  available 
segment  is  at  40H.  After  the  relocation 
process  is  complete,  the  image  is  ready 
to  be  output  to  the  HEX  file. 

The  most  common  format  for  trans¬ 
ferring  code  or  data  to  an  embedded 
system  is  to  use  Intel  MCS-86  Hex  code, 
and  that  is  what  this  program  does. 
Virtually  every  emulator  and  debugger 
will  support  downloads  in  this  format. 
Because  it  is  the  closest  thing  to  a  uni¬ 
versal  format,  it  is  used  here.  Before 
the  code  image  is  sent,  a  single  record 
is  sent  specifying  which  segment  the 
load  is  to  go  into.  In  this  case,  that  will 
be  FOOOH.  The  image  is  then  formatted 
into  records,  and  output  —  one  by 
one  —  until  they  have  all  been  issued. 

Finally,  LOCATE  outputs  a  single  JMP 
instruction  that  will  be  located  at 
FFFF-.OOOO.  This  is  the  restart  location 


for  the  8088  processor.  When  the  pro¬ 
cessor  powers  up,  or  receives  an  exter¬ 
nal  reset  signal,  control  is  transferred 
to  this  location  and  execution  begins. 
Because  both  the  code  segment  and 
initial  IP  values  are  found  in  the  EXE 
header,  they  can  be  output  as  part  of 
the  jump  instruction,  causing  it  to  auto¬ 
matically  point  to  our  startup  code. 

The  last  detail  at  this  point  is  to  out¬ 
put  a  single  EOF  record  in  Intel  hex 
format.  The  code  is  at  this  point  ready 
to  be  sent  to  our  target  hardware. 

The  Startup  Code 

Although  LOCATE  will  try  to  relocate 
any  EXE  program  in  any  language,  it 
will  not  produce  useful  code  without 
a  few  items  being  taken  into  account. 
Most  of  them  are  covered  by  the  inclu¬ 
sion  of  a  startup  file,  START.ASM.  When 
compiled,  START.OBJ  will  replace  the 
startup  code  produced  by  the  C  com¬ 
piler,  usually  found  in  CRT0.ASM. 

The  first  problem  is  the  ordering  of 
the  segments.  As  mentioned  previously, 
the  only  reference  point  available  in 
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EXE  Header 


Figure  1:  Structure  of  an  EXE  file 


1A  Overlay  number 

18  Displacement  of  relocation  table  in  bytes 

16  Displacement  of  CODE  segment  in  paragraphs 

14  Initial  value  of  IP 

12  Word  checksum 

10  Initial  value  of  SP 

OE  Displacement  of  STACK  segment  in  paragraphs 

0C  Maximum  number  of  paragraphs  required 

0A  Minimum  number  of  paragraphs  required 

08  Size  of  the  header  in  1 6  byte  paragraphs 

06  Number  of  relocation  table  items 

04  Size  of  the  file  in  51 2  byte  pages 

02  Length  of  image  mod  512 

00  EXE  Program  Signature 

Figure  2:  Structu  re  of  the  header 
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the  EXE  file  regarding  the  location  of 
data  in  the  EXE  file  is  the  stack  segment 
value.  This  means  that  we  need  to  force 
the  stack  segment  to  be  the  first  seg¬ 
ment  in  RAM.  The  sample  file  shown 
for  START.ASM  does  this  by  listing  the 
segments  used  in  a  C  program  in  the 
desired  order.  By  having  START.OBJ 
be  the  first  file  read  in  by  the  linker,  the 

A  “Locator”  takes  the 
output  from  the  linker 
and  moves  code  and 
data  around  so  that 
they  match  up  with  the 
RAM  and  ROM  in  the 
target  hardware 


segment  order  shown  will  be  the  one 
used.  In  START.ASM,  the  DGROUP  seg¬ 
ment  is  defined  to  contain  the  stack, 
so  the  stack  segment  listed  in  the  EXE 
header  will  be  the  first  segment  after 
the  code  segments.  The  example  shown 
in  the  next  section  of  this  article  will 
work  for  Microsoft  C  or  Turbo  C.  Turbo 
C  does  not  use  a  CONST  class  of  seg¬ 
ment,  but  will  not  object  to  the  pres¬ 
ence  of  one. 

A  second  problem  for  embedded  sys¬ 
tems  is  how  to  handle  initialized  data. 
In  just  about  any  program  there  will 
be  some  data  in  the  CONST,  BSS,  and 
DATA  segment  types.  Loading  them 
into  RAM  would  work,  but  only  once. 
If  the  system  were  to  lose  power,  the 
code  would  still  be  present  in  the  ROM 
when  restarted,  but  all  of  the  down¬ 
loaded  data  would  have  vanished. 

This  version  of  LOCATE  and  START 
.ASM  handles  this  in  a  straightfoiward 
way.  All  of  the  initialized  data  in  the 
image  can  be  found  immediately  after 
the  code  segments.  The  initialized  data 
values  in  the  image  are  loaded  into 
ROM  just  as  they  are  found  in  the  code 
image.  When  the  program  restarts,  con¬ 
trol  is  transferred  to  START.ASM.  All  it 
does  is  make  a  copy  of  all  the  initial¬ 
ized  data  from  ROM  into  RAM.  This 
actually  takes  less  space  in  the  ROM 
than  would  be  used  to  initialize  them 
using  code. 

A  few  precautions  are  needed  to  cre¬ 
ate  code  that  will  actually  work  under 
this  system.  First,  some  compilers  will 
generate  code  that  performs  stack  check¬ 


ing  each  time  a  function  call  is  invoked. 
Because  we  are  tinkering  with  the  stack 
segment,  this  code  frequently  will  not 
work.  Both  Turbo  C  and  Microsoft  C 
allow  you  to  disable  stack  checking 
with  command  line  switches,  and  these 
should  be  used. 

C  library  routines  should  always  be 
viewed  with  distrust.  Some  of  the  li¬ 
brary  routines  perform  DOS  calls,  and 
these  will  obviously  not  work  on  an 
embedded  system.  Others  have  built 
in  linker  commands  that  will  reorder 
your  segment  definitions.  Unfortunately, 
the  only  way  to  tell  if  a  library  routine 
will  work  is  usually  to  just  try  linking 
it  in.  Microsoft  C  will  generate  in  line 
code  for  many  library  routines,  and 
these  will  almost  always  work.  Once 
again,  this  can  be  invoked  with  com¬ 
mand  line  options. 

An  Example 

A  sample  program  that  uses  this  system 
is  shown  in  Listing  Three,  page  153. 
The  program  performs  the  standard  first 
function  of  a  C  program,  which  is  to 
print  simply  a  “Hello,  world!”  message 
on  the  screen.  Naturally,  print/ will  not 
work  in  my  embedded  system,  so  it  has 
been  replaced  with  my_printf( ). 

The  function  my_printf( )  is  writing 
characters  to  an  imaginary  printer  port 
that  has  to  be  polled  before  it  can  be 
written  to.  It  calls  the  library  routines 
outportb  and  inportb  to  access  the  hard¬ 
ware.  The  only  predefined  data  it  will 
have  will  be  the  string  “Hello,  world!\ 
n”.  Using  Turbo  C,  this  program  can 
be  compiled  with  the  command  line: 

TCc  -ms  -c  HELLO. C 

The  Microsoft  C  command  line  would 
be: 

CL  /AS  /C  /Oi  /Gs  HELLO. C 

The  Microsoft  C  command  line  speci¬ 
fies  no  stack  checking,  as  well  as  gen¬ 
eration  of  intrinsic  functions. 

After  compiling,  the  code  would  be 
linked  with  the  line: 

TLINK  START.OBJ+HELLO 

.OBJ, HELLO. EXE, HELLO.MAP,  \TC\ 

LIB\CS; 

or 

LINK  START.OBJ+HELLO. OBJ, 
HELLO. EXE, HELLO. MAP/MAP; 

The  resulting  map  file  should  look  simi¬ 
lar  to  the  one  in  Figure  3.  This  shows 
that  the  program  and  startup  code  will 
be  located  first,  followed  by  constant 
data,  the  uninitialized  data,  and  the 
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(continued  from  page  126) 
stack.  The  program  is  then  located  us¬ 
ing  the  following  command  line: 

LOCATE  HELLO.EXE  HELLO. HEX 

This  produces  an  Intel  hex  file  that 
looks  like  the  one  in  Figure  4.  This 
program  is  ready  to  be  loaded  and 
executed  in  the  target  system.  The  only 
real  complication  to  debugging  at  this 
point  is  the  relocation  of  symbol  val- 


Figure  3-'  Map  file  after  compilation 


Figure  4:  Contents  of  hex  file 


ues.  The  offset  values  in  the  map  will 
all  be  correct,  but  the  segments  will  all 
be  wrong. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 


Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  152.) 

Vote  for  your  favorite  feature/artiole. 

Circle  Reader  Service  No.  7. 


ARCHIVES 

Realizable  Fantasies 

DDJ  will  continue  the  active  pursuit  of  ‘re¬ 
alizable  fantasies'  that  are  within  the  bounds 
of  current  technology  and  knowledge.  This 
includes  computer  music,  real-time  video 
graphics,  and  unusual  input  techniques.  We 
will  also  explore  shared  memory,  computer 
networking  via  telephone,  and  who  knows 
what  else.  You  are  part  of  this.  The  Journal 
is  primarily  a  communication  medium  and 
an  intellectual  rabble-rouser.  Send  us  your 
ideas,  your  creations,  your  problems,  and 
your  solutions.  The  more  we  all  share,  the 
more  we  all  gain.  —  DDJ  Editorial,  March 
1976. 
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PJAGRAMMING  PAR  AD  1 6  MS 


A  Taste  of  Lisp 


Over  the  next  months  I’ll  be  look¬ 
ing  at  Lisp,  Common  Lisp,  and 
recent  developments  in  Lisp 
programming  that  make  the  lan¬ 
guage  an  interesting  option  for  profes¬ 
sional  programmers.  This  month,  I’ll 
prepare  the  ground  by  taking  a  look  at 
Lisp  in  general,  debunking  some  myths, 
giving  a  sense  of  what  it’s  like  to  pro¬ 
gram  in  Lisp,  and  sketching  the  history 
of  the  language,  leading  to  the  estab¬ 
lishment  of  the  Common  Lisp  standard. 

Time  (or  Lisp 

One  of  the  programming  paradigms  I 
wanted  to  explore  when  I  conceived 
this  column  was  interactive  recursive 
function-based  list  processing:  Lisp. 
Learning  Lisp  back  in  the  1970s  was  a 
revelation  for  me,  opening  my  eyes  to 
the  arbitrariness  of  the  Fortran/Basic/ 
Pascal  approach  I  had  naively  thought 
was  the  one  true  methodology  of  pro¬ 
gramming.  Lisp  was  really  a  different 
paradigm,  requiring  a  different  way  of 
thinking  about  problems,  and  embody¬ 
ing  different  ideas  about  the  value  of 
memory  and  time. 

That  reference  to  the  value  of  mem¬ 
ory  and  time  was  intended  to  be  only 
partially  ironic.  Lisp  implementations 
of  the  1970s  generally  were  written  by 
people  who  believed  that  memory  was 
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cheap  and  was  getting  cheaper,  and 
who  valued  development  flexibility  over 
execution  speed  —  these  were  imple¬ 
mentations  that  ate  cycles  and  RAM. 
But  there  is  time  and  there  is  time. 
While  the  Lisp  systems  of  the  1970s 
were  not  generally  fast  number  crunch¬ 
ers,  they  were  demonstrably  good  for 
developing  highly-complex  applica¬ 
tions,  and  some  Lisp-based  numeric 


applications  of  this  era  probably  could 
not  have  been  developed  in,  say,  For¬ 
tran  in  any  acceptable  span  of  time. 
Lisp  became  the  language  of  choice  for 
artificial  intelligence  work,  but  for  years, 
as  a  result  of  execution-time  slowness, 
memory  hungriness,  and  a  prolifera¬ 
tion  of  incompatible  dialects,  it  could 
not  be  considered  seriously  for  com¬ 
mercial  applications.  Recent  develop¬ 
ments,  though,  have  made  Lisp  a  lan¬ 
guage  worth  any  serious  programmer’s 
attention. 

One  of  these  is  the  increasing  power 
of  personal  computers.  With  brief  ex¬ 
ceptions,  memory  has  indeed  contin¬ 
ued  getting  cheaper,  and  systems  have 
been  getting  faster  and  more  powerful. 
Another  development  is  the  work  that 
has  gone  into  creating  efficient  Lisp 
implementations.  Some  of  this  work 
has  been  tied  to  specific  hardware,  but 
progress  has  also  been  made  in  Lisp 
implementations  on  standard  hardware. 
Together,  these  developments  have 
been  whittling  away  at  the  stumbling 
blocks  between  Lisp  and  the  non-aca¬ 
demic  programmer. 

But  arguably  the  most  important  event 
in  Lisp’s  history  is  the  definition  and 
acceptance  of  the  Common  Lisp  stan¬ 
dard,  which  has  probably  saved  the  life 
of  the  language. 

This  is  a  good  thing,  because  there 
is  a  whole  list  of  problems  for  which 
Lisp  is  the  best  language  in  existence. 
I’m  pretty  sure  there  is,  anyway,  al¬ 
though  I  couldn’t  prove  it;  probably 
nobody  could.  Wade  Hennessey,  in  his 
book  Common  Lisp  (McGraw-Hill, 
1989),  runs  down  the  somewhat  longer 
list  of  problem  areas  in  which,  for  some 
people  at  least,  Lisp  is  the  language  of 
choice.  His  claim  is  a  provable  and 
correct  version  of  my  unprovable  as¬ 
sertion.  His  list  includes:  Emulating  hu¬ 
man  vision,  doing  symbolic  algebra, 


developing  special-purpose  languages, 
exploring  natural  language  understand¬ 
ing,  theorem  proving,  planning  com¬ 
plex  actions,  computer-aided  design, 
programmer  education,  and  even  writ¬ 
ing  text  editors  (such  as  Gnuemacs) 
and  doing  system  programming  (at  least 
on  Lisp  machines). 

Pulling  together  a  standard  for  Lisp 
after  20  years  of  divergent  develop¬ 
ment  was  a  little  like  gathering  the  scat¬ 
tered  energy  of  the  Big  Bang.  Guy  Steele 
found  a  better  simile.  He  prefaces  his 
definitive  Common  Lisp:  The  Language 
(Digital  Press,  1984)  with  a  James  Madi¬ 
son  quotation  from  The  Federalist  about 
the  difficulty  of  hammering  out  con¬ 
sensus  on  the  Constitution.  It  took  a 
kind  of  electronic  Constitutional  Con¬ 
vention  to  unite  the  rebel  colonies  of 
Lisp  development. 

Lisp  had  grown,  after  its  creation 
around  I960  by  John  McCarthy,  in  many 
directions,  the  most  important  in  the 
1970s  being  the  MacLisp,  InterLisp,  and 
Scheme  dialects.  By  1980,  Scheme  had 
begotten  T,  MacLisp  had  inspired  NIL 
and  Franz  Lisp,  special  purpose  hard¬ 
ware  had  given  the  world  Zetalisp  and 
others,  and  the  needs  of  university  re¬ 
searchers  had  produced  SpiceLisp  and 
the  wistfully-named  Portable  Standard 
Lisp  (PSL).  Common  Lisp  was  the  com¬ 
promise  dialect  designed  in  the  early 
1980s  to  be  palatable  to  as  many  Lisp 
developers  as  possible.  Common  Lisp 
is  not  the  collection  of  features  that  the 
above-mentioned  dialects  have  in  com¬ 
mon,  as  the  name  might  suggest.  It  is 
much  more  a  union  of  features  than 
an  intersection. 

One  of  the  areas  into  which  Com¬ 
mon  Lisp  extends  Lisp  is  object-ori¬ 
ented  programming,  particularly  with 
CLOS,  the  Common  Lisp  Object  Sys¬ 
tem,  aka  Thmalltalk,  about  which  we’ll 
hear  more  next  month. 
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PROGRAMMING  PARADIGMS 


What  Lisp  Is 

Some  of  these  characterizations  will 
not  seem  true  of,  say,  CLOS,  but  what 
I’m  describing  here  is  the  core  to  which 
things  such  as  CLOS  are  extensions. 

Lisp  is  recursive.  Is  it  ever.  Data  struc¬ 
tures  and  functions  are  routinely  de¬ 
fined  through  recursion.  The  professor 
from  whom  I  learned  Lisp  told  a  lot  of 
lies,  such  as  that  all  of  Lisp  could  be 
constructed  by  recursive  definitions  us¬ 
ing  just  five  primitive  functions.  It’s  a 
good  lie,  because  it  suggests  the  de¬ 
gree  to  which  Lisp  depends  on  recur¬ 
sion. 

Lisp  is  function-based.  Programming 
in  Lisp  is  a  matter  of  expressing  a  prob¬ 
lem  as  a  composition  of  functions.  To 
write  a  program,  you  define  a  function, 
and  the  definition  consists  primarily  of 
function  calls,  with  some  scaffolding. 
(You  need  a  little  more  than  five  primi¬ 
tive  functions,  and  not  all  functions  are 
defined  recursively.)  Values  passed  to 
functions  are  typically  the  values  re¬ 
turned  by  other  functions,  although  func¬ 
tions  themselves  can  be  passed,  just  as 
other  data  can.  The  same  professor 
taught  that  no  Lisp  function  should  take 
more  than  five  lines  to  write,  another 
useful  lie  that  gives  a  sense  of  how  the 
functional  style  works:  “pure”  Lisp  pro¬ 
gramming  makes  less  use  of  structur¬ 
ing  tools  than  Pascal  programming,  us¬ 
ing  the  function  as  almost  the  only 
structure. 

Lisp  is  LISt  Processing.  A  Lisp  pro¬ 
gram  is  a  list,  and  the  list  is  the  funda¬ 
mental  data  structure  of  Lisp.  The  obvi¬ 
ous  implication  of  these  two  statements 
is  that  Lisp  programs  are  Lisp  data,  and 
this  is  in  fact  a  defining  feature  of  the 
language.  It  makes  it  easy  for  one  pro¬ 
gram  to  read,  create,  or  execute  other 
programs.  It’s  the  source  of  the  great 
extensibility  of  the  language,  which  is 
in  turn  the  source  of  the  plethora  of 
idiosyncratic  versions  that  sprang  up 
and  led  to  a  crisis  in  compatibility,  and 
then  to  a  kind  of  Continental  Congress 
of  Lisp  developers  in  response  to  the 
crisis,  and  ultimately  to  Common  Lisp. 

Lisp  is  interactive.  There  have  been 
Lisp  compilers  for  a  long  time,  but  the 
interpreter  is  central  to  any  implemen¬ 
tation  —  for  several  reasons.  Lisp  was 
originally  designed  to  be  a  language  in 
which  provably  correct  programs  could 
be  written,  but  provability  constraints 
tend  to  be  loosened  in  the  tricks  that 
have  to  be  played  to  generate  efficient 
compiled  code  from  a  Lisp  system.  More¬ 
over,  the  kinds  of  problems  to  which 
Lisp  is  typically  applied  require  a  lot 
of  exploratory  programming  that  also 
makes  the  interpreter  necessary. 

The  style  of  interaction  is  not  com¬ 
mand  action,  however,  but  function 
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call.  Because  even  the  main  program 
is  a  function,  invoking  a  Lisp  program 
is  usually  a  different  process  from  in¬ 
voking  a  Pascal  program.  To  invoke  a 
Lisp  program,  you  call  the  function  with 
appropriate  arguments,  and  it  returns 
a  value.  The  argument  list  can  be  empty, 
in  which  case  calling  the  function  feels 
more  like  invoking  a  Pascal  program. 
Rather  than  supply  the  input  to  a  func¬ 
tion  as  parameters,  you  can  write  an 
“Input”  function  that  conducts  a  dialog 
with  the  user  to  get  the  input.  The 
value  returned  can  be  an  arbitrarily 
complex  object,  and  the  function  can 
produce  side  effects. 

So  to  perform  a  computation  and 
then  print  the  results  in  a  table,  you 
could  write  a  computational  function 
ComputeValues ,  an  input  function 
GetValues,  and  an  output  function 
PrintTable.  PrintTable  would  produce 
its  output  as  a  side  effect.  You  could 
then  perform  this  function  call: 

(PrintTable  (ComputeValues 

(GetValues))) 

What  Lisp  Isn't 

Lisp  has  a  reputation.  Some  of  it  isn’t 
deserved. 

Lisp  is  not  an  AI  language.  It  is,  how¬ 
ever,  the  premiere  language  for  artifi¬ 
cial  intelligence  programming.  Its  vir¬ 
tues  for  AI  programming  include,  but 
are  not  restricted  to,  the  ability  to  ma¬ 
nipulate  programs  as  data,  which  makes 
it  good  for  symbolic  processing  of  the 
sort  done  in  symbolic  Algebra  programs; 
and  its  interactive  style,  which  facili¬ 
tates  exploratory  programming  and  proto¬ 
typing.  These  virtues  are  themselves 
not  restricted  to  the  domain  of  artificial 
intelligence. 

Lisp  isn’t  inherently  slow.  It  has  been 
a  prevailing  attitude  in  the  Lisp  com¬ 
munity  that  performance  is  not  very 
important,  and  that’s  changed,  as  I  hope 
to  show  next  month. 

Lisp  isn’t  a  memory  hog.  There’s  noth¬ 
ing  inherent  in  Lisp  that  makes  it  a 
memory  hog,  although  past  implemen¬ 
tations  have  often  been  wasteful  of  mem¬ 
ory.  The  problems  to  which  Lisp  is 
characteristically  applied  (see  Hen¬ 
nessey’s  list  a  few  paragraphs  back)  are 
a  different  matter.  Some  of  them  do 
require  a  lot  of  memory,  no  matter 
what  language  is  used  to  solve  them. 

A  Taste  of  Lisp 

Here’s  an  example  that  is  basically  ac¬ 
curate,  although  it  glosses  over  some 
complexities. 

You  define  the  function  using  de¬ 
fun,  which  takes  three  arguments:  A 
string  representing  the  name  of  the  func¬ 
tion  to  be  defined,  a  list  of  its  argu¬ 


ments,  and  a  list  that  is  a  function  call. 
This  last  list  is  the  body  of  the  function 
being  defined.  For  example: 

(defun  <name>  <argument-list> 

<body>) 

Here’s  a  recursive  definition  of  a  func¬ 
tion  that,  given  a  nonnegative  integer 
n,  returns  2  to  the  nth  power: 

(power-of-two  (n) 

(cond 
((=  n  0)  1) 

(t  (*  2  (power-of-two  (-  n  1)))) 

The  name  of  the  function  is  power-of- 
two,  it  takes  one  argument,  n,  and  the 
body  of  the  definition  is 

(cond 

((=  n  0)  1) 

(t  (*  2  (power-of-two  (-  n  1))))) 

This  expression  consists  of  the  func¬ 
tion  (actually  a  macro)  cond  applied 
to  two  arguments.  The  arguments  are 

((=  n  0)  1),  and 

(t  (*  2  (power-of-two  (-  n  1)))) 

cond  is  short  for  conditional,  and  it 
takes  any  number  of  two-item  lists  as 
arguments,  returning  the  last  item  of 
the  first  list  whose  first  item  is  true. 
That  is,  it  works  like  a  case  structure, 
picking  out  a  return  value  based  on 
tests  associated  with  the  possible  re¬ 
turn  values.  In  this  case,  the  first  list  is 
((=  n  0)  1),  and  cond  understands  this 
to  mean  "if  (=  n  0)  is  true,  then  return 
1."  The  expression  (=  n  0)  is  a  call  to 
the  function  =,  which  follows  Lisp  prefix- 
and-parentheses  notation  and  is  a 
Boolean  function  that  returns  true  if  its 
arguments  are  equal,  and  false  other¬ 
wise.  So  if  (=  n  0)  returns  true,  cond 
returns  1. 

If  (=  n  0)  returns  false,  then  cond 
examines  the  next  expression,  (t  (*  2 
(power-of-two  (-  n  1)))).  The  first  ele¬ 
ment  of  this  expression  is  a  system 
constant,  t,  which  always  returns  true. 
This  line  typifies  the  syntax  of  the  “else” 
clause  of  a  cond.  Because  t  always 
returns  true,  a  cond  whose  last  list  starts 
with  t  is  guaranteed  to  return  some 
value.  In  this  case,  if  the  last  list  is 
examined,  the  value  returned  by  cond 
is  the  value  of  (*  2  (power-of-two  (-  n 
1))).  This  is  the  multiplication  function, 
*  applied  to  2  and  a  recursive  call  to 
power-of-two.  In  the  recursive  call, 
power-of-two  gets  as  its  argument  (-  n 
1),  or  n-1  in  mathematical  infix  form. 

In  other  words,  the  function  power-of- 
two  returns  1  if  called  with  the  argu¬ 
ment  0,  and  for  any  larger  integer  re- 
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turns  2*power-of-two(n-l).  The  defini¬ 
tion  ensures  that,  for  proper  arguments, 
the  recursion  will  terminate. 

I  worked  through  this  example  in 
excruciating  detail  because  it  gives  a 
strong  taste  of  “pure”  Lisp.  Lisp  isn’t 
as  pure  as  it  once  was,  and  in  one 
sense  that  makes  it  easier  to  learn.  Other 
languages  employ  recursion,  for  exam¬ 
ple,  and  Lisp  employs  structures  that 
avoid  some  of  the  costs  of  deeply- 
recursive  function  definitions. 

But  this  similarity  of  Lisp  to  other 
languages  can  also,  paradoxically,  make 
it  harder  to  understand  Lisp.  Common 
Lisp  has  features  that  will  be  familiar 
to  Pascal  and  Smalltalk  and  Forth  and 
C  programmers,  which  can  lead  to  think¬ 
ing  of  it  as  something  other  than  what  it 
is,  so  that  its  unique  features  seem  like 
eccentricities.  Looking  at  “pure”  Lisp 
can  help  in  understanding  what  the 
language  is  really  about.  This  example 
was  intended  to  be  a  taste  of  that. 

AND  (Now  for  Something  Completely 
Different) 

Looking  through  my  “Ancient  Program¬ 
ming  Languages”  file,  I  come  across  a 
description  of  a  language  called  “AND.” 
AND  is  a  remarkably  simple  and  pow¬ 
erful  language,  written  using  just  four 
symbols.  The  symbols  combine  in  trip¬ 
lets  to  form  twenty  commands  and  three 
marks  of  punctuation  (there  is  some 
redundancy  in  the  coding,  obviously). 
AND  is  invariably  implemented  as  a 
one-pass  compiler.  Despite  the  lan¬ 
guage’s  simplicity,  no  one  yet  under¬ 
stands  it  fully,  possibly  due  to  the  lack 
of  documentation.  Work  has  begun  on 
the  manual,  which  is  expected  to  run 
into  millions  of  pages. 

AND  has  been  around  longer  than 
Lisp  or  Fortran,  and  there  are  a  lot  of 
AND  programs  in  use  today.  Some  soft¬ 
ware  systems  based  on  AND  have 
solved  difficult  calculus  problems,  pi¬ 
loted  rockets,  won  chess  matches, 
solved  crossword  puzzles,  written  nov¬ 
els,  graduated  from  prestigious  univer¬ 
sities,  and  managed  multinational  cor¬ 
porations.  Despite  these  impressive 
achievements,  AND  is  generally  re¬ 
garded  as  inappropriate  for  artificial 
intelligence  programming. 

Wait  a  minute.  Did  I  misspell  the 
name  of  the  language?  I’m  sure  those 
three  letters  are  in  it,  but  I  may  have 
got  them  in  the  wrong  order. 
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TEXTSRCH  Continued: 
The  Expression 
Interpreter 


Last  month  we  built  an  expression 
parser  that  processes  expressions 
consisting  of  keywords,  Boolean 
operators,  and  parentheses.  We 
will  use  the  expressions  in  text  search¬ 
ing  queries  for  a  new  “C  Programming” 
column  project,  a  text  data  base  index¬ 
ing  and  retrieval  system.  This  month 
we  give  the  name  TEXTSRCH  to  the 
project,  and  continue  with  the  expres¬ 
sion  interpreter. 

The  text  data  base  that  TEXTSRCH 
will  support  is  one  that  consists  of  a 
large  number  of  text  files  that  do  not 
change  much.  Typical  applications  in¬ 
clude  files  of  electronic  mail  messages 
and  engineering  documentation.  There 
are  many  others,  of  course,  but  the 
characteristic  they  share  is  that  they  are 
relatively  static. 

The  primary  purpose  for  the  data 
base  is  to  store  our  files  of  text  in  a 
centrally  organized  place.  The  primary 
purpose  for  TEXTSRCH  is  to  allow  us 
to  find  the  files  we  want  to  read,  based 
on  some  criteria.  Given  that  we  know 
something  about  what  we  are  looking 
for,  we  want  to  be  able  to  express 
those  criteria  in  the  form  of  a  query 
expression  and  to  find  the  files  in  the 
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data  base  that  match  the  expression.  A 
typical  expression  might  be: 

(cobol  and  fortran)  and  not  pascal 

A  search  of  the  data  base  would  tell  us 
which  files  match  the  query,  that  is, 
which  files  contain  the  words  “cobol” 
and  “fortran”  but  do  not  contain  the 
word  “pascal.” 
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The  expression  parser  from  last 
month  did  a  lexical  scan  of  the  expres¬ 
sion,  converting  the  expression’s  words 
and  operators  into  tokens,  and  placing 
them  into  a  stack  in  postfix  notation. 
This  month  we  will  build  the  TEXTSRCH 
expression  interpreter.  Its  function  is 
to  extract  the  keywords  from  the  stack, 
initiate  a  search  of  the  data  base  for  a 
match  on  each  one,  and  combine  the 
results  of  the  search  with  the  Boolean 
operators  to  determine  which  files  match 
the  search  criteria.  After  we  build  such 
a  file  list,  we  will  switch  to  a  text  scan 
to  complete  the  search  and  find  the 
places  in  the  files  where  the  words  and 
phrases  appear.  Those  processes  will 
come  in  a  later  installment.  The  index 
that  we  will  build  allows  us  to  get  down 
to  the  file  level  with  a  minimum  of 
search  time. 

First  let’s  consider  how  we  will  in¬ 
dex  our  text  data  base.  We  won’t  build 
or  use  the  index  in  this  month’s  install¬ 
ment,  but  we  must  understand  its  op¬ 
eration  in  order  to  build  the  expression 
interpreter. 

Our  data  base  will  consist  of  a  num¬ 
ber  of  text  files  and  a  word  index.  The 
index  will  contain  an  entry  for  each 
keyword  or  phrase  that  appears  in  the 
data  base.  The  index  entry  for  a  par¬ 
ticular  word  will  tell  us  which  files 
contain  that  word  by  pointing  to  a  file 
list.  The  list  is  recorded  as  a  bit  map 
where  each  bit  represents  a  file.  At  any 
given  time,  the  number  of  files  in  the 
data  base  is  constant,  so  the  length  of 
the  bit  map  for  any  entry  is  fixed  at  that 
number  of  bits. 

When  we  search  the  index  for  a  word, 
we  will  get  back  a  fixed-length  bit  map 
with  those  bits  turned  on  that  corre¬ 
spond  to  the  files  that  contain  the  word. 
The  mechanics  of  the  index  and  the 


search  are  not  important  to  us  now;  it 
is  necessary  for  us  to  know  only  that  a 
search  returns  such  a  bit  map. 

With  such  a  map  we  can  tell  if  a 
word  does  or  does  not  appear  in  a  file. 
Suppose  our  data  base  has  16  text  files 
in  it  (not  very  many,  but  enough  to 
illustrate  the  principle).  If  we  use  the 
index  to  tell  us  which  files  include  the 
word  “fortran,”  it  might  return  to  us  a 
bit  map  such  as  this: 

0010001011000010 

Reading  the  bits  from  right  to  left,  we 
can  see  that  the  second,  seventh,  eighth, 
tenth,  and  fourteenth  files  in  the  list 
contain  the  word.  In  our  data  base 
manager,  we  will  have  a  table  of  file 
names  that  match  the  bit  positions,  so 
by  applying  the  one  bits,  we  can  derive 
the  file  names  where  the  word  appears. 
Understand  that  we  have  not  actually 
read  the  file  to  get  this  information  — 
not  during  the  search,  that  is.  Sometime 
in  the  past  we  read  all  the  files  to  build 
the  index.  This  is  why  such  data  base 
architectures  work  best  with  relatively 
static  data.  The  most  time-intensive  pro¬ 
cess  is  the  construction  of  the  index. 
After  that,  searches  can  be  a  snap. 

You  can  see  how  a  Boolean  query 
would  work.  We  will  search  the  index 
for  each  word  in  the  query.  Then  we 
will  apply  the  Boolean  operators  to  the 
bit  maps  that  the  search  returns.  The 
final  bit  map  is  the  one  that  lists  the 
files  that  match  the  complete  search 
criteria. 

You  will  remember  from  last  month 
that  the  query  begins  life  in  infix  nota¬ 
tion  that  the  parser  translates  into  postfix 
notation.  The  search  itself  must  be 
driven  by  an  expression  interpreter  that 
reads  the  postfix  stack. 
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(continued  from  page  132) 

Let’s  see  now  how  to  interpret  a 
postfix  expression.  Consider  a  simple 
expression  such  as  this  one 

apples  and  oranges 

The  postfix  stack  for  this  expression 
would  look  like  this: 

<and> 

apples 

oranges 

The  interpreter  pops  entries  from  the 
stack  and  processes  each  one  accord¬ 
ing  to  what  it  is.  If  the  entry  is  a  binary 
operator  token  such  as  the  <and> 
shown  here,  the  interpreter  pops  the 
next  two  tokens,  processes  them,  and 
combines  the  two  operands  by  apply¬ 
ing  the  operator.  If  the  entry  is  a  word 
or  phrase  operand,  the  interpreter  calls 
the  search  process  to  convert  the  word 
or  phrase  into  a  bit  map. 

Here  is  how  our  “apples  and  or¬ 
anges”  expression  would  be  interpreted. 
First  the  interpreter  pops  the  <and> 
token.  Next  it  pops  the  oranges  token 
and  converts  it  into  a  bit  map.  Then  it 
pops  the  apples  token  and  converts  it 
into  a  bit  map.  Because  the  <and> 
token  is  waiting,  the  interpreter  logi¬ 


cally  ANDs  the  two  bit  maps  and  re¬ 
turns  the  result. 

To  see  how  the  interpreter  works 
with  a  more  complex  expression,  con¬ 
sider  this: 

fortran  and  not  (cobol  or  pascal) 

The  postfix  stack  for  this  expression 
looks  like  this: 

<and> 

<not> 

<or> 

pascal 

cobol 

fortran 

The  interpreter  pops  the  <and>  token 
just  as  it  did  with  the  simpler  example. 
This  means  it  expects  two  more  oper¬ 
ands  to  AND  together  to  get  the  result. 
The  next  interim  result  it  must  compute 
is  indicated  by  the  <not>  token  that  it 
pops.  This  token  says  that  the  result  of 
the  next  operand  must  be  the  ones 
complement  of  the  search  result.  The 
next  token  is  the  <or>,  which  says  that 
two  operands  must  be  popped  and 
logically  ORed  together.  The  pascal  and 
cobol  operands  come  next.  The  inter¬ 
preter  calls  the  search  function  for  each 
of  these  words  and  gets  back  two  bit 


maps,  which  it  ORs  together.  Then  the 
interpreter  takes  the  ones  complement 
of  that  result,  and  the  result  of  all  that 
is  the  first  operand  required  by  the 
<and>  operator.  The  next  token 
popped  is  fortran.  The  interpreter  ANDs 
its  bit  map  with  the  first  bit  map,  and 
that  delivers  the  result  of  the  search. 
Out  of  breath?  What  I  have  just  de¬ 
scribed  seems  complicated  but  is  a  rela¬ 
tively  simple  algorithm  that  uses  recur¬ 
sion  in  a  function  that  returns  the  search 
result.  When  it  pops  an  operator,  it 
calls  itself  to  pop  the  next  stack  entry 
or  two  and  returns  the  result  that  comes 
from  applying  the  operator. 

Listing  One,  page  154,  is  a  new  ver¬ 
sion  of  textsrch.h  to  replace  the  one 
from  last  month.  A  notable  addition  to 
this  file  is  the  MAXFILES  global  vari¬ 
able.  This  variable  specifies  the  maxi¬ 
mum  number  of  text  files  in  your  data 
base.  The  bitmap  structure  defines  the 
multiple-integer  bit  map  that  represents 
the  search  result.  We  use  a  structure 
here  so  that  we  can  easily  pass  the  map 
between  functions. 

Listing  Two,  page  154,  is  exinterp.c, 
the  expression  interpreter.  It  expects 
the  postfix  expression  to  have  been 
built  by  the  parser  from  last  month.  It 
returns  a  bit  map  that  represents  the 
result  of  the  search.  We’ll  discuss  more 
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about  the  search  later.  The  exinterp 
function  calls  the  recursive  pop  func¬ 
tion  to  get  the  bit  map.  The  pop  func¬ 
tion  is  where  the  real  work  is  done.  It 
pops  a  token  from  the  postfix  stack 
and  processes  it.  If  that  token  is  an 
operand  (a  word),  the  pop  function 
calls  the  search  function,  which  returns 
a  bit  map.  The  bit  map  has  a  bit  set  for 
each  file  that  includes  the  word.  If  the 

The  primary  purpose  for 
TEXTSRCH  is  to  allow 
us  to  find  the  files  we 
want  to  read,  based  on 
some  criteria 


token  is  an  operator,  the  pop  function 
calls  itself  recursively  to  get  the  next 
token  or  two  for  the  operator  to  work 
on.  The  three  functions  named  and, 
or,  and  not  modify  the  bit  map  to  re¬ 
flect  the  result  of  the  Boolean  opera¬ 
tions  they  represent.  We  use  functions 
here  because  the  bit  map  is  an  array. 
(Think  how  much  easier  this  would 
be  with  C++.) 

Listing  Three,  page  155,  is  search. c. 
This  one  is  a  throwaway.  Although  it 
works,  it  is  less  than  efficient.  Its  pur¬ 
pose  is  to  allow  us  to  test  and  demon¬ 
strate  the  expression  evaluation  algo¬ 
rithms.  It  includes  three  generic  func¬ 
tions  that  we  will  replace  later.  The  first 
one,  called  init_database,  initializes  the 
data  base  system.  For  now,  all  it  does 
is  build  a  list  of  file  names  that  have  the 
.TXT  extension.  This  stub  function  uses 
MS-DOS  file  structures  and  the  Turbo 
C  findfirst  and  findnext  functions.  If 
you  are  using  a  different  environment, 
the  substitutions  should  be  simple.  What 
you  want  is  a  list  of  all  the  file  names 
in  the  data  base  built  into  the  array 
called  names. 

The  second  generic  stub  function  is 
called  search.  Its  purpose  is  to  search 
the  data  base  to  determine  which  files 
have  the  specified  word  in  them.  This 
one  cheats.  It  calls  the  grep  program 
and  redirects  its  output  to  a  file  called 
“hits.”  The  grep  command  that  it  exe¬ 
cutes  looks  like  this: 

grep  -1  -i  <word>  *.txt  >hits 

This  format  works  with  the  Turbo  C 
grep  program  and  should  work  with 
most  others.  The  -1  parameter  tells  grep 
to  list  only  the  file  names  that  match 


the  search,  and  the  -i  parameter  tells  it  final  bit  map.  That  final  one  is  the  one 
to  make  the  search  case  insensitive,  that process_result gets.  In  this  stubbed 
When  the  grep  program  is  done,  the  version,  process_resu.lt  simply  lists  the 
search  function  reads  the  hits  file  and  files  that  are  found  to  match  the  search 
compares  its  entries  to  the  file  name  criteria. 

list  that  init_database  built.  For  those  Listing  Four,  page  156,  is  textsrch.c, 
files  that  match,  the  search  function  the  main  function  of  the  TEXTSRCH 
sets  a  bit  in  the  bit  map  that  it  builds  program  and  the  one  that  ties  the  search 
and  returns.  process  together.  It  calls  init_database 

The  third  generic  stub  function  in  and  then  reads  the  search  expression 
search. c  is  called  process_result.  It  ac-  from  the  console.  It  calls  lexical_scan 
cepts  a  bit  map  as  the  result  of  an  from  last  month  to  convert  the  expres- 
expression  search.  Remember  that  sion  to  postfix  notation.  If  the  expres- 
search  builds  a  bit  map  for  a  single  sion  is  in  error,  the  program  displays  a 
word,  and  exinterp  combines  all  the  caret  under  the  token  where  it  found 
bit  maps  with  the  operators  to  build  a  the  problem.  Otherwise,  it  calls  exin- 
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terp  to  interpret  the  expression  and 
process_result to  process  the  result. 

You  need  to  compile  express. c  from 
last  month  and  textsrch.c,  search. c,  and 
exinterp.c  from  this  month  to  build  the 
program.  Make  sure  that  you  use  the 
new  textsrch.h  from  this  month. 

To  run  the  program,  build  your  data 
base  first.  Copy  all  of  your  text  files  into 
a  single  subdirectory  and  give  them  the 
file  extension  .TXT.  If  the  files  have 
word  processor  stuff  embedded  in  them, 
run  them  through  your  word  processor 
to  build  straight  ASCII  text  files.  Other¬ 
wise,  grep  might  not  be  able  to  find  the 
words  it  searches  for. 

These  instructions  assume  an  MS- 
DOS  environment.  Make  sure  that  the 
grep  and  textsrch  programs  are  in  the 
path  and  that  you  are  logged  onto  the 
subdirectory  where  you  built  the  data 
base.  Run  the  textsrch  program  from 
the  command  line.  It  will  prompt  you 
for  an  expression.  Type  one  in  and 
watch  it  churn.  If  your  data  base  is  big, 
it  will  take  a  while.  Later,  after  we  build 
an  index,  the  search  will  be  much  faster. 
The  result  of  the  program  will  be  a 
displayed  list  of  files  that  match  the 
query.  You  can  verify  the  results  with 
grep. 

Next  month  we’ll  work  on  building 
an  index  into  the  data  base.  Things  get 
interesting  because  we  have  several  dif¬ 
ferent  ways  to  approach  the  problem. 

OOPSLA 

I  attended  the  ACM’s  fourth  annual  Con¬ 
vention  On  Object-Oriented  Program¬ 
ming  Systems,  Languages,  and  Applica¬ 
tions  (OOPSLA),  held  in  New  Orleans 
in  October,  1989.  This  was  my  first  trip 
to  the  Crescent  City,  a  rare  confession 
from  an  old  jazz  musician,  and  besides 
the  hoopla  of  OOPSLA,  I  heard  plenty 
of  good  jazz  and  ran  into  some  old 
friends,  both  on  the  conference  floor 
and  on  bandstands  throughout  the  town. 

C++  permeated  the  show.  This  is 
clearly  the  platform  of  the  very  near 
future.  There  were  demonstrations  of 
C++  language  environments  from 
ParcPlace  and  Apple  as  well  as  a  num¬ 
ber  of  products  that  enhance  the  C++ 
platform.  Absent  were  Zortech,  Intek, 
and  Guidelines,  the  main  purveyors 
today  of  complete  C++  systems  for  the 
PC.  We  can  expect  announcements 
soon,  I  hope,  from  some  of  the  other 
vendors. 

One  subject  popped  up  frequently 
in  conversations  with  the  C++  language 
vendors.  There  is  no  standard  class 
library,  and  no  one  seems  to  know 
where  the  first  one  will  come  from.  The 
attitude  seems  to  be  that  users  of  the 
language  will  each  build  their  own. 
This  reminds  me  of  the  early  days  of  C 
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when  the  few  functions  described  in 
K&R  constituted  the  only  standard  we 
had,  and  the  compiler  vendors  extended 
it  with  their  own  unique  versions  of  the 
things  left  out.  There  was  the  Unix 
library  to  go  from,  but  many  of  the  PC 
compilers  went  their  own  ways.  Mar¬ 
ket  pressure  enforced  compliance  with 
a  de  facto  standard  long  before  the 
ANSI  X3J11  committee  was  close  to  a 
finished  draft.  That  pressure  was  cre¬ 
ated  by  the  overwhelming  success  of 
the  Microsoft  C  compiler.  Every  other 
compiler  vendor  tried  then  to  be  com¬ 
patible  with  good  old  MSC,  and  a  PC 
standard  of  sorts  evolved.  Some  of  that 
standard  —  the  pieces  that  were  not 
PC  specific  —  found  its  way  into  the 
ANSI  draft. 

Right  now  there  are  several  books 
about  C++.  Most  of  them  describe  some 
specific  classes  that  they  use  to  explain 
tiow  you  build  classes  rather  than  to 
Advance  a  standard  for  a  class  library. 

I  did  the  same  thing  myself  a  few  col¬ 
umns  back  with  homegrown  classes 
for  windows,  menus,  strings,  and  linked 
lists.  None  of  these  disparate  libraries 
are  likely  to  drive  an  industry-accepted 
standard.  I  suspect  that  the  first  com¬ 
piler  vendor  to  bundle  a  class  library 
with  a  highly  successful  C++  compiler 
will  hold  the  lead. 

Bjarne  Stroustrup  makes  the  point 
that  we  mustn’t  think  about  a  universal 
class  library  the  way  the  pure  object- 
oriented  data  model  would  have  us 
do.  Classes  defy  universal  definition 
because  the  universe  is  too  big.  Re-  , 
member  that  the  purpose  of  the  stan¬ 
dard  C  library  is  to  define  methods  for 
manipulating  generic  objects:  Files, 
strings,  characters,  numbers,  memory 
blocks,  program  execution,  dates,  times, 
and  so  on.  A  standard  class  library  must 
restrict  itself  as  well  to  classes  that  have 
general  application,  and  the  hierarchy 
for  a  given  program  is  not  necessarily 
a' subset  of  a  universally  defined  hierar¬ 
chy  but  rather  one  contrived  to  suit  the 
problem  at  hand.  Eventually  the  build¬ 
ers  of  vertical  applications  might  come 
to  share  their  work  in  a  series  of  appli¬ 
cation-specific  class  libraries.  I  doubt 
it,  though.  Few  such  industry-wide  shar¬ 
ings  of  C  function  libraries  exist. 

The  Teaching  of  C 

Another  frequently-expressed  sentiment 
at  OOPSLA  was  that  C++  is  too  hard  to 
learn,  and  the  language  industry  fears 
that  programmers  will  be  scared  off  by 
this.  They  compare  C++  to  one  of  the 
new  Pascals  with  object-oriented  ex¬ 
tensions  and  conclude  that  the  Pascal 
route  is  easier  to  travel.  They  are  right 
to  some  extent.  C++  is  more  difficult 
to  learn  than  object-oriented  Pascal. 


But  then  again,  traditional  C  is  more 
difficult  to  learn  than  traditional  Pascal, 
yet  C  became  and  remains  the  domi¬ 
nant  language.  Why?  Because,  once 

There  is  no  standard 
C++  class  library,  and 
no  one  seems  to  know 
where  the  first  one  will 
come  from.  The  attitude 
seems  to  he  that  users 
of  the  language  will 
each  build  their  own 


learned,  C  becomes  the  programmer’s 
preferred  language,  religious  language 
wars  notwithstanding.  I  think  that  C  is 
more  difficult  to  learn  only  because  it 
is  more  difficult  to  teach.  We  need  to 
educate  the  teachers  first.  They  need 


to  know  how  to  present  C  (and  C++) 
to  the  student  in  logical  increments. 

C  teachers  should  be  required  to  teach 
Pascal  first.  Maybe  its  syntax  will  help 
them  understand  the  properties  of  a 
programming  language  whose  original 
purpose  was  for  teaching  programming. 
C  instructors  around  the  country  are 
bewildering  students  with  abstruse  code 
examples  the  likes  of  which  only  a 
terse  language  such  as  C  will  permit.  It 
isn’t  that  you  have  to  write  C  programs 
that  way,  it’s  just  that  you  can,  and  the 
teachers  haven’t  learned  to  leave  that 
part  until  later. 

One  of  the  first  lessons  in  K&R  is 
about  how  you  can  say  this: 

while  ((c  =  getchar(  ))  !=  EOF) 


Many  teachers  conclude  that  this  facil¬ 
ity  of  C  to  support  embedded  expres¬ 
sions  is  so  powerful  that  it  needs  to  be 
taught  first  thing  out  of  the  chute.  There 
is  no  compelling  reason  to  avoid  such 
expressions  once  you  understand  them, 
but  there  is  also  no  reason  why  a  new¬ 
comer  to  C  shouldn’t  be  spared  these 
details  until  he  or  she  is  ready  for  it. 

The  K&R  book  precedes  this  exam¬ 
ple  with  a  less  terse  one  that  breaks 
each  of  the  expressions  and  operations 
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into  individual  statements  like  this: 

c  =  getchar(  ); 
while  (c  !=  EOF)  ( 

c  =  getchar( ); 


The  purpose  of  this  earlier  example  is  to 
introduce  the  experienced  programmer 
to  the  terser  style  of  code  and  to  illus¬ 
trate  how  every  statement  is  an  ex¬ 
pression  and  that  you  can  use  that  fea¬ 
ture  of  C  to  write  fewer  lines  of  code. 

Upon  seeing  such  a  program,  a  C 
veteran  is  immediately  moved  to  im¬ 
plode  everything  until  it  looks  like  the 
first  example.  But  the  rookie  finds  the 
more  verbose  program  a  lot  easier  to 
comprehend.  The  student  sees  a  work¬ 
ing  program  before  learning  a  lot  of  the 
finer  points  of  C.  The  extent  to  which 
a  teacher  should  delay  some  of  the 
finer  details  will  depend  on  the  pro¬ 
gramming  experience  of  the  new  C 
student,  particularly  because  more  and 
more  curricula  are  catering  to  students 
who  pass  progressively  through  layers 
of  prerequisite  classes  without  logging 
any  real-world  programming  time.  Try, 
for  example,  to  explain  to  someone 
who  is  not  a  programmer  why  recur¬ 
sion  is  important. 

Another  problem  is  that  teachers 
teach  too  many  other  complex  topics 
in  what  are  supposed  to  be  C  courses. 
They  strive  to  shroud  C  in  mystery.  I 
recently  tutored  a  student  who  was 
enrolled  in  an  advanced  C  course  at  a 
community  college.  The  programming 
assignments  required  her  to  use  the 
low-level  I/O  and  interrupt  functions 
of  Turbo  C  to  manipulate  the  sectors 
of  a  DOS  diskette  directory.  The  class 
spent  more  time  learning  about  the 
internals  of  DOS’s  file  system  than  about 
C.  The  instructor’s  rationale  for  such 
assignments  was  that  C  is  used  primar¬ 
ily  for  systems  programming,  and  DOS 
is  the  system  that  the  school  uses.  A 
student  who  is  going  into  a  non-DOS 
C  environment  has  been  cheated  by 
this  approach.  To  begin  with,  the  in¬ 
structor’s  assumption  is  no  longer  valid. 
We  use  C  to  develop  nearly  every  kind 
of  software  system.  By  spending  so 
much  of  the  class’s  time  and  energy 
on  the  learning  of  DOS  and  BIOS  sec¬ 
tor  I/O,  the  instructor  has  lost  valuable 
opportunities  to  teach  C.  This  class 
would  have  been  more  appropriately 
labeled  an  MS-DOS  Systems  Program¬ 
ming  Course  with  C  as  the  program¬ 
ming  language.  Fewer  students  would 
have  signed  up,  of  course,  but  the  ones 
who  did  would  have  gotten  what  they 
paid  for,  and  the  others  could  have 
been  elsewhere  in  a  real  C  class. 
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The  ANSI  Comer 

Sometimes  an  improvement  can  get  in 
the  way.  The  draft  ANSI  specification 
for  standard  C  adds  adjacent  string  lit¬ 
eral  concatenation  to  the  language,  and 
that  is  a  handy  thing  to  have.  With  this 
feature  you  can  code  adjacent  literals, 
and  the  compiler  will  concatenate  them. 
For  example,  consider  this  code: 

printf(  "Hello,"  "World"); 

When  the  compiler  sees  adjacent  string 
literals  such  as  these,  it  combines  them. 
The  power  of  this  facility  becomes  ap¬ 
parent  when  used  along  with  the  pre¬ 
processor  in  this  way: 

#define  PROGRAM  "Jiffy  Spreadsheet" 
^define  VERSION  "vl.23" 

^define  DATE  "1990" 

printf(PROGRAM  VERSION  " 

Copyright "  DATE); 

This  feature,  handy  as  it  is,  cost  me  a 
bit  of  time.  I  had  the  following  array  in 
a  program: 

char  *names[]  =  ( 

"add", 

"change", 

"delete", 

"cut" 

"paste", 

NULL 


See  that  missing  comma  after  the  “cut” 
literal?  I  didn’t,  not  for  a  long  time,  and 
I  couldn’t  figure  out  why  this  statement 
worked  only  some  of  the  time: 

if  (strcmp(names[i],  name)  =  =  0) 

I  could  add,  change,  and  delete,  but  I 
couldn’t  cut  or  paste.  After  I  found  the 
problem,  I  stared  in  disbelief,  wonder¬ 
ing  why  the  compiler  hadn’t  warned 
me  about  the  missing  comma.  Then  it 
hit  me.  Good  old  ANSI  C  thought  I 
really  meant  to  build  a  “cutpaste”  string. 
But,  when  viewed  in  the  context  of 
how  I  coded  the  array,  the  missing 
comma  was  hard  to  spot,  and,  once 
revealed  to  the  old  eyeball,  looked  like 
it  should  have  been  flagged  by  the 
compiler  as  an  error.  Even  after  I  saw 
the  error,  it  was  not  immediately  obvi¬ 
ous  to  me  that  I  had  coded  perfectly 
acceptable  ANSI  C  language.  The  com¬ 
piler,  however,  looks  dispassionately 
at  our  code  and  cannot  guess  our  in¬ 
tentions.  What  I  coded  was  legitimate 
C,  yet  it  didn’t  work  worth  a  hoot. 

Here  is  another  use  for  the  *  prepro¬ 
cessor  operator  that  we  discussed  last 
month.  Suppose  you  have  some  maxi¬ 
mum  number  of  things  your  program 
will  handle  and  you  define  that  maxi¬ 


mum  this  way: 

^define  MAXTHINGS  500 

When  the  user  tries  to  add  the  501st 
thing,  you  want  to  display  a  message 
that  specifies  the  limit.  We  used  to  do 
it  this  way. 

printf("%d  entries  only",  MAX); 

This  is  a  contrivance  of  constants. 
MAXTHINGS  is  a  constant,  and  should 
be  included  in  the  string  literal.  But 
pre-ANSI  C  had  no  convenient  way  to 
do  that  and  still  preserve  the  global 
definition  of  MAXTHINGS.  With  the 
new  #  operator  and  adjacent  string  con¬ 
catenation,  we  can  do  this: 

#define  str(x)  #x 
printfSTR(MAX "  entries  only"); 

Book  of  the  Month 

Get  yourself  a  copy  of  C  Traps  and 
Pitfalls  by  Andrew  Koenig  (Addison- 
Wesley,  1989).  It  is  a  collection  of  the 
mistakes  a  C  programmer  makes.  Be¬ 
sides  the  obvious  ones  (the  dangling 
else,  for  example),  the  book  contains 
many  insightful  discussions  of  less  ob¬ 
vious  but  common  errors  including  pro¬ 
grammer-induced  malfunctions  of  the 
dreaded  C  pointer. 

Many  of  the  errors  that  Koenig  de¬ 
scribes  will  be  flagged  as  warnings  by 
contemporary  ANSI  conforming  com¬ 
pilers.  But  a  lot  of  pre-ANSI  code  is  still 
out  there  in  maintenance,  and  we  must 
either  turn  the  warnings  off  or  disre¬ 
gard  them,  and  so  we  are  sometimes 
susceptible  to  these  errors  now  just  as 
in  the  old  days. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  154.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  10. 
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Dressing  the  Truth 
In  Rubber  Suits 


Remember  AI?  Sure  you  do.  A  cou¬ 
ple  of  years  ago,  it  was  going  to 
change  the  face  of  the  planet, 
according  to  the  legions  of  igno¬ 
rant  Esther  Dyson  wannabees  selling 
$900  newsletters  to  corporate  seatwarm- 
ers  with  lots  of  money  to  waste.  AI  was 
going  to  allow  programs  to  configure 
themselves.  AI  was  going  to  allow  us 
to  get  our  work  done  without  expend¬ 
ing  any  effort.  AI  was  going  to  allow 
our  software  to  read  our  minds.  It  got 
so  bad  that  PC  Week  columnist  Jim 
Seymour  suggested  that  software  ven¬ 
dors  could  double  sales  by  slapping  a 
gold  starburst  sticker  on  the  outside  of 
every  product  package  reading,  “New! 
Improved!  With  AI!” 

Meanwhile,  back  in  the  trenches,  the 
guys  who  were  researching  AI  were 
sadly  shaking  their  heads.  They  never 
made  those  promises,  or  any  promises. 
They  weren’t  trying  to  create  an  artifi¬ 
cial  human  brain.  They  were  just  look¬ 
ing  for  new  ways  to  arrange  the  same 
old  instructions  we’ve  been  fetching 
and  executing  all  along.  The  human 
brain  is  a  pretty  successful  computer, 
they  reasoned,  so  why  not  try  to  learn 
something  from  the  way  it  works?  Had 
they  called  it  cognitive  modeling  or 
somesuch,  nothing  dramatic  would 
have  happened.  (Industry  mavens  rarely 
abuse  what  they  can’t  pronounce.)  But 
say  “artificial  intelligence”  and,  wham- 
mo!  Isaac  Asimov’s  robots  come  strid¬ 
ing  over  the  horizon,  with  Popular  Me- 
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chanics ,  People  Magazine ,  and  finally 
The  National  Enquirer  in  hot  pursuit. 

You’ll  notice  that  nobody’s  talking 
much  about  AI  anymore.  The  hypemon- 
gers  buried  it  so  deep  that  nobody  in 
the  mainstream  software  development 
community  may  ever  take  it  seriously 
again.  The  hype  machines  have  been 
quiet  lately,  but  don’t  assume  that  they’re 
gone  —  they’re  just  getting  a  valve-and- 


ring  job  so  to  be  in  top  shape  when  the 
next  fad  happens  by,  like  remoras  watch¬ 
ing  for  a  passing  grouper. 

Lately,  I’ve  begun  to  hear  them  rev¬ 
ving,  this  time  over  something  with  a 
lot  more  near-term  potential  than  AI: 
Object-oriented  programming.  People 
who  never  said  OOPs  before,  except 
when  using  chopsticks,  have  become 
self-anointed  experts,  and  have  begun 
dressing  the  truth  in  rubber  suits. 

So  let’s  dump  some  sand  in  the  hype 
machines,  and  nail  some  nascent  con¬ 
ventional  wisdom  to  the  wall. 

Rubber  Truth  #1 :  OOP  Makes  Coding 
Effortless 

Dream  on.  Furthermore,  OOP  doesn’t 
even  make  coding  easy.  One  might 
argue  that  it  makes  coding  more  diffi¬ 
cult,  in  that  OOP  requires  considerable 
forethought  and  design  effort  up  front. 

An  object  hierarchy  requires  a  start¬ 
ing  point;  a  handful  of  abstract  classes 
that  exist  to  broadcast  certain  charac¬ 
teristic  behavior  down  the  many  in¬ 
heritance  branches.  The  root  of  the 
tree  is  a  foundation  on  which  thou¬ 
sands  or  tens  of  thousands  of  lines  of 
code  may  depend.  If  you  discover  half¬ 
way  through  a  50,000  line  application 
that  you’ve  conceptualized  the  funda¬ 
mental  abstract  classes  wrong,  you 
might  just  have  to  kiss  25,000  lines  of 
code  good-bye.  So  take  heed: 

Duntemann's  OOP  Warning  #1 : 
Invalidating  the  Root  Invalidates 
The  Leaves! 

When  you  cast  a  program  design  in 
OOP  terms,  think  very  hard  about  the 
nature  of  your  conceptual  model.  Once 
you’ve  created  a  solid,  correct,  and  work¬ 
able  foundation  in  terms  of  an  object 
hierarchy,  coding  gets  a  little  easier 
because  you  can  inherit  and  reuse  some 
of  that  hard,  early  general  work  in  the 
later,  more  specific  tasks.  That  doesn't 
mean  that  the  total  effort  required  to 
finish  the  project  is  going  to  be  any 
less.  It’s  just  that  the  hardest  work  gets 


done  up  front,  and  the  rest  of  it  seems 
easy  only  by  comparison. 

Rubber  Truth  #2:  OOP  Makes  Programs 
Bulletproof 

I  confess,  I’ve  stretched  this  one  a  little 
myself,  and  have  been  bitten  in  the 
hindparts  for  my  trouble.  At  first  thought, 
encapsulation  might  appear  to  make  it 
harder  for  bugs  to  propagate  beyond 
the  bounds  of  the  object  in  which  they 
occur.  Unfortunately,  all  method  code 
is  bequeathed  to  an  object’s  children, 
for  good  or  for  bad.  There’s  no  soft¬ 
ware  equivalent  of  Maxwell’s  Daemon 
sitting  on  a  post  at  the  object’s  inter¬ 
face,  letting  features  pass  down  the 
object  hierarchy  but  keeping  the  bugs 
behind.  So,  folks,  keep  in  mind: 

Duntemann's  OOP  Warning  #2:  Bugs  Are 
Just  as  Inheritable  as  Features 

It’s  true  to  an  extent  that  languages  that 
enforce  encapsulation,  such  as  Small¬ 
talk  and  Actor,  prevent  a  certain  class 
of  under-the-table  bugs  caused  by  di¬ 
rectly  referencing  an  object’s  state  or 
instance  variables.  In  Smalltalk  and  Ac¬ 
tor,  you  simply  cannot  reference  an 
object’s  internal  state  (that  is,  what  in 
Object  Pascal  we  would  call  its  fields) 
directly.  This  makes  bug  propagation 
a  one-way  street  down  along  the  ob¬ 
ject  hierarchy,  which  is  better  than  noth¬ 
ing.  Unfortunately,  even  this  protec¬ 
tion  is  missing  from  C++  and  the  vari¬ 
ous  dialects  of  Object  Pascal.  Both 
Turbo  Pascal  and  QuickPascal  require 
that  you,  the  programmer,  enforce  encap¬ 
sulation,  and  if  you’re  a  bad  enforcer, 
you’re  no  better  off  than  with  tradi¬ 
tional  structured  programming  tech¬ 
niques. 

Rubber  Truth  #3:  OOP  Allows  Easy 
Free-form  Prototyping,  and  You  Can  Keep 
The  Prototype! 

This  is  one  of  those  deceptive  and  infu¬ 
riating  assertions  that  in  certain  circum¬ 
stances  might  well  be  right  —  but  for 
all  the  wrong  reasons.  I’m  reminded 
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(continued  from  page  140) 
of  a  pre-Lego  construction  toy  I  had 
when  I  was  six  called  “Lock-A-Blox.” 
It  was  a  boxful  of  brightly-colored 
blocks,  with  slots  on  two  faces  and 
tabs  on  the  two  opposite  faces.  All  the 
tabs  fit  all  the  slots,  and  all  block  di¬ 
mensions  were  always  even  multiples 
of  the  smallest.  Everything  always  fit 
together,  no  matter  how  you  tried  it. 
There  were  no  wrong  combinations, 
no  embarrassing  chinks  or  bulges  where 
things  didn’t  quite  fit. 

Nonetheless,  no  matter  what  you  built 
with  it,  from  the  Brooklyn  Bridge  to  the 
Eiffel  Tower  to  Godzilla,  your  creation 
always  looked  like  ...  a  bunch  of  Lock- 
A-Blox. 

Rapid  free-form  prototyping  is  in¬ 
deed  possible  in  Smalltalk  and  Actor. 
It’s  done  by  taking  instances  of  the 
hundred-plus  object  types  in  the  stan¬ 
dard  class  library  and  hooking  them 
together  until  things  work.  You  stick 
menu  B  behind  radio  button  A,  and  if 
they  don’t  look  quite  right,  well,  pull 
them  apart  and  try  something  else. 
There’s  no  sense  of  loss  in  throwing 
away  the  menu  because  you  didn’t  have 
to  write  the  code  to  create  the  menu. 
It  was  all  there  in  the  class  library,  like 
bubble-packed  cold  meat  hanging  on 
pegs  in  the  refrigerator  case  down  at 
Safeway. 

You  can  very  quickly  get  a  series  of 
menus  and  other  screen  controls  to¬ 
gether  in  Smalltalk  or  Actor,  and  if  the 
prototype  user  interface  isn’t  too  messy, 
you  have  a  reasonable  chance  of  filling 
in  the  guts  without  having  to  abandon 
and  rewrite  the  user  interface. 

There’s  a  price  to  be  paid:  Your  ap¬ 
plication  will  be  made  out  of  pieces 
written  by  somebody  else,  and  it  will 
have  a  look  and  overall  structure  dic¬ 
tated  by  the  shape  of  those  pieces.  This 
is  not  necessarily  a  bad  thing,  espe¬ 
cially  if  you’re  sick  of  messing  around 
with  your  own  window  manager  code 
and  you  are  looking  for  a  standard  user 
interface. 

That,  however,  is  for  Smalltalk  and 
Actor.  There  is  currently  no  massive 
class  library  in  QuickPascal,  Turbo  Pas¬ 
cal,  or  Zortech  C++.  In  Object  Pascal 
and  C++  you  have  to  build  your  own 
Lock-A-Blox,  with  all  the  time,  effort, 
and  torn  hair  that  that  implies. 

Duntemann's  OOP  Warning  #3:  The 
Quality  of  an  OOP  Prototype  Depends 
Utterly  on  the  Quality  of  tne  Standard 
Class  Library 

The  bottom  line  of  this  rubber  truth  is 
that  the  ease  of  prototyping  has  less  to 
do  with  OOP  than  with  a  well-thought- 
out  library  of  prefab  program  compo¬ 
nents.  I’ve  done  some  amazingly  easy 


prototyping  with  Turbo  Power  Soft¬ 
ware’s  Turbo  Professional  5  0,  and  with 
a  superb  Modula-2  library  product  called 
“Repertoire,”  all  without  object-oriented 
anything.  OOP  contributes  a  little  — 
objects  are  more  independent  than  tra¬ 
ditional  procedures  and  functions,  and 
thus,  they  combine  better  and  with 
fewer  possible  side  effects  —  but  far 
less  than  most  people  think. 

Turbo  Pascal  prototyping  will  be 
made  lots  easier  once  Turbo  Power’s 
Object  Professional  library  is  finished 
and  shipping.  (This  may  well  be  the 
case  now,  while  you’re  reading  this; 
though,  while  I’m  writing,  they  still  have 
a  ways  to  go.)  And  over  time,  such 
ambitious  class  libraries  will  become 
de  rigueur  in  all  OOP  languages,  just 
as  they  have  been  in  Smalltalk  and 
Actor  from  day  one. 

Object-oriented  programming  is  no 
magic  pill.  It  does  not  allow  effortless 
programming  of  complex  applications 
that  work  the  first  time  and  never  break. 
It  does  not  make  applications  run  faster, 
but  if  badly  used  can  make  them  run 
slower.  (In  fairness  to  OOP,  this  is  also 
true  of  most  every  programming  tech¬ 
nique  you  could  name.)  Its  benefits  fall 
mostly  to  the  programmer:  Greater  rich¬ 
ness  of  expression  in  program  design; 
greater  potential  to  reuse  well-designed 
program  components;  and  greater  abil¬ 
ity  to  fix,  change,  and  extend  existing 
applications  in  a  maintainable  manner. 
From  the  outside,  the  programs  will 
look  exactly  the  same. 

The  Parent  Trap 

I  treated  polymorphism  in  detail  back 
in  November,  but  it  may  be  time  to 
come  back  and  shed  some  light  into 
some  corners  that  have  remained  dark 
through  it  all.  I  lurk  on  CompuServe  a 
lot,  tallying  the  subjects  people  have 
trouble  understanding  —  that’s  an  ex¬ 
cellent  place  for  professional  explain¬ 
ers,  like  me,  to  get  their  raw  material. 
And  whereas  the  broad  concepts  of 


Figure  1:  The  domain  of  object 
class  ARC 


polymorphism  seem  to  be  coming 
across,  the  details  keep  getting  scram¬ 
bled  and  misconstrued. 

Chief  among  these  is  the  matter  of 
polymorphic  assignment  compatibility. 

In  an  object  hierarchy,  assignment  com¬ 
patibility  is  extended  along  a  given  ob¬ 
ject  class’  domain.  This  domain  includes 
the  class  and  all  of  its  descendant  classes, 
as  shown  in  Figure  1.  The  shaded  classes 
are  the  domain  of  class  Arc. 

The  rule  is  this:  An  object  can  be 
assigned  to  any  type  “rootward”  in  its 
domain.  (Let’s  not  argue  about  “above” 
or  “below,”  because  those  words  de¬ 
pend  utterly  on  how  you  draw  the 
hierarchy.  In  Figure  1,  the  root  of  the 
hierarchy  is  at  the  top  of  the  page.)  In — 
other  words,  you  could  take  an  in¬ 
stance  of  type  Arc  and  assign  it  to  an 
instance  of  type  Circle: 

MyCircle  :=  My  Arc; 

Ordinarily,  Pascal  would  call  you  down 
on  type  conflict  grounds,  and  it  still 
will,  if  you  were  to  assign  MyArc  to 
something  outside  of  its  domain;  say, 
to  an  instance  of  type  Rectangle  or 
Polygon. 

One  thing  to  remember  that  people 
too  often  forget  is  that  the  reverse  is 
not  true:  You  cannot  assign  a  parent 
to  a  child.  This  won’t  compile: 

MyArc  :=  MyCircle; 

Try  to  remember  this  key  phrase:  “To 
the  general  assign  the  specific.”  One 
way  to  think  of  an  object  hierarchy  is 
as  a  movement  from  the  most  general 
abstract  classes  at  the  root  to  the  most 
specific  classes  at  the  leaves.  If  you’d 
prefer  an  earthier  mnemonic,  try  this: 
“You  can  hang  a  leaf  on  a  root.  You 
can’t  hang  a  root  on  a  leaf.”  Think  of 
assigning  the  specific  to  the  general  as 
hanging  a  leaf  on  the  root. 

Making  the  Compiler  Swallow 
Polymorphism 

The  whole  idea  behind  extending 
assignment  compatibility  rootward 
through  an  object’s  domain  is  to  make 
polymorphism  syntactically  kosher  to 
the  compiler.  In  a  sense,  polymorphism 
is  the  hiding  of  different  classes  behind 
the  mask  of  a  common  ancestor  class. 
The  mask  hides  the  differences  between 
the  classes,  and  emphasizes  those  as¬ 
pects  the  classes  have  in  common  — 
in  this  case,  the  aspects  defined  in  the 
common  ancestor  class. 

In  Figure  1,  for  example,  Line,  Rec¬ 
tangle,  and  Circle  are  all  descended 
from  Point.  Point  is  literally  all  that  the 
three  have  in  common.  Inside  Point 
there  is  a  pair  of  methods  for  display- 
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(continued  from  page  142) 
ing  and  erasing  the  object’s  graphic 
image:  Show  and  Hide.  Inheritance 
causes  Show  and  Hide  to  be  passed 
down  into  all  of  Points  child  classes. 
The  child  classes,  however,  have  the 
option  of  redefining  their  own  specific 
methods  under  the  names  Show  and 
Hide.  A  line  is  drawn  differently  from 
a  circle,  so  Line. Show  would  necessar¬ 
ily  be  different  from  Circle.Show. 

Nonetheless,  the  method  name  and 
the  general  idea  (to  display  a  figure  on 
the  screen)  is  the  same  for  all  the  graphic 
object  classes.  So  bring  on  the  masks: 

VAR 

Figures  :  ARRAY!  1.. 3]  OF  Point; 

ACircle  :  Circle; 

ARectangle  :  Rectangle; 

ALine  :  Line; 


Figurestl]  :=  ACircle; 

Figures[2]  :=  ALine; 

Figures[31  :=  ARectangle; 

FOR  I  :=  1  TO  3  DO 
Figurestl], Show; 

Here  we  have  an  array  of  type  Point, 
to  which  we  assign  instances  of  Circle, 
Line,  and  Rectangle  as  we  choose.  Be¬ 
cause  Point  is  within  the  domain  of  all 
three,  extended  assignment  compati¬ 
bility  allows  the  compiler  to  accept  these 
assignments,  even  though  they  violate 
traditional  Pascal  strong  typing. 

Polymorphism  enters  the  picture  in 
the  FOR  statement,  where  we  step 
through  the  array,  calling  the  Show 
method  belonging  to  each  array  ele- 


144 

94 


ment.  Even  though  the  elements  of  the 
array  Figures  are  all  nominally  type 
Point,  late  binding  and  polymorphism 
allow  the  Circle.Show  method  to  be 
invoked  for  element  1,  the  Line. Show 
method  for  element  2,  and  the  Renau¬ 


lt’ s  just  that  the  hardest 
work  gets  done  up  front, 
and  the  rest  of  it  seems 
easy  only  by 
comparison 


gle.Show  method  for  element  3-  With¬ 
out  extended  assignment  compatibil¬ 
ity,  the  three  graphics  figure  objects 
could  never  have  been  assigned  to  the 
array,  and  the  polymorphic  method  calls 
could  never  have  happened. 

The  Parting  of  the  Pascals 

One  (serious)  catch.  The  syntax  shown 
before  doesn’t  work  in  Turbo  Pascal. 
It  compiles  correctly,  but  polymorphism 
won’t  happen.  In  other  words,  if  you 
compile  the  above  code  fragment  un¬ 
der  Turbo  Pascal,  the  FOR  statement 
will  execute  Point. Show  for  all  three 
of  its  array  elements  —  as  if  the  poly¬ 
morphic  assignments  to  the  three  de¬ 
scended  classes  never  took  place. 

This  isn’t  a  bug  —  it’s  part  of  the 
spec.  QuickPascal  will  compile  and  run 
code  like  the  example  shown  earlier. 
The  two  Object  Pascals  differ  signifi¬ 
cantly  in  their  object  philosophy  (while 
agreeing  in  almost  everything  else),  but 
the  most  fundamental  difference  be¬ 
tween  them  is  that  all  QuickPascal  ob¬ 
jects  are  allocated  on  the  heap,  whereas 
Turbo  Pascal  objects  may  be  allocated 
either  on  the  heap  or  (by  default)  in  the 
data  segment.  Turbo  Pascal  objects  al¬ 
located  in  the  data  segment  (static  ob¬ 
jects)  and  addressed  directly  cannot 
take  part  in  polymorphism. 

Keep  this  in  mind,  always:  Polymor¬ 
phism  is  by  nature  a  dynamic  business, 
and  is  done  through  pointers.  If  an 
object  is  not  accessed  through  a  pointer, 
it  won’t  polymorph. 

So  how,  then,  does  QuickPascal  man¬ 
age  to  make  the  example  code  above 
run  correctly?  It’s  an  aspect  of  the  be- 
tween-two-worlds  nature  of  objects  in 
QuickPascal.  When  a  QuickPascal  ob¬ 
ject  is  declared,  it’s  declared  statically, 
just  as  any  variable  is: 


VAR 

ACircle  :  Circle; 

However,  declaring  a  QuickPascal  ob¬ 
ject  is  not  enough.  Before  it  can  be 
used  (actually,  before  it  really  exists)  it 
must  be  allocated  on  the  heap,  via  New: 

New(ACircle); 

Thereafter,  the  object  can  be  referenced 
as  though  it  were  a  static  variable: 

ACircle. Show; 

No  caret  symbols  here,  even  though 
ACircle  exists  entirely  on  the  heap.  In 
a  sense,  QuickPascal  objects  are  nei¬ 
ther  fully  static  nor  fully  dynamic. 
They’re  just .  .  .well.  .  .  objects,  that’s  all. 

Behind  the  scenes,  an  apparently 
static  reference  to  a  QuickPascal  object 
really  is  a  pointer  reference.  The  name 
of  a  QuickPascal  object  is  in  truth  a 
pointer  to  that  object  on  the  heap. 
They’ve  just  done  away  with  the  famil¬ 
iar  caret  or  “up  arrow”  pointer  refer¬ 
ence  notation. 

In  Turbo  Pascal,  by  contrast,  an  ob¬ 
ject  is  either  fully  static  and  exists  in  the 
data  segment,  or  is  fully  dynamic  and 
exists  on  the  heap  and  must  be  ac¬ 
cessed  through  the  traditional  pointer 
reference  notation.  A  Turbo  Pascal  ob¬ 
ject  is  best  approached  as  a  record  with 
some  special  properties,  and  obeys  all 
the  rules  a  record  would  with  respect 
to  allocation  and  referencing. 

Thus,  when  in  QuickPascal,  we  as¬ 
sign  object  instances  to  an  array  of 
object  instances,  we’re  actually  assign¬ 
ing  object  pointers  to  an  array  of  object 
pointers: 

Figurestl]  :=  ACircle; 

Figures[2]  :=  ALine; 

Figures[3]  :=  ARectangle; 

Here,  ACircle  is  actually  a  pointer  to  a 
block  of  memory  on  the  heap  contain¬ 
ing  the  object’s  actual  data  and  method 
table.  Similarly,  the  Figures  array  is  in 
reality  an  array  of  pointers  —  not  whole 
objects.  If  we  had  intended  to  use  the 
elements  of  Figures  without  assigning 
already-allocated  objects  to  them,  we 
would  have  had  to  allocate  each  indi¬ 
vidual  element  of  Figures  with  the  New 
statement: 

New(Figurestlt); 

New(Figures[l]); 

New(Figures[l]); 

This  static/dynamic  duality  of  Quick¬ 
Pascal  objects  (and  Apple  Pascal  ob¬ 
jects  before  them)  is  a  source  of  some 
serious  confusion  to  newcomers.  Best 
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to  remember:  All  QuickPascal  objects 
are  at  the  end  of  pointer  references, 
whether  it  looks  like  they  are  or  not! 

Polymorphism  Through  Pointers 

Fortunately,  both  QuickPascal  and 
Turbo  Pascal  objects  can  be  manipu¬ 
lated  through  explicit  pointer  references. 
And  just  as  assignment  compatibility  of 
objects  is  loosened  up  within  an  ob¬ 
ject’s  domain,  so  is  the  assignment  com¬ 
patibility  of  pointers  to  those  objects. 

In  other  words,  just  as  a  Circle  object 
may  be  assigned  to  a  Point  object,  a 
pointer  defined  as  a  pointer  to  Circle 
may  be  assigned  to  a  pointer  defined 
as  a  pointer  to  Point: 

TYPE 

PointPtr  =  APoint; 

CirclePtr  =  ^Circle; 

VAR 

CircleHandle  :  CirclePtr; 
PointHandle  :  PointPtr; 


Pointhandle  :=  CircleHandle; 

In  this  situation,  polymorphism  will 
work  with  either  compiler,  using  iden¬ 
tical  syntax. 


Virtual  Method  Table,  which  I  described 
in  some  detail  in  my  November  col¬ 
umn.  When  Twerp  is  assigned  to  Per¬ 
son,  all  of  Twerp’s  data  is  copied  over 
Person’s,  but  the  VMT  links  are  not 
involved  in  the  move.  Person’s  VMT 
link  remains  intact,  even  after  the  as¬ 
signment  overwrites  all  of  Person’s  data 
with  Twerp’s.  Why?  The  VMT  contains 
the  size  of  its  object,  returned  by  the 
Sizeof  function  and  used  internally  by 
other  aspects  of  the  run-time  library. 
Especially  when  you’re  dealing  with 
statically  allocated  data,  you  do  not 
want  to  lose  track  of  how  big  an  indi¬ 
vidual  item  is.  Get  it  wrong  during  some¬ 
thing  as  simple  as  an  assignment,  and 
you  overwrite  adjacent  data. 

In  short,  static  data  is  no  place  for 
polymorphic  fooling  around.  It’s  much 
safer  on  the  heap,  where  you  can  throw 
pointers  around  instead  of  whole  ob¬ 
jects. 

Much  better  to  do  it  this  way: 

Link  :=  @Dad; 

KidLink  :=  @Twerp; 

Link  :=  KidLink; 

LinkA.Talk; 

Here,  Link  is  a  pointer  to  Father  object 
Dad,  and  KidLink  is  a  pointer  to  Son 
object  Twerp.  Assigning  KidLink  to  Link 


The  best  way  to  show  polymorphism 
through  pointers  is  with  a  complete 
program.  There’s  no  substitute  for  load¬ 
ing  up  a  piece  of  code  and  watching  it 
work  before  your  eyes.  Listings  One 
and  Two,  page  158,  are  pretty  much 
the  same  program,  implemented  as  their 
particular  compilers  demand.  Listing 
One  is  the  QuickPascal  version,  and 
Listing  Two  is  the  Turbo  Pascal  5.5 
version. 

The  programs  implement  two  object 
classes:  Father  and  Son.  Son  is  a  de¬ 
scendant  of  Father.  Both  have  meth¬ 
ods  named  Talk,  which  display  appro¬ 
priate  text  to  the  screen  for  each  class. 
Father  says  one  thing;  Son  says  an¬ 
other.  The  main  body  of  each  program 
does  three  things: 

1.  Allocates  and  initializes  three  ob¬ 
jects,  Dad  (of  type  Father),  Twerp 
(of  type  Son),  and  Person  (also  of 
type  Father). 

2.  Attempts  polymorphism  through  di¬ 
rect  references.  This  works  for  Quick¬ 
Pascal  and  fails  for  Turbo  Pascal. 

3.  Attempts  polymorphism  through 
pointer  references.  This  works  iden¬ 
tically  for  both  compilers. 

Assigning  a  Son  instance  to  a  Father 
instance  is  done  in  both  programs: 


can  be  done  because  Links  referent 
shares  KidLinks  referent’s  domain.  And 
this  time,  specifying  Link^.Talk  exe¬ 
cutes  Son.Talkbecause  polymorphism 


The  best  way  to 
show  polymorphism 
through  pointers 
is  with  a 

complete  program 


works  through  pointer  references  in 
both  QuickPascal  and  Turbo  Pascal. 
No  data  is  moved;  once  the  assignment 
happens,  Link  points  directly  to  Twerp, 
so  Link^.Talk  executes  Twerp’s  Talk 
method. 

The  Limits  of  Polymorphism 

This  is  terrific  stuff  —  hiding  the  son 
behind  a  mask  of  the  father.  There’s  a 
catch:  The  only  object  methods  or  data 


Person  :=  Twerp; 

Person. Talk; 

The  method  invocation  will  call  Son.  Talk 
in  QuickPascal  and  Father.  Talk  in  Turbo 
Pascal.  Why? 

Person  and  Twerp  are  both  pointers 
beneath  the  skin  of  QuickPascal,  and 
assigning  Twerp  to  Person  only  copies 
the  Twerp  pointer  to  the  Person  pointer. 
This  is  easy  and  fast  —  all  pointers  are 
the  same  size,  32  bits. 

In  the  Turbo  Pascal  version,  on  the 
other  hand,  Person  and  Twerp  are  both 
objects  in  the  data  segment.  They  are 
of  different  sizes.  Assigning  Twerp  to 
Person  means  moving  physical  data 
from  one  location  in  the  data  segment 
to  another.  To  avoid  disrupting  data 
beyond  the  bounds  of  Person,  Twerp 
will  have  to  be  truncated  during  the 
move  —  because  Twerp  is  larger  than 
Person.  Data  is  lost,  which  is  never  a 
good  idea. 

If  you  look  beneath  the  surface  of 
the  Turbo  Pascal  version,  you’ll  find  that 
data  is  moved  from  Twerp  to  Person, 
and  that  the  Twerp. Girlfriend’s  field  is 
lost  in  the  move.  Person  retains  its  iden¬ 
tity  as  a  Father  object,  however,  and  any 
call  to  a  method  in  Person  will  invoke 
Father’s  methods  rather  than  Son’s. 

The  key  here  is  Person’s  link  to  the 


accessible  through  polymorphic  assign¬ 
ment  are  those  that  the  two  involved 
classes  have  in  common.  This  is  subtle, 
and  causes  a  lot  of  head  scratching 
during  the  learning  process. 

Consider:  We’ve  assigned  a  pointer 
to  Twerp  to  a  pointer  to  Dad.  Now,  can 
we  access  a  field  specific  to  Twerp 
through  that  pointer?  No! 

Try  adding  this  to  either  Listing  One 
or  to  Listing  Two  after  the  assignment 
of  KidLink  to  Link. 

Writeln(LinkA. Girlfriends); 

Now,  Link  points  to  a  Son  object,  but 
the  compiler  will  steadfastly  claim  ig¬ 
norance  that  the  Girlfriends  field  ex¬ 
ists.  (Turbo  Pascal  will  give  you  error 
44,  and  QuickPascal  will  give  you  error 
60.)  Hell,  if  we  can  access  Twerps  meth¬ 
ods  through  Link,  we  should  be  able 
to  access  Twerps  fields!  And  we  can  • — 
but  only  those  fields  that  Twerp  and 
Dad  both  have  in  common.  Type  Fa¬ 
ther  defines  an  Age  field  and  Yon  inher¬ 
its  it,  but  Son  defines  a  Girlfriends  field 
that  Father  doesn’t  have.  A  pointer  de¬ 
fined  as  pointing  to  a  Father  type  (as 
Link  is)  can’t  access  things  (either  meth¬ 
ods  or  data)  that  aren’t  defined  in  type 
Father. 

Why  not?  Well,  loosening  assignment 
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compatibility  rules  doesn’t  mean  throw¬ 
ing  them  away  entirely.  Neither  com¬ 
piler  is  quite  smart  enough  to  deduce 
things  across  an  assignment  statement. 
Assigning  a  SonPtrto  a  FatherPtr doesn’t 
change  the  fact  that  the  FatherPtr  is  a 
FatherPtr  in  the  compiler’s  symbol  ta¬ 
ble.  When  you  try  to  access  a  field 
called  Girlfriends  through  a  FatherPtr, 
the  compiler  checks  the  fields  defined 
under  type  Father  for  a  field  called 
Girlfriends  and  doesn’t  see  it. 

If  you  want  to  access  .Son-specific 
fields  through  a  FatherPtr  you’ll  have 
to  help  the  compiler  a  little,  with  some 
“Pizza  Terra  Typecasting.”  (See  my  May 
1989  column  for  an  explanation  of  that 
peculiar  reference  .  .  .  .  )  Try  this  in  either 
Listing  One  or  Listing  Two,  again,  after 
the  assignment  of  KidLink  to  Link. 

Writeln(SonPtr(Link)A. Girlfriends); 

This  time  it  works,  both  from  a  compile¬ 
time  and  a  run-time  perspective.  Cast¬ 
ing  Link  (a  FatherPtr)  onto  a  SonPtr 
lets  the  compiler  check  and  see  that, 
yes,  there  really  is  a  Girlfriends  field 
associated  with  the  pointer  in  ques¬ 
tion.  All  of  the  usual  dangers  of  type¬ 
casting  apply.  As  always,  do  what  you 
must;  just  know  what  you’re  doing. 

Typecasting  used  in  this  way  kills 
the  magic  of  polymorphism,  in  that 
what  we’re  doing  is  peeking  behind 
the  Father  mask  to  see  the  Son  hiding 
there,  and  acting  on  that  knowledge. 
Theoretically,  we  aren’t  supposed  to 
know  the  type  of  the  object  “behind” 
a  polymorphic  assignment.  However, 
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if  we  want  to  make  use  of  elements 
specific  to  the  actual  type  of  the  object, 
peeking  is  our  only  recourse. 

Typecasting  your  way  around  poly¬ 
morphic  type-blindness  can  get  you 
out  of  some  tight  corners  on  occasion. 
One  way  to  avoid  typecasting  is  to 
migrate  fields  and  methods  “up”  the 
hierarchy  so  that  all  classes  within  a 
domain  share  all  fields  and  methods, 
even  if  the  fields  are  not  used  and  the 
methods  are  empty  in  the  more  general 
classes.  In  our  simple  example,  this 
would  mean  giving  the  Girlfriends  field 
to  Father  and  letting  Son  inherit  it,  just 
as  is  done  with  the  Age  field.  Better 
still,  (and  at  the  risk  of  sounding  a  little 
too  Eastern)  let  the  son  be  a  son  while 
he  is  a  Son,  but  when  he  is  playing 
Father  let  him  leave  his  girlfriends  at 
home  .... 

Programmer's  Productivity  Pack 

I’ll  never  forget  the  rush  of  loading 
Sidekick  for  the  first  time  back  in  1984, 
and  seeing  a  calculator  that  worked  in 
hex.  No  more  fiddling  on  paper  and 
machine  gun  bashing  on  my  ancient 
SR10.  Sidekick  changed  the  way  I  ap¬ 
proached  certain  things  in  program¬ 
ming,  because  there  was  no  longer  any 
need  to  avoid  working  in  pure  hex  or 
even  binary. 

The  notion  of  memory  resident  tools 
took  off  with  Sidekick,  but  mostly  to¬ 
ward  the  users  —  DOS  shells  to  make 
picking  files  easier,  things  like  that.  It’s 
nice  to  find  an  occasional  TSR  tool  that 
won’t  do  the  users  a  damned  bit  of 
good.  Such  a  one  is  Falk  Data  Systems’ 
Programmer’s  Productivity  Pack  (PPP). 

The  PPP  is  a  loose  collection  of  use¬ 
ful  gadgetry  centering  on  a  world-class 
programmer’s  calculator  with  four  memo¬ 
ries  and  a  full  set  of  bit-wise  logical 
operators,  including  AND,  OR,  NOT, 
XOR,  shifts,  and  rotates.  The  binary 
display  field  allows  you  to  set  individ¬ 
ual  bits  rather  than  enter  31  digits  just 
to  set  the  MSB  to  1.  Values  are  dis¬ 
played  simultaneously  in  binary,  hex, 
decimal,  and  (gakkh!)  octal. 

The  calculator  is  good,  but  the  most 
innovative  gadget  in  the  PPP  is  a  sort 
of  empirical  keyboard  reference  screen 
that  displays  the  scan  codes  of  any  key 
combination  you  can  press  on  the  key¬ 
board.  If  you  need  to  look  up  the  scan 
code  for  a  key  combination,  don’t  bother 
with  a  book;  just  press  the  key  combi¬ 
nation  —  and  you’ll  get  the  scan  code. 
As  a  bonus,  attached  to  certain  key 
combinations  are  helpful  notes  indicat¬ 
ing  whether  certain  PC-family  BIOS  ver¬ 
sions  do  or  don’t  recognize  a  given  key 
combination.  Key  code  information  is 
also  given  for  the  dBase  data  base  and 
dBase  compatible  languages  such  as 


Clipper  and  Quicksilver,  along  with 
helpful  notes  such  as  pointing  out  that 
dBase  and  friends  consider  the  Ctrl-\ 
and  FI  keys  to  be  identical. 

The  shift  and  lock  keys  are  also  dis¬ 
played  as  the  bit  patterns  they  really 
are.  Beats  thumbing  through  some  tech 
ref  manual  any  day.  Other  details  are 
right  on:  Redefinition  of  PPP’s  several 
hotkey  assignments,  the  ability  to  un¬ 
load  the  utility  from  memory  on  com¬ 
mand,  an  unusually  readable  manual, 
and  a  superb  paper  (!)  ASCII  code  chart 
that  I  have  framed  on  the  wall  beside 
the  machine.  There’s  more  to  it  but  I’m 
out  of  space  at  this  point.  Highly  rec¬ 
ommended. 

Memory  Hog  Heaven 

This  is  a  good  time  to  be  a  program¬ 
mer.  Tom  Swan’s  newest  book,  Master¬ 
ing  Turbo  Pascal  5-5  is  on  the  streets; 
finally  something  good  in  print  about 
objects.  Eighty  nanosecond,  1-Mbyte 
SIMMS  are  down  to  about  $125  if  you 
shop;  by  the  time  you  read  this  they 
could  be  at  $100.  You  can  get  a  20- 
MHz  386  system  with  4  Mbytes  of  RAM 
for  about  $2500.  With  Windows/386 
you  can  load  Turbo  Pascal,  QuickPas- 
cal,  PageMaker,  and  Paradox  each  into 
its  own  virtual-86  partition  and  carom 
from  one  to  another  like  a  rock  off  a 
canyon  wall.  Software  development  is 
more  than  just  code;  it’s  also  data  dic¬ 
tionary  management  and  documenta¬ 
tion.  With  Windows/386,  you  can  build 
your  own  dream  system  for  creating 
that  ultimate  app. 

Good  old  days?  We’re  here,  guys. 
Really. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  158.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  11. 
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LOCATION  IS  EVERYTHING 


Listing  One  (Text  begins  on  page  124.) 


-  LOCATE. C  - 

Copyright  (C)  1989  by  Mark  R.  Nelson 
Program:  LOCATE. C 
Author:  Mark  R.  Nelson 

Summary:  LOCATE  reads  in  MS-DOS  formate  EXE  files  and  writes 
out  relocated  code  in  Intel  Hex  format.  The  code 
segment  is  relocated  to  start  at  F000:0000.  Data 
is  relocated  to  start  at  0040:0000. 


♦include  <stdio.h> 
♦include  <stdlib.h> 


if  (verbose) 

print_header ( ) ; 

image_offset=header .size_of_header_in_paragraphs*16; 

image_size  =  (header . file_size_in_pages-l) *512; 

image_size  -=  image_offset; 

image_size  +=  header . image_length_mod_512; 

if  (image_size  >  OxFFFFL) 

fatal_error ("The  EXE  image  is  larger  than  I  can  handle!"); 
f irst_data_segment_in_exe_file=header .disp_of_stack_in_paragraphs; 


-  read_input  — 

This  routine  reads  the  code  image  into  a  buffer.  Any  trouble  with 
the  buffer  or  the  file  generates  a  fatal  error. 


♦define  TRUE  1 
♦define  FALSE  0 


struct  exe  header 


unsigned  int  signature; 

unsigned  int  image_length_mod_512; 

unsigned  int  file_size_in_pages; 

unsigned  int  num_of_relocation_table_items; 

unsigned  int  size_of_header_in_paragraphs; 

unsigned  int  min_num_of_paragraphs_required; 

unsigned  int  max_num_of_paragraphs_required; 

unsigned  int  disp_of_stack_in_paragraphs; 

unsigned  int  initial_sp; 

unsigned  int  word_checksum; 

unsigned  int  initial_ip; 

unsigned  int  disp_of_code_in_paragraphs; 

unsigned  int  disp_of_relocation_table; 

unsigned  int  ove rlay_n umber ; 

}  header; 

FILE  *exe_file; 

FILE  *hex_file; 

unsigned  char  *image; 

unsigned  long  int  image_size; 

unsigned  long  int  image_offset; 

unsigned  long  first_data_segment_in_exe_file; 

int  verbose=TRUE; 

unsigned  int  output_base_code_segment=0xF000; 
unsigned  int  output_base_data_segment=0x0040; 

main (int  argc,char  *argv[]) 

1 

printf ("Locate  1.0  Copyright  (C)  1989  by  Mark  R.  NelsonXn"); 


open_files (argc,  argv)  ; 
read_header_data ()  ; 
read_input ( ) ; 

process_relocation_table () ; 
dump_output () ; 
output_restart_code ( )  ; 
output_intel_hex (0, 0, 1,  NULL) ; 


/*  Open  the  input  and  output  files 
/*  Read  in  the  EXE  file  header 
/*  Read  the  code  image  into  a  buffer 
/*  Relocate  all  segment  references 
/*  Write  the  code  image  to  the  HEX  file 
/*  Write  the  restart  code  line 
/*  Output  an  EOF  record 


-  open_files  - 

This  routine  opens  an  EXE  file  and  a  HEX  file.  If  they  are  specified 
on  the  command  line,  those  names  are  used.  Otherwise  the  user  is 
prompted  for  file  names 


read_input () 

{ 

image=malloc (image_size) ; 
if  (image==NULL) 

fatal_error ( "Couldn' t  allocate  output  image  space!"); 
if  ( f seek (exe_file, image_off set, SEEK_SET)  !=  0) 

fatal_error ("Couldn't  seek  to  image  in  the  input  file!"); 
if  ( f read ( image, 1, (int) image_size, exe_file)  !=  (int) image_size) 
fatal_error ("Couldn' t  read  in  the  image!"); 


**  -  process_relocation_table  - 

**  This  routine  loops  through  all  of  the  entries  in  the  relocation 

**  table.  Each  entry  points  to  a  segment  value  in  the  code  image. 

**  That  segment  value  is  checked  to  see  if  it  points  to  code  or 
**  data.  If  it  points  to  data,  .it  is  relocated  to  start  at  the 

**  output_base_data_segment .  Code  segments  are  relocated  to  start 

**  at  output_base_code_segment . 

process_relocation_table () 

( 

int  i; 

unsigned  int  reloc [2]; 
unsigned  long  int  spot; 
unsigned  int  *guy; 
unsigned  int  old_value; 
unsigned  int  new_value; 

fseek (exe_file, (long) header .disp_of_relocation_table, 0) ; 
for  (i=0;i<header .num_of_relocation_table_items; i++) 

( 

if  (fread(reloc,2,2,exe_file)  !=  2) 

fatal_error ("Couldn' t  read  relocation  data  from  file!"); 
printf ("Record  %3d:  %04X: %04X: ", i, reloc [1] , reloc[0] ) ; 

spot=reloc (1] *16  +  reloc [0]; 
old_value=* (int  *) (image+spot) ; 
printf ("  was:  %04X",  old_value); 
if  (old_value  <  f irst_data_segment_in_exe_f ile) 
new_value=old_value+output_base_code_segment; 
else 

new_value=old_value- 

f irst_data_segment_in_exe_f ile+output_base_data_segment; 

Mint  *) (image+spot) =new_value; 
printf ("  now  is:  %04X\r",  new_value) ; 

) 

printf ("\n")  ; 


open_files (int  argc, char  *argv[]) 

{ 

char  exe_file_name[81] ; 
char  hex_file_name [81] ; 

if  (argc>l) 

strcpy (exe_file_name, argv[l] ) ; 

else 


-  dump_output  - 

This  routine  loops  the  entire  code  image.  It  outputs  34  bytes 
at  a  time  in  Intel  Hex  format  until  it  is  done.  While  it  is 
doing  this  it  keeps  the  user  posted  by  writing  the  addresses 
to  the  screen.  Note  that  this  module  would  need  some  modifications 
to  handle  images  greater  than  64K. 


printf ("EXE  file  name?  "); 
scanf ("%s" ,exe_file_name) ; 


exe_file=fopen (exe_file_name, "rb") ; 
if  (exe_file==NULL) 

fatal_error ("Had  trouble  opening  the  input  file!"); 
if  (argc  >  2) 

strcpy (hex_file_name, argv [2] ) ; 

else 


printf ("Hex  file  name?  "); 
scanf ("%s", hex  file  name) ; 


hex_file=fopen (hex_file_name, "w") ; 
if  (hex_file==NULL) 

fatal_error ("Had  trouble  opening  the  output  file!"); 


**  - read_header_data - 

**  This  routine  reads  in  the  EXE  header  structure  and  computes  both 
**  the  image  offset  and  size.  The  compuataions  are  all  done  using 
**  numbers  found  in  the  header.  This  program  arbitrarily  limits 
**  the  code  image  size  to  64K,  but  could  easily  be  expanded  to  go 
**  to  larger  sizes. 

read_header_data () 


dump_output ( ) 

{ 

unsigned  char  *output_pointer; 
long  int  output_size; 
int  record_size; 
unsigned  int  output_address; 
unsigned  char  segment_address (2] ; 

output_pointer=image; 
output_s i ze=image_s i ze ; 
output_address=0; 

segment_address  [  0  ]  =output_base_code_segment»8  ; 
segment_address [l]=output_base_code_segment  &  Oxff; 
output_intel_hex (2, 0, 2, segment_address) ; 
while  (output_size  >  0) 

I 

printf ("%04X\r", output_address) ; 

record_size= (output_size  >34)  ?  34  :  output  size; 

output_intel_hex (record_size, output_address,  0, output_pointer) ; 

output_pointer  +=  record  size; 

output_size  -=  record_size; 

output_address  +=  record  size; 

} 

printf ("\n") ; 


-  output_restart_code  - 

This  routine  writes  a  JMP  START  instruction  out  at  location 
at  FFFF:0000.  The  address  of  START  is  contained  in  the  EXE 
header  block. 


if  (f read (&header, sizeof (struct  exe_header) , l,exe_file)  !=  1) 
fatal_error ("Couldn' t  read  header  from  file!"); 


output_restart_code () 
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unsigned  char  jmp_code[5]; 
unsigned  char  segment_address [2] ; 

segment_address [0] =0xf f  ; 

segment_address [1] =0xff ; 

output_intel_hex (2, 0, 2, segment_address) ; 

jmp_code [0] =0xea;  /*  JMP  ????:???? 

jmp_code[l]=header.initial_ip  &  Oxff; 

jmp_code[2]=header.initial_ip  »  8; 

header. disp  of  code  in_paragraphs  +=  output_base_code_segment; 
jmp_code [3]=header .disp_of_code_in_paragraphs  &  Oxff; 
jmp_code [ 4 ] =header . disp_of_code_in_paragraphs  »  8  ; 
header .disp_of_code_in_paragraphs  -=  output_base_code_segment; 
output_intel_hex (5, 0,0, jmp_code) ; 

) 


-  output_intel_hex  - 

This  routine  writes  a  single  record  of  Intel  Hex. 


output_intel_hex (int  size, unsigned  int  address, int  type, unsigned  char  buffer[]) 

{ 

int  checksum; 
int  i; 


larger  than  the  END_OF_ROM  segment . 


TEXT 

SEGMENT 

BYTE 

PUBLIC 

'CODE' 

TEXT 

ENDS 

END  OF  ROM 

SEGMENT 

PARA 

PUBLIC 

' STARTUP_CODE' 

END  OF  ROM 

ENDS 

CONST 

SEGMENT 

PARA 

PUBLIC 

'CONST' 

CONST 

ENDS 

3SS 

SEGMENT 

WORD 

PUBLIC 

'BSS' 

BSS 

ENDS 

DATA 

SEGMENT 

WORD 

PUBLIC 

' DATA' 

DATA 

ENDS 

_STACK 

SEGMENT 

WORD 

STACK  1 

'STACK' 

MY STACK 

DB  512  DUP  (' 

?) 

_STACK 

ENDS 

;  Note  here  that  if  DGROUP  does  not  contain  the  stack,  which  may 
;  be  true  for  larger  models,  the  STACK  segment  needs  to  be  moved 
;  to  be  the  first  one  after  END_OF_ROM. 

DGROUP  GROUP  _CONST,_BSS,_DATA,_STACK 

extrn  main: far 


fprintf (hex_file, " :%02X%04X%02X", size, address,  type)  ; 
checksum=size+address+  (address»8)  +type; 
for  (i=0;i<size;i++) 

{ 

fprintf (hex_f ile, "%02X", buffer [i] ) ; 
checksum  +=  buffer [ij; 

} 

checksum  =  -checksum  &  Oxff; 
fprintf (hex_file, "%02X\n", checksum) ; 


-  print_header  - 

This  is  a  routine  that  lets  the  program  print  out  the  contents 
of  the  header.  It  is  here  primarily  for  assistance  in  debugging. 


print_header () 

1 

printfC'Link  program  signature: 

printf ("%4 .4X\n", header. signature) ; 

printf ("Length  of  image  mod  512: 

printf ( "%4 . 4X\n" , header . image_length_mod_512)  ; 

printf ("Size  of  file  in  512  byte  pages,  including  header: 

printf ("%4 .4X\n", header . f ile_size_in_pages) ; 

printf ("Number  of  relocation  table  items: 

printf ("%4 .4X\n", header .num_of_relocation_table_items) ; 

printf ("Size  of  header  in  16  byte  paragraphs: 

printf ("%4 .4X\n", header .size_of_header_in_paragraphs) ; 

printf ("Minimum  #  of  16  byte  paragraphs  needed  above  program: 

printf ("%4 . 4X\n" , header .min_num_of_pa ragr aphs_requi red) ; 

printf ("Maximum  #  of  16  byte  paragraphs  needed  above  program: 

printf ( "%4 . 4X\n" , header .max_num_of_paragraphs_required) ; 

printf ("Displacement  of  stack  within  load  module  in  paragraphs: 

printf ( "%4 . 4X\n" , header .disp_of_stack_in_paragraphs) ; 

printf ("Offset  to  be  loaded  in  SP: 

printf ("%4.4X\n", header. initial_sp) ; 

printf ("Word  checksum: 

printf ("%4.4X\n", header. word_checksum) ; 

printf ("Of fset  to  be  loaded  in  IP: 

printf ("%4.4X\n", header. initial_ip) ; 

printf ("Displacement  of  code  segment  in  16  byte  paragraphs: 
printf ("%4 . 4X\n",  header .disp_of_code_in_paragraphs) ; 
printf ("Displacement  of  1st  relocation  table  item: 
printf ( "%4 . 4X\n" , header . disp_of_relocation_table) ; 
printf ("Overlay  number: 
printf ("%4.4X\n", header. overlay_number) ; 


-  fatal_error 

A  self-documenting  utility. 


/ 


") 

") 

") 

") 

") 

") 


") 

") 


") 

") 

") 

") 

") 


fatal_error (char  ‘message) 

{ 

printf (message)  ; 
exit  (1)  ; 

) 


public  _ acrtused 

acrtused  =  9876h 


;This  value  makes  many  of  the 
; library  routines  happy 


END  OF_ROM  SEGMENT  PARA  PUBLIC  'STARTUP  CODE' 


ASSUME  CS : END_OF_ROM 
PUBLIC  START 


START  PROC  FAR 


MOV 

AX, DGROUP 

;This  code  initializes  the 

MOV 

SS,  AX 

;SS:SP  pair  with  the  proper 

MOV 

SP, OFFSET  MYSTACK+512  ; values. 

;  This 

section  cf  code 

is  charged  with  i 

moving  all  predefined  values  out 

;  of  ROM  and  into  RAM. 

This  is  done  by 

copying  all  values  out  of  the 

part 

of  ROM  immediately  following  the 

last  code  segment  into  the 

data 

section. 

MOV 

AX,  CS 

;The  present  code  segment  is  the 

ADD 

AX,  3 

;last  code  segment,  and  we  know 

MOV 

DS,  AX 

;that  the  first  data  segment  will 

;be  three  up  form  here.  Put  that 

; value  into  DS 

MOV 

AX, DGROUP 

;Now  set  ES  to  point  to  the  first 

MOV 

ES,  AX 

; section  of  RAM. 

XOR 

SI, SI 

;SI  and  DI  are  the  registers 

XOR 

DI,DI 

;used  in  the  MOVSB  instruction. 

MOV 

CX, OFBFFH 

;This  rep  instruction  will  fill 

REP 

MOVSB 

everything  in  a  64K  RAM  following 

;the  interrupt  vector  space. 

MOV 

AX,  ES 

;Now  set  up  DS  to  point  to  DGROUP 

MOV 

DS,  AX 

STI 

; Enable  interrupts  and  the  jump 

JMP 

main 

;to  the  start  of  the  C  code 

START 

ENDP 

END_OF_ROM  ENDS 

END  START 


End  Listing  Two 


Listing  Three 


-  HELLO. C  - 

Copyright  (C)  1989  by  Mark  R.  Nelson 
Program:  HELLO. C 
Author:  Mark  R.  Nelson 

Summary:  Hello  demonstrates  the  LOCATE  program.  It  simulates 
output  of  a  string  to  a  printer  on  an  embedded  system. 


End  Listing  One 


main  () 
{ 


Listing  Two 


my _print ("Hello,  world! \n" ) ; 
while  (1)  ; 


Module : 
Author: 
Summary: 


-  START. ASM  - 

Copyright  (C)  1989  by  Mark  R.  Nelson 
START. ASM 
Mark  R.  Nelson 

This  module  is  an  alternate  startup  routine  for  Microsoft 
or  Turbo  C  programs  running  on  non  DOS  hardware.  It  has 
three  main  jobs.  First,  it  sets  up  the  segment  definitions 
so  that  the  STACK  segment  is  the  first  segment  in  RAM. 
Second,  it  initializes  all  predefined  data.  Third,  it  jumps 
to  the  user's  main()  routine. 


Note  here  that  if  DGROUP  does  not  contain  the  stack,  which  may 
be  true  for  larger  models,  the  STACK  segment  needs  to  be  moved 
to  be  the  first  one  after  END_OF_ROM. 

Also  note  that  for  the  startup  code  to  work  properly,  the  first 
segment  in  the  data  area  must  be  paragraph  aligned.  This  insures 
that  for  the  startup  code,  the  first  data  segment  is  exactly  3 


my_print (char  ‘message) 

while  (‘message) 

( 

if  (*message==' \n' ) 

{ 

while  ( (inportb(0x200)  &  0x80)  ==  0) 
outportb (0x200, ' \r' ) ; 

) 

while  ( (inportb (0x200)  &  0x80)  ==  0)  ; 
outportb (0x200, *message++) ; 

) 

} 


End  Listings 
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153 


C  PROGRAMMING 


Listing  One  (Text  begins  on  page  132.) 

/* - textsrch.h - */ 

#define  OK  0 
♦define  ERROR  !0K 

#define  MXTOKS  25  /*  maximum  number  of  tokens  */ 

tdefine  MAXFILES  512  /*  maximum  number  of  files  */ 

tdefine  MAPSIZE  MAXFILES/16  /*  number  of  ints/map  */ 

/*  -  the  search  decision  bitmap  (one  bit  per  file)  -  */ 

struct  bitmap  { 

int  map [MAPSIZE] ; 

}; 


/*  -  the  postfix  expression  structure  -  */ 

struct  postfix  { 

char  pfix;  /*  tokens  in  postfix  notation  */ 

char  *pfixop;  /*  operand  strings  */ 

} ; 


/* - the  postfix  stack - */ 

extern  struct  postfix  pftokens[]; 
extern  int  xp_offset; 

/*  -  expression  token  values  -  */ 

♦define  TERM  0 
#define  OPERAND  '0' 

♦define  AND 
♦define  OR  '  ! ' 

♦define  OPEN  '  (' 

♦define  CLOSE  ')' 

♦define  NOT  '  ! ' 

♦define  QUOTE 

/* - textsrch  prototypes - */ 

struct  postfix  *lexical_scan (char  *expr) ; 

struct  bitmap  exinterp (void) ; 

void  init_database (void)  ; 

struct  bitmap  search (char  *word) ; 

void  process_result (struct  bitmap); 

End  Listing  One 

Listing  Two 

/* - exinterp. c -  */ 

/* 

*  An  expression  interpreter  that  processes  the 

*  tokens  on  a  postfix  stack. 

*/ 


♦include  "textsrch.h" 

static  struct  postfix  *pf  =  pftokens; 

static  struct  bitmap  pop (void); 

static  struct  bitmap  not (struct  bitmap  mapl); 

static  struct  bitmap  and(struct  bitmap  mapl,  struct  bitmap  map2); 
static  struct  bitmap  or(struct  bitmap  mapl,  struct  bitmap  map2); 

/*  -  entry  to  the  interpreter 

returns  a  bitmap  which  indicates  the  files 

that  match  a  search  expression  -  */ 

struct  bitmap  exinterp (void) 

{ 

/* - find  the  top  of  the  postfix  stack - */ 

while  (pf->pfix  !=  TERM) 
pf++; 

/* - get  the  result  of  the  expression - */ 

return  pop(); 


/*  pops  an  operand  and  converts  it  to  a  bit  map  -  */ 

static  struct  bitmap  pop (void) 

( 

struct  bitmap  mapl; 

switch  ( (--pf ) ->pfix)  { 
case  OPERAND: 

mapl  =  search (pf->pfixop) ; 
break; 
case  NOT: 

mapl  =  not (pop() ) ; 
break; 
case  AND: 

mapl  =  and (pop (),  pop()); 
break; 
case  OR: 

mapl  =  or  (pop  () ,  pop() )  ; 
break; 
default : 
break; 

I 

return  mapl; 


/* - unary  <not>  operator -  */ 

static  struct  bitmap  not  (struct  bitmap  mapl) 

( 

int  i; 

for  (i  =  0;  i  <  MAPSIZE;  i++) 
mapl. map [i]  =  “mapl .map [i] ; 
return  mapl; 
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{ 


/* - binary  <and>  operator - */ 

static  struct  bitmap  and (struct  bitmap  mapl,  struct  bitmap  map2) . 

( 

int  i; 

for  (i  =  0;  1  <  MAPSIZE;  i++) 
mapl. map [i]  &=  map2 .map[i] ; 
return  mapl; 

} 

/* - binary  <or>  operator - */ 

static  struct  bitmap  or (struct  bitmap  mapl,  struct  bitmap  map2) 

{ 

int  i; 

for  (i  =  0;  i  <  MAPSIZE;  i++) 
mapl.map[i]  !=  map2.map[il ; 
return  mapl; 

J 

End  Listing  Two 


Listing  Three 

/* - search. c - */ 

/* 

*  stub  functions  to  simulate  the  TEXTSRCH  retrieval  process 
*/ 

#include  <stdio.h> 

((include  <dir.h> 

((include  <string.h> 

((include  <process.h> 

((include  "textsrch.h" 

static  char  names [MAXFILES] [13] ; 
static  int  namect; 

static  void  setbit (struct  bitmap  *mapl,  int  bit); 
static  int  getbit (struct  bitmap  *mapl,  int  bit); 

/* - initialize  the  data  base  environment - * / 

void  init_database (void) 

( 

struct  ffblk  ff; 
int  rtn; 

rtn  =  findfirst ("* .txt",  &ff,  0) ; 
while  (rtn  !=  -1  &&  namect  <  MAXFILES)  ( 
strcpy (names [namect++] ,  ff . f f_name) ; 
rtn  =  f indnext (&f f ) ; 


/* - search  the  data  base  for  a  match  on  a  word - */ 

struct  bitmap  search (char  *word) 


int  i; 

FILE  *fp; 
char  str [80] ; 
struct  bitmap  mapl; 

for  (i  =  0;  i  <  MAPSIZE;  i++) 
mapl. map [i]  =0; 

sprintf(str,  "grep  -1  -i  %s  *.txt  >hits",  word); 
system(str); 

if  ( ( f p  =  fopen ("hits",  "rt") )  !=  NULL)  ( 
while  (fgets(str,  80,  fp)  !=  NULL)  ( 
*strchr(str,  ':')  =  '\0'; 
for  (i  =  0;  i  <  MAXFILES;  i  ++)  ( 

if  (stricmp (str+5,  names [i])  ==  0)  ( 

setbit (&mapl,  i); 
break; 

) 

) 

) 

fclose (fp) ; 

) 

return  mapl; 


/*  -  process  the  result  of  a  query  expression  search  -  */ 

void  process_result (struct  bitmap  mapl) 

I 

int  i; 

for  (i  =  0;  i  <  MAXFILES;  i++) 
if  (getbit (&mapl,  i)) 

print f  ("\n%s",  names [ i ] ) ; 

I 

/* - sets  a  designated  bit  in  the  bit  map - */ 

static  void  setbit (struct  bitmap  *mapl,  int  bit) 

( 

int  off  =  bit  /  16; 

int  mask  =  1  «  (bit  %  16); 

mapl->map[of f ]  !=  mask; 

) 

/* - tests  a  designated  bit  in  the  bit  map - */ 

static  int  getbit (struct  bitmap  *mapl,  int  bit) 

{ 

int  off  =  bit  /  16; 

int  mask  =  1  «  (bit  %  16); 

return  mapl->map[of f ]  &  mask; 

I  End  Listing  Three 


(Listings  continued  on  page  156) 
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C  PROGRAMMING 


Listing  Four  ( Listing  continued,  text  begins  on  page  132.) 

/* - textsrch.c - */ 

/* 

*  The  TEXTSRCH  program. 

*/ 

#include  <stdio.h> 

♦include  <process.h> 

♦include  <string.h> 

♦include  "textsrch.h" 

void  main (void) 

{ 

char  expr[80]; 

/* - initialize  the  text  data  base - */ 

init_database  () ; 
do  { 

/* - read  the  expression  from  the  console - */ 

printf ("\nEnter  the  search  expression : \n" ) ; 
gets  (expr) ; 
if  (*expr)  { 

/*  —  scan  for  errors  and  convert  to  postfix  —  */ 
if  (lexical_scan (expr)  ==  NULL)  { 

/*  -  the  expression  is  invalid  -  */ 

while (xp_of fset — ) 
putchar('  '); 
putchar  ('  A  / )  ; 
printf ("\nSyntax  Error"); 
exit  (1) ; 

) 

/*  —  interpret  the  expression,  search  the  data  base, 

and  process  the  hits - */ 

process_result (exinterp ( ) ) ; 

1 

)  while  (*expr); 

) 


End  Listings 
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STRUCTURED  PROGRAMMING 


Listing  One  (Text  begins  on  page  140.) 

Listing  Two 

PROGRAM  PolyTest;  {  For  QuickPascal  1.0  } 

PROGRAM  PolyTest;  {  For  Turbo  Pascal  5.5  ) 

(  BY  Jeff  Duntemann  } 

{  BY  Jeff  Duntemann  ) 

{  For  DDJ  1/90  ) 

(  For  DDJ  1/90  ) 

USES  Crt; 

USES  Crt; 

TYPE 

FatherPtr  =  "Father; 

TYPE 

Father  =  OBJECT 

FatherPtr  =  "Father; 

Age  :  Integer; 

Father  =  OBJECT 

PROCEDURE  Init; 

Age  :  Integer; 

PROCEDURE  Talk; 

CONSTRUCTOR  Init; 

END; 

PROCEDURE  Talk;  VIRTUAL; 

END; 

SonPtr  =  "Son; 

Son  =  OBJECT (Father) 

SonPtr  =  "Son; 

Girlfriends  :  Integer; 

Son  =  OBJECT (Father) 

PROCEDURE  Init;  OVERRIDE; 

Girlfriends  :  Integer; 

PROCEDURE  Talk;  OVERRIDE; 

CONSTRUCTOR  Init; 

END; 

PROCEDURE  Talk;  VIRTUAL; 

END; 

VAR 

Dad  :  Father; 

VAR 

Twerp  :  Son; 

Dad  :  Father; 

Person  :  Father; 

Twerp  :  Son; 

Link  :  FatherPtr; 

Person  :  Father; 

KidLink  :  SonPtr; 

Link  :  FatherPtr; 

KidLink  :  SonPtr; 

PROCEDURE  Father. Init; 

CONSTRUCTOR  Father. Init; 

BEGIN 

Self. Age  :=  42; 

BEGIN 

END; 

Age  :=  42; 

END; 

PROCEDURE  Father. Talk; 

PROCEDURE  Father. Talk; 

BEGIN 

Writeln('This  is  the  old  man  talking.'); 

BEGIN 

END; 

Writeln ('This  is  the  old  man  talking.'); 

END; 

PROCEDURE  Son. Init; 

CONSTRUCTOR  Son. Init; 

BEGIN 

Self. Age  :=  11; 

BEGIN 

Self .Girlfriends  :=  5; 

Age  : =  11; 

END; 

Girlfriends  :=  5; 

END; 

PROCEDURE  Son. Talk; 

PROCEDURE  Son. Talk; 

BEGIN 

Writeln('Cool  it,  daddy-o!'); 

BEGIN 

END; 

Writeln ('Cool  it,  daddy-o!'); 

END; 

BEGIN 

ClrScr; 

BEGIN 

ClrScr; 

New (Dad);  {  These  three  statements  allocate  the  objects  on  the  heap  ) 

New (Twerp) ; 

Dad. Init;  {  Type  Father  ) 

New (Person) ; 

Twerp. Init;  f  Type  Son  ) 

Person. Init;  {  Type  Father  } 

Dad. Init;  {  Type  Father  } 

Twerp. Init;  (  Type  Son  } 

Person. Init;  (  Type  Father  } 

(  The  following  does  not  work  polymorphically  in  Turbo  Pascal:  } 

{  The  following  works  polymorphically  in  QuickPascal  but  not  Turbo:  ) 

Person  :=  Twerp;  (  The  assignment  is  kosher  to  the  compiler...) 

Person. Talk;  {  ...but  polymorphism  does  NOT  work  here...  ) 

Person  :=  Twerp;  {  Assign  a  Son  object  to  a  Father  object  ) 

{  ...and  Dad  speaks  instead  of  the  kid.  } 

Person. Talk;  (  Polymorphism  allows  the  Son. Talk  method  to  be  ) 

Writeln (' Person"  s  age  is:  ' , Person. Age) ; 

{  executed  from  Person,  which  is  type  Father  ) 

Readln; 

Writeln (' Person' ' s  age  is:  ', Person. Age) ;  (  Check  the  age  on-screen!  } 

Readln; 

{  This,  on  the  other  hand,  works  polymorphically  as  it  should:  } 

(  Working  through  pointers  works  with  either  Turbo  or  Quick  Pascal:  } 

Link  :=  @Dad;  {  Link  is  defined  as  a  FatherPtr  ) 

Link". Talk;  (  Dad  speaks  here...  } 

Link  :=  @Dad;  (  Link  is  defined  as  a  "Father  } 

Link". Talk;  {  Dad  speaks  here...  ) 

KidLink  :=  @Twerp;  (  Twerp  is  type  Son  } 

Link  :=  KidLink;  {  Assign  a  SonPtr  to  FatherPtr  ) 

KidLink  :=  @Twerp;  {  Twerp  is  type  Son  ) 

Link". Talk;  (  Even  tho  Link  is  a  FatherPtr,  the  kid  talks  here.  } 

Link  :=  KidLink;  {  Assign  a  SonPtr  to  a  FatherPtr  ) 

Readln; 

Link". Talk;  {  Even  tho  Link  is  a  FatherPtr,  the  kid  talks  here.  ) 

Readln; 

END. 

END. 

End  Listing  One 

End  Listings 
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Overlay  Architect  and  Overlay  Op¬ 
timizer,  two  tools  that  manage  overlay 
structures,  have  been  released  by  At- 
Last!  Software.  According  to  AtLast!, 
Overlay  Architect  can  handle  more  than 
4000  modules  and  16,000  code  symbols, 
supports  libraries  and  object  modules, 
works  with  most  compilers,  produces 
nested  overlays  and  multiple  overlay  ar¬ 
eas,  supports  indirect  calls,  detects  un¬ 
used  functions  and  modules,  supports 
multiple  entry  points,  as  well  as  full  use 
of  the  Plink86plus  TRACK  command. 
The  company  claims  that  this  will  re¬ 
sult  in  the  smallest  possible  executable 
program  size  by  using  nested  overlays 
and  multiple  overlay  areas;  on  a  386,  a 
program  consisting  of  a  megabyte  of 
code  in  a  thousand  modules  can  be 
analyzed  by  Overlay  Architect  in  less 
than  three  minutes. 

Overlay  Optimizer  analyzes  the  per¬ 
formance  of  a  program’s  overlay  struc¬ 
ture  and  determines  how  overlays  should 
be  rebuilt  for  optimal  performance.  It 
requires  a  Plink86plus  map  file  and  the 
debug  output  of  the  sample  debug  run 
of  a  program;  you  specify  the  size  to 
which  your  program  can  grow,  and  Over¬ 
lay  Optimizer  creates  a  link  response 
file  that  reflects  the  new  overlay  struc¬ 
ture.  It  is  a  two-step  process:  You  first 
have  to  run  your  program  with  the  de¬ 
bugging  version  of  the  Plink86plus  over¬ 
lay  loader,  and  then  run  Overlay  Op¬ 
timizer.  The  Architect  and  Optimizer  can 
be  purchased  together  for  $569,  or  sepa¬ 
rately  for  $369  and  $269,  respectively. 
Reader  service  no.  20. 

AtLast!  Software,  Inc. 

449  Mountain  View  Road 
Boulder,  CO  80302 
303-938-1210 

A  monitor  called  the  “DB-51  Enhanced 
System  Monitor,”  for  8051/31-and  80515/ 
535-based  single  board  computers,  has 
been  released  by  Allen  Systems.  This 
monitor  allows  for  development  and 
debugging  of  user  software  right  on  the 
target  8051  hardware.  It  supports  a  com¬ 
mand  set  to  facilitate  user  operation. 
The  monitor  is  EPROM-resident,  and  can 
be  directly  installed  into  the  user  hard¬ 
ware.  After  object  code  output  is  down¬ 
loaded  from  the  host  into  RAM  on  the 
target  system  under  DB-51  control,  the 


host  is  configured  as  a  terminal  that 
allows  the  user  direct  access  to  the  DB- 
51  and  its  available  commands  for  de¬ 
bugging  and  testing. 

In  addition  to  the  command  set,  DB- 
51  also  features  the  routing  of  interrupt 
service  routines  through  external  RAM, 
and  line-oriented  command  entry  which 
allows  simple  command-line  editing  prior 
to  command  processing.  In  addition,  DB- 
51  display  information  can  be  suspended, 
resumed,  and  aborted.  And  upon  in¬ 
itialization,  the  DB-51  checks  the  target 
hardware  and  then  configures  itself  for 
optimum  resource  utilization. 

In  addition  to  the  software  and  user’s 
manual,  a  listing  of  the  DB-51  source 
is  also  available  on  hardcopy  and  on 
disk.  It  sells  for  $100.  Reader  service 
no.  21. 

Allen  Systems 
2346  Brandon  Rd. 

Columbus,  OH  43221 
614-488-7122 

Tronix  has  released  a  Unix/Xenix  Ker¬ 
nel  Debugger  (KDB).  The  symbolic  de¬ 
bugger  runs  on  SCO’s  System  V/386 
and  Xenix/386,  Interactive  Systems’  386/ 
IX,  Everex’s  Enix,  and  AT&T’s  System 
V,  Release  3.2.  According  to  Benjamin 
Chou,  president,  it  is  “designed  to  let 
the  Unix/Xenix  system  software  engi¬ 
neer  easily  control  the  execution  and 
environment  of  software  within  the 
Unix/Xenix  operating  system.”  The 
Tronix  Kernel  Debugger  enables  pro¬ 
grammers  to  set  break  point  at  data 
address(es),  trace  any  process’s  stack, 
display  data  in  a  predefined  data  struc¬ 
ture  format,  display  and  modify  code 
and  data,  single  step  through  code, 
display  information  about  all  the  pro¬ 
cesses  that  are  running,  and  display 
and  modify  registers,  all  within  the  Unix/ 
Xenix  kernel. 

Tronix  KDB  requires  150K-bytes  from 
hard  disk  during  installation,  and  after¬ 
wards  the  new  kernel’s  size  is  about 
120K-bytes  larger  than  a  regular  ker¬ 
nel.  The  product  sells  for  $475,  and 
source  code  and  a  free  demonstration 
disk  are  also  available.  Reader  service 
no.  22. 

Tronix  International 

10601  S.  DeAnza  Blvd.,  Ste.  216 

Cupertino,  CA  95014 

408-973-8559 

Microsystems  Software  has  an¬ 
nounced  CodeRunneR,  a  highly-opti¬ 
mized  library  for  creating  fast,  compact 
TSR  programs  with  full  DOS  access, 
using  Borland’s  Turbo  C  and  Microsoft 
C.  Users  can  supposedly  create  C  pro¬ 
grams  on  a  performance  and  code  size 
par  with  assembly  language  at  a  frac¬ 
tion  of  the  development  time  and  cost. 


Developers  can,  says  president  J.  Scott 
Benson,  “stay  with  high-level  languages 
like  C,  and  yet  produce  very  tight  code 
that  can  still  fit  their  user’s  systems.” 

Among  CodeRunneR’s  features  are 
the  elimination  of  initialization  code 
and  data  when  programs  go  resident, 
a  function-level  granular  and  auto-in- 
itializing  run-time  library,  the  ability  to 
create  multitasking  programs,  a  BCD 
floating-point  package,  full  hotkey  sup¬ 
port,  transparent  DOS  access,  and  two 
levels  of  event  schedulers.  CodeRun¬ 
neR  lists  for  $149,  and  Microsystems 
offers  a  30-day  money-back  guarantee 
if  you  can  find  a  commercially-avail- 
able  C  library  that  delivers  smaller  or 
faster  run-time  code.  Reader  service 
no.  23. 

Microsystems  Software,  Inc. 

600  Worcester  Rd. 

Framingham,  MA  01701 
508-626-8511 

Andrews  Data  Systems  has  an¬ 
nounced  the  release  of  object  libraries 
for  Borland  Turbo  Pascal  5  5  and  Mi¬ 
crosoft  QuickPascal  1.0.  Both  products 
include  a  window  object  library  for 
text  and  graphics,  a  remote  object  sup¬ 
port  library  for  distributed  processing, 
and  a  concurrent  object  support  library 
for  multitasking  within  applications.  The 
remote  object  library  is  bundled  with 
a  serial  object  library  that  may  also  be 
purchased  separately. 

A  network  library  that  is  scheduled 
to  be  released  in  December  will  also 
support  the  distributed  processing  pro¬ 
vided  under  the  remote  object  library 
using  NetBIOS.  A  Novell  implementa¬ 
tion  is  slated  for  early  this  year,  and 
future  products  will  include  C++  object 
libraries.  Source  code  is  available  with 
all  products.  The  libraries  cost  $59  each, 
$89  with  source,  or  $149/$189  for  Win¬ 
dows/Remote/  Concurrent  combination. 
Both  compiler  versions  are  included 
in  each  library.  Reader  service  no.  27. 
Andrews  Data  Systems 
P.O.  Box  37123 
Denver,  CO  80237 
800-255-5550  ext.  615 

MetaWare  has  released  High  C  com¬ 
piler  Version  1.6  for  MS-DOS  and  386/ 
486DOS.  The  package  includes  Meta- 
Ware’s  High  C  compiler  for  OS/2  and 
real-mode  MS-DOS.  Version  1.6  fea¬ 
tures  expanded  libraries,  new  docu¬ 
mentation,  two  editors,  a  disk  cache 
utility,  a  b-tree  library,  and  a  graphics 
library  for  the  386/486  in  protected 
mode.  MetaWare’s  new  make  facility 
is  included,  as  well  as  a  set  of  Unix- 
style  utilities  for  the  MS-DOS  operating 
system.  This  upgrade  comes  with  the 
( continued  on  page  165) 
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(continued  from,  page  161) 

GFX/386  Graphics  library,  produced 
in  conjunction  with  C  Source,  which 
provides  specific  floating-point  graph¬ 
ics  functions.  High  C  also  includes  the 
EC  editor  from  C  Source,  HyperDisk 
disk  cache  from  HyperWare,  and  source 
code  for  the  MicroEMACS  editor. 

The  High  C  library  is  ANSI  confor¬ 
mant,  and  additional  library  functions 
bring  it  to  86  percent  compatibility  with 
Microsoft’s  C  libraries.  The  High  C  com¬ 
piler  also  provides  cross-language  call¬ 
ing,  diagnostics,  and  configurability.  Tog¬ 
gles  and  pragmas  allow  developers  to 
select  from  a  variety  of  compiler  fea¬ 
tures.  The  High  C  compiler  is  discussed 
in  the  two-part  article  “Stalking  General 
Protection  Faults”  by  Andrew  Schulman, 
which  begins  this  month  in  DDJ. 

Current  licensees  covered  by  the  tech¬ 
nical  support  program  can  upgrade  for 
free.  Users  of  Version  1.5  who  do  not 
have  this  policy  can  upgrade  for  $75 
on  the  8088,  80186,  and  80286;  the 
upgrade  for  the  80386  is  $150.  Other¬ 
wise,  the  product  is  licensed  for  $595 
for  DOS  and  $895  for  386/486DOS. 
Reader  service  no.  25. 

Meta  Ware  Inc. 

2161  Delaware  Avenue 
Santa  Cruz,  CA  95060-5706 
408-429-6382 

Sun  Microsystems  has  introduced 
GUIDE  (Graphical  User  Interface  De¬ 
sign  Editor),  a  design  tool  for  building 
an  Open  Look  graphical  user  interface 
for  applications.  The  GUIDE  prototyper 
is  an  interactive  tool  that  features  a 
palette  of  icons  that  represent  various 
objects,  such  as  window  control  func¬ 
tions,  scrollbars,  and  menus,  so  a  de¬ 
veloper  can  drop  an  icon  into  the  de¬ 
sired  location  instead  of  writing  new 
code.  GUIDE  automatically  generates 
the  user  interface  code,  which  can 
shorten  development  time.  And  appli¬ 
cations  designed  with  it  can  offer  “drag 
and  drop”  file  loading,  so  users  can 
select  an  icon  and  the  application  will 
automatically  load. 

The  GUIDE  prototyper  runs  on  Re¬ 
lease  4.X  of  the  SunOS  operating  sys¬ 
tem  on  the  XI  1/NeWS  window  system. 
GUIDE  media,  documentation,  and  a 
right-to-use  license  will  be  sold  un¬ 
bundled  for  $250,  and  will  be  available 
sometime  during  the  first  quarter  of 
1990.  Reader  service  no.  26. 

Sun  Microsystems,  Inc. 

2550  Garcia  Ave. 

Mountain  View,  CA  94043 
415-336-6536 

Invention  Software  has  released  the 
Extender  DialogHandler,  the  latest  ad¬ 
dition  to  their  development  series.  Dia¬ 


logHandler  includes  over  160  routines 
which  decrease  the  time  required  to 
program  modal  dialogs  with  complete 
functionality. 

DialogHandler  supports  the  list  man¬ 
ager,  and  builds  in  features  like  range 
checking,  on-the-fly  character  filtering 
to  maintain  number  integrity,  default 
item  bold  outlines,  and  cut,  copy,  and 
paste  support  with  context  checking. 
DialogHandler  also  supports  user 
hooks,  key  equivalents,  and  animated 
icons  and  pictures.  It  comes  with  com¬ 
plete  documentation  and  5000  lines  of 
example  code,  and  you  can  call  for  free 
technical  support.  The  Extender  Dia¬ 
logHandler  with  full  source  code  costs 
$189-95,  without  $99. 95.  Reader  ser¬ 
vice  no.  28. 

Invention  Software 
P.O.  Box  3168 
Ann  Arbor,  MI  48106 
313-996-8108 

The  Software  Organization  an¬ 
nounced  a  new  programming  tool,  Dia- 
logCoder,  that  is  supposed  to  eliminate 
95  percent  of  the  coding  normally  as¬ 
sociated  with  dialog  box  programming. 
The  company  claims  that  DialogCoder 
automatically  generates  compilable  C 
source  code  from  dialog  templates  to 
manage  all  controls  in  the  dialog;  that 
it  uses  graphical  metaphors  to  express 
the  relationships  between  dialog  con¬ 
trols  and  actions;  that  it  allows  users 
to  interactively  specify  the  state  of  each 
dialog  control  during  initialization  and 
command  processing;  that  it  supports 
listbox  initialization  from  ASCII  files, 
resources  bound  to  an  application,  and 
directory  lists;  that  it  supports  multiline 
edit  initialization  from  ASCII  file;  and 
that  it  provides  validation  code  for  text 
and  number  edit  controls. 

The  DialogCoder  also  supports  all 
controls  provided  by  the  Microsoft  and 
Whitewater  dialog  editors,  as  well  as 
the  entrance  and  exit  processing  for 
edit  fields.  DialogCoder  is  designed  for 
both  novice  and  experienced  Windows 
programmers  —  the  learning  curve  is 
about  one  hour  for  an  experienced  Win¬ 
dows  programmer  —  and  even  non¬ 
programmers  can  use  it,  provided 
they’re  given  detailed  dialog  design  speci¬ 
fications  to  follow.  DialogCoder  requires 
a  286-  or  386-based  machine  with  mini¬ 
mum  memory  for  Windows  2.X,  and  a 
Microsoft-compatible  mouse  is  optional. 
The  cost  is  $349.  Reader  service  no.  29- 
The  Software  Organization,  Inc. 
617-354-2012 
800-696-2012 

Software  Translations  Inc.  (STI)  has 

announced  the  release  of  v7.5  of  its 
B-Tran  Basic  to  C  translator,  which  trans- 


165 


OMNI r  E  R  E  S  T 


lates  Microsoft  QuickBasic  v4.5  and  the 
recently  announced  Basic  7.0  to  C 
source  code.  Software  Translations  guar¬ 
antees  99  percent  translation  of  code, 
including  user-defined  variables,  multi¬ 
dimensional  dynamic  arrays,  and  named 
COMMON  blocks.  B-Tran  is  available 
for  all  machines  running  DOS,  Unix, 
Xenix,  AIX,  Ultrix,  and  VMS.  It  trans¬ 
lates  more  than  1000  lines  per  minute 
of  QuickBasic  code  into  C  that  com¬ 
plies  with  SVID,  X/Open,  ANSI,  and 
K&R  standards.  One  command  trans¬ 
lates,  compiles,  and  links.  The  C  code 
it  produces  is  supposedly  readable  for 
Basic  developers,  though  it  does  offer 
the  appearance  of  a  professional  C  pro¬ 
gram.  And  B-Tran  translated  code  has 
none  of  the  memory  or  code  size  re¬ 
strictions  of  QuickBASIC.  Pricing  starts 
at  $449  for  the  Microsoft  C  compiler 
under  DOS.  Other  translators  available 
include  DEC  VAX  Basic,  DEC  Basic  + 
and  Basic  +2,  TI  Basic,  and  CBasic. 
Technical  support  and  maintenance  is 
also  provided.  Reader  service  no.  30. 
Software  Translations  Inc. 

The  Carriage  House 
28  Green  St. 

Newburyport,  MA  01950 
508-462-5523 


The  NetWare  Programmer’s  Work¬ 
bench,  a  collection  of  software  devel¬ 
opment  tools  for  client/server  applica¬ 
tions  in  a  networked  environment,  has 
been  announced  by  Novell.  The  prod¬ 


uct  includes  the  Novell/Watcom  C  Net¬ 
work  Compiler  for  developing  client- 
side  applications  and  the  C  Network 
Compiler/386  for  developing  server- 
side  applications.  Also  included  are  the 
NetWare  RPC  (remote  procedure  call), 
the  Phar  Lap  386  assembler,  a  library 
of  functions  that  are  ANSI  C  and  IEEE 
POSEX-compIiant,  and  a  prerelease  ver¬ 
sion  of  NetWare  386  v3.1  SDK. 

According  to  Nancy  Woodward,  No¬ 
vell’s  vice  president  and  general  man¬ 
ager  of  development  products,  “The 
NetWare  Programmer’s  Workbench  al¬ 
lows  programmers  to  build  distributed 
applications  using  standard  program¬ 
ming  tools  and  familiar  procedures.” 
Novell  intends  for  this  factor  to  increase 
the  rate  at  which  these  new  applica¬ 
tions  are  developed.  And  programmers 
are  not  limited  to  the  NetWare  APIs  — 
you  can  now  design  your  own  for  writ¬ 
ing  to  the  network  operating  system 
and  install  them  as  NLMs  (NetWare  Load¬ 
able  Modules),  which  are  dynamically 
linkable  modules  that  allow  the  net¬ 
work  operating  system  functions  to  be 
easily  extended. 

The  NetWare  Programmer’s  Work¬ 
bench  is  available  to  qualified  Strategic 
Partners  for  $3995.  The  C  Network  Com¬ 
piler/386  and  C  Network  Compiler  are 
available  for  $995  and  $695,  respec¬ 
tively.  Reader  service  no.  40. 

Novell  Development  Products 
P.O.  Box  9802 
Austin,  TX  78766 
512-346-8380 


NEMO  2.0,  a  real-time,  rule-based  ex¬ 
pert  system  development  package  writ¬ 
ten  in  C,  is  available  from  S20  Devel- 
oppement,  a  French  company.  NEMO 
2.0  has  the  ability  to  monitor  an  on¬ 
going  process  and  respond  to  events 
as  they  occur,  through  its  “Perception 
Module.”  NEMO  2.0  can  be  applied  for 
maintenance  functions  and  safety  evalu¬ 
ations,  and  provides  real-time  capabili¬ 
ties  for  applications  in  areas  such  as 
telecommunications  and  the  petroleum 
industry. 

NEMO  2.0  consists  of  a  facts  base,  a 
rule  base,  and  an  inference  engine. 
The  product  development  environment 
includes  a  knowledge  compiler  and 
optimizer  for  response  time;  a  graphic 
multi-window  developer  interface  that 
allows  the  display  of  the  object  hierar¬ 
chy  tree,  control  of  the  inference  en¬ 
gine,  and  online  help  screens;  and  a 
graphic  multi-window  operator  inter¬ 
face  can  be  customized  to  generate 
windows  for  facts  and  explanation  dis¬ 
play  and  for  creation  and  animation  of 
process  graphical  views  and  synoptics. 

NEMO  2.0  runs  on  a  386  workstation 
under  Unix,  on  Sun  3,  Sun  4,  SPARCsta- 
tion,  on  HP  9000  Series  and  on  a  DEC 
VAXstation  with  Ultrix  or  VMS.  1  Mbyte 
of  RAM  and  3  Mbytes  on  hard  disk  are 
required.  Reader  service  no.  41. 

Expert  Knowledge 
1801  Avenue  of  the  Stars,  Ste.  507 
Los  Angeles,  CA  90067 
213-556-1628 
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Standing  in  the  Rubble,  Looking  Up 

On  October  17,  1989,  a  major  earthquake  shook  the  San  Francisco  Bay  Area,  wreaking  billions 
of  dollars  in  property  damage  and  an  immeasurable  cost  in  human  suffering. 

A  friend  of  mine,  John  Anderson,  died  in  the  quake. 

Remarkably  few  lives  were  lost,  considering  the  magnitude  and  duration  and  the  extent  of  property 
damage.  We  who  live  in  the  Bay  Area  kept  reminding  ourselves  after  the  event  how  lucky  we  were, 
but  for  those  of  us  who  had  lost  a  friend,  the  general  good  fortune  only  made  our  personal  loss 
harder  to  accept.  We  felt  betrayed  by  the  law  of  averages,  and  could  only  repeat,  meaninglessly, 
that  John  had  been  in  the  wrong  place  at  the  wrong  time. 

I  believe  that  John  was  in  the  right  place  at  the  right  time:  It  was  the  earth  that  was  at  fault.  John 
had  been  visiting  a  software  company  in  San  Francisco  that  Tuesday  afternoon,  talking  about  a 
variety  of  topics,  all  of  which  were  really  one  grand  topic:  Pushing  the  envelope.  It  was  John’s 
theme,  what  he  had  got  into  computers  for;  probably  what  he  had  become  a  writer  for  and  what 
he  was  pursuing  in  his  music.  He  believed,  wholeheartedly  and  without  embarrassment,  in  pushing 
back  the  limits  to  human  achievement.  The  fact  that  he  was  pursuing  this  goal  on  that  afternoon 
doesn't  give  meaning  to  the  catastrophe,  but  it  lets  us  glimpse  something  of  value  through  the 
meaninglessness. 

I  first  “met”  John  through  a  clever  article  he  wrote  years  ago  in  Creative  Computing.  I  finished 
the  piece,  looked  at  the  byline,  flipped  back  to  the  masthead,  and  dug  out  other  issues  of  Creative 
to  see  who  this  funny  guy  was.  He  was,  I  saw,  someone  who  saw  in  computers  a  tool  for  the 
humanities  rather  than  for  engineers.  He  clearly  embodied  the  real  meaning  of  the  phrase  “creative 
computing."  By  the  time  I  met  him  in  person  at  MacUser  in  1988, 1  knew  him  well. 

Sort  of.  1  was  surprised  to  learn  how  technical  he  was.  In  earlier  times  he  had  written 
programming  articles,  and  he  had  played  with  hardware  to  the  extent  of  building  a  “Hackintosh.” 
He  was,  I  discovered,  the  founder  and  sole  developer  of  Acme  Dot,  one  of  the  first  stackware 
companies. 

But  the  kinds  of  stacks  he  did  were  indicative  of  his  view  of  computers.  They  were  explorations 
in  new  media,  artful  experiments  in  animation,  and  new  ways  of  combining  art,  design,  and  writing. 
He  didn’t  do  any  calendar  or  address  book  stacks,  or  anything  else  he  had  seen  elsewhere.  He 
pushed  the  envelope. 

His  most  recent  work  was  all  done  under  the  label  of  MacUsei1  s  Media  Lab,  which  sounds  like, 
and  is,  R&D.  John  was  pursuing  a  project  on  the  edge  of  publishing  technology,  exploring  what 
publishing  could  be  in  the  age  of  computers,  considering  alternatives  to  paper  and  innovative 
ways  to  deliver  live  action,  sound,  and  executable  code  to  subscribers  along  with  the  usual  words 
and  pictures.  He  was  pushing  the  envelope. 

John  was  interested,  not  surprisingly,  in  the  space  program,  and  had  lived  for  a  time  in  Titusville, 
Florida,  near  the  Kennedy  Space  Center.  He  told  me  once  about  the  auspices  under  which  he 
arrived  there.  He  had  been  working  for  Creative  Computing  magazine  when  Ziff-Davis  folded  it, 
and  he  needed  to  find  a  job.  Patch  Communications,  then  the  publisher  of  Computer  Shopper,  was 
looking  for  an  editor,  and  was  located  in  Titusville.  John  was  interested.  As  he  was  getting  off  the 
plane  in  Florida,  he  heard  some  disturbing  news  on  a  portable  radio  someone  in  the  airport  was 
waving  around.  After  he  had  his  rented  car  and  was  driving  toward  Patch,  he  heard  the  details  of 
the  Challenger  disaster  on  the  car  radio,  but  he  didn’t  really  need  them.  All  the  way  to  the  interview, 
driving  straight  toward  the  Space  Center,  he  could  see  it. 

He  went  through  the  interview  in  a  daze.  Afterward,  he  had  no  recollection  of  what  he  had  said 
in  the  interview. 

Everyone  knows  how  the  space  program  was  slowed  down  by  the  Challenger  disaster.  Many 
people  drew  lessons  from  the  disaster,  and  it  added  strength  to  the  argument  that  we  ought  to  get 
this  planet  in  order  before  we  go  traipsing  around  the  solar  system.  The  most  grandiose  expression 
of  the  fix-earth-first  viewpoint  is  probably  the  statement  “The  stars  were  not  made  for  Man.” 

1  believe  that  the  stars  were  not  made  for  Man,  and  recent  experience  has  convinced  me  that  the 
Earth  wasn’t,  either.  But  except  that  we  should  engineer  our  buildings  and  spacecraft  carefully,  I 
can’t  see  any  significance  in  either  observation. 

Pushing  back  the  limits  of  human  achievement,  reaching  for  the  stars,  that’s  not  something  we 
do.  It’s  what  we  are. 


7 'M, 


Michael  Swaine 
editor-at-large 
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MANAGING  MULTIPLE  DATA  SEGMENTS  UNDER  MICROSOFT 
WINDOWS:  PART  I 

by  Tim  Paterson  and  Steve  Flenniken 

In  the  first  installment  of  this  two-part  article,  Tim  and  Steve  present  a  segment  table 
technique  that  helps  you  cope  with  MS  Windows’  “memory  movement”  phenomenon. 

THREE-DIMENSIONAL  GRAPHICS  USING|THE  X  WINDOW  SYSTEM 

by  Michael  Stroyan 

3-D  graphics  are  possible  with  X  Window  systems  even  though  most  toolkits  don’t  provide 
much  support  for  creating  them.  Michael  shares  his  experiences  with  porting  3-D  graphics 
to  X,  and  provides  you  with  solutions  to  some  thorny  problems. 

PICK-A-NUMBER  INTERFACES 

by  Bob  Camp 

Sometimes  trailing-edge  technology  provides  the  right  tool  for  the  right  job.  Bob  states  his 
case  for  when  you  might  choose  “pick-a-number”  interfaces  rather  than  cutting-edge 
windowing  interfaces. 

SELF-ADJUSTING  DATA  STRUCTURES 

by  Andrew  M.  Liao 

Self-adjusting  heuristic  algorithms  are  ideal  for  lists,  binary  search  trees,  and  heaps.  Andrew 
explains  what  they  are,  and  how  you  can  use  them. 

MULTIPLEXING  ERROR  CODES 

by  William  J,  McMahon 

It's  possible  to  detect  unexpected  errors  by  using  function  communication  techniques  such 
as  the  one  Bill  presents  here. 

PROGRAMMING  RISC  ENGINES 

by  Neal  Margulis 

Neal  uses  Intel’s  i860  to  illustrate  how  programmers  can  take  advantage  of  pipelined 
execution,  while  Hal  Hardenbergh  adds  his  thoughts  on  RISC  vs.  CISC. 


EXAM 


ROOM 


CTALK/VIEWS 

by  Noel  Bergman 

In  this  month’s  “Examining  Room,”  Noel  checks  up  on  C_talk/Views  from  CNS,  focusing 
on  the  Browser,  Streamliner,  Interface  Generator,  and  MVC. 

PROGRAMMER'S  WORKBENCH _ 

STALKING  GENERAL  PROTECTION  FAULTS:  PART  n 

by  Andrew  Schulman 

Andrew  continues  his  hunt  for  GP  faults,  this  month  using  32-bit  C  compilers  and  Phar  Lap’s 
386 1  DOS  Extender.  He  then  returns  to  16-bit  land  to  see  how  GP  faults  can  be  caught  under 
OS/2. 

COLUMNS _ 

PROGRAMMING  PARADIGMS 

by  Michael  Swaine 

This  month  Mike  resumes  his  examination  of  Lisp,  taking  a  look  at  Lisp’s  representation 
scheme  and  the  wide  range  of  data  structures  supported  by  the  Common  Lisp  standard. 

C  PROGRAMMING 

by  Al  Stevens 

A1  continues  TEXTSRCH,  his  text  retrieval  system  that  provides  a  concordance-like  index 
into  a  text  data  base  that  uses  two  general-purpose  functions  —  parsing  the  command  line 
and  binary  trees  —  you  might  find  useful  in  other  projects. 

STRUCTURED  PROGRAMMING 

by  Jeff  Duntemann 

Jeff  takes  time  to  reflect  upon  The  Quake  of  ’89  before  moving  on  to  Arizona  and  Modula-2. 


A  special  thanks  to  Bob  Ogburn  of  Halted 
Specialties  Co.  (Santa  Clara,  Calif.)  for 
the  equipment  used  in  this  issue’s  photos. 


DEPARTMENTS _ 

EDITORIAL . 6 

by  Jonathan  Erickson 

LETTERS . 8 

by  you 

SWAINE ’S  FLAMES . 160 

by  Michael  Swaine 

PROGRAMMER'S 
SERVICES _ 

OF  INTEREST . 148 

compiled  by  Janna  Custer 

ADVERTISER  INDEX . 152 

where  to  go  for  more  information 
on  products 

PROGRAMMER’S 
MARKETPLACE . 154 

classified  ads 


NEXT  ISSUE _ 

March  gets  DDJ back  on  the  assembly  line 
with  our  lineup  of  assembly  language  arti¬ 
cles  from  the  perspective  of  both  the  80x86 
and  680x0  families.  We’ll  also  share  some 
of  the  tricks  that  ASM  pros  use,  and  we’ll 
take  a  look  at  80386  debugging  problems. 
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Last  month’s  reminiscence  about  past  members  of  the  DDJ  family  brings  us  to  this  month’s 
introduction  to  Ray  Valdes,  DDJs  new  technical  editor.  Ray  joined  DDJ  just  before  Christmas 
and,  from  what  I  can  tell,  has  pretty  much  adjusted  to  coming  into  an  office  on  a  regular  basis. 
For  the  past  few  years,  you  see,  Ray’s  been  keeping  his  own  hours  as  a  contract  programmer,  working 
on  projects  ranging  from  MUMPS  to  C++  to  HyperCard.  His  specialities,  however,  are  high-end 
graphics  and  font  technology,  topics  that  go  hand-in-glove  with  his  background  in  graphic  design. 

If  you  want  to  talk  with  Ray  about  these  or  other  topics,  he  can  be  reached  here  at  the  DD/offices, 
or  on  MCI  Mail  and  the  DDJ  Listing  Service  as  Rvaldes.  His  CompuServe  ID  number  will  be 
forthcoming.  We’re  happy  that  Ray  has  joined  us  and  pleased  with  the  immediate  contribution 
he’s  made.  You  can  look  forward  to  seeing  and  hearing  more  from  him  in  the  future, 


Speaking  of  last  month’s  editorial,  about  the  same  time  I  was  rooting  through  those  early  issues 
of  DDJ  and  reminding  myself  of  how  the  magazine  began  as  a  forum  for  Tiny  Basic,  Microsoft 
came  to  town  with  the  release  of  MS  Basic  7.0.  Talk  about  contrasts.  The  source  for  Tiny  Basic, 
which  consisted  of  several  hundred  or  so  lines  of  code,  was  published  in  a  few  magazine  pages. 
Basic  7.0,  on  the  other  hand,  comes  with  over  2000  pages  of  documentation  and,  if  you  use  all  of 
the  libraries,  help  systems,  and  the  like  (you  don’t  have  to  use  them  all,  only  what  you  want)  it 
will  claim  up  to  14  or  so  Mbytes  on  your  hard  disk.  Basic  7.0  includes  new  language  features,  an 
integrated  environment,  new  optimization  techniques,  tools,  threaded  p-code  technology,  and  on 
and  on. 

I’m  not  at  all  trying  to  compare  the  two,  mole  hills  to  mountains  being  what  they  are,  but  instead 
to  point  out  how  far  computing  and  programming  have  come  over  a  relatively  short  time.  Not  only 
is  the  software  technology  there  to  develop  environments  like  7.0,  but  also  affordable  hardware  to 
support  it. 

Incidentally,  for  those  of  you  Basic-kind-of-guys  who  wondered  whatever  happened  to  Borland’s 
Turbo  Basic,  it  has  had  some  new  life  pumped  into  it  by  the  folks  at  Spectra  Software  (aka  PC  SIG) 
and  released  under  the  name  of  PowerBasic.  A  bunch  of  new  features  have  been  added  and  if 
you’re  interested,  give  them  a  call  at  408-730-9291. 


Back  in  September,  we  published  DDJs  editorial  calendar  for  the  first  half  of  this  year.  Since 
we’re  already  two  months  into  that  list,  it’s  high  time  we  finish  it  up. 


January 

Real-time  and 

Embedded  Systems  Programming 

July 

Graphics  Programming 

August 

Annual  C  Issue 

February 

Windowing  Systems 

September 

Structured  Languages 

March 

Assembly  Language  Programming 

October 

Operating  Systems 

April 

Neural  Networks 

November 

Object-Oriented  Programming 

May 

Memory  Management 

December 

Communications  and 

June 

Hypertext 

Connectivity 

If  you  have  article  ideas  for  any  of  these  topics,  give  Mike,  Ray,  or  me  a  call  (415-366- 
3600)  or  drop  us  a  note  (c/o  DDJ,  501  Galveston  Dr.,  Redwood  City,  CA  94063,  c/o  DDJ 
on  MCI  Mail,  or  c/o  76704,50  on  CompuServe). 


As  we  expected,  Scott  Guthery’s  article  “Are  the  Emperor’s  New  Clothes  Object  Ori- 
ented ?’XDDJ,  December  1989)  generated  a  lot  of  mail,  pro  and  con.  So  much,  in  fact,  that 
we’re  going  to  try  to  pull  it  all  together  into  an  article  and  continue  the  debate.  Some  of 
the  responses  have  been  long  (Marshall  Giguere’s  rebuttal  was  as  long,  if  not  longer,  than 
Scott’s  original),  others  short  and  to  the  point.  If  there’s  anything  you’d  like  to  add,  get  it 
to  us  as  quickly  as  possible.  Or  if  you’d  like  to  hold  off  and  respond  to  the  responses, 
that’ll  be  fine  too.  It  should  be  coming  up  in  a  couple  of  months. 


And  for  those  of  you  who  have  been  wondering  whatever  happened  to  the  Rhealstone 
real-time  benchmark  proposal  follow-up  we  promised  last  year,  Robin  Kar  has  completed 
the  code  implementation.  We  should  be  running  that  article  within  the  next  two  or  three 
months  as  well. 


editor-in-chief 


(Uj 

'  Jonathan  Erickson 
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L  E  ITERS 


Standardizing  the  Standardizing 
Process 

Dear  DDJ, 

Apparently  columnist  Al  Stevens  got  a 
little  carried  away  in  his  November  1989 
column  when  he  compared  the  ANSI 
standardization  process  to  democracy. 

Surely  Mr.  Stevens  knows  that  a  com¬ 
mittee  is,  at  best,  only  a  representative 
democracy.  As  we  in  the  U.S.  are  re¬ 
minded  every  couple  of  years,  one  demo¬ 
cratic  problem  lies  in  determining  who 
gets  to  be  on  the  committee.  Since  I 
do  not  remember  voting  for  these  peo¬ 
ple,  I  wonder  whose  interests  they  re¬ 
ally  represent. 

Actually,  I  commend  the  C  standardi¬ 
zation  committee  for  the  extent  to  which 
they  have  discussed  their  issues  in  print; 
there  has  even  been  some  serious  dis¬ 
cussion  of  comments  from  outsiders. 
In  contrast,  I  was  recently  involved  with 
comments  to  the  ANSI  X3J9  Extended 
Pascal  standardization  committee.  Since 
I  have  read  no  articles  whatsoever  on 
Pascal  standardization  issues,  I  wonder 
how  many  Pascal  programmers  realize 
that  such  a  standard  is  now  virtually 
complete. 

My  introduction  to  Extended  Pascal 
was  a  note  in  IEEE  Computer  (Sept. 
1988,  p.  70)  which  mentioned  that  a 
draft  standard  was  available  (for  $35). 
After  receiving  the  draft  I  became  con¬ 
cerned  about  its  content.  In  fact,  I  as¬ 
sumed  that  no  group  of  responsible 
professionals  would  consider  releas¬ 
ing  such  a  document  as  an  example  of 
their  work.  But  I  did  submit  comments; 
that  was  in  October  1988. 

In  June,  1989,  I  received  a  package 
which  included  copies  of  all  the  vari¬ 
ous  comments  received,  with  The  Com¬ 
mittee’s  formal  response  to  each  point. 
Apparently  I  got  in  on  the  tail  end  of 
the  feedback  process,  since  most  of  the 
comments  were  from  various  other  na¬ 
tions’  standards  organizations,  as  well 
as  some  individuals  who  were  com¬ 
menting  on  previous  responses.  The 
Committee  did  decide  to  make  some 
changes.  But  my  earlier  assumption  was 
wrong:  For  the  most  part,  the  draft  was 
allowed  to  stand. 


After  an  eight-month  delay  for  The 
Committee  to  get  its  responses  together, 
the  commentors  were  given  “fifteen 
working  days”  to  accept  or  reject  their 
individual  responses.  Note  that  the  Ex¬ 
tended  Pascal  draft  standard  is  a  volu¬ 
minous,  excruciatingly  detailed  specifi¬ 
cation,  and  not  everyone  can  simply 
drop  what  they  are  doing  to  analyze 
responses,  generate  objections,  and  con¬ 
struct  a  formal  response  to  The  Com¬ 
mittee.  I  did  just  that,  however,  and 
perhaps  I  was  the  only  one  who  did, 
for  the  response  letter  that  I  finally 
received  this  September  addressed  my 
objections  only,  and  seemed  appall¬ 
ingly  condescending. 

As  an  engineer  myself,  I  would  be 
the  first  to  admit  that  some  engineers 
seem  to  vie  with  one  another  to  pro¬ 
duce  the  most  complex  and  oblique 
specification  possible.  I  guess  if  no¬ 
body  can  understand  the  spec,  then 
nobody  can  criticize  it;  of  course,  then 
nobody  can  help  find  the  bugs  in  it, 
either.  And  I  have  seen  some  really 
awful  specifications,  with  special  men¬ 
tion  going  to  IEEE  Std  488-1975.  But 
the  Extended  Pascal  draft  standard, 
which  purported  to  describe  a  struc¬ 
tured  programming  language,  was  it¬ 
self  so  unstructured  as  to  be  almost 
unreadable. 

The  creation  of  a  specification  need 
not  differ  from  the  creation  of  a  pro¬ 
gram;  each  must  eventually  describe  a 
derivative  logical  system  that  actually 
works.  A  complex  system  must  have  a 
detailed  description,  of  course,  but  not 
necessarily  a  complex  organization; 
that’s  the  whole  point  of  structured  pro¬ 
gramming.  In  fact,  if  a  system  can  only 
be  understood  in  a  complex  way,  how 
can  anyone  use  it  reliably?  Simple  sys¬ 
tems  can  be  reliable,  but  complex  sys¬ 
tems  always  contain  errors,  unless  they 
can  be  exhaustively  tested  by  an  im¬ 
partial  mechanism,  and  even  then,  you 
never  really  know. 

Some  of  my  comments  included  the 
lack  of  exception  handling,  the  lack  of 
alphanumeric  Goto  labels,  the  com¬ 
plete  lack  of  any  comment  nesting  at 
all,  and  the  lack  of  multiple  integer  and 
real  data  types  corresponding  to  word 
sizes  and  IEEE  reals.  I  wanted  addi¬ 
tional  C-like  looping  enhancements 
such  as  Break  and  Continue  to  avoid 
the  use  of  unstructured  mid-loop  Gotos, 
but  The  Committee  preferred  Goto  in¬ 
stead.  And  I  was  especially  concerned 
over  the  specification  of  a  single  Com¬ 
plex  data  type  with  a  deliberately  un¬ 
defined  implementation.  There  are  two 
common  representations  for  complex 
numbers,  and  each  is  best  suited  for 
different  types  of  computation.  The  in¬ 
ability  to  force  a  particular  representa¬ 


tion  seemed  to  be  a  serious  program¬ 
ming  limitation  and  a  “numerical  analy¬ 
sis  nightmare.”  But  the  particular  is¬ 
sues  involved  are  not  really  the  point. 

The  point  in  that  we  have  a  stan¬ 
dardization  process  functioning  largely 
behind  closed  doors,  without  a  broad 
base  of  general  input  from  the  real 
users  of  the  system  under  definition. 
The  real  users  of  a  Pascal  system  are 
individual  Pascal  programmers.  Where 
are  all  the  comments  from  these  users? 
When  were  they  contacted?  How  are 
they  being  kept  informed?  Why  were 
no  standardization  discussions  printed 
in  popular  programming  magazines? 
Although  I  am  a  member  of  IEEE,  I 
cannot  imagine  that  this  organization 
is  the  appropriate  sponsor  of  a  pro¬ 
gramming  language  standard;  a  better- 
suited  organization  would  seem  to  be 
the  software-oriented  ACM. 

This  experience  has  taught  me  a  lot 
about  what  a  standard  really  means. 
First  of  all,  there  is  no  reason  to  think 
that  voting  should  produce  a  good  stan¬ 
dard.  Design  should  be  an  exercise  in 
consistency  and  correctness,  something 
not  conferred  by  a  winning  vote.  In¬ 
deed,  voting  for  Clarity  seems  unpopu¬ 
lar,  possible  (cynically)  because  if  a 
normally  intelligent  person  could  sim¬ 
ply  read  the  standard,  they  might  not 
need  an  expert  consultant  to  help  in¬ 
terpret  it. 

And,  when  you  think  about  it,  demo¬ 
cratic  voting  is  itself  an  adversarial  pro¬ 
cess  (indeed,  a  form  of  ritualized  com¬ 
bat).  There  may  be  a  substantial  minor¬ 
ity  which  is  firmly  opposed  to  the  out¬ 
come,  and  in  scientific  or  engineering 
disputes,  the  minority  view  may  well 
be  correct.  Moreover,  as  in  the  case  of 
our  national  political  parties,  those  in 
the  minority  have  an  honorable  duty 
to  continue  their  opposition,  if  they 
feel  it  to  be  right,  against  the  day  when 
their  arguments  may  prevail.  Thus,  it 
is  important  that  not  everyone  change 
the  way  they  do  things  simply  because 
a  particular  design  is  voted  “standard.” 
And  there  is  certainly  no  reason  to  force 
programming  classes  to  use  a  particu¬ 
lar  language  version  selected  by  some 
elitist  committee. 

At  one  time  there  was  some  discus¬ 
sion  in  DDJ  of  Borland’s  Turbo  Pascal 
with  respect  to  the  Pascal  “standard.” 
I  used  to  wonder  why  Turbo  Pascal  did 
not  provide  a  Standard  Pascal  mode, 
but,  after  studying  the  Extended  Pascal 
draft  standard,  now  I  know:  Standard 
Pascal  is  a  turkey.  Although  I  do  have 
some  differences  with  the  Turbo  Pas¬ 
cal  design,  it  is  a  fine  language  for 
program  expression;  it  is  also  clearly 
described  in  a  structured  manner.  Per- 
(continued  on  page  12) 
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(continued  from  page  8) 
haps  Turbo  Pascal  represents  the  prod¬ 
uct  for  the  loyal  opposition. 

Our  standards  process  could  be  based 
on  the  more  democratic  and  obviously 
more  successful  Japanese  approach  of 
building  a  widely  held  consensus,  in 
which  case  the  standards  would  carry 
some  real  weight.  But  in  this  Pascal 
standardization  effort,  we  instead  see 
Ugly  American  political  domination  in 
action.  We  see  back  room  maneuver¬ 
ing  for  ANSI  institutional  support  of  a 
particular  design,  essentially  without 
regard  for,  or  input  from,  most  of  the 
real  potential  users.  This  is  not  democ¬ 
racy,  and  it  may  be  time  for  a  change. 
Terry  Ritter,  P.E. 

Blue  Jean  Computer  Engineering 
Austin,  Texas 

Container  Object  Fix 

Dear  DDJ, 

I  really  am  glad  to  see  the  number  of 
OOPS  articles  that  have  been  in  DDJ 
recently.  I  especially  appreciated  An¬ 
ders  Hejlsberg’s  article  on  container  ob¬ 
jects  (“Container  Object  Types  in  Turbo 
Pascal,”  Nov.  1989),  but  have  found 
several  errors  in  the  code  listings: 

In  Listing  one,  function  ListNode.Prev , 
change  the  two  references  to  Self  to 
reference  the  address  of  Self  (@Self)  as 
follows: 

P  :=  ©Self; 

while  PA. Next  <>  @Self  do  P  :=  PA.Next; 

The  code  will  not  compile  without  the 
above  changes,  as  self  is  a  listnode 
object  type  while  A1  is  a  ListNodePtr 
type. 

In  Listing  two,  change  the  with  state¬ 
ment  in  procedure  Getldent  by  adding 
an  address  operator  to  Name  as  follows: 

with  IdentRefPtr(Idents.Search(  @Name, 
NewIdent))A  do 

The  first  parameter  to  search  (the  key) 
should  be  a  pointer. 

One  useful  addition  to  the  list  meth¬ 
ods  is  a  procedure  to  concatenate  two 
lists.  The  circular  list  type  in  the  con¬ 
tain  unit  can  be  efficiently  concatenated 
by  swapping  the  two  lists  last. next 
pointer. 

In  a  circular  list  representation, 
last. next  points  to  the  first  list  element. 
Given  the  list  (a,  b,  cl,  a.next->b,  b.next- 
>c,  and  c.next->a.  Last  is  a  pointer  to  c. 
To  concatenate  list  Id,  e,  f),  all  we  need 
to  do  is  make  f.next  point  to  a  and 
c.next  point  to  d.  In  other  words,  the 
last^ .  next  pointers  of  the  two  lists  need 
to  be  swapped.  Then  the  last  variables 
of  the  lists  need  to  be  adjusted. 

unit  Concat; 
interface 
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Uses  Contain;  (  from  DDJ  Nov.  ’89 
type 

CatListPtr  =  ACatList;  CatList  = 

object(List) 
procedure  cat(L:  CatListPtr);  end; 
implementation 

Procedure  CatList. Cat(L:  CatListPtr); 
{  Concatenate  list  L  to  the  list  invok¬ 
ing  the  method  -  L  is  appended  to  the 
END  of  the  list  being  acted  on. ) 

Var  P:  ListNodePtr;  { temporary  )  Begin 
I  swap  the  two  pointers  ) 

P  :=  LastA.Next; 

LastA.Next  :=  LA. LastA.Next; 

LA. LastA.Next  :=  P; 

{  adjust  pointers  I 
Last  :=  LA. Last; 

LA. Last  :=  NIL;  End;  END. 

Eric  Friedman 
Glenview,  Illinois 

Delving  into  Drive  Paths 

Dear  DDJ, 

I  have  been  able  to  make  a  great  deal 
of  use  of  the  information  in  Mr.  James’ 
article,  “Undocumented  DOS,”  June, 
1989.  In  the  process,  I  have  determined 
a  more  precise  definition  of  the  Drive 
Path  Table  that  he  presented.  Perhaps 
some  of  your  readers  will  find  this  in¬ 
formation  as  useful  as  I  have. 

The  Drive  Path  Table  is  as  follows. 
(Note  that  some  of  the  following  infor¬ 
mation  is  in  direct  conflict  with  the 
information  presented  by  Mr.  James.) 

The  number  of  entries  in  the  Drive 
Path  Table  is  set  by  the  LASTDRIVE=xx 
command  in  your  CONFIG.SYS  file. 
To  access  the  Drive  Path  Table  for  a 
particular  drive,  start  with  the  drive  num¬ 
ber  (0  =A,  1=B,  .  .  .)  and  make  sure  it 
is  less  than  the  LASTDRIVE=xx  value; 
if  it  is  not  less,  the  drive  number  is 
invalid.  (See  Mr.  James’  article,  Table 
2,  byte  21H.)  If  the  drive  number  is 
valid,  multiply  it  by  51H  and  add  that 
value  to  the  Drive  Path  Table  pointer 
(same  article,  same  table,  offset  16H). 
The  resulting  32-bit  value  points  at  the 
Drive  Path  Table  entry  for  that  drive. 
For  normal  drives,  the  pathname  field 


contains  the  current  default  pathname 
(e.g.  C:\MY_PATH),  the  flags  field  has 
the  value  4000H,  and  the  root-length 
field  has  the  value  2. 

For  unused  drives,  the  flags  field  has 
the  value  0.  All  remaining  fields  are  set 
to  all  Os  or  all  Is,  except  the  pathname 
field,  which  contains  the  drive  letter,  a 
colon,  and  a  ’  \  ’. 

For  drives  created  with  the  SUBST 
command,  the  pathname  field  contains 
the  target  path,  the  flags  field  has  the 
value  5000H,  and  the  root-length  field 
is  set  to  the  length  of  the  target  path. 
For  example,  after  executing  the  com¬ 
mand  SUBST  E:  CABIN  the  pathname 
field  for  drive  E  would  be  “CABIN”, 
and  the  root-length  field  would  have 
the  value  6. 

Now,  if  you  change  directories  on 
drive  E  (e.g.  CD  E:NEXT)  the  pathname 
field  is  updated  (C:\BIN\NEXT)  but 
the  root-length  field  remains  unchanged 
at  6. 

If  you  use  the  JOIN  command  on  a 
drive,  the  pathname  field  contains  the 
path  to  which  the  drive  is  joined,  the 
flags  field  contains  the  value  6000H, 
and  the  root-length  field  is  set  to  2.  For 
example,  after  the  command  JOIN  A: 
C:\DRTVEA  the  pathname  field  for  drive 
A  would  be  “CADRIVEA”.  Because 
drive  A  is  no  longer  a  valid  drive,  you 
cannot  change  the  current  default  di¬ 
rectory  of  this  drive.  If  you  CD  to  CA 
DRIVEA\ANYPATH,  that  pathname  is 
stored  in  the  Drive  Path  Table  entry  for 
drive  C,  not  A. 

For  network  drives,  the  pathname 
field  contains  the  network  name,  fol¬ 
lowed  by  the  network  path;  the  net¬ 
work  name  is  preceded  by  two  back¬ 
slashes.  The  flags  field  contains  the 
value  OCOOOH,  and  the  root-length  field 
is  set  to  the  length  of  the  combined 
network  name  and  path  strings.  For 
example,  after  the  command  NET  USE 
F:  \\MYNET\MYPATH  the  pathname 
field  for  drive  F  would  contain 
“\\  MYNET\MYPATH”,  and  the  root- 
length  field  would  contain  the  value  14. 

Now,  if  you  change  directories  on 
drive  F  (e.g.  CD  F:NEXT)  the  pathname 
(continued  on  page  14) 


Offset 

Size 

Description 

0 

byte 

pathname:  an  ASCIIZ  string. 

[67] 

43  H 

word 

flags: 

8000H  a  network  drive. 

4000H  this  entry  is  valid. 

2000H  a  JOIN  drive. 

1000H  a  SUBST  drive. 

45  H 

dword 

pointer  to  the  drive  parameter  block. 

49H 

word 

block/track/sector  information. 

4BH 

dword 

unused  (set  to  OFFFFFFFFH) 

4FH 

word 

root  length. 
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(continued  from  page  12) 
field  is  updated  (\\MYNET\MYPATH\ 
NEXT)  but  the  root-length  field  remains 
unchanged  at  14. 

For  network  drives,  the  last  few  fields 
of  the  Drive  Path  Table  are  redefined 
slightly.  Beginning  at  offset  45H,  the 
Drive  Path  Table  becomes: 


45H 

dword 

unused  (set  to  0) 

49H 

dword 

pointer  to  a  net¬ 
work  drive  table 

4DH 

word 

saved  parameter 

4FH 

word 

root  length 

The  pointer  at  offset  49H  points  into 
a  linked  list  of  network  devices  (drives 
and  printers). 

The  saved-parameter  field  stores  a 
user-defined  value.  This  value  is  se¬ 
lected  when  the  drive  is  created.  (See 
INT  21H  function  5F03H.)  I  suppose  it 
would  be  used  by  someone  writing  a 
network  driver,  who  needed  to  keep 
track  of  additional  information  about 
the  drive. 

When  accessing  the  Drive  Path  Ta¬ 
ble,  you  should  be  aware  of  the  AS¬ 
SIGN  command.  If  the  ASSIGN  com¬ 
mand  has  been  invoked,  it  will  auto¬ 
matically  translate  drive  letters  that  are 
passed  through  the  conventional  INT 
21H  function  calls.  But,  it  will  NOT 
translate  these  drive  letters  as  you  ac¬ 
cess  the  Drive  Path  Table  directly. 

In  DOS  3.xx,  you  can  determine 
whether  ASSIGN  is  installed  (ASSIGN 
is  a  TSR)  like  this: 

MOV  AX,0600H 
INT  2FH 
OR  AL,AL 
JZ  NOTINSTALLED 
88 

If  ASSIGN  is  installed,  you  can  get  a 
pointer  to  its  translation  table  like  this: 

MOV  AH,19H 
INT  21H 

PUSH  AX;  save  the  current 
default  drive 
MOV  AX.0601H 
INT  2FH 

POP  DX;  restore  the  drive 
MOV  AH,0EH 
INT  21H 

MOV  AL,ES:[0103H+drivenumberl] 

;  drivenumber:  1=A,  2=B, .  .  . 

The  translation  table  is  always  26 
bytes.  By  default,  each  drive  is  assigned 
to  itself  (e.g.  entry  1=1,  entry  2=2,  .  .  .). 
After  an  assignment  such  as  ASSIGN 
A=  C,  entry  1  gets  the  value  3,  and  then 
all  attempts  to  access  drive  A  are  routed 
to  drive  C. 

Thus,  whenever  you  access  the  Drive 


Path  Table,  you  should  index  the  drive 
number  into  the  ASSIGN  translation  ta¬ 
ble,  if  it  exists.  And  if  you  use  the 
pathname  field,  you  should  reverse- 
assign  the  drive  letter  therein. 

Reverse-assigning  a  drive  letter  means 
scanning  the  ASSIGN  translate  table  to 
find  a  drive  number  that,  when  trans¬ 
lated,  will  result  in  the  drive  letter  that 
appears  in  the  Drive  Path  Table  path¬ 
name  field.  And  be  prepared  that  you 
may  not  be  able  to  find  such  a  drive 
number. 

For  DOS  2.xx,  I  do  not  know  of  a 
reliable  way  of  determining  whether 
the  ASSIGN  command  is  installed.  The 
ASSIGN  command  tries  to  detect  itself, 
but  the  method  it  uses  is  not  the  ele¬ 
gant  INT  2FH  interface,  and  it  fails  un¬ 
der  certain  circumstances. 

To  detect  itself,  DOS  2.xx  ASSIGN 
looks  at  the  first  few  bytes  pointed  at 
by  the  INT  21H  interrupt  vector.  If  those 
bytes  match  the  first  few  bytes  of  AS¬ 
SIGN’S  INT  21H  handler  (80,  FC,  0C, 
76,  2D,  80,  FC,  50),  ASSIGN  decides 
that  it  is  already  installed.  Rather  than 
installing  a  second  copy  of  itself,  AS¬ 
SIGN  updates  the  installed  translation 
table,  and  exits  quietly.  (To  access  the 
installed  translation  table,  ASSIGN  uses 
the  segment  value  from  interrupt  vec¬ 
tor  21H  and  an  offset  value  of  0103H.) 

The  problem  is  that,  after  installing 
ASSIGN,  if  you  install  any  TSR  that  also 
has  an  INT  21H  handler,  this  detection 
scheme  fails.  In  fact,  if  you  run  the 
ASSIGN  command  again  under  these 
circumstances,  it  will  install  itself  a  sec¬ 
ond  time.  This  will  likely  cause  strange 
results,  because  the  drives  may  be  trans¬ 
lated  multiple  times. 

If,  when  working  with  drives,  your 
program  uses  exclusively  one  method 
or  the  other  (that  is,  either  conven¬ 
tional  interfaces  or  undocumented  in¬ 
terfaces,  but  not  both)  then  you  prob¬ 
ably  need  not  worry  about  the  ASSIGN 
command. 

If  you  must  use  both  interfaces,  and 
you  want  your  program  to  work  cor¬ 
rectly  in  DOS  v2.xx,  you  should  warn 
the  program’s  users  about  the  restric¬ 
tions  regarding  the  DOS  2.xx  ASSIGN 
command. 

In  summary,  the  Drive  Path  Table 
allows  access  to  information  that  would 
not  otherwise  be  available  to  normal 
programs  (i.e.  the  JOIN  and  SUBST  in¬ 
formation.) 

Michael  Cook 

Mitel  Semiconductor 

Kanata,  Ontario 


Graphics  For  the  Rest  of  Us 

Dear  DDJ, 

I  found  the  interview  with  David  Parker 


in  Michael  Swaine’s  column  entitled 
“Parker’s  Perceptions”  in  the  October 
1989  DDJ  especially  interesting  since 
I’m  a  very  satisfied  user  of  his  “Ac- 
roSpin”  graphics  software.  I’d  known 
nothing  about  the  person  behind  it! 

Swaine  says  “it  seems  to  have  a  good 
product,”  and  I  can  testify  that  it  does 
indeed.  My  colleagues  and  I  need  to 
do  3-D  graphics  in  a  variety  of  lan¬ 
guages,  on  a  number  of  different  IBM 
PC  compatible  machines.  We  also  can¬ 
not  afford  fancy  hardware;  my  own 
machine  doesn’t  even  have  a  hard  drive. 

AcroSpin  is  the  only  product  I’ve 
seen  that  does  the  things  I  need  on  the 
hardware  I’ve  got.  On  all  our  PC’s  at 
this  institution,  I’ve  yet  to  encounter 
one  that  has  some  kind  of  graphics  and 
cannot  run  AcroSpin.  It’s  clean,  simple, 
and  does  exactly  what  the  manual  says 
it’ll  do. 

Matthew  D.  Healy 

Zoology  graduate  student 

Duke  University,  North  Carolina 

FPCA  ’89  Proceedings 

Dear  DDJ, 

I  very  much  enjoyed  Ronald  Fischer’s 
report  on  functional  programming  and 
FPCA  ’89-  I  must  take  issue  with  Mr. 
Fischer  on  one  point.  He  states  that 
“Scheme  is  a  deviation  of  Lisp  that 
doesn’t  offer  lazy  evaluation.”  Scheme 
certainly  does  offer  delayed  (lazy)  evalu¬ 
ation,  via  the  DELAY  and  FORCE  primi¬ 
tives.  See,  for  instance,  Chapter  3  of 
Abelson,  Sussman,  and  Sussman’s  Struc¬ 
ture  and  Interpretation  of  Computer 
Programs  for  a  superb  introduction  to 
streams  and  delayed  evaluation  in 
Scheme. 

I  was  disappointed  that  the  article 
did  not  mention  how  to  obtain  the 
conference  proceedings.  Could  you  pro¬ 
vide  this  information? 

David  Cabana 

Tampa,  Florida 

DDJ:  Sure,  David.  If  you  are  a  member 
of  the  ACM  (Association  for  Computing 
Machinery),  you  can  obtain  a  copy 
through  them  for  $22.  Just  call  800-342- 
6626.  If  you  are  not  a  member,  you  ’ll 
have  to  pay  a  little  extra  and  buy  the 
book  from  Addison-Wesley  for  $35.50. 
Their  number  in  Reading,  Mass.,  is 
617-944-3700. 

We  welcome  your  comments  (and  sug¬ 
gestions).  Mail  your  letters  (include  disk 
if  your  letter  is  lengthy  or  contains  code) 
to  DDJ,  510  Galveston  Dr.,  Redwood 
City,  CA  94063,  or  send  them  electroni¬ 
cally  to  CompuServe  76704,50  or  via 
MCI  Mail,  c/o  DDJ .  Please  include  your 
name,  city,  and  state.  We  reserve  the 
right  to  edit  letters. 
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Managing  Multiple 
Data  Segments  Under 
Microsoft  Windows 

Segment  tables  can  help  you  manage  multiple  data  segments 

under  MS  Windows 


Tim  Paterson  and  Steve  Flenniken 


f  you’ve  ever  done  any  serious  program  development 
work  for  Microsoft  Windows,  you’re  probably  aware 
of  the  freewheeling  attitude  Windows  takes  with  mem¬ 
ory  management.  In  short,  nothing  stays  put! 

In  this  two-part  article,  well  present  a  technique  that 
helps  you  cope  with  this  “memory  movement”  phenome¬ 
non  by  using  a  little-known  Windows  feature,  the  segment 
table.  In  this  month’s  installment,  well  begin  by  defining  the 
problem  and  identifying  the  solution,  including  a  short 
library  of  macros  and  functions  that  will  make  the  technique 
easy  to  use.  Next  month,  well  have  a  working  sample 
application  that  demonstrates  both  the  use  of  the  segment 
table  and  our  library,  and  provides  a  window  (figuratively 
and  literally)  into  the  operation  of  the  segment  table  while 
Windows  is  running. 

The  memory  movement  activity  described  above  is  par¬ 
ticularly  obvious  in  a  Windows  debugging  session  under 
Symdeb.  Especially  when  Symdeb  has  been  asked  for  full 
memory  movement  reporting  I/Wf),  the  memory  movement/ 
allocation/discard  messages  just  spew  out  on  the  debugging 
screen.  The  purpose  of  all  this  activity  is  to  utilize  global 
memory  as  efficiently  as  possible.  Each  item  being  manipu¬ 
lated  is  a  segment  that  was  defined  by  the  programmer 
either  at  compile  and  link  time,  or  at  run  time.  The  offset  of 
a  particular  item  within  one  of  these  segments  is  not  affected 


Tim  is  the  original  author  of  MS-DOS,  Versions  1.x,  which 
he  wrote  in  1980-  82  while  employed  by  Seattle  Computer 
Products  and  Microsoft.  He  was  also  the  founder  of  Falcon 
Technology,  which  was  eventually  sold  to  Phoenix  Tech¬ 
nologies,  the  ROM  BIOS  maker.  Steve  formerly  worked  at 
Seattle  Computer  Products,  Rosesoft  ( makers  of  ProKey), 
and  is  now  with  Microrim,  working  with  OS/2  and  Presen¬ 
tation  Manager.  They  can  be  reached  c/o  DDJ. 


by  movement  of  the  segment.  (Offsets  within  the  local  heap 
in  the  default  data  segment  can  change,  but  this  is  indepen¬ 
dent  of  global  memory  management.) 

While  these  segments  are  being  moved  around,  Windows 
keeps  the  values  in  DS  and  SS  updated.  SS  is  always  the 
default  data  segment  ( DGROUP ),  and  DS  usually  is,  too.  But 
DS  could  be  any  segment  known  to  Windows,  and  if  Win¬ 
dows  moves  that  segment,  DS  will  reflect  that  change. 
However,  some  segments  (particularly  code  segments)  are 
discardable;  if  DS  is  set  to  a  segment  that  is  later  discarded, 
there  will  be  no  updating  and  no  warning.  Note  that  ES  is 
never  updated  for  segment  movement. 

Because  SS  and  DS  are  kept  current  by  Windows,  near 
pointers  into  the  stack  or  to  static  data  are  not  a  problem. 
Far  pointers,  on  the  other  hand,  seem  to  become  invalid  at 
every  opportunity  available  to  Windows.  Fortunately,  Win¬ 
dows  does  not  interrupt  your  code  and  move  things;  any 
block  of  instructions  that  doesn’t  give  control  to  Windows 
does  not  have  to  worry  about  memory  movement  for  its 
duration.  Windows  gets  control  from  a  program  (and  pos¬ 
sibly  moves  memory)  in  three  ways.  First,  and  most  obvious, 
the  program  gives  Windows  control  whenever  it  calls  a 
Windows  function.  Second,  almost  any  far  call  the  program 
makes  could  also  give  control  to  Windows.  Third,  almost 
any  far  return  might  do  it  as  well.  These  second  and  third 
cases  occur  because  code  segments  are  normally  marked 
as  discardable,  and  Windows  has  positioned  itself  to  grab 
control  and  load  any  code  segment  that’s  not  in  memory 
when  it  gets  called  or  returned  to.  This  cannot  happen  when 
calling/returning  into  a  fixed  segment,  or  when  calling/ 
returning  into  the  currently  executing  segment,  since  in 
each  case  the  target  segment  is  already  present. 

At  face  value,  it  would  appear  that  you  could  never  pass 
a  far  pointer  as  a  parameter  nor  store  it  in  a  pointer  variable, 
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because  it  wouldn’t  be  valid  by  the  time  it  got  used.  (One 
exception  is  far  pointers  to  data  in  DGROUP,  which  will  not 
be  invalidated  when  passed  to  Windows  functions.)  The 
standard  solution  for  seasoned  Windows  programmers  is 
to  lock  the  segments  of  the  data  down,  so  that  they  won’t 
move.  Locked  segments,  however,  are  blockages  that  choke 
up  Windows’  memory  management  and  hurt  performance. 
A  well-behaved  Windows  application  will  lock  no  more 
than  a  few  segments  at  a  time,  and  then  only  for  a  short 
period.  Seasoned  Windows  programmers  know  about  all 
this  stuff  because  they’ve  all  read  Chapter  8  of  Charles 
Petzold’s  Programming  Windows. 

There  is  another  approach  that  is  useful  only  for  passing 
parameters  between  assembly  language  routines  because  it 
violates  the  C  calling  convention.  A  single  far  pointer  can 
be  passed  by  using  DS  to  carry  the  segment,  passing  the 
offset  in  another  register  or  on  the  stack.  As  mentioned 
already,  Windows  will  keep  DS  updated  while  it  moves 
memory  around,  as  long  as  it  doesn’t  point  to  a  segment 
that  gets  discarded.  There  is,  however,  a  restriction  on  the 
value  in  DS  at  the  time  of  a  far  call  from  (not  to)  a  discardable 
code  segment.  DS  must  contain  a  segment  that  is  subject  to 
Windows’  memory  management,  that  is,  one  that  has  a  Win¬ 
dows  handle  associated  with  it.  Segments  outside  of  Windows’ 
memory  management  would  include  low  memory  (such  as 
40H ,  where  BIOS  data  are  stored)  or  expanded  memory 
(say,  at  segment  EOOOH)  that  is  managed  directly  by  the 
application.  This  restriction  is  needed  should  the  caller’s 
code  segment  be  discarded.  When  this  happens,  the  return 
address  on  the  stack  is  patched  so  that  it  will  transfer  to 
code  in  Windows  that  reloads  the  caller.  As  part  of  this 
patching,  the  saved  value  of  DS  in  the  stack  gets  replaced 
by  its  handle.  A  handle  does  not  require  all  16  bits,  and  the 


extra  bits  made  available  by  this  replacement  are  used  to 
store  some  of  the  segment  reload  and  return  information. 

Big  Applications 

Let’s  consider  one  of  the  big  applications  —  spreadsheets, 
word  processors,  data  base  managers,  and  integrated  pro¬ 
gramming  environments  —  that  might  (someday)  be  run 
under  Windows.  Taking  a  spreadsheet  program  as  an  exam¬ 
ple,  we  can  speculate  on  how  its  data  segments  might  be 
organized. 

First,  each  spreadsheet  needs  at  least  one  data  segment 
for  its  cell  values  and  formulas.  Considering  the  huge  size 
that  modern  spreadsheet  programs  can  theoretically  attain 
(16,384  rows  x  256  columns  >  4  million  cells),  many  seg¬ 
ments  of  64K  could  be  required.  After  all,  each  cell  will  take 
many  bytes  to  represent  a  formula  or  constant. 

But  besides  a  segment  for  cell  information,  there  are  other 
kinds  of  data  tied  to  each  spreadsheet.  For  example,  names 
can  be  defined  to  refer  to  cells  within  the  sheet,  and  you 
need  to  keep  track  of  which  segments  constitute  the  cell 
data.  This  stuff  might  all  go  into  a  “control”  data  segment 
for  each  spreadsheet. 

The  spreadsheet  program  would  allow  several  sheets  to 
be  loaded  at  once,  each  in  their  own  window.  Each  spread¬ 
sheet  loaded  will  require  at  least  two  data  segments.  The 
program-wide  data,  such  as  the  list  of  information  (e.g., 
name  and  path)  about  each  loaded  sheet,  should  probably 
go  into  its  own  segment,  rather  than  into  DGROUP.  The  rule 
we’re  following  is  that  data  that  grow  at  the  whim  of  the 
user  —  like  loading  more  sheets  —  should  not  be  crammed 
into  DGROUP ,  as  it  already  contains  plenty  of  stuff.  It’s 
embarrassing  to  have  a  program  report  “out  of  memory” 
because  DGROUP  is  full,  when  there  is  really  200K  of  global 
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memory  left. 

The  point  is,  a  big  application  will  need  a  lot  of  data 
segments.  And  the  data  are  mostly  structures  which  will  get 
passed  around  by  reference.  In  other  words,  far  pointers 
will  be  necessary  everywhere.  And  Windows  will  be  happy 
to  move  memory  around  and  invalidate  these  pointers  be¬ 
fore  they  ever  get  used.  Or  the  segments  can  be  locked,  and 
the  application  will  turn  into  a  memory  pig. 

The  Segment  Table 

A  little-known  alternative  to  this  dilemma  has  been  built  into 
Windows  specifically  to  help  with  these  problems  of  multi¬ 
ple  data  segments.  Because  a  description  does  not  appear 
in  the  Windows  Software  Development  Kit,  we  will  create 
our  own  terminology  in  order  to  explain  it.  With  this  method, 
segments  are  never  locked,  so  Windows  has  the  freedom 
to  manage  memory  for  optimum  efficiency.  Segment  refer¬ 
ences  are  passed  around  and  stored  indirectly,  but  can  be 
dereferenced  into  a  hard  segment  number  instantly,  without 
calling  a  Windows  function. 

The  heart  of  the  mechanism  is  the  segment  table.  This  is 
an  array  of  words  in  DGROUP  that  the  application  program 
registers  with  Windows  by  calling  the  Windows  function 
DefineHandleTable(pSegTable).  The  words  in  the  segment 
table  are  the  segment  numbers  of  all  the  data  segments  used 
by  the  application.  Windows  will  keep  these  segment  num¬ 
bers  updated  and  valid  as  memory  is  moved  around. 

To  use  this  technique,  the  application  must  first  set  aside  a 
static  array  of  words  in  DGROUP.  Source  code  in  Microsoft 
C  might  look  like  that  in  Example  1. 

The  first  two  words  in  the  segment  table  have  special 
meaning,  while  the  rest  can  all  contain  segment  numbers. 
The  length  of  the  array  is  set  to  MAXPSEGS  +2  to  account 
for  this.  The  array  declaration  assumes  that  the  Small  or 
Medium  model  is  being  used,  which  is  typical  of  Windows 
applications.  If  the  Compact  or  Large  model  is  used,  NEAR 
should  be  added  to  assure  allocation  in  DGROUP. 

The  first  word  of  the  segment  table,  cwSegs ,  contains  the 
number  of  segment  entries  in  the  table.  This  is  the  number 
of  words  Windows  scans,  looking  for  the  segment  it  just 
moved.  If  it  finds  it,  Windows  will  replace  the  old  value  in 
the  table  with  the  new  location  of  the  segment.  Windows 
will  continue  to  scan  the  table  in  case  the  segment  appears 
in  it  more  than  once. 

In  the  sample  code  in  Example  1,  an  initializer  could  have 
been  used  in  the  declaration  of  SegmentTable  to  set  Seg- 
mentTable[0]  CcwSegs)  to  MAXPSEGS  (30).  However,  it’s 


/*  WORD  defined  as  unsigned  short  in  windows. h  */ 
#define  MAXPSEGS  30  /*  max  #  of  table  segments  */ 

WORD  SegmentTable [MAXPSEGS+2 ] ; 

#define  cwSegs  SegmentTable [0] 

#define  cwClear  SegmentTable [1] 

Example  1:  Sample  source  code  for  setting  aside 
the  segment  table 


tdefine  segDgroup  SegmentTable [2] 

segDgroup  =  HIWORD((void  FAR  *) SSegDgroup) ; 
++cwSegs;  /*  was  zero,  now  1  */ 


Example  2:  Sample  code  for  putting  the  group  into  the  tablel 


if  (  hMem  =  GlobalAlloc (flags,  dwBytes)  ) 

SegmentTable [i]  =  HIWORD (  GlobalHandle (hMem)  ); 
else 

/*  out  of  memory  */ 

Example  3-'  GlobalHandleC  )  converts  a  handle  to  a 
segment 


more  efficient  to  make  cwSegs  only  as  large  as  needed  to 
include  all  active  entries  in  the  table.  For  example,  if  only 
the  first  five  entries  in  the  segment  table  actually  have 
segments  it  them,  there  is  no  point  in  having  Windows  scan 
30  entries  every  time  it  moves  memory.  The  initial  value  for 
cwSegs  could  be  zero  (as  shown  here),  or  it  could  be  the 
smallest  number  of  segments  the  application  could  need. 

The  application  program’s  initialization  code  will  register 
the  table  with  Windows.  For  example: 

void  FAR  PASCAL  DefineHandleTable(WORD  NEAR  *); 

/*  prototype  V 

DefineHandleTable(SegmentTable); 

When  this  call  is  made,  Windows  will  zero  out  cwClear  and 
the  following  cwSegs  entries  in  the  table.  The  application 

Finding  these  empty  entries  is  simple 
and  involves  no  searching.  Keeping 
cwSegs  as  small  as  possible  is 
important  for  good  performance, 
because  Windows  scans  the  whole 
table  for  every  memory  movement 


can  then  start  putting  segment  numbers  in  the  table,  which 
Windows  will  keep  updated.  The  first  segment  the  applica¬ 
tion  will  want  in  the  table  is  DGROUP  itself.  Although  the 
correct  value  of  DGROUP  is  always  maintained  in  segment 
register  55  (and  usually  DS),  it  can  be  helpful  to  have  it  in 
the  table  as  well,  for  reasons  we’ll  explain  later.  This  would 
require  code  like  that  in  Example  2. 

All  data  segments,  besides  the  default  data  segment 
DGROUP ,  must  be  allocated  with  the  Windows  function 
GlobalAlloc(  ).  GlobalAlloc(  )  (Example  3)  returns  a  handle, 
not  a  segment,  and  traditionally  a  call  to  GlobalLock( )  is 
used  to  get  the  segment  and  lock  it.  We  don’t  want  it  locked, 
however,  so  a  call  to  GlobalHandleC )  should  be  used  in¬ 
stead.  GlobalHandleC  )  is  sort  of  a  strange  beast  because  its 
argument  can  be  either  a  handle  or  a  segment  —  it  will 
figure  out  which.  (This  is  actually  pretty  easy,  because 
handles  are  always  even  numbers,  and  segments  are  always 
odd.)  Given  a  handle  or  a  segment,  GlobalHandleC )  returns 
both:  The  low  word  of  the  return  value  is  the  handle,  and 
the  high  word  is  the  segment. 

Using  Fixed  Table  Entries 

If  we  were  building  a  big  application  such  as  a  spreadsheet, 
we  would  probably  always  need  some  data  segments  in 
addition  to  DGROUP.  Let’s  suppose  we  always  have  two 
additional  data  segments.  One  of  them  will  store  the  full 
path  name  of  each  spreadsheet  file  that  is  currently  loaded. 
The  other  segment  will  have  some  kind  of  “descriptor”  for 
each  loaded  sheet,  including  the  offset  of  its  name  in  the  first 
segment.  Because  these  segments  are  always  there,  we’ll 
assign  them  to  the  next  two  locations  in  SegmentTable  after 
DGROUP. 

^define  segPathNames  SegmentTable[31 

^define  segSheetDescr  SegmentTable[4] 
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(continued  from  page  18) 

Initialization  procedures  should  call  the  Windows  func¬ 
tions  GlobalAlloc( )  and  GlobalHandle( )  to  assign  values 
to  these  table  entries.  Note  that  the  value  in  cwSegs  ( Seg - 
mentTablelO])  must  be  maintained  at  no  less  than  the  num¬ 
ber  of  entries  in  the  table  being  used.  At  the  latest,  cwSegs 
can  be  updated  immediately  after  the  segment  number  is 
stored  in  the  table  —  before  any  function  call  or  return  is 
made.  For  example,  after  the  first  segment  number  of  these 
two  has  been  stored,  cwSegs  must  be  no  less  than  2;  thus  the 
first  two  entries  in  SegmentTable  ( segDgroup  and  segPath 
Names')  will  be  kept  updated  as  memory  is  moved  during 
the  function  calls  that  allocate  segSheetDescr.  After  segSheet 
Descr  has  been  set,  cwSegs  must  be  no  less  than  3. 

I’ve  been  saying  “no  less  than”  because  it’s  OK  if  cwSegs 
is  bigger  than  what’s  needed.  In  fact,  the  simplest  approach 
for  this  example  would  be  to  initialize  it  to  3  in  the  declara¬ 
tion  of  SegmentTable.  The  effect  of  this  is  that  Windows  will 
scan  three  entries  whenever  it  moves  memory  around  to  see 
if  any  of  them  are  the  segment  it  just  moved.  Because 


/*  HIWORD  defined  in  windows. h  */ 

♦define  FARPTR (off , seg)  ((void  FAR* ) MAKELONG (off , seg) ) 
‘(WORD  FAR  *)  FARPTR (0, segSheetDescr)  =  0; 


Example  4:  Macro  for  creating  a  file  pointer 


♦define  FARWORD (off , seg)  (‘(WORD  FAR*) FARPTR (of f, seg) ) 
FARWORD (0, segSheetDescr)  =  0;  /*  no  sheets  loaded  */ 


Example  5:  Macro  for  referencing  a  particular  type 


♦define  FARDESCR (of f )  (‘(DESCR  FAR* ) FARPTR 

(off, segSheetDescr) ) 

typedef  struct  /*  descriptor 

for  a  spreadsheet  */ 

unsigned  short 

Sheetld; 

char 

‘SheetName; 

)  DESCR; 

FARDESCR (pCurSheet ) .Sheetld  = 

NextSheetNura++ ; 

pCurSheetName  =  FARDESCR (pCurSheet) .SheetNarae; 

Example  6:  Building  in  a  segment 


if  (  hMem  =  GlobalAlloc (flags,  dwBytes)  ) 
( 

pSeg  =  SSegmentTable [++cwSegs  +  1] ; 
*pSeg  =  HIWORD (  GlobalHandle (hMem)  ); 

1 

else 

/*  out  of  memory  */ 


Example  7:  Allocating  a  segment 


typedef  unsigned  long  IFP; 

♦define  MAKEIFP (off ,pseg)  ( (IFP) MAKELONG (of f, pseg) ) 
♦define  IFP2SEG(ifp)  (  ‘(WORD  NEAR  *) HIWORD (ifp) ) 
♦define  IFP2PTR(ifp)  FARPTR (LOWORD (ifp) , IFP2SEG (ifp) ) 


Example  8:  Defining  a  new  data  type 


IFP  memcpyifp ( 

MAKEIFP (SCurSheetBuf, SsegDgroup) ,  /*  destination  */ 
MAKEIFP (pCurSheet, SsegSheetDescr) ,  /*  source  */ 
sizeof (DESCR)  /*  bytes  to  copy  */ 

) ; 


Example  9:  A  call  to  a  general-purpose  block  copy  routine 


external  data  in  C  is  initialized  to  zero,  it  will  never  find  a 
match  on  the  segment  number,  and  nothing  will  happen. 
But  it  doesn’t  hurt  even  if  garbage  is  present  in  the  scanned 
part  of  SegmentTable —  if  a  match  is  found,  Windows  will 
update  that  location  with  the  new  segment  number.  New 
garbage  in  place  of  the  old  —  no  problem,  so  long  as 
cwSegs  is  still  within  the  total  size  set  aside  for  SegmentTable. 

Some  macros  can  be  a  big  help  in  putting  the  segment 
table  to  use.  The  segment  from  the  segment  table  must  be 
combined  with  an  offset  into  a  long  integer  that  is  typecast 
to  a  far  pointer  as  shown  in  Example  4.  Another  typecast  is 
needed  when  the  pointer  is  dereferenced  to  specify  the  type 
being  pointed  to.  If  there  are  many  references  to  a  particular 
type,  a  macro  for  that  type  can  reduce  some  of  the  clutter 
as  shown  in  Example  5. 

This  idea  can  be  extended  one  step  further.  Some  of  the 
entries  in  the  segment  table  have  a  dedicated  meaning, 
which  could  be  written  into  a  macro.  Suppose  that  there 
was  a  separate  structure  in  the  segment  segSheetDescr  for 
each  spreadsheet  that’s  been  loaded.  Because  these  struc¬ 
tures  can  only  exist  in  that  one  segment,  the  access  macro 
can  have  that  segment  built  in,  as  in  Example  6. 

In  actual  practice,  you  might  want  to  copy  a  structure 
such  as  this  into  a  fixed  location  in  DGROUP  to  improve 
both  the  code  size  and  the  speed  of  repeated  accesses.  This 
particularly  makes  sense  when  there  is  a  single  “current” 
structure  that  is  used  heavily,  which  certainly  applies  to  the 
spreadsheet  case.  Those  structures  that  aren’t  current  can 
still  be  accessed  with  the  additional  overhead. 

Variable  pSegs 

So  far,  we  have  only  talked  about  a  few  dedicated  entries 
in  the  segment  table.  But  a  big  application  will  need  to  grab 
and  release  new  data  segments  on  the  fly.  For  example, 
earlier  we  proposed  that  each  spreadsheet  could  need  two 
segments,  and  any  number  of  spreadsheets  could  be  loaded 
at  once.  We  need  a  method  to  allocate  new  entries  in  the 
segment  table  as  spreadsheets  are  loaded. 

There’s  no  trick  to  this  part.  Windows  doesn’t  care  which 
entries  in  the  segment  table  we  use.  One  simple-minded 
approach  would  be  to  use  cwSegs  to  keep  track  of  the  next 
free  entry.  For  example,  if  cwSegs  is  5,  then  SegmentTable[2] 
through  SegmentTable[6] are  in  use.  SegmentTable[7] would 
be  the  next  free  entry,  and  cwSegs  would  need  to  be  incre¬ 
mented  when  it’s  allocated,  as  shown  in  Example  7. 

The  final  result  of  the  allocation  is  pSeg,  which  is  a  pointer 
to  a  segment.  This  replaces  the  Windows  handle  as  the  way 
to  remember  a  segment.  If  you  wanted  to  set  the  first  word 
in  a  newly  allocated  segment  to  zero,  you  could  use 

FARWORD(0,*pSeg)  =  0; 

Now  that  we’re  using  pSegs,  we’ll  need  a  new  data  type  to 
represent  a  pSeg  combined  with  an  offset.  Let’s  call  it  an 
“Indirect  Far  Pointer,”  or  IFP.  IFP  is  a  32-bit  quantity,  with 
an  offset  in  the  low  word  and  a  near  pointer  to  a  segment 
in  the  high  word,  as  in  Example  8. 

The  IFP  is  the  quantity  that  will  be  passed  as  a  parameter 
to  other  functions  in  the  program.  Note,  however,  that  the 
IFP  cannot  be  passed  to  Windows  nor  to  any  standard  C 
libraries.  Example  9  shows  an  example  of  a  call  to  a  general- 
purpose  block  copy  routine  that  uses  IFPs  to  specify  the 
source  and  destination.  Except  for  using  IFPs,  this  function 
has  the  same  inputs,  outputs,  and  purpose  as  the  standard 
Microsoft  C  library  routine  memcpy( ).  The  first  argument  is 
the  destination,  in  this  case  the  static  variable  CurSheetBuf 
of  type  DESCR ,  which  holds  the  whole  descriptor  for  the 
“current”  spreadsheet.  Now  you  can  see  why  an  entry  in  the 
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(continued  from  page  20) 

segment  table  is  reserved  for  DGROUP,  even  though  its 
current  value  can  always  be  found  in  segment  register  SS. 
Because  the  copy  routine  is  general  purpose,  it  must  always 


IFF  memcpyifp (IFP  Destlfp,  IFP  Sourcelfp,  unsigned  cb) 
{ 

unsigned  i; 

for  (i=0;  i<cb;  i++) 

((char  FAR  *) IFP2PTR (Destlfp) ) [i]  = 
((char  FAR  *) IFP2PTR (Sourcelfp) ) [i] ; 
return (Destlfp) ; 

} 


Example  10:  One  way  to  code  memcpyifpC ) 


char  FAR  *Dest; 
char  FAR  ‘Source; 

Dest  =  IFP2PTR (Destlfp) ; 

Source  =  IFP2PTR (Sourcelfp) ; 
for  (i=0;  i<cb;  i++) 

Dest[i]  =  Sourcefi); 


Example  11:  Storing  pointers  in  local  variables 


IFP  memcpyifp (IFP  Destlfp,  IFP  Sourcelfp,  unsigned  cb) 

movedata(  IFP2SEG (Sourcelfp) ,  /*  source  sea 

*/ 

LOWORD (Sourcelfp) , 

/*  source  offset  */ 

IFP2SEG (Destlfp) , 

/*  destination  seg  */ 

LOWORD (Destlfp) , 

/*  destination  offset 

*/ 

cb 
)  ; 

return (Destlfp) ; 

} 

/*  count  of  bytes  */ 

Example  12:  Writing  memcpyifpC )  using  a  standard 
library  function 


be  passed  IFPs,  which  are  offset/pSeg  pairs.  In  order  to  pass 
a  DGROUP  variable,  such  as  CurSheetBuf  we  must  be  able 
to  pass  a  pointer  to  a  place  where  DGROUP  is  stored. 

In  this  example,  the  source  of  the  copy  is  the  descriptor 
that  is  being  made  current.  MAKEIFP  builds  the  reference 
for  the  source  by  using  the  offset  held  in  the  static  variable 
pCurSheet,  and  the  dedicated  pSeg  segSheetDescr.  Note  how 
the  “address  of”  operator  applied  to  segDgroup  or 
segSheetDescr  returns  a  pSeg;  leaving  it  off  would  fetch  the 
segment  value  itself  from  SegmentTable. 

One  way  to  code  memcpyifpC )  is  shown  in  Example  10. 
Unfortunately,  the  Microsoft  C  compiler  is  not  as  good  at 
eliminating  loop  invariants  as  we  might  like.  Even  at  maxi¬ 
mum  optimization  (/Ox),  the  generated  code  completely 
rebuilds  both  far  pointers  —  and  fetches  the  segments  from 
the  segment  table  —  each  time  through  the  loop.  A  slight 
variation,  then,  would  be  to  bring  the  building  of  the  far 
pointers  out  of  the  loop  and  store  them  in  a  couple  of  local 
variables,  such  as  those  shown  in  Example  1 1 . 

The  code  generated  for  this  sequence  is  pretty  good,  and 
ends  with  the  block  move  instruction  REP  MOVSW to  actu¬ 
ally  perform  the  copying.  It  is  critical,  however,  to  remem¬ 
ber  the  limitations  of  applying  this  technique  to  other  cases. 
Once  an  IFP  has  been  dereferenced,  there  is  no  longer  any 
protection  from  global  heap  movement.  Almost  any  far  call 
can  be  assumed  to  invalidate  far  pointer  variables.  An  ex¬ 
ception  to  this  rule  is  when  far  calls  are  made  to  functions 
in  the  same  segment;  because  the  segment  is  already  loaded, 
no  memory  movement  will  occur.  This  allows  us  to  write 
“helper”  functions  to  access  standard  C  library  routines.  The 
helper  must  reside  in  the  same  segment  as  the  run  time,  and 
converts  the  IFPs  passed  to  it  into  far  pointers  for  the  library 
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function.  As  shown  in  Example  12,  memcpyifp( )  could  be 
written  using  the  standard  Microsoft  C  library  function  move- 
data( ),  which  takes  explicit  segment  and  offset  arguments. 

For  the  best  performance  and  smallest  size,  key  functions 
can  be  coded  in  assembly  language.  Listing  One,  page  89, 
shows  an  assembly-language  version  of  memcpyifpC ),  dem¬ 
onstrating  the  dereferencing  of  IFPs. 

The  segtab/e  Library 

Listing  Two,  page  89,  shows  the  segtable  library,  a  collection 
of  five  functions  that  manage  memory  through  a  segment 
table.  The  header  file  segtable. h  (Listing  Three,  page  90) 
includes  all  the  function  prototypes,  type  definitions,  and 
macro  definitions  needed  to  use  the  library.  The  first  few 
lines  of  segtable. h  are  constants  that  should  be  tailored  to 
the  application:  MAXPSEGS  is  the  maximum  number  of 
segments  that  the  segment  table  can  hold.  You  want  this 
large  enough  so  you  never  run  out,  but  you  don’t  want  to 
eat  up  too  much  of  DGROUP with  the  table.  Microsoft  Excel, 
for  example,  apparently  has  room  for  more  than  2000  seg¬ 
ments.  MINPSEGS  is  the  initial  value  for  cwSegs.  It  must  be 
equal  to  the  number  of  fixed  table  entries  —  at  least  1,  for 
segDgroup. 

Immediately  following  these  constants  are  the  definitions 
of  the  fixed  table  entries.  segDgroup  is  always  there  as 
SegmentTable[2],  and  any  additional  entries  must  follow 
with  consecutive  indices. 

The  header  file  also  defines  a  pair  of  validation  macros 
for  debugging  purposes.  VALIDPSEG(pseg)  verifies  that  its 
pSeg  argument  points  into  the  segment  table  and  is  word- 
aligned  (even).  VALID_VARlABLE_PSEG(pseg)  adds  the  ad¬ 


ditional  requirement  that  the  pSeg  point  above  the  fixed 
table  entries,  into  the  variable  part  of  the  table.  The  library 
routines  make  these  checks  whenever  possible  if  the  DE¬ 
BUG  switch  is  turned  on.  Also,  whenever  a  segment  table 
entry  contains  a  valid  segment  number,  there  are  checks  to 
verify  that  the  entry  is  odd  (as  are  all  Windows  segment 
numbers).  If  any  of  these  debugging  tests  fails,  the  library 
will  call  the  function  SegmentErrorf ). 

The  five  library  functions  are  described  in  the  following 
section. 

void  FAR  PASCAL  Segmentlnit(void)  —  This  function 
registers  the  segment  table  with  Windows  and  initializes  the 
segDgroup  entry.  All  other  fixed  table  entries  will  have  a 
zero  value,  which  is  appropriate  for  allocating  with  Segment- 
Realloc(  ). 

PSEG  FAR  PASCAL  SegmentAllocf DWORD  size)  —  First, 
this  function  must  find  an  unused  entry  in  the  segment  table. 
It  does  not  use  the  simple  method  described  earlier;  instead, 
it  keeps  a  free  list  that  links  together  all  entries  that  were 
once  used  but  have  been  freed.  A  static  variable  points  to 
the  head  of  the  list.  The  segment  table  is  located  at  an  even 
address,  so  all  the  links  in  the  free  list  will  also  be  even.  This 
means  that  when  Windows  scans  the  table  for  a  segment  it 
is  moving,  it  will  never  match  with  a  link  because  the 
segments  are  always  odd.  If  the  free  list  is  empty,  then 
cwSegs  is  increased  and  the  next  entry  at  the  end  of  the  table 
is  taken. 

This  approach  to  finding  unused  entries  ensures  that 
cwSegs  is  never  increased  if  there  is  already  a  free  slot  within 
the  in-use  range.  Finding  these  empty  entries  is  very  simple 
and  involves  no  searching.  Keeping  cwSegs  as  small  as 
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possible  is  important  for  good  performance,  because  Win¬ 
dows  scans  the  whole  table  for  every  memory  movement, 
which  happens  quite  frequently.  An  additional  step  could 
be  to  detect  when  an  entry  at  the  end  of  the  table  is  being 
freed,  so  cwSegs  could  be  reduced,  but  that  is  probably 
more  work  than  it’s  worth. 

Once  an  empty  entry  is  found,  Windows  is  called  to 
allocate  the  amount  of  memory  requested.  The  GMEM_ 
MOVEABLE  flag  is  always  used.  If  the  application  requires 
it,  the  function  could  be  modified  to  accept  the  memory 
flags  as  an  argument.  If  all  goes  well,  the  function  returns  a 
pSeg,  a  pointer  to  the  entry  in  the  table;  zero  returned 
indicates  a  failure. 

void  FAR  PASCAL  SegmentFree(PSEG pseg)  —  This  func¬ 
tion  frees  the  data  associated  with  the  pSeg  argument,  and 
frees  the  table  entry  by  placing  it  on  the  free  list.  This 
function  should  not  be  called  on  a  fixed  table  entry,  because 
it  will  make  that  entry  available  for  general  use. 
void  FAR  PASCAL  DataFree(PSEG  pseg)  —  This  func¬ 
tion  frees  the  data  associated  with  the  pSeg  argument,  but 
the  pSeg  itself  is  still  reserved.  Its  table  entry  will  contain 
zero.  SegmentRealloc  may  be  used  later  to  allocate  some 
memory  to  the  pSeg. 

BOOL  FAR  PASCAL  SegmentRealloc(PSEGpseg  DWORD 
size)  —  This  function  changes  the  amount  of  memory  allo¬ 
cated  to  a  pSeg.  It  can  be  used  on  any  valid  pSeg,  whether 
or  not  any  data  are  currently  allocated  to  it.  This  function  is 
used  for  the  initial  allocation  of  fixed  table  entries  (except 
segDgroup ). 

void  FAR  PASCAL  SegmentError  (void)  —  This  func¬ 
tion  is  present  only  when  the  DEBUG  switch  is  on.  It  is  the 
central  exit  point  should  any  of  the  debugging  checks  fail. 
As  written,  it  does  nothing  but  FatalExit(-l).  The  easiest 
way  to  use  it  is  to  simply  put  a  breakpoint  there,  so  you  can 
do  a  stack  backtrace  as  the  first  step  to  figuring  out  what 
went  wrong.  But  it  could  also  be  spruced  up  to  report  an 
error  without  requiring  a  debugger  to  be  present. 

Next  Month 

By  now,  you  should  have  a  good  understanding  of  the 
problems  of  managing  multiple  data  segments  under  Win¬ 
dows,  not  to  mention  how  a  segment  table  can  help  you 
come  to  terms  with  these  problems.  Next  month,  we’ll 
introduce  a  sample  program,  called  SEGMENTS,  that  demon¬ 
strates  the  use  of  the  segtable  library  and  lets  you  watch  as 
Windows  updates  the  segment  table  before  your  eyes. 

Availability 

All  source  code  is  available  on  a  single  disk  and  online.  To 
order  the  disk,  send  $14.95  (Calif,  residents  add  sales  tax) 
to  Dr.  Dobb’s  Journal ,  501  Galveston  Dr.,  Redwood  City, 
CA  94063,  or  call  800-356-2002  (from  inside  Calif.)  or  800-533- 
4372  (from  outside  Calif.).  Please  specify  the  issue  number 
and  format  (MS-DOS,  Macintosh,  Kaypro).  Source  code  is 
also  available  online  through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing  Service  (603-882- 
1599)  supports  300/1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the  system  answers,  type: 
listings  (lowercase)  at  the  log-in  prompt. 

DDJ 


(Listings  begin  on  page  89) 
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Three-Dimensional  Graphics 

Using  the 

X  Window  System 


X  can  produce  reasonably  fast  and  visually 
acceptable  3-D  graphics 


Michael  Stroyan 


The  X  Window  System  gives  a 
new  level  of  portability  to  graph¬ 
ics  programs.  X  is  available  on 
many  workstations.  It  is  sup¬ 
ported  by  X  terminals,  and  by 
X  server  programs  that  can  be  run  on 
PCs.  There  are  several  toolkits  avail¬ 
able  to  assist  with  the  implementation 
of  graphical  user  interfaces  on  X,  but 
there  is  little  support  for  three-dimen¬ 
sional  graphics  using  X.  This  article 
discusses  the  options  for  creating  3-D 
graphics  programs.  It  describes  the  ex¬ 
perience  of  porting  a  3-D  graphics  li¬ 
brary  to  X,  some  of  the  issues  that  came 
up,  and  the  solutions  to  those  issues. 
An  example  program  shows  some  of 
these  solutions. 

Approaches  to  Three-Dimensional 
Graphics 

Three-dimensional  graphics  are  cre¬ 
ated  within  XI 1  windows  using  a  vari¬ 
ety  of  approaches.  These  options  in¬ 
clude  normal  Xlib  calls,  3-D  graphics 
libraries  (using  either  Xlib  or  a  peer- 
level  interface  that  cooperates  with  an 
X  server  to  get  directly  to  the  hard¬ 
ware),  and  extensions  to  XI 1  that  in¬ 
crease  the  server’s  capabilities.  Each 
approach  has  advantages  and  disad¬ 
vantages  that  make  it  appropriate  in 
different  circumstances. 


Michael  is  a  programmer  with  the  Graphics 
Technology  Division  of  Hewlett-Packard  Com¬ 
pany  and  can  be  reached  at  3404  E.  Har¬ 
mony  Rd.,  MS/73,  Fort  Collins,  CO  80525. 


Using  the  normal  two-dimensional 
Xlib  graphics  to  render  transformed 
points  is  the  most  direct  method.  Con¬ 
version  from  3-D  to  2-D  coordinates  is 
done  in  a  client  program  that  uses  Xlib 
commands  to  draw  the  2-D  results. 
These  commands  to  the  X  server  are 
either  parts  of  the  picture  (such  as  vec¬ 
tor  and  polygon  primitives),  or  an  en¬ 
tire  picture  (such  as  an  XPutlmage  com¬ 
mand).  Using  the  X  server  to  render 
vectors  and  polygons  reduces  the  com¬ 
plexity  of  the  task  and  improves  pro¬ 
gram  performance. 


The  rendering  capabilities  of  the  X 
server  are  limited,  however.  More  so¬ 
phisticated  images  can  only  be  created 
by  computing  the  complete  image  in  a 
client  program  and  sending  that  image 
to  the  server  as  an  array  of  pixel  values. 
When  writing  a  program  for  use  in  X 
Windows,  Xlib  calls  may  be  the  best 
choice.  Programs  written  for  X  Win¬ 
dows  often  use  such  features  as  X 
toolkits  to  take  full  advantage  of  the 
window  system.  Once  tied  to  the  win¬ 
dow  system  by  these  features,  there  is 
little  reason  to  use  standard  graphics 
libraries.  The  Xlib  intrinsics  are  the  only 
commonly  available  interface  for  graph¬ 
ics  in  X  Windows.  Putting  all  3-D  fea¬ 
tures  in  the  program  source  allows  (po¬ 
tential)  portability  of  the  program  to  all 
systems  with  Xlib.  Using  a  3-D  graph¬ 
ics  library  limits  the  program  to  sys¬ 
tems  that  have  that  library.  The  amount 
of  extra  effort  involved  to  use  only  Xlib 
routines  varies  with  the  nature  of  the 
program.  A  CAD  program  may  require 
a  number  of  extra  routines  for  transfor¬ 
mation  and  input  operations  that  a  3-D 
graphics  standard  library  would  have 
supplied.  A  ray  tracing  program,  how¬ 
ever,  produces  a  list  of  pixel  values 
that  easily  work  with  the  XPutlmage 
operation. 

A  slightly  more  difficult  approach  is 
implementing  a  3-D  graphics  library 
that  is  layered  above  Xlib.  Implement¬ 
ing  a  standard  involves  adapting  the 
features  of  X  to  suit  the  required  be¬ 
havior  of  the  standard.  Matching  all  of 
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the  features  requires  additional  work. 
This  extra  effort  pays  off  because  many 
existing  programs  that  rely  on  this  stan¬ 
dard  can  then  be  used  in  X  Windows. 
A  few  such  libraries  have  been  created. 
Hewlett-Packard  has  added  A7/£>-based 
XI 1  support  to  the  HP  Starbase  and 
HP  Graphical  Kernel  System  (GKS)  li¬ 
braries.  An  XI 1  implementation  of  the 
GKS  standard  has  been  created  at  the 
University  of  Illinois  at  Urbana-Cham- 
paign.  Template  Graphics  has  produced 
an  Xlib  implementation  for  their  Figaro 
PHIGS  library. 

A  peer-level  library  has  a  very  differ¬ 
ent  relationship  to  the  X  server.  This 
type  of  library  arranges  direct  access 
to  the  display  either  by  using  X  server 
extensions,  or  by  using  the  low-level 
resource  allocation  utilities  also  used 
by  the  X  server.  The  direct  hardware 
access  approach  gives  a  library  supe¬ 
rior  speed  and  broader  use  of  hard¬ 
ware  capabilities  than  an  Y7t£>-based 
implementation.  This  is  especially  im¬ 
portant  for  graphics  workstations  that 
support  operations  such  as  transforms, 
hidden  surface  removal,  and  shading 
in  specialized  hardware.  A  peer-level 
library  sacrifices  the  networking  capa¬ 
bility  of  X.  Programs  using  such  a  li¬ 
brary  must  run  on  the  same  system  that 
they  display  their  output  on.  Hewlett- 
Packard  uses  this  type  of  library  for  the 
Starbase  and  GKS  libraries  on  HP-UX, 
and  for  the  Domain  graphics  libraries 
on  HP/Apollo  workstations. 

The  XI 1  protocol  has  a  mechanism 
for  defining  new  groups  of  features, 
called  “extensions.”  An  X  server  im¬ 
plementation  could  provide  an  exten¬ 
sion  that  processes  and  renders  three- 
dimensional  data.  The  MIT  X  Consor¬ 
tium  is  sponsoring  a  3-D  graphics  ex¬ 
tension  named  PEX  (PHIGS  Extensions 
to  X).  The  PEX  extension  will  provide 
support  for  PHIGS  in  the  X  protocol. 
A  server  supporting  PEX  will  be  able 
to  render  PHIGS  primitives.  The  server 
will  also  have  the  option  of  providing 
support  for  storing  groups  of  primi¬ 
tives  in  the  server.  This  will  allow  com¬ 
plicated  images  to  be  edited  and  re¬ 
drawn  without  retransmitting  all  the 
data  from  the  client  program  to  the 
display  server.  A  sample  implementa¬ 
tion  of  PEX  should  be  ready  sometime 
near  December  of  1990.  It  will  take 
additional  time  for  vendors  to  provide 
efficient  PEX  implementations.  Vendors 
of  X  servers  on  limited  hardware,  such 
as  X  terminals,  may  never  choose  to 
provide  the  PEX  extensions. 

The  Approach  Taken 

Hewlett-Packard  has  produced  several 
libraries  to  assist  with  the  creation  of 


3-D  graphics  in  the  X  Window  System. 
These  libraries  use  both  the  peer-level 
interface  approach  and  the  layered  Xlib 
approach  for  Starbase  and  GKS  librar¬ 
ies.  Prototypes  of  the  PEX  extension 
approach  were  demonstrated  at  the 
SIGGRAPH  ’88  and  SIGGRAPH  ’89  con¬ 
ferences.  The  rest  of  this  article  con¬ 
centrates  on  implementing  a  device 
driver  to  layer  the  Starbase  graphics 
library  above  the  Xlib  library.  The  tech¬ 
niques  developed  to  implement  this 
“Starbase  on  Xll,”  or  “soxll”  driver, 
apply  to  creating  other  libraries  and 
programs  that  display  3-D  graphics  us¬ 
ing  Xlib. 

Transformations  and  Clipping 

Transforming  3-D  coordinates  to  2-D 
coordinates  is  a  well-understood  pro¬ 
cess.  Matrix  operations  are  applied  to 
the  3-D  coordinates  to  perform  rota¬ 
tions,  translations,  and  perspective  pro¬ 
jections.  These  techniques  are  described 
in  many  computer  graphics  reference 
books,  including  those  listed  in  the 
bibliography.  The  soxll  driver  relies 
on  existing  utilities  in  the  Starbase  li¬ 
brary  to  perform  transformations  and 
clipping. 

The  program  in  Listing  One  (page 
92)  uses  three  matrices  to  process  co¬ 
ordinates  through  modeling,  viewing, 
and  device  scaling  transformations,  The 
modeling  matrix  is  made  of  a  concate¬ 
nation  of  rotations  about  the  X  and  Y 
axes.  The  matrix  is  updated  to  follow 
mouse  movements.  The  viewing  ma¬ 
trix  is  precomputed  to  show  a  perspec¬ 
tive  view  looking  at  the  origin,  from  a 
point  at  (0,  0,  -  15).  It  maps  the  world 
coordinates  into  virtual  device  coordi¬ 
nates  (VDCs),  ranging  from  (0,  0,  0)  to 
(2,  2,  2).  The  device  matrix  maps  VDC 
units  to  device  coordinates  —  the  win¬ 
dow  coordinates  of  Xlib. 

The  VDC  to  device  coordinate  trans¬ 
formation  is  slightly  different  for  X  than 
for  most  other  devices  because  the  size 
of  the  X  Window  “device”  can  change. 
The  soxll  driver  leaves  the  device 
coordinate  transformation  unchanged 
when  a  window  is  resized.  If  a  window 
shrinks,  the  driver  shows  a  “porthole” 
into  an  image  larger  than  the  window. 
An  application  programmer  can  watch 
for  resize  events  and  update  device  map¬ 
ping  to  match  the  new  window  size. 
This  gives  a  “rubber  sheet”  effect  —  the 
image  stretches  to  match  the  size  of  the 
window.  In  the  program  in  Listing  One, 
the  device  transformation  matrix  is  up¬ 
dated  whenever  the  window  size 
changes  so  that  the  image  maps  to  the 
new  window  size.  There  is  no  clipping 
code  in  this  example;  it  relies  on  the 
object  being  within  the  viewing  volume. 
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(continued  from  page  30) 

Partial  Polygons 

To  improve  performance,  soxll  uses 
X  server  polygon  drawing  routines  to 
draw  polygons.  This  causes  a  problem 
with  some  polygons.  The  Starbase  graph¬ 
ics  library  supports  polygons  with  holes 
in  them  by  defining  primitives  called 
partial  polygons.  (The  PHIGS  graphics 
standard  calls  these  groups  of  poly¬ 
gons  “Fill  Area  Sets.”)  The  program  in 
Listing  One  shows  a  cube  with  a  hole 
in  one  side.  The  hole  in  the  face  of  the 
cube  is  a  partial  polygon.  Polygons 
with  holes  in  them  are  described  as  a 
group  of  partial  polygons,  followed  by 
a  normal  polygon.  Each  polygon  or 
partial  polygon  is  a  loop  of  vertices. 
These  loops  may  be  the  outside  edges 
of  separate  areas,  or  the  outside  and 
inside  edges  of  a  single  polygon.  Xlib 
does  not  explicitly  support  holes  in 
polygons.  To  use  Xlib  polygon  rou¬ 
tines  and  produce  the  desired  result, 
the  soxll  driver  rearranges  the  vertices 
and  relies  on  a  detail  of  the  definition 
of  Xlib  polygons. 

X  protocol  defines  that  drawing  a 
polygon  only  affects  the  pixels  that  are 
within  the  interior,  or  on  an  edge  other 
than  the  right  and  bottom  edges.  This 
allows  adjacent  polygons  to  share  com¬ 
mon  edges  without  both  polygons  af¬ 
fecting  the  pixels  on  the  common  edges. 
A  mesh  of  vertices  drawn  with  an  ex¬ 
clusive  OR  won’t  leave  gaps  between 
polygons.  As  a  result,  if  a  polygon  is 
pinched  down  so  that  two  edges  are 
on  the  same  coordinates,  no  pixels  are 
changed  along  the  pinched  area.  All 
of  the  pixels  are  on  a  right  or  bottom 
edge  and  are  therefore  left  alone.  If 
such  a  double  edge  crosses  the  interior 
of  a  polygon,  there  is  no  gap  where  the 
edges  cross  the  interior. 

When  asked  to  draw  a  complex  poly¬ 
gon,  the  soxll  driver  connects  the  par¬ 
tial  polygons  to  each  other  by  one  of 
these  thin  double  edges.  The  result  is 
that  one  loop  of  vertices  drawn  by 


XFillPolygon  appears  to  be  multiple  dis¬ 
jointed  loops.  If  the  polygon  is  edged, 
the  edges  are  later  drawn  along  the 
edges  of  the  partial  polygon  loops  with 
an  XDrawLines  call  for  each  smaller 
loop.  Figure  1  shows  an  example  poly¬ 
gon.  This  polygon  is  defined  to  Star- 
base  as  a  partial  polygon,  with  the  ver¬ 
tices  numbered  1,  2,  3,  4,  and  5;  fol¬ 
lowed  by  a  polygon  with  vertices  num¬ 
bered  6,  7,  8,  9,  and  10.  The  X  server  is 
sent  one  XFillPolygon  request  with  all 
of  the  vertices  from  1  to  11.  Then  the 
edges  are  sent  as  two  XDrawLines  calls 
with  the  vertices  of  the  Starbase  partial 
polygon  and  polygon  calls. 

Color  Map  Support 

X  protocol  deals  with  many  different 
types  of  hardware,  each  of  which  has 
a  variety  of  methods  for  representing 
and  controlling  colors.  X  protocol  cate¬ 
gorizes  the  representation  of  colors  into 
six  different  visual  classes:  StaticGray, 
Grayscale,  StaticColor,  Pseudocolor, 
TrueColor,  and  DirectColor.  These 
classes  indicate  whether  a  display  in¬ 
terprets  pixel  values  as  levels  of  bright¬ 
ness  or  as  indices  into  tables  of  colors. 
They  also  indicate  whether  any  color 
tables  have  writable  entries,  and 
whether  the  bits  in  a  pixel  are  grouped 
into  particular  bits  that  determine  the 
red,  green,  and  blue  brightness  of  a 
color.  Some  displays,  such  as  the  HP 
Turbo  SRX,  support  multiple  visual 
classes  at  the  same  time.  The  soxll 
driver  supports  all  six  classes  of  visu¬ 
als,  but  I  will  only  discuss  the  Pseudo- 
Color  class,  because  it  raises  the  most 
interesting  issues.  A  Pseudocolor  class 
visual  indicates  that  pixel  values  are 
indices  into  a  writable  table  of  colors, 
called  a  “color  map.” 

The  Starbase  library,  like  most  graph¬ 
ics  standards,  is  based  on  a  model  of 
controlling  a  virtual  device.  One  result 
is  that  the  library  presents  color  maps 
as  being  completely  available  to  appli¬ 
cation  programs.  The  Xlib  concept  of 
color  maps  is  different.  Xlib  knows  that 
many  programs  will  be  executing  on 
one  display,  and  usually  must  share  a 
single  hardware  color  map.  Reconcil¬ 
ing  these  two  approaches  to  color  maps 
can  be  done  in  two  different  ways. 
Either  the  library’s  color  indices  can 
be  mapped  to  a  different  set  of  allo¬ 
cated  Xlib  indices,  or  a  new  software 
color  map  can  be  allocated  by  Xlib  for 
the  exclusive  use  of  the  soxll  driver. 

The  allocation  of  individual  indices 
is  unsatisfactory  if  an  application  uses 
Boolean  pixel  changing  functions  to 
combine  colors  on  the  display.  A  pro¬ 
gram  may  expect  to  OR  together  a  red 
color  in  index  1  and  a  green  color  in 
index  2  to  produce  a  yellow  color  that 
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(continued  from  page  32) 
it  set  in  index  3-  Rearranged  color  indi¬ 
ces  will  not  necessarily  produce  the 
expected  result. 

Allocating  a  complete  color  map  also 
has  drawbacks.  Because  most  displays 
only  support  one  color  map  at  a  time, 
the  server  switches  the  hardware  color 
map  to  correctly  display  the  current 
window.  All  other  windows  ar  then 
displayed  with  essentially  randc  1  col¬ 
ors.  This  can  be  visually  jarring  mak¬ 
ing  the  rest  of  the  windows  more  eye 
catching  than  the  supposed  center  of 
interest. 

The  sox  11  driver  uses  some  of  each 
color  method  to  avoid  most  of  the  weak- 
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nesses  of  each  method.  The  driver  starts 
by  using  the  default  X  color  map.  It 
then  allocates  a  new  color  map  if  a 
program  changes  any  of  the  color  map 
entries.  This  means  a  Starbase  program 
can  share  the  common  default  color 
map,  as  long  as  it  doesn’t  care  about 
the  index  values  for  each  color.  When 
a  program  needs  to  control  the  color 
of  particular  indices,  a  full  color  map 
is  used,  which  gives  the  program  com¬ 
plete  control. 

When  a  color  map  is  allocated,  soxl  1 
uses  some  color  map  tricks  to  replace 
missing  Xlib  features.  The  Starbase  li¬ 
brary  defines  a  control  called  “display 
enable.”  This  selects  the  bits  in  a  pixel 


that  are  used  to  index  into  a  color 
map.  When  looking  up  a  color,  those 
bits  that  are  not  display  enabled  are 
read  as  zero.  Several  HP  displays  pro¬ 
vide  this  control  in  hardware,  but  the 
X  protocol  does  not  have  this  feature. 
The  soxll  driver  simulates  hardware 
display  enable  by  rewriting  the  color 
map.  Thus  all  indices  that  differ  only 
by  bits  in  display  disabled  planes  have 
the  same  color. 

The  display  enable  feature  can  be 
used  for  double  buffering.  In  double 
buffering,  bits  in  a  pixel  are  divided 
into  two  sets.  Half  of  the  bits  hold  the 
image  that  is  being  displayed,  while 
the  other  half  are  cleared  and  redrawn 
to  create  a  new  image.  With  double 
buffering,  the  transition  from  display¬ 
ing  one  image  to  displaying  the  next 
is  extremely  fast.  When  the  undisplayed 
image  is  ready,  the  color  map  is  rewrit¬ 
ten  and  the  new  image  is  displayed  in 
completed  form.  There  is  no  flicker 
while  the  image  is  changing.  This  is 
important  for  animation,  where  images 
are  being  constantly  updated. 

Listings  Two  (page  98)  and  Three 
(page  98)  show  the  header  declara¬ 
tions  and  code  for  an  Xlib  double  buff¬ 
ering  utility.  This  allocates  colors  from 
a  shared  color  map,  then  maps  the 
program’s  pixel  indices  to  the  values 
returned  from  Xlib.  The  utility  will  only 
work  with  PseudoColor  class  visuals, 
and  will  only  succeed  if  there  are  suffi¬ 
cient  free  pixels  to  allocate  from  the 
color  map. 

Hidden  Surface  Removal 

When  drawing  3-D  objects  as  wire¬ 
frame  outlines,  removal  of  hidden  lines 
is  helpful,  but  not  vital,  to  the  percep¬ 
tion  of  the  objects’  structures.  Perspec¬ 
tive  projection  and  the  motion  of  verti¬ 
ces  during  rotations  give  clues  about 
the  distance  of  points.  When  drawing 
objects  with  solid  faces,  removal  of 
surfaces  appearing  behind  other  sur¬ 
faces  is  very  important.  The  image  only 
makes  sense  to  our  eyes  if  “hidden 
surfaces”  remain  hidden. 

The  soxll  driver  does  not  perform 
hidden  surface  removal.  An  applica¬ 
tion  program  using  either  Xlib  or  the 
soxl  1  driver  can  do  some  hidden  sur¬ 
face  removal  before  drawing  polygons. 
A  program  can  detect  and  remove  the 
faces  of  objects  that  are  directed  away 
from  the  viewer.  A  vector  pointing  per¬ 
pendicularly  out  from  the  face  (a  “nor¬ 
mal”),  is  either  entered  as  part  of  the 
object  data,  or  computed  from  the  ver¬ 
tices  of  each  face.  Perspective  transfor¬ 
mation  is  applied  to  this  normal  vector. 
If  the  resulting  vector  has  a  negative  Z 
component,  then  the  face  is  on  the 
back  of  the  object  as  seen  from  this 
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viewing  position.  The  back  faces  can 
be  removed,  because  they  should  never 
be  visible.  Back  face  removal  detects  all 
hidden  surfaces  of  a  single  convex  ob¬ 
ject,  but  won’t  always  be  sufficient  for 
multiple  or  more  complicated  objects. 

Another  hidden  surface  removal 
method  that  can  be  applied  by  an  ap¬ 
plication  program  using  the  sox  11  driver 
is  called  the  “painter’s  algorithm.”  This 
consists  of  sorting  the  polygons  in  an 
object  so  that  the  most  distant  are  drawn 
first.  When  two  polygons  overlap  each 
other  on  the  display,  the  closer  poly¬ 
gon  will  be  drawn  last  and  will  cover 
up  the  more  distant  one.  The  faces  of 
the  object  drawn  by  the  example  pro¬ 
gram  in  Listing  One  have  been  sorted 
so  that  the  painter’s  algorithm  applies 
to  those  faces  that  are  not  back  faces. 
For  more  general  objects,  an  actual  sort¬ 
ing  of  the  faces  is  required. 

The  painter’s  algorithm  fails  if  faces 
pierce  through  each  other  or  if  a  group 
of  faces  are  arranged  to  form  a  cycle 
of  overlapping  polygons.  If  face  A  hides 
part  of  face  B,  face  B  hides  part  of  face 
C,  and  face  C  hides  part  of  face  A,  the 
polygons  cannot  be  sorted.  Another 
technique  must  be  used.  Two  possible 
methods  are  scan  line  hidden  surface 
removal  or  Z  buffering.  To  use  either 
of  these  techniques  with  Xlib  requires 
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that  the  conversion  from  vectors  and 
polygons  to  scan  lines  or  pixels  be 
done  by  the  client  program,  instead  of 
the  X  server.  If  an  application  must 
handle  graphics  of  such  complexity, 
an  approach  different  than  layering  on 
Xlib  may  have  to  be  used.  Peer-level 
interface  Starbase  drivers  perform  these 
hidden  surface  removal  operations 
quickly,  using  hardware  scan  conver¬ 
sion  and  Z  buffering. 

Summary 

The  X  Window  System  produces  rea¬ 
sonably  fast  and  visually  acceptable 
3-D  graphics.  Depending  on  applica¬ 
tion  requirements,  the  existing  Xlib  graph¬ 
ics  interface,  extensions  to  the  X  proto¬ 
col,  or  coexisting  peer-level  3-D  graph¬ 
ics  libraries  can  be  used  to  provide  a 
variety  of  capabilities,  performance 
ranges,  and  portability  levels.  Xlib  calls, 
which  provide  the  best  portability 
among  the  currently  available  X  imple¬ 
mentations,  can  be  used  to  implement 
most  features  of  existing  3-D  graphics 
libraries. 
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Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  92.) 

Vote  for  your  favorite  feature/artiole. 
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Interfaces 

Just  say  “no"  to  window  dressing 


Bob  Canup 


In  this  age  of  “user  friendly”  inter¬ 
faces  with  pop-up  windows,  pull¬ 
down  menus,  and  a  plethora  of 
moving  bars  in  almost  every  pro¬ 
gram,  you  may  question  why  I 
would  write  an  article  about  old-fash¬ 
ioned,  pick-a-number  menus.  The  an¬ 
swer  to  that  puzzle  is  that  the  pick-a- 
number  menu  has  some  powerful  sub¬ 
tleties  that  make  it  difficult  to  replace 
in  certain  computer  applications.  Pick-a- 
number  interfaces  are  the  easiest  inter¬ 
face  for  a  programmer  to  write  into  a 
program,  and  they  consume  the  least 
amount  of  computer  resources.  If  pick- 
a-number  interfaces  are  properly  coded, 
people  who  have  no  computer  experi¬ 
ence  can  use  them  easily.  In  addition, 
these  interfaces  allow  touch  typists  to 
work  without  moving  their  eyes  away 
from  the  screen. 

I  recently  had  the  misfortune  to  enter 
a  large  amount  of  data  into  a  mailing 
list  program  that  has  all  of  the  modern 
interface  fads  —  exploding  windows, 
function  keys,  moving-bar  menus, 
sound  effects,  and  Yes/No  confirmations 
(which,  amusingly,  used  function  keys, 
instead  of  the  Y  or  N  keys).  The  pro¬ 
grammer  obviously  had  devoted  a  great 
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deal  of  time  and  effort  to  the  interface 
portion  of  the  program.  The  reason 
that  I  said  “misfortune”  earlier  is  that 
in  any  programming  project  to  which 
a  given  amount  of  effort  is  made,  the 
effort  expended  in  glitter  and  gloss 
comes  at  the  expense  of  substance  and 
functionality.  With  the  program  in  ques¬ 
tion,  the  missing  functionality  was  the 
lack  of  a  means  to  handle  the  possi¬ 
bility  of  a  power  failure.  If  a  power 
failure  occurred  while  you  were  add¬ 
ing  data  to  the  mailing  list,  all  of  the 
data  in  the  mailing  list  would  be  lost. 
In  addition,  if  you  exited  the  program 
without  manually  closing  the  database, 
all  of  the  data  that  was  ever  entered 
into  the  program  would  be  lost.  The 
only  way  to  back  up  the  data  was  to 
use  the  user  manual  to  close  the  file, 
and  then  copy  the  data  file  to  a  differ¬ 
ent  file  name. 

Now  I’m  not  about  to  claim  that  the 
addition  of  a  pick-a-number  interface 
to  this  program  would  have  solved  the 
program’s  problems.  My  earlier  com¬ 
ment  about  the  trade-offs  that  can  be 
made  when  the  level  of  effort  is  fixed 
is  true,  but  it  is  also  true  that  all  too 
often,  the  level  of  effort  is  not  fixed. 
Given  an  easier  interface  to  write,  the 
programmer  simply  lowers  the  level 
of  effort  that  is  devoted  to  the  program. 
Nevertheless,  programmers  who  change 
to  a  simpler  user  interface  gain  more 
time  to  at  least  consider  what  they  are 
doing  with  the  rest  of  the  program. 

Programmers  write  complicated  user 


interfaces  for  a  number  of  reasons.  For 
one  thing,  a  fancier  interface  is  more 
challenging  to  write,  so  many  program¬ 
mers  find  it  more  interesting  to  code. 
A  three-ring-circus-style  interface  is  use¬ 
ful  for  impressing  compu-boobs,  and 
may,  in  some  cases,  sell  lots  of  pro¬ 
grams.  Most  programmers  don’t  under¬ 
stand  what  user  friendly  means,  so  they 
assume  that  it  means  something  that 
dazzles  the  eye.  Finally,  a  trendy,  fad¬ 
dish  program  interface  makes  the  soft¬ 
ware  look  modern  and  up-to-date. 

Pick-a-number  interfaces  are  appro¬ 
priate  in  the  following  circumstances: 
1.  You  are  writing  a  custom  program 
for  a  business,  and  the  program  will 
be  used  by  people  who  are  interested 
in  the  program’s  utility,  not  in  how 
flashy  the  program  appears;  2.  The  code 
will  be  used  by  many  people  who  may 
not  be  sophisticated  computer  users; 
3.  The  amount  of  time  needed  to  build 
the  finished  program  is  important;  4.  Com¬ 
puter  resources  are  limited;  5.  Speed 
and  error  prevention  are  important  in 
the  program. 

Pick-a-number  interfaces  are  not  ap¬ 
propriate  in  the  following  cases:  1.  The 
program  is  intended  for  use  by  man¬ 
agement  personnel  who  fancy  them¬ 
selves  as  “computer  literati”  and  who 
request  other  interfaces;  2.  The  pro¬ 
gram  is  game  software,  where  glitter 
and  gloss  is  the  whole  purpose;  3.  You 
are  trying  to  impress  someone  with 
your  programming  skill;  4.  Your  pro- 
(continued  on  page  41) 
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(continued  from  page  38) 
gram  really  doesn’t  do  much,  so  it  is 
necessary  to  cover  up  this  fact;  5.  You 
are  developing  a  program  for  commer¬ 
cial  distribution,  and  the  marketing  peo¬ 
ple  insist  upon  a  different  interface. 

The  80/20  Percent  Rule 

Granted,  it  is  possible  to  write  a  clumsy 
user  interface  in  any  technology.  De¬ 
spite  the  fact  that  the  interface  of  the 
mailing  list  program  mentioned  earlier 
offered  all  of  the  leading-edge  ways  of 
doing  things,  the  interface  was  awk¬ 
ward  and  slow  to  use.  I  generally  had 
to  step  through  three  levels  of  moving 
bars  in  order  to  do  what  1  wanted  to 
do  —  just  enter  data  and  print  mailing 
lists.  Of  course,  this  awkwardness  is 
also  true  of  most  pick-a-number  inter¬ 
faces.  Generally,  programmers  require 
users  to  wade  through  pages  of  menus 
before  the  users  are  allowed  to  do  what 
they  want  to  do.  The  reason  for  this 
phenomenon  is  that  it  is  just  as  difficult 
to  write  code  that  is  rarely  used  in  the 
program  as  it  is  to  write  code  that  will 
be  used  often.  As  a  result,  program¬ 
mers  give  equal  importance  in  the  user 
interface  to  both  often-used  and  rarely 
used  options. 

When  the  term  “user  friendly”  is  ap¬ 
plied  to  a  program,  it  means  that  the 


program  usually  does  just  what  the  user 
wants  it  to  do  with  a  minimum  amount 
of  fuss  and  bother  on  the  user’s  part. 
The  application  of  the  “80/20  percent 
rule”  to  menu  design  is  an  important 
part  of  creating  a  user-friendly  program. 
You  should  determine  what  will  be 
done  with  the  program  80  percent  of 
the  time,  and  then  devote  menu  op¬ 
tions  that  accomplish  exactly  these  func¬ 
tions  to  the  20  percent  of  the  code  that 
will  perform  them.  Then  place  the  most- 
■  used  options  at  the  front  of  the  menu. 
The  menu  shown  in  Example  1  illus¬ 
trates  this  approach.  (The  code  that 
generates  this  menu  is  shown  in  Listing 
One,  page  100.)  Most  of  the  time,  the 


Mailing  List  Menu 
(  Press  Esc  key  to  leave  program) 

1.  Enter  new  mail  list  data 

2.  Print  a  Zip  code  sorted  mail  list 

3.  Change  existing  data 

4.  Delete  a  single  address  from  the  list 

5.  Browse  through  the  existing  data 

6.  Backup  data 

7.  Print  a  mail  list  not  sorted  by  Zip 

8.  Perform  other  functions 

Enter  the  number  of  your  selection  and 
press  Enter  key: 


Example  1:  In  pick-a-number  inter¬ 
faces,  the  most  commonly  used  options 
should  be  available  early  in  the  menu 


user  will  pick  either  option  1  or  option 
2,  which  handle  the  primary  functions 
of  the  mailing  list  program. 

This  80/20  design  rule  leads  to  a 
program  that  users  usually  enjoy  work¬ 
ing  with  because  it  usually  does  just 
what  they  want  to  do  with  a  minimum 
amount  of  bother.  Also,  following  this 
rule  results  in  a  program  that  requires 
a  minimum  amount  of  training  for  the 
people  who  use  it.  I  have  found  it  far 
easier  to  teach  people  how  to  use  a 
program  designed  in  this  fashion,  than 
to  show  them  how  to  use  a  bell-and- 
whistle-style  interface.  Virtually  anyone 
who  can  read  can  learn  how  to  use  a 
program  that  is  designed  according  to 
the  80/20  rules.  I  maintain  that  suc¬ 
cessfully  learning  how  to  use  a  pro¬ 
gram  that  is  driven  by  a  moving  bar  or 
by  function  keys  requires  a  bit  more 
computer  experience. 

One  interesting  aspect  of  the  menu 
in  Example  1  is  the  requirement  that 
the  user  must  press  the  Enter  key  after 
a  menu  selection  is  entered.  When  I 
first  began  coding  menus  into  programs, 
I  designed  the  programs  so  that  the 
requested  function  was  performed  with¬ 
out  requiring  the  user  to  press  the  En¬ 
ter  key.  This  approach  limited  the  size 
of  the  menu  to  only  ten  functions  (0.  .9). 
In  addition,  the  users  were  uncertain 


about  whether  or  not  the  computer 
was  active. 

The  issue  of  consistency  in  data  in¬ 
put  is  also  related  to  this  Enter  key 
issue.  I  have  found  it  vital  to  always 
require  that  input  into  a  data  field  he 
followed  by  a  press  of  the  Enter  key. 
If  you  allow  a  user  to  skip  automati¬ 
cally  to  the  next  field  when  a  field  fills 
up,  but  you  require  the  user  to  press 
the  Enter  key  only  if  the  field  is  not 
filled,  then  the  preprocess  of  data  entry 
requires  constant,  conscious  checking 
on  the  part  of  the  person  who  enters 
the  data.  Additionally,  the  cursor  can 
be  placed  in  the  wrong  data  field  if  the 
user  tries  to  enter  more  data  than  a  field 
can  hold. 

Data  entry  can  never  become  a  sub¬ 
conscious,  automatic  task  because  the 
speed  of  data  entry  is  limited.  Subcon¬ 
scious  tasks  are  executed  much  more 
quickly  by  the  user  than  are  conscious 
tasks,  and  the  limited  data  entry  speed 
places  a  higher  level  of  stress  on  the 
data  entry  personnel.  Imagine  the  stress 
that  would  occur  during  the  process 
of  driving  if  stopping  the  car  some¬ 
times  required  you  to  press  the  brake 
pedal,  and  other  times  (if,  for  example, 
the  car  in  front  of  you  weighed  more 
than  3,800  pounds)  you  had  to  twist 
the  rearview  mirror  without  pressing 


the  brake  pedal.  It  may  appear  waste¬ 
ful  to  always  require  the  user  to  press 
the  Enter  key  after  data  entry  in  each 
field  is  finished,  but  the  technique  both 
substantially  speeds  up  the  data  entry 
process  and  increases  the  program’s 
ease  of  use. 

Pick-A-Number  Code 

I  am  basically  a  lazy  programmer  who 
wants  the  computer  to  do  as  much  of 
the  grunt  work  as  possible,  so  I  wrote 
code  that  automates  the  process  of  cen¬ 
tering  and  dividing  menu  data  into  col¬ 
umns,  and  provides  error  rejection  dur¬ 
ing  user  input.  (As  Robert  Heinlein  said, 
“Progress  is  not  made  by  early  risers, 
it  is  made  by  lazy  people  looking  for  an 
easier  way  of  doing  something.”)  The 
code  that  implements  these  functions 
is  written  in  Modula-2  and  has  been 
tested  with  the  Logitech  Modula-2  com¬ 
piler  (Version  3..0).  The  process  of  con¬ 
verting  this  code  so  that  it  can  run  with 
other  Modula  compilers  will  probably 
be  straightforward. 

The  procedure  Grab  in  the  module 
READA  (Listings  Two  and  Three,  page 
100  )is  a  general-purpose  data-field  en¬ 
try  routine  that  requires  a  press  of  the 
Enter  key  after  a  data  field  is  filled.  An 
alarm  sounds  if  an  attempt  to  overflow 
the  field  is  made.  The  procedure  Menu 


in  the  module  MENU  (Listings  Four 
and  Five,  pages  101  and  102)  imple¬ 
ments  pick-a-number  interfaces  for 
menus  that  contain  up  to  60  entries. 
This  procedure  centers  the  menu  items 
on  the  screen,  and  divides  the  menu 
entries  so  that  they  occupy  from  one 
to  four  columns  for  display. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  100.) 

Vote  for  your  favorite  feature/articie. 
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Self-Adjusting 
Data  Structures 


Use  self-adjusting  heuristics  to  improve  the 
performance  of  your  applications 


Andrew  M.  Liao 


Application  programs  are  often 
developed  using  standard  data 
structure  techniques  such  as 
stacks,  queues,  and  balanced 
trees  with  the  goal  of  limiting 
worst  case  performance.  Such  programs, 
however,  normally  carry  out  many  op¬ 
erations  on  a  given  data  structure.  This 
means  that  you  may  be  able  to  trade 
off  the  individual  worst  case  cost  of 
each  operation  for  that  of  the  worst 
case  cost  over  a  sequence  of  opera¬ 
tions.  In  other  words,  any  one  particu¬ 
lar  operation  may  be  slow,  but  the  av¬ 
erage  time  over  a  sufficiently  large  num¬ 
ber  of  operations  is  fast.  This  is  an 
intuitive  definition  of  amortized  time,  a 
way  of  measuring  the  complexity  of  an 
algorithm.  In  this  case,  the  algorithms 
to  be  concerned  with  are  those  that 
carry  out  operations  on  data  structures. 

The  heuristic  I’ll  discuss  in  this  arti¬ 
cle  is  called  the  “structural  self-adjust¬ 
ing  heuristic.”  To  illustrate  what  I  mean 

Andrew  received  his  master’s  degree  in 
computer  science  from  RPI  in  Troy, 
New  York.  He  can  be  reached  through 
his  Bitnet  address,  which  is  aliao%eagle 
@wesleyan.bitnet.  You  can  also  reach 
him  through  the  DDJ  office. 


by  self-adjusting,  consider  the  follow¬ 
ing  example:  Suppose  you’re  running 
an  information  warehouse  and  your 
task  is  to  distribute  information  to  peo¬ 
ple  who  request  it.  The  information  in 
this  warehouse  could  be  stored  in  a 
fixed  order,  such  as  the  order  of  infor¬ 
mation  in  a  library.  You  quickly  notice, 
however,  that  certain  pieces  of  infor¬ 
mation  are  requested  more  often  than 
others.  You  could  make  the  job  easier 
by  moving  the  most  often  requested 
information  close  to  the  service  counter. 
This  means  that  instead  of  having  to 
search  through  the  depths  of  the  ware¬ 
house  at  any  given  time,  you  have  a 
good  portion  of  the  most  requested 
information  nearby. 

As  this  example  suggests,  self-adjust¬ 
ing  heuristic  algorithms  are  ideally  suited 
to  lists,  binary  search  trees,  and  priority 
queues  (heaps).  In  lists,  the  heuristic 
attempts  to  keep  the  most  frequently 
accessed  items  as  close  to  the  front  as 
possible.  In  binary  search  trees,  the 
heuristic  attempts  to  keep  the  most  fre¬ 
quently  accessed  items  as  close  to  the 
root  as  possible,  while  preserving  the 
symmetric  ordering.  Finally,  in  heaps, 
the  heuristic  attempts  to  minimize  the 
cost  of  modifying  the  structure,  and 
partially  orders  the  heap  in  a  simple, 


uniform  way.  To  illustrate  how  these 
algorithms  can  be  implemented,  I’ve 
provided  sample  Pascal  source  code. 

Self-Adjusting  Lists 

A  singly  linked  list  is  a  group  of  records 
where  each  record  contains  one  field 
that  holds  an  individual  piece  of  user 
data,  and  another  field  that  holds  a 
pointer  to  the  next  record  in  the  list. 
An  initial  pointer  that  indicates  which 
record  starts  the  list  is  (or  should  be) 
kept.  This  pointer  enables  you  to  search, 
insert,  and  delete  operations. 

Move-to-Front  Singly  Linked  Lists 

To  understand  how  the  move-to-front 
(MTF)  approach  works,  consider  a  situ¬ 
ation  in  which  a  particular  application 
uses  an  open  hash  table  with  a  linked 
list  that  is  associated  with  each  array 
location.  Suppose  that  the  hashing  rou¬ 
tine  for  this  application  is  as  good  as  it 
can  possibly  be.  If  you  wish  to  improve 
the  search  performance  without  un¬ 
duly  complicating  the  supporting  code, 
however,  you  might  examine  the  per¬ 
formance  of  the  search  performed  on 
the  lists.  Chances  are  that  certain  ele¬ 
ments  are  accessed  more  often  than 
others.  The  use  of  either  a  transpose 
or  a  frequency  count  heuristic  (two 
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(continued  from  page  44) 
other  common  access  approaches)  does 
not  appear  to  be  a  good  idea  because 
of  the  search  overhead  involved  with 
each  approach.  Both  methods  require 
either  a  local  exchange  operation  or 
extra  searching  in  order  to  reinsert  an 
accessed  item  into  the  correct  part  of 
the  list.  Also,  the  count  method  re¬ 
quires  a  change  in  the  list:  The  addition 
of  an  integer  field  that  maintains  the 
access  count.  All  three  heuristics  are 
effective  in  that  they  search  less  than 
half  the  list. 

One  reason  why  the  MTF  heuristic 
performs  better  than  the  transpose 
method  is  that  the  transpose  heuristic 
causes  the  list  to  converge  more  slowly 
to  its  optimal  ordering.  In  the  case  of 
MTF,  an  element  is  brought  to  the  front 
of  the  list.  Furthermore,  such  an  element 
quickly  “sinks”  to  the  end  of  the  list  over 
the  course  of  a  sequence  of  accesses  if 
that  element  is  not  a  sufficiently  wanted 
item.  Essentially,  MTF  may  be  viewed 
as  an  optimistic  method  in  the  sense 
that  the  method  “believes”  that  an  ac¬ 
cessed  item  will  be  accessed  again. 
Analogously,  the  transpose  heuristic 
may  be  viewed  as  pessimistic  in  that  it 
“doubts”  that  an  accessed  item  will  be 
accessed  again.  The  count  method  is  a 
compromise  between  the  two. 

As  Figure  1  and  Listing  One  (page 
105)  illustrate,  searching  is  the  key  op¬ 
eration  for  the  MTF  heuristic.  This  search 
operation  is  very  much  like  a  normal 
search  on  a  singly  linked  list,  except 
that  an  extra  pointer  is  kept  to  the 
current  predecessor  of  the  list  node 
that  is  currently  being  examined.  Once 
a  given  item  is  found,  the  pointer  to  its 
predecessor  node  is  used  to  alter  the 
predecessor  node’s  link  field  so  that 
the  link  field  points  to  the  successor 
node  of  the  accessed  item.  The  link 
field  in  the  desired  node  is  then  altered 
to  point  to  the  first  element  in  the  list, 
and  the  head-of-list  pointer  is  set  to 
point  to  the  new  front-of-the-list  item. 
For  all  intents  and  purposes,  the  insert 
operation  is  a  push  operation  —  the 
new  item  is  immediately  put  at  the 
front  of  the  list.  Finally,  an  MTF  search 
is  used  to  perform  a  delete.  If  the  item 
to  be  deleted  is  located  at  the  front  of 
the  list,  that  item  is  removed  from  the 
front  of  the  list. 

Self-Adjusting  Heaps 

A  “heap”  is  a  tree-based  data  structure 
in  which  each  record  node  keeps  a 
key,  along  with  pointers  to  the  record 
node’s  successors.  The  heap  maintains 
an  ordering  of  items  such  that  every 
node  has  a  key  less  than,  or  equal  to, 
the  keys  of  the  node’s  successors.  This 
last  description  is  the  concept  of  “heap¬ 


ordering.” 

There  are  a  number  of  classical  pri¬ 
ority  queue  structures  (such  as  2  -  3 
trees,  leftist  heaps,  and  binomial  heaps) 
that  are  amenable  to  fast  merging  opera¬ 
tions.  Of  these,  the  simplest  scheme  for 
maintaining  a  heap  with  fast  merge 
operations  is  the  “leftist  heap,”  which 
was  developed  to  maintain  partially  or¬ 
dered  lists  with  a  logarithmic  time- 
merge  operation.  A  leftist  heap  is  based 
upon  a  binary  tree  node  that  contains 
rank,  weight,  and  two  pointer  fields  (to 
indicate  left  and  right  children).  The 
rank  field  is  defined  to  be  0  if  a  node 
is  a  leaf.  Otherwise,  the  rank  field  is 
defined  as  one  more  than  the  mini¬ 
mum  value  of  both  the  rank  of  the 


leftchild  and  the  rank  of  the  rightchild. 

A  binary  tree  is  a  leftist  heap  if  it  is 
heap-ordered  and  if  the  rank  of  a  given 
leftchild  is  greater  than,  or  equal  to,  the 
rank  of  its  rightchild  sibling.  The  prob¬ 
lem  with  maintaining  leftist  heaps  is 
that  the  configuration  of  the  data  struc¬ 
ture  is  based  upon  the  rank  definition. 
All  operations  are  heavily  dependent  upon 
the  value  kept  in  the  rank  field  of  a  given 
node.  To  illustrate  the  point,  I’ll  de¬ 
scribe  the  leftist  heap  merge  operation. 

The  leftist  heap  merge  operation  is 
made  possible  by  a  modified  version 
of  an  “enqueue”  process  (which  takes 
a  heap  and  a  queue  pointer’s  record 
as  parameters).  This  particular  enqueue 
operation  saves  the  root  of  the  heap 
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(continued  from  page  46) 
and  moves  the  front  queue  pointer 
down  to  the  rightchild  of  the  root  just 
saved.  You  then  break  the  link  be¬ 
tween  the  saved  root  and  its  rightchild. 
If  the  queue  pointers  are  both  empty, 
point  the  front  and  rear  pointers  to  the 
root  node  that  was  just  saved,  and  set 
the  rightchild  pointer  field  of  the  root 
to  empty.  Otherwise,  point  the  rightchild 
pointer  to  the  node  currently  pointed 
to  by  the  rear  queue  pointer,  and  point 
the  rear  queue  pointer  to  this  newly 
obtained  node. 

Implement  the  merge  with  the  fol¬ 
lowing  steps:  While  neither  of  the  two 
heaps  being  merged  is  empty,  call 
enqueue  with  the  currently  minimum 
key  and  with  the  queue  pointer’s  rec¬ 
ord.  Next,  while  the  “first”  heap  is  not 
empty,  call  enqueue  with  that  heap 
and  with  the  queue  pointer’s  record. 
Perform  the  same  steps  for  the  other 
heap.  These  three  processes  merge  the 
right  path.  Complete  the  process  with 
a  bottom-up  traversal  of  the  right  path 
in  order  to  fix  up  the  rank  fields  and 
to  perform  any  necessary  swaps  to  main¬ 
tain  the  structural  invariant. 

Now  point  to  the  current  two  bot¬ 
tommost  nodes  on  the  merge  path.  If 
there  is  no  left  sibling  of  the  bottom¬ 
most  node,  make  the  rightchild  a 


leftchild  and  set  its  parent’s  rank  field 
to  0.  Next,  set  the  rightchild’s  rightchild 
pointer  field  to  empty.  If  the  bottom¬ 
most  node  has  a  left  sibling,  compare 
the  two  children  and  swap  them  when 
the  rank  of  the  left  sibling  is  less  than 
that  of  the  right  sibling.  In  any  event 
(given  this  case),  set  the  parent’s  rank 
field  to  1+  rank  of  the  rightchild.  Also 
note  which  nodes  are  the  next  two 
bottommost  nodes  on  the  merge  path 
at  this  point,  and  make  sure  that  the 
parent  node  before  this  step  points  to 
the  rightchild.  This  process  continues 
until  the  root  is  reached  when  the  root 
of  the  new  heap  is  returned.  Once  the 
merge  operation  for  leftist  heaps  has 
been  described,  the  other  heap  opera¬ 
tions  are  easy  to  implement. 

This  description  of  the  merge  opera¬ 
tion  suggests  that  two  passes  are  re¬ 
quired  over  the  merge  path.  The  ques¬ 
tion  remains:  How  do  you  improve 
performance  without  unduly  compli¬ 
cating  the  algorithms  that  maintain  the 
heap?  This  can  be  done  with  a  restruc¬ 
turing  method  that  essentially  exchanges 
every  node  on  the  result  heap’s  right 
path  with  the  node’s  left  sibling.  The 
version  of  the  technique  presented  here 
also  has  a  feature  in  which  one  top- 
down  pass  completes  the  merge.  The 
resulting  structure,  called  a  “top-down- 


skew  heap,”  is  a  self-adjusting  analog 
of  the  leftist  heap. 

Top-Down-Skew  Heaps 

A  skew  heap  is  based  upon  a  simple 
binary  tree  node  that  contains  a  weight 
plus  pointer  fields  to  left  and  right  chil¬ 
dren.  The  process  of  merging  is  made 
possible  by  another  modified  version 
of  the  enqueue  algorithm.  In  this  case, 
it’s  not  necessary  to  maintain  the  rank/ 
balance  field  in  order  to  obtain  loga¬ 
rithmic,  amortized  performance. 

This  particular  enqueue  operation 
saves  the  root  of  the  heap  and  moves 
the  front  queue  pointer  down  to  the 
rightchild  of  the  root  just  saved.  You 
then  break  the  link  between  the  saved 
root  and  its  rightchild  by  changing  the 
current  leftchild  into  a  rightchild.  If  the 
queue  pointers  are  both  empty,  point 
the  front  and  rear  pointers  to  the  root 
node  just  saved,  and  set  the  root’s 
leftchild  pointer  to  empty.  Otherwise, 
the  newly  obtained  node  becomes  the 
leftchild  of  the  node  that  is  currently 
indicated  by  the  rear  queue  pointer, 
after  which  the  rear  queue  pointer  is 
changed  to  indicate  the  newly  obtained 
node.  (See  Figure  2.) 

The  following  steps  implement  the 
merge:  While  neither  of  the  two  heaps 
being  merged  is  empty,  call  enqueue 


q 


qi  q2 


(d)  Next  to  last  merge  step 


qi 


q2 


(e)  Last  node  merged  to 
result  heap 


(f)  Resulting  heap 
after  the  merge 


Figure  2:  Merging  two  skew  heaps 
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(continued  from  page  48) 
with  the  heap  that  contains  the  current 
minimum  key  and  the  queue  pointer’s 
record.  Next,  while  the  “first”  heap  is 
not  empty,  call  enqueue  with  that  heap 
and  with  the  queue  pointer’s  record. 
Follow  the  same  process  for  the  other 
heap.  (This  approach  is  analogous  to 
Tarjan  and  Sleator’s  conceptual  noting 
that  the  left  and  right  children  of  every 
node  on  the  merge  path  are  swapped. 
The  implementation  used  here,  how¬ 
ever,  is  a  variation.)  Once  either  of  the 
two  heaps  being  merged  becomes 
empty,  merely  attach  the  remaining  heap 
to  the  bottom  of  the  result  heap’s  left 
path.  Again,  the  rest  of  the  heap  opera¬ 
tions  are  easy  to  define. 

Pairing  Heaps 

Much  like  the  leftist  heap,  the  binomial 
heap  has  an  analogous  self-adjusting 
counterpart.  This  new  structure,  called 
the  “pairing  heap,”  is  a  recent  develop¬ 
ment  in  heaps  that  supports  the  de- 
creaseKey  operation .  The  essential  defi¬ 
nition  of  the  pairing  heap,  like  that  of 
the  skew  heap,  is  based  upon  a  simple 
binary  tree  record  node  that  contains 
at  least  weight  plus  three  pointer  fields 
(to  indicate  the  parent  and  the  left  and 
right  siblings).  Like  most  heaps,  the 
pairing  heap  depends  upon  a  merge 
operation,  but  has  a  less  complicated 
scheme  than  its  classical  counterpart. 

In  the  case  of  the  binomial  heap,  you 
need  to  maintain  a  forest  of  trees  where 
each  tree  contains  a  number  of  nodes 
equal  to  a  non-negative  integer  power 
of  two.  Thus,  a  binomial  heap  of  n 
items  can  be  represented  by  a  forest  in 
which  each  tree  corresponds  one-to- 
one  with  the  one  bit  that  represents  the 
value  of  n  in  binary.  (This  eventually 
leads  to  the  fact  that  all  of  the  binomial 
heap  operations  are,  in  the  worst  case, 
logarithmic  time.)  Needless  to  say,  the 
code  needed  to  implement  a  binomial 
heap  merge  operation  is  complicated 
and  difficult  to  maintain. 

The  merge  operation  for  pairing 
heaps  begins  by  determining  which  of 
the  two  heaps  has  the  minimal  weight 
at  the  root.  The  heap  with  the  non¬ 
minimum  key  at  the  root  then  becomes 
the  child  at  the  root  of  the  other  heap. 
The  heap  that  is  being  made  into  a 
subtree  points  its  root  node  right  sib¬ 
ling  pointer  to  the  child  of  the  root  of 
the  other  heap.  Furthermore,  the  first 
heap’s  parent  pointer  is  set  to  the  new 
heap  root,  and  the  new  heap  root  points 
its  leftchild  pointer  to  the  root  of  the 
heap  that  is  being  made  into  a  subtree. 
The  merge  operation  returns  the  root 
of  the  new  heap.  (See  Figure  3-) 

Given  the  above  definition  of  the 
merge  operation,  the  DeleteMin  opera¬ 
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tion  (see  Figure  4  and  Listing  Three, 
page  106)  is  easy  to  describe.  I  will 
describe  the  front-back  one-pass  vari¬ 
ation  here.  To  begin,  save  the  root  node 
and  keep  a  pointer  to  the  leftchild. 
Next,  empty  the  pointer  to  the  root. 
While  subtrees  are  linked  to  the  leftchild 
of  the  root,  remove  trees  in  pairs  (be¬ 
ginning  with  the  leftchild)  and  merge 
the  trees,  then  merge  the  result  to  the 
heap  pointed  to  by  the  root  pointer. 
Repeat  this  step  until  there  are  no  more 
trees.  (The  pairing  heap  derives  its  name 
from  the  restructuring  operation  that 
takes  place  during  a  DeleteMin .) 

Describing  the  DecreaseKey  opera¬ 
tion  for  pairing  heaps  (see  Figure  5)  is 
just  as  easy.  This  operation  assumes 
that  you  have  direct  access  to  the  node 


argl  arg2 


(a)  Heaps  before 
merging 


argl  arg2 


(b)  After  one  step  of 
the  merge 


argl  arg2 


(c)  Another  merge 
step 


root  (function  return) 


(d)  Resulting  heap 


Figure  3'-  Merging  two  pairing  heaps 
Dr.  Dobb’s Journal,  February  1990 


whose  weight  field  is  being  decreased, 
to  a  root  to  the  heap  that  contains  the 
node,  and  to  the  value  by  which  you 
wish  to  decrease  the  weight.  Go  to  the 
parent  of  the  node  that  is  being  oper¬ 
ated  on,  and  then  go  to  the  leftchild  of 
that  parent.  Scan  along  the  right  sibling 
list  to  find  the  predecessor  of  the  node 
that  will  be  operated  upon.  When  the 
predecessor  is  located,  clip  out  the  tree 
rooted  at  the  node  upon  which  you 
wish  to  carry  out  the  actual  Deer ease- 
Key  operation.  To  clip  out  the  tree,  link 
around  the  node  in  question.  If  the 
node  is  a  leftchild,  make  its  right  sib¬ 
ling  the  new  leftchild.  Now  decrease 
the  weight  and  merge  the  tree  that  is 
rooted  at  the  node  with  the  root  of  the 
pairing  heap. 

The  simple  local  restructuring  heu¬ 
ristics  presented  here  provide  an  ele¬ 
gant  approach  to  the  development  of 
heap  structures.  In  fact,  these  heaps 
are  simpler  to  understand  and  to  im¬ 
plement  than  either  the  leftist  or  bino¬ 
mial  heaps.  Furthermore,  indications 
are  that  self-adjusting  heaps  are  just  as 
competitive  in  practice  as  their  classi¬ 
cal  counterparts.  In  any  event,  I’ve  pre¬ 


sented  two  very  different  (though  ef¬ 
fective)  local  restructuring  heuristics. 
The  first  heuristic  reorganizes  lists  in 
order  to  make  frequently  requested  list 
items  more  accessible.  The  second  heu- 

Self-adjusting  heuristic 
algorithms  are  ideally 
suited  to  be  used  with 
lists,  binary  search  trees, 
and  priority  queues 
(heaps) 


ristic  applies  a  simple  local  restructur¬ 
ing  method  (in  place  of  maintaining 
balance/accounting  data  and  resolving 
special  structural  cases)  in  order  to 
quickly  maintain  both  the  structure  and 
the  partial  ordering  of  a  heap. 

Now  let’s  consider  an  efficient  self- 
adjusting  heuristic  for  binary  search 


trees.  This  algorithm  makes  frequently 
requested  items  in  the  tree  more  easily 
accessible,  and  quickly  maintains  both 
the  structure  and  the  sorted  ordering 
of  the  tree. 

Self-Adjusting  Binary  Search  Trees 

In  a  “binary  search  tree,”  each  node 
keeps  a  key  along  with  two  pointers 
to  the  node’s  successors.  The  ordering 
is  such  that  if  a  node  has  key  K,  every 
node  in  that  node’s  left  subtree  must 
have  keys  less  than  K,  and  every  node 
in  its  right  subtree  must  have  keys 
greater  than  K.  This  is  known  as  “sym¬ 
metric  ordering.”  The  performance  costs 
of  generic  binary  search  tree  operations 
are,  in  the  worst  case,  logarithmic  time 
(if  the  input  data  is  sufficiently  ran¬ 
dom).  Such  a  tree  may  also  degenerate 
as  a  result  of  insertions  and  deletions, 
and  yield  steadily  poorer  performance. 

The  process  of  tree  degeneration  has 
led  to  the  development  of  various 
height/weight  balanced  trees  and  B- 
tree  schemes.  Although  these  various 
schemes  guarantee  logarithmic  worst 
case  times  per  operation,  some  of  the 
schemes  are  not  as  efficient  as  possible 


Figure  4:  DeleteMin  process  on  a  pairing  heap 
Dr.  Dobb’s Journal,  February  1990 
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under  nonuniform  access  patterns.  Fur¬ 
thermore,  many  of  these  schemes  re¬ 
quire  extra  space  for  balance/account¬ 
ing  information,  and  the  need  to  keep 
this  information  current  tends  to  com¬ 
plicate  maintenance  of  the  data  struc¬ 
ture.  Certain  cases  must  be  checked 
on  each  update,  thus  incurring  a  large 
overhead. 

Rotation  is  the  key  technique  that 
makes  some  of  the  balanced  and  previ¬ 


ous  self-adjusting  tree  schemes  possi¬ 
ble.  In  fact,  rotation  plays  a  part  in  the 
implementation  of  the  splay  tree.  Be¬ 
fore  this  discussion  continues,  it  is  nec¬ 
essary  to  understand  how  a  right  rota¬ 
tion  and  a  left  rotation  at  any  node  of 
a  binary  tree  are  performed. 

As  Listing  Two  (page  105)  shows, 
you  implement  a  right  rotation  with  the 
following  steps:  If  the  pointer  to  a  start¬ 
ing  root  of  some  tree  is  not  empty  and 


that  node  has  a  left  subtree,  save  the 
pointer  to  the  root  and  then  save  the 
pointer  to  the  right  subtree  of  the  initial 
left  subtree.  Then  make  the  pointer  to 
the  initial  left  subtree  the  new  starting 
root  pointer,  and  let  the  original  root 
be  the  rightchild  of  the  new  root.  Fi¬ 
nally,  designate  the  pointer  to  the  saved 
rightchild  of  the  original  leftchild  as  a 
leftchild  of  the  new  root’s  rightchild 
(which  is  the  original  root). 

Implement  a  left  rotation  in  a  similar 
manner.  If  the  pointer  to  a  starting  root 
of  some  tree  isn’t  empty,  and  that  node 
has  a  right  subtree,  save  the  pointer  to 
the  root  and  then  save  the  pointer  to 
the  left  subtree  of  the  initial  right  sub¬ 
tree.  Then,  designate  the  pointer  to  the 
initial  right  subtree  as  the  new  starting 
root  pointer,  and  let  the  original  root 
be  the  leftchild  of  the  new  root.  Finally, 
designate  the  pointer  to  the  saved 
leftchild  of  the  original  rightchild  as  a 
rightchild  of  the  new  root’s  leftchild 
(which  is  the  original  root). 

The  drawbacks  of  many  of  the  effi¬ 
cient  search  tree  techniques  motivated 
the  development  of  the  splay  tree.  Be¬ 
cause  binary  search  trees  maintain 
sorted  sets,  the  question  arose  as  to 
whether  the  speed  of  the  search  pro¬ 
cess  could  be  improved  if  certain  items 
had  a  higher  request  frequency  than 
others.  In  an  attempt  to  improve  per¬ 
formance,  Allen,  Munro,  and  Bitner  pro¬ 
posed  two  self-adjusting  techniques  on 
search  trees  during  the  late  1970s.  The 
gist  of  the  first  scheme  is  a  single  rota¬ 
tion  of  the  item  accessed  towards  the 
root.  The  second  scheme  involves  mul¬ 
tiple  rotations  of  the  accessed  item  all 
the  way  to  the  root.  The  techniques  are 
analogous  to  the  variations  of  the  trans¬ 
pose  methods  for  singly  linked  lists. 
Neither  heuristic  is  efficient  in  the  am¬ 
ortized  sense,  since  long  access  se¬ 
quences  exist  where  the  time  per  ac¬ 
cess  is  linear.  It  is  thus  clear  that  the 
search  paths  to  frequently  accessed 
items  need  to  be  as  short  as  possible. 
Tarjan  and  Sleator’s  proposed  self-ad¬ 
justing  heuristic  halves  the  depth  of 
each  node  on  the  path  to  an  accessed 
item  when  the  item  is  finally  moved  to 
the  root.  A  splay  tree  is  a  binary  search 
tree  that  employs  this  heuristic. 

Splay  Trees 

The  proposed  self-adjusting  heuristic 
has  two  versions.  The  “bottom-up  splay” 
is  appropriate  if  you  already  have  di¬ 
rect  access  to  the  node  that  is  to  be 
moved  to  the  root.  Heuristic  restructur¬ 
ing  occurs  during  the  second  pass  back 
up  the  search  path  (assuming  that  the 
first  pass  down  the  tree  is  performed 
.  in  order  to  find  the  item).  The  second 
I  version  of  the  proposed  self-adjusting 


root 


root 


(a)  Pairing  Heap  before 
DecreaseKey  operation 
(note  the  parent 
pointers).  Also,  "p"  is 
the  direct  pointer  to  the 
node  having  its  key 
decreased,  "temp”  will 
be  used  to  find  that 
node's  left  sibling. 


root 


temp 


root 


(e)  Link  around  node 
with  decreased  key  (i.e. 
clip  out  that  subtree). 


root 


temp 


(f)  Subtree  with 
decreased  key  clipped 
out 


(c)  Searching  for  the  left 
sibling... 


(g)  Remerge  subtree 
back  into  main  tree 


Figure  5:  DecreaseKey  process  on  a  pairing  heap 
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(continued  from  page  54) 
heuristic,  called  a  “top-down  splay,”  is 
an  efficient  variation  of  the  process 
used  to  carry  out  Tarjan  and  Sleator’s 
self-adjusting  heuristic.  This  variant  re¬ 
quires  a  pointer  to  the  tree  (call  it  7), 
that  points  to  the  current  node  to  be 
examined  during  the  search.  This  heu¬ 
ristic  also  requires  two  double  pointer, 
records,  called  L  and  R  (for  left  and 
right  subtrees),  that  point  to  all  items 
less  than  or  greater  than  the  node  at  T. 
Figure  6  describes  this  step. 

As  illustrated  in  Figure  7,  the  splay¬ 
ing  process  repeatedly  applies  one  of 
the  appropriate  cases  until  there  are 
no  more  cases  to  apply.  At  this  point, 
the  leftchild  of  the  remaining  root  is 
attached  to  the  bottom  right  of  L,  and 
the  rightchild  is  attached  to  the  bottom 
left  of  R.  The  final  step  points  the 
leftchild  of  the  final  remaining  root  to 
the  subtrees  kept  by  Z,  and  points  the 
rightchild  to  the  subtrees  kept  by  R. 
(Unlike  the  bottom-up  variation,  the 
top-down  heuristic  includes  the  splay 
step.)  When  the  search/access  for  a 
requested  node  fails,  change  the  last 
node  on  the  search  path  into  the  root 
of  the  tree.  This  step  makes  the  defini¬ 
tion  of  all  of  the  other  operations 
very  easy. 

To  search  for  a  node,  simply  apply  the 


Case  1  (Top-Down  Zig): 

If  x  is  the  root  of  T  and  y  is  the 
accessed  item  (with  x=parent(y) 
then  if  y  is  a  leftchild,  then  break 
the  link  from  x  to  y  and  add  x 
to  the  bottom  left  of  R  (else  if  y 
is  a  rightchild,  add  x  to  the  bot¬ 
tom  right  of  L)  and  nowT  points 
to  y,  the  new  root. 

Case  2  (Top-Down  Zig-Zig): 

If  x  is  the  root  of  T  and  y 
(child(x)=y=parent(z))  and  z  are 
both  leftchildren  (or  both  right- 
children)  then  do  a  rotation  to 
the  right  (or  symmetrically,  a 
rotation  to  the  left),  break  the 
link  from  y  to  z  and  attach  y  to 
the  bottom  left  of  R  (else  bot¬ 
tom  right  of  R)  and  now  T  points 
to  z,  the  new  root. 

Case  3  (Top-Down  Zig-Zag): 

If  x  is  the  root  of  T  and  y  is  a 
leftchild  of  x  and  z  s  a  rightchild 
of  y  (or  y  is  a  rightchild  of  x  and 
z  s  a  leftchild  of  y),  break  the 
link  from  x  to  y  and  attach  x  to 
the  bottom  left  of  R  (else  the 
bottom  right  of  L),  break  the 
link  from  y  to  z  and  attach  y  to 
the  bottom  right  of  L  (else  the 
bottom  left  of  R)  and  now  T 
points  to  z,  the  new  root. 


searching  process  as  described  earlier. 
The  process  of  insertion  involves  search¬ 
ing  for  the  key  Vto  be  inserted.  If  Uis 
less  than  the  key  at  the  root,  make  the 
node  that  contains  V  point  its  leftchild 
pointer  to  the  leftchild  of  the  root  (which 
breaks  the  link  from  the  root  to  that 
leftchild),  and  point  the  rightchild 
pointer  to  the  root.  Otherwise,  the  left- 
child  pointer  of  the  node  that  contains 
V points  to  the  root,  and  the  rightchild 
pointer  points  to  the  rightchild  of  the 
root  (and  the  link  from  the  root  to  the 
rightchild  is  broken).  The  insertion  step 
is  completed  by  designating  the  node 
that  contains  Uas  the  root. 

The  split  operation  is  essentially  the 
process  of  breaking  the  tree  at  the  root 
in  the  manner  described  in  the  descrip¬ 
tion  of  the  insertion  process.  The  pro¬ 
cess  of  deletion  is  just  as  easy.  Perform 
the  splay  search  from  the  key  to  be 
deleted.  If  the  root  does  not  contain 
the  node  with  the  key  to  be  deleted, 
nothing  happens.  If  the  root  does  con¬ 
tain  the  node  with  the  key  to  be  de¬ 
leted,  keep  pointers  to  the  two  sub¬ 
trees  at  the  root,  perform  a  splay  search 
for  the  maximum  key  in  the  left  subtree 
(and  designate  the  root  of  the  left  sub¬ 
tree  as  the  new  root),  and  point  the 
rightchild  pointer  of  the  root  to  the 
right  subtree.  The  join  operation  of  two 


binary  search  trees  (assuming  that  all 
items  in  Tree  1  are  less  than  those  in 
Tree  2)  is  simply  the  non-no  operation 
of  the  delete  algorithm  just  described. 

The  self-adjusting  heuristic  provides 
an  alternative  to  the  standard  balancing/ 
accounting  worst-case  asymptotic  so¬ 
lutions  used  to  develop  efficient  pro¬ 
grams  —  and  may,  in  fact,  be  the 
method  of  choice.  Furthermore,  the  al¬ 
gorithms  to  maintain  these  self-adjust¬ 
ing  data  structures  are  both  conceptu¬ 
ally  easy  to  understand  and  simple  to 
implement  in  practice. 

In  which  applications  could  these 
data  structures  be  used  to  improve  per¬ 
formance?  Some  possibilities  are  sym¬ 
bol  table  management  applications 
(MTF  lists,  splay  trees,  and  possibly  in 
conjunction  with  hashing  schemes), 
graph  algorithms  (skew  and  pairing 
heaps,  particularly  with  respect  to  find¬ 
ing  minimum  spanning  trees  and  the 
shortest  paths  in  graphs),  and  other 
network  optimization  algorithms  (such 
as  splay  trees,  particularly  in  maximum/ 
minimum  network  flow  algorithms).  Re¬ 
cent  work  by  Jones,  Bern,  and  de  Car¬ 
valho,  as  well  as  my  own  work,  indi¬ 
cates  that  some  of  the  self-adjusting 
data  structures  do  seem  to  perform  bet¬ 
ter  in  practice  than  do  conventional 
data  structures. 


Figure  6:  The  top-down  splay  step 
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(c)  "Link-left"  step.. 
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(d)  "Link-right”  step 


Left  Right 


(e)  Another  "link-left” 
step;  and  item  17  found 


(f)  Reassemble  step. 

Note;  if  17  itself  had  children 
previous  to  the  final  assembly,  the 
potential  leftchild  of  1 7  would  have 
become  the  rightmost  child  of  the 
eventual  left  subtree.  Similarly, 
the  potential  rightchild  of  1 7  would 
have  become  the  leftmost  child  of 
the  eventual  right  subtree. 


Figure  7:  Finding  Item  #1 7  in  a  binary  search  tree  using  the  splay-move-to-root  heuristic 
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Multiplexing  Error 

Codes 


Improve  error  diagnosis 


William  J.  McMahon 


Diagnosing  unexpected  errors 
can  be  one  of  the  most  frus¬ 
trating  and  troublesome  as¬ 
pects  of  software  develop¬ 
ment.  Even  the  most  well- 
designed  software  can  have  minor  flaws 
that  have  catastrophic  consequences. 
The  actual  symptoms  often  give  no 
clue  as  to  the  nature  of  the  defect. 
Worse,  they  may  even  be  difficult  to 
reproduce,  particularly  if  the  bug  is 
reported  from  the  field. 

A  programmer  can  often  spend  hours, 
if  not  days,  iterating  through  many  cy¬ 
cles  of  program  modification  and  test¬ 
ing  to  track  down  even  a  small  defect. 
Fortunately  there  are  many  tools  and 
techniques  to  help.  Interactive  debug¬ 
gers,  code  interpreters,  built-in  debug 
code,  and  robust  error  handling  within 
the  program  itself  are  all  useful,  but 
each  has  its  limitations. 

All  but  the  last  of  the  techniques  just 
mentioned  require  that  the  program 
be  run  again  to  duplicate  the  error  in 
question.  But  this  is  not  always  con¬ 
venient  or  possible.  In  such  cases,  how 
the  program  deals  with  an  unexpected 
error  the  first  time  it  occurs  becomes 
extremely  important.  If  the  error  is  re¬ 
ported  in  such  a  way  that  the  program¬ 
mer  can  close  in  on  it  with  that  infor- 


William  is  a  senior  programmer  for 
Digital  Products  Inc.  and  can  be 
reached  at  108  Water  Street,  Water- 
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mation  alone,  much  time  can  be  saved. 
The  major  problem  with  unexpected 
errors  is,  of  course,  that  they  are  unex¬ 
pected  and  therefore  impossible  to  han¬ 
dle  specifically.  They  require  a  system¬ 
atic  approach. 

For  systematic  error  handling  to  be 
effective,  it  has  to  be  used  widely  and 
consistently.  As  a  practical  matter,  this 
means  that  error  handling  cannot  re¬ 
quire  much,  if  any,  extra  work  from  the 
programmer. 

This  leaves  us  with  two  apparently 
conflicting  goals:  Providing  enough  in¬ 
formation  to  easily  diagnose  unexpected 
errors  wherever  they  occur,  while  add¬ 
ing  little  or  no  extra  work  to  the  origi¬ 
nal  programming  task.  The  following 
is  a  description  of  a  scheme  I  have 
used  to  do  just  that. 

unsigned  mid_level (char  *parm) 

{ 

unsigned  err,  low_level(); 
if  (parm  ==  NULL) 
return  (1); 

err  =  low_level(i,  j); 
if  (err) 

return  (ERR_COMBINE (err,  3)); 
return  (0) ; 

} 

unsigned  low_level (int  x,  int  y) 

{ 

if  (x  >  0) 

return  (1) ; 
if  (x  >  y) 

return  (2) ; 

return  (0) 

} _ 

Example  1:  Combining  codes  and 
returning  to  the  next  level 


Overview 

The  error  handling  system  presented 
here  hinges  on  function  communica¬ 
tion.  Functions  that  use  this  scheme 
will  return  an  error  code.  A  return  value 
of  zero  is  used  to  indicate  success, 
while  a  non-zero  return  indicates  some 
sort  of  failure.  Exception  handling  logic 
can  then  be  processed  whenever  such 
a  function  returns  a  non-zero  value.  In 
most  cases  the  exception  processing 
amounts  to  returning  an  indication  of 
failure  to  the  calling  function.  Because 
most  low-level  functions  do  not  know 
the  context  in  which  they  were  called, 
they  cannot  deal  with  the  error  directly. 

The  failure  returns  back  through  sev¬ 
eral  levels  of  functions  until  it  is  finally 
dealt  with  in  some  way.  If  it  is  an  unan¬ 
ticipated  error,  the  program  will  prob¬ 
ably  abort  with  some  sort  of  error  mes¬ 
sage.  To  be  able  to  trace  the  root  cause 
of  the  error,  we  need  to  be  able  to 
identify  its  source  and  preserve  the  logic 
path  to  it. 

To  do  that  this  scheme  associates 
each  possible  error  condition  within  a 
function  with  a  numeric  code.  At  the 
lowest  level  that  numeric  value  is  sim¬ 
ply  returned.  At  each  subsequent  re¬ 
turn  the  return  value  is  combined  with 
another  numeric  code.  This  uniquely 
identifies  each  return,  preserving  the 
path  to  the  original  failure.  Because  the 
path  is  preserved,  the  numeric  code 
needs  to  be  unique  only  within  each 
function. 
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(continued  from  page  60) 

Consider  the  following  example:  The 
original  error  causes  the  return  of  an 
error  code.  This  code  uniquely  identi¬ 
fies  the  location  of  the  error  within  that 
function.  After  testing  the  return  value 
of  the  function,  the  calling  function 
also  generates  an  error  code  that 
uniquely  identifies  the  location  of  that 
call  within  that  function. 

The  two  codes  are  combined  and 
returned  to  the  next  level.  This  process 
is  repeated  at  each  level  until  the  error 
is  either  handled  or  the  program  is 
aborted.  The  code  fragment  in  Exam¬ 
ple  1  shows  how  this  might  work.  Note 
that  the  function  mid_level  can  return 
both  an  individual  error  code  (if  parm 
is  NULL)  or  a  combined  error  code  (if 
low_level returns  an  error). 

The  fact  that  the  individual  error  num¬ 
bers  are  hard  coded  might  seem  to 
violate  good  programming  practice,  but 
because  they  must  be  unique  within 
each  function,  they  should  be  hard 
coded. 

Combining  Codes 

The  actual  combining  of  error  codes  is 
done  with  the  macro  ERR_  COMBINE, 
which  is  the  key  to  this  scheme.  Com¬ 
bining  error  codes  must  be  done  in 
such  a  way  that  they  can  be  later  sepa¬ 
rated  and  decoded. 

Consider  the  simple  scheme  where 
the  ERR_COMBINE  macro  is  defined 
as  in  Example  2.  Multiplying  the  origi¬ 
nal  code  by  ERR_BUMPER  before  add¬ 
ing  the  new  number,  shifts  the  original 


♦define  ERR_BUMPER  10 

#define  ERR_COMBINE (orig,  to_add)  ( (orig  * 
ERR  BUMPER)  +  to_add) 


Example  2:  Defining  a  simple  ERR, 
COMBINE  macro 


void  err_print (FILE  *stream,  unsigned  err_code) 
{ 

do 

{ 

fprintf (stream,  "%d",  (err_code  % 

ERR  BUMPER)); 

} 

while  ( (err_code  /=  ERR_BUMPER)  >  0); 

} _ 

Example  3:  This  function  will  decode 
the  combined  error  code  and  display 
the  individual  codes 


main {) 

{ 

unsigned  err,  function (); 

err  =  function  (); 
if  (err) 

abort (ERR_COMBINE (err,  3) ) ; 

} 

void  abort (unsigned  err_code) ; 

{ 

fprintf (stderr,  "\n  ERROR:"); 
err_printf (stderr,  err_code) ; 
exit  (err_code) ; 

) _ 

Example  4:  Code  produced  once 
function  failure  has  been  located 


left  so  that  its  value  is  not  lost  when  the 
new  code  is  added. 

A  value  of  10  for  ERR_BUMPER  is 
convenient  because  the  error  number 
can  be  visually  decoded,  but  when  do¬ 
ing  so  it  needs  to  be  interpreted  from 
right  to  left.  Each  digit  in  the  decimal 
integer  display  represents  the  error  num¬ 
ber  at  each  function  level.  The  right¬ 
most  digit  represents  the  highest-func- 
tion  level. 

Decoding  Error  Numbers 

Visual  decoding  is  not  necessary.  The 
function  in  Example  3  will  decode  the 
combined  error  code  for  any  value  of 
ERR_BUMPER  and  display  the  individ¬ 
ual  codes  so  that  they  can  be  inter¬ 
preted  from  left  to  right. 

Consider  the  output  ERROR:  34152. 
While  this  error  message  is  far  too  cryp¬ 
tic  to  understand  by  itself,  a  program¬ 
mer  with  access  to  the  source  code  can 
pinpoint  the  root  cause  of  the  error 
quickly.  The  process  is  simple,  starting 
with  the  main  function,  locate  the  func¬ 
tion  failure  that  produces  code  3-  See 
Example  4.  Next,  move  to  that  function 
and  locate  the  function  failure  in  that 
function  that  produces  code  4.  Repeat 
this  process  at  each  function  level  until 
the  last  one  is  reached. 

It  is  a  good  idea  to  check  the  syntax 
of  each  function  call  at  every  step.  The 
defect  is  not  always  with  the  lowest- 
level  function.  I  have  found  that  when 
this  process  is  complete,  the  bug  is 
often  obvious. 

Some  Improvements 

The  ERR_  COMBINE  macro  in  the  previ¬ 
ous  example  makes  two  important  as¬ 
sumptions.  First,  the  individual  error 
codes  are  always  less  than  the  value 
of  ERR_BUMPER.  Second,  the  combin¬ 
ing  of  the  error  codes  does  not  over¬ 
flow  the  data  type  used  for  the  error 
return  ( unsigned  inf). 

Because  the  individual  error  num¬ 
bers  are  hard  coded,  the  first  assump¬ 
tion  is  fairly  easy  to  control.  You  will 
find  that  most  functions  will  need  only 
a  few  error  numbers.  If  your  function 
requires  much  more  than  a  half  dozen, 
it  is  probably  too  large  and  should  be 
split  up  into  two  or  more  smaller  rou¬ 
tines  anyway.  In  the  rare  case  when 
extra  codes  are  needed,  two  codes  can 
be  combined  as  follows: 

error  =  ERR_COMBINE 

( ERR_  COMBINEferror,  9),  1); 

The  second  assumption,  that  the  error 
code  will  not  overflow,  is  much  more 
dangerous.  In  a  system  of  any  size  func¬ 
tions  will  be  nested  at  many  levels.  An 
unsigned  (2  byte)  int  and  an  error 
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( continued  from  page  62) 
bumper  of  10  allows  for  only  four  or 
five  levels  of  nesting  before  the  error 
code  will  overflow.  We  can  increase 
the  maximum  levels  by  using  a  long 
rather  than  an  integer,  as  well  as  by 
reducing  the  value  of  the  error  bumper. 
However,  an  int  is  preferable  to  long, 
from  a  coding  efficiency  standpoint, 
because  an  mlwill  usually  be  the  “natu¬ 
ral”  size  for  the  CPU  (K  &  R  p.  34). 
Efficiency  is  an  important  considera¬ 
tion  because  this  error  code  will  be 
returned  and  tested  in  many  places. 

We  cannot  guarantee  that  the  error 
code  will  never  overflow.  But  as  Exam¬ 
ple  5  shows,  a  function  rather  than  a 
macro  lets  you  develop  a  more  sophis¬ 
ticated  scheme  to  save  error  codes  that 
would  be  lost  in  an  overflow.  We  can 
then  provide  support  for  very  large 
systems  while  making  no  special  re¬ 
quirements  on  the  capacity  of  the  error 
code  or  the  size  of  the  error  bumper. 

The  err__combine  function  tests  for 
potential  overflow.  When  required,  the 
original  multiplexed  code  will  be  saved 
in  another  location  and  then  reset,  at 
which  point  normal  processing  will  con¬ 
tinue. 

The  saved  code  is  stored  in  a  stack 
implemented  as  an  array  that  can  be 
made  as  large  as  required  by  the  pro¬ 
gram  size.  An  additional  function 
( err _pop)  is  required  to  pop  any  over¬ 
flow  portions  of  the  multiplexed  error 
code  off  the  stack.  The  previous 
err _print  function  can  be  changed  to 
display  the  entire  error  code,  as  shown 
in  Example  6. 

The  source  code  in  Listing  One,  page 
108  combines  all  the  aforementioned 
concepts  into  a  single  module  of  utility 


functions,  ready  for  use  in  any  new 
programming  project. 

The  err_combine  function  in  that  mod¬ 
ule  has  an  additional  feature  worth  some 
note.  It  tests  the  original  error  code 
value,  and  if  it  is  a  special  “pass  through” 
value,  the  error  codes  are  not  com¬ 
bined.  Only  the  original  pass  through 
value  is  returned.  In  this  way  excep¬ 
tions  that  are  expected  (such  as  user 
abort)  can  be  easily  handled  using  the 
same  exception  processing  logic.  The 
rather  cryptic  abort  function  used  in  a 
previous  example  can  now  be  ex¬ 
panded  as  shown  in  Example  7. 


Where  the  case  values  of  this  switch 
statement  are  some  predefined  pass 
through  values,  the  rule  is:  Any  value 
that  is  an  even  multiple  of  ERR_BUMPER 
is  not  modified,  the  original  value  will 
be  passed  through.  This  rule  works 
well  because  of  the  way  that  the  com¬ 
bine  algorithm  works.  Multiples  of 
ERR_BUMPER  will  not  be  generated  as 
error  codes  because  individual  error 
codes  are  non-zero  by  definition. 

Summary 

As  mentioned  earlier,  the  power  of  this 
error  handling  scheme  lies  in  the  de- 


unsigned  err_combine {unsigned  original,  unsigned  to_add) 
{ 

if  (original  >  UINT_MAX  /  ERR_BUMPER) 

{  /*  UINT_MAX  is  in  limits. h  */ 

err_push (original) ; 
original  =  0; 

} 

return  (original  *  ERR_BUMPER  +  to_add) ; 

} 

♦define  MAX_0VERFL0WS  10 

static  unsigned  err_stack [MAX_0VERFL0WS] ; 

static  unsigned  err_stack_top  =  0; 

unsigned  err_pop() 

{ 

if  (err_stack_top  <=  0) 
return  (0) ; 

— err_stack_top; 

return  (err_stack [err_stack_top] ) ; 

} 

void  errjpush (unsigned  err_code) 

{ 

if  (err_stack_top  <  MAX_0VERFL0WS) 

{ 

err_stack [err_stack_top]  =  err; 
++err_stack_top; 

} 

} 


Example  5:  Using  a  function  instead  of  a  macro 


void  err_print (FILE  ‘stream,  unsigned  in  err_code) 

{ 

while  (err_code) 

( 

do 

{ 

fprintf (stream,  "%d",  (err  %  ERR_BUMPER) ) ; 

} 

while  ( (err_code  /=  ERR_BUMPER)  >  0); 
err_code  =  errjpopO; 

} 

} 


Example  6:  Changing  ERR_PRINT  to  display  the  entire  error  code 


void  abort (err) 

{ 

switch  (err) 

{ 

case  DISK_SPACE_ERROR: 

printf("\n  Not  enough  disk  space  to  run  program"); 
break; 

case  MEMORY_ERROR: 

printf("\n  Not  enough  memory  to  run  program."); 
break; 

case  USER_ABORT: 

printf (stderr,  "\n  Program  aborted  by  user."); 
break; 
default : 

printf ("\n  Unexpected  error:  %d  ",  err); 
printf ("\n  Please  record  this  error  number,"); 
printf ("\n  and  call  technical  support  at"); 
printf ("\n  1-800-555-1234."); 
break; 

} 

exit  (err) ; 

} 
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tection  of  unexpected  errors  through 
its  systematic  use.  It  can  detect  errors 
only  where  it  is  used.  To  encourage  its 
wide  use,  it  has  been  designed  to  mini¬ 
mize  the  work  required  to  implement 
it.  Any  time  an  error  condition  is  re¬ 
turned  by  a  function,  it  can  simply  be 
kicked  upstairs  without  concern  for  los¬ 
ing  calling  context  information. 

Because  a  unique  identifier  is  added 
each  step  of  the  way,  valuable  trace 
information  can  be  provided.  This  in¬ 
formation  can  often  be  critical  in  dis¬ 
covering  the  nature  of  a  program  de¬ 
fect.  And  by  providing  the  information 
with  the  first  occurrence  of  the  bug, 
we  can  significantly  reduce  the  diagno¬ 
sis  time,  particularly  for  bugs  with  symp¬ 
toms  that  are  difficult  to  reproduce. 

Because  the  trace  information  is  pre¬ 
served,  the  individual  error  codes  need 
to  be  unique  to  the  function  only.  This 
is  very  convenient  in  large  systems 
where  managing  many  error  numbers 
would  become  quite  cumbersome. 

You  may  have  guessed  that  this  error 
identification  scheme  is  most  helpful 
in  the  early  stages  of  development,  and 
it  is.  But  it  is  also  helpful  late  in  a 
program’s  life  cycle.  It’s  esf  ecially  good 
for  catching  those  “once  in  a  blue  moon” 
bugs.  Usually  all  you  need  is  the  error 
code  and  the  correct  version  of  the 
source  code. 

You  will  find  that  this  system  will 
not  always  lead  you  to  the  program 
defect  by  itself,  and  you  may  have  to 
resort  to  other  debugging  techniques, 
but  it  will  provide  you  with  a  valuable 
head  start. 

Notes 

The  C  Programming  Language,  by  Brian 
Kernighan  and  Dennis  Ritchie.  Prentice 
Hall,  Englewood  Cliffs,  Newjersey,  1978. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 
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Cjalk/Views 


Recently  ported  to  Microsoft  Windows,  this  unique 
language  adds  a  powerful  class  library  for  dealing 
with  graphical  user  interfaces 


Noel  Bergman 


With  object-oriented  program¬ 
ming  emerging  as  the  ma¬ 
jor  new  programming  para¬ 
digm  for  the  1990s,  and  C 
being  the  darling  language 
of  professional  software  developers  in 
the  PC  and  minicomputer  arenas,  what 
could  be  more  natural  than  object- 
oriented  extensions  to  C?  C_talk  is  one 
such  object-oriented  extension  to  C  and 
it  is  very  much  in  the  mold  pioneered 
by  Brad  Cox’s  Objective-C  language. 
While  there  are  a  number  of  such  de¬ 
rivative  languages,  they  all  nonetheless 
have  similar  differences  from  the  other 
great  object-oriented  C  dialect,  AT&T’s 
C++. 

C_talk  is  extended  from  C  with  two 
basic  constructs:  classes  and  messages. 
C_talk  messages  take  the  form: 

[<  lvalue  >  =]  @<  receiver  > 

<  message  >@ 

The  optional  assignment  is  an  enhance¬ 
ment  from  earlier  versions  of  C_talk, 
and  allows  a  method  to  return  a  value. 
(Remember  that  a  message  is  what  you 
send  to  an  object,  and  a  method  is  the 
actual  code  that  handles  a  message.) 


Noel  Bergman  is  the  president  of  Devel¬ 
opment  Technologies ,  Inc.,  a  software 
development  consulting  firm  with  spe¬ 
cial  interests  in  OS/2,  Windows,  and 
OOP.  He  can  be  reached  on  Compu¬ 
Serve  (CIS  ID:  76704,34)  where  he  is 
a  volunteer  Sysop  on  Microsoft’s  Com¬ 
puServe  forum.  Development  Technolo¬ 
gies  can  be  reached  at  8329  High 
School  Road,  Elkins  Park,  PA  19117 
or 215-386-9599. 


C_talk  uses  a  more  Smalltalk-like  syn¬ 
tax  with  named  parameters,  unlike  the 
C++  method/message  syntax.  (For  more 
information  on  the  C_talk  syntax,  see 
“A  Class- ier  C”  by  Ernie  Tello,  DDJ  De¬ 
cember  1988,  page  74.)  As  with  Small¬ 
talk,  C_talk’s  class  hierarchy  has  a  sin¬ 
gle  class  object,  from  which  all  other 
classes  are  derived.  There  is  no  multi¬ 
ple  inheritance,  though  the  true  poly¬ 
morphism  in  C_talk  cuts  down  on  the 
need  for  multiple  inheritance,  unlike 
C++. 

If  a  language  has  true  polymorphism, 
it  is  possible  to  have  an  arbitrary  col¬ 
lection  of  objects,  and  to  send  a  mes¬ 
sage  to  each  member  object  without 
knowing  its  type.  This  is  not  possible 
in  C++.  Although  virtual  functions  do 
provide  limited  polymorphism,  each 
object  in  a  collection  must  be  descended 
from  a  common  ancestor  who  declared 
the  virtual  function.  One  way  of  getting 
around  this  in  C++  is  to  use  multiple 
inheritance,  but  a  detailed  explanation 
of  how  is  beyond  the  scope  of  this 
article. 

C++  supports  static,  or  early  binding; 
this  means  that  the  function  to  be  called 
at  run  time  is  known  at  compile  time. 
In  the  case  of  a  virtual  function,  the 
index  in  an  array  of  pointers  to  func¬ 
tions  is  known.  True  polymorphism 
includes  dynamic,  or  late  binding,  in 
which  the  method  is  looked  up  for  the 
specific  object  and  executed.  But  there 
is  a  run-time  penalty  for  late  binding. 
Objective-C  now  offers  the  option  of 
mixed  early  and  late  binding.  C_talk 
only  offers  late  binding  in  the  language, 
but  a  new  tool,  C_talk/Views,  performs 
some  early  binding  at  compile  time. 


The  Cjalk/Views  Package 

C_talk/Views  is  a  package  made  up 
from  a  number  of  components.  The 
C_talk  Browser  is  a  specialized  editor 
for  working  with  object  classes  and 
methods;  the  C_talk  preprocessor  con¬ 
verts  C_talk  into  C;  class  libraries  pro¬ 
vide  a  base  set  of  fundamental  object- 
oriented  classes;  and  a  special  class 
library  is  provided  for  working  with 
graphical  user  interfaces.  C_talk  also 
includes  a  Make  facility  and  a  Stream¬ 
liner.  The  latter  is  a  specialized  tool 
that  attempts  to  determine  when  early 
binding  can  be  used  and  optimizes  the 
code  accordingly. 

Most  of  these  tools  were  covered  in 
Ernie  Tello’s  earlier  C_talk  review,  so 
I’ll  focus  on  what  is  new  in  the  C_talk/ 
Views  package:  Windows  Browser, 
Streamliner,  Interface  Generator,  and 
Views. 

The  Cjalk  Browser 

The  C_talk  Browser  is  the  tool  you’ll 
use  for  most,  if  not  all,  of  your  C_talk 
editing.  It  is  possible  to  use  a  normal 
text  editor,  but  the  C_talk-to-C  prepro¬ 
cessor  needs  certain  specially  format¬ 
ted  information,  so  it  is  likely  that  you’ll 
use  a  standard  text  editor  only  to  edit 
some  methods  on  occasion. 

The  C_talk  Browser  is  functionally 
the  same  as  the  earlier  Browser,  which 
was  based  on  text  windows.  In  fact,  a 
text-based  Browser  is  included  in  the 
same  package  with  the  Microsoft  Win¬ 
dows  Browser.  Figures  1  and  2  show 
the  text-windows-based  browser  and 
the  Microsoft  Windows  Browser,  re¬ 
spectively.  The  differences  are  in  the 
manipulation  of  menus  and  windows. 
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(continued  from  page  66) 

Streamlining:  Early  Binding  for  Speed 

The  Streamliner,  CTSW,  is  used  when 
preparing  a  product  for  final  testing.  It 
analyzes  your  application,  strips  out 
classes  and  methods  that  the  analysis 


reports  cannot  possibly  use,  and  per¬ 
forms  static  binding  of  messages.  The 
result  is  code  that  may  be  half  the  size 
of  non-streamlined  code,  and  that  typi¬ 
cally  has  two-thirds  of  the  messages 
statically  bound. 


Figure  1:  Text  windows  based  browser 


The  Streamliner  does  have  some 
quirks,  but  these  are  minor  and  are 
actually  documented  in  the  manual. 

The  Interface  Generator 

C_talk/Views  includes  a  CTIG  utility 
that  translates  the  .DLG  output  from 
the  Microsoft  Windows  Dialog  Editor 
into  a  C_talk/Views  class.  Basically,  it 
writes  the  class  method  CreateOf_  and 
instance  method  initialize.  You  edit 

C_talk  does  not  allow 
you  to  build  DLLs  from 
Cjalk  code,  although 
you  can  use  DLLs 
written  in  C  or  MASM 


C  talk/Uievs  Browser  -  GEHflPP 


□  create  UiewOf 


|  File  Edit  Search  Classes  Methods  Make 
Region  — 

Window 

ControlWindow. . . 
uiew 


|create_  name  UiewOF_  model 
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Figure  2:  The  Microsoft  Windows  Browser 
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Figure  3-  A  subset  of  the  C_talk/Views  classes 


the  new  class,  adding  instance  vari¬ 
ables  and  methods  to  flesh  it  out  into 
a  complete  dialog  subclass  that  is  ready 
for  use  in  applications.  In  essence,  CTIG 
takes  a  description  of  the  visual  por¬ 
tion  of  a  dialog  and  codes  it  for  you, 
leaving  you  to  code  only  the  dialog’s 
function. 

Actually,  CTIG  takes  care  of  one  of 
the  Windows  programmer’s  least  favor¬ 
ite  dialog  characteristics  —  how  the 
code  looks  on-screen.  CTIG  generates 
code  that  will  look  correct  on  the  dis¬ 
play,  regardless  of  the  display’s  aspect 
ratio  and  resolution. 

Currently,  CTIG  is  limited  to  generat¬ 
ing  subclasses  of  Views’  DIALOG  class, 
which  are  framed  dialogs.  But  those 
dialogs  are  the  majority  of  dialogs  used 
today. 

The  New  Classes 

OK,  enough  with  the  tools.  These  are 
just  delivery  vehicles  for  the  true  power 
of  OOP,  the  object  classes  themselves. 
C_talk  comes  with  a  full  complement 
of  foundation  object  classes  in  the  Small¬ 
talk  model.  To  this  has  been  added 
Views,  a  rich  set  of  classes  for  working 
with  graphical  user  interfaces.  Most  of 
these  classes  are  shown  in  Figure  3. 

The  earlier  C_talk  article  discussed 
the  foundation  classes,  so  I  will  again 
focus  on  what  is  new  in  C_talk/Views. 

Additional  Foundation  Classes 

In  addition  to  the  new  Views  classes, 
there  is  a  new  foundation  class  in  the 
C_talk/Views  package  that  provides  sup¬ 
port  for  persistent  objects.  [Editor’s  note. 
See  “Persistent  Objects”  by  Charles-A. 


68 

140 


Dr.  Dobb’s Journal,  February  1990 


EXAMINING  ROOM 


(continued  from  page  68) 

Rovira,  Dr.  Dobb’s  Macintosh  Journal, 
Fall  1989.]  A  future  release,  which  should 
be  available  by  the  time  this  article 
reaches  print,  is  expected  to  add  sup¬ 
port  for  communications,  timers,  and 
debugging. 

Persistence  is  implemented  through 
an  Archiver  object  class.  Archiver  ob¬ 
jects  take  care  of  most  of  the  details 
involved  in  storing  and  loading  archives. 
Objects  that  are  to  be  kept  in  the  ar¬ 
chives,  however,  must  implement  the 
methods  putTo_  and  getProm_,  which 
are  responsible  for  storing  and  loading 
the  subclass’  instance  variables.  This 
form  of  persistence  is  suitable  for  many 
applications,  but  does  not  directly  sup¬ 
port  random  access  to  objects. 

Views:  Classes  for  Windowing  Systems 

Previous  versions  of  C_talk  also  included 
windowing  classes,  albeit  text-based.  The 
new  Views  classes  should  not  be  con¬ 
fused  with  those  earlier  windowing  pack¬ 
ages,  although  there  are  some  similarities. 

Model/View/ Controller 

The  paradigm  chosen  to  be  imple¬ 
mented  in  the  Views  class  library  is  a 
modification  of  the  classic  Smalltalk 
Model/View/Controller  (MVC)  meta¬ 
phor.  This  framework  formalizes  pro¬ 
gram  structure  and  places  classes  into 
one  of  three  categories: 

Models  —  Virtualize  a  concept  with¬ 
out  concern  for  its  representation.  For 
example,  the  hierarchy  of  classes  in  a 
program,  or  a  network  of  workstations 
on  a  LAN. 

Views  —  Provide  a  visual  representa¬ 
tion  of  a  model.  One  such  representa¬ 
tion  is  the  list  of  classes  in  the  C_talk 
browser.  Another  representation  of  the 
same  information  would  be  the  directed 
graph  in  Figure  3. 

Controllers  —  Provide  the  interface  be¬ 
tween  the  other  classes  and  input  de¬ 
vices.  The  interactions  between  mod¬ 
els,  views,  and  controllers  are  more 
involved  in  the  Smalltalk  MVC  model. 
In  the  Views  adaptation  of  MVC,  the 
notifier  is  the  only  kind  of  controller. 
This  simplification  works  well  with  the 
Windows/PM  application  model,  be¬ 
cause  it  is  analogous  to  the  message 
queue.  In  fact,  the  OS/2  version  of 
Views  will  probably  use  one  notifier 
for  each  message  queue  thread. 

The  Views  implementation  of  the 
MVC  paradigm  differs  from  the  classic 
MVC  paradigm  (see  The  Journal  of  Ob¬ 
ject-Oriented  Programming,  August/ 
September  1988)  in  a  number  of  ways. 
In  the  latter,  Controllers  talk  directly  to 
both  views  and  models.  Models  can 
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be  active  when  talking  to  controllers  portant  to  remember  that  main( )  is  information,  is  queried  when  the  view 
and  views.  The  Views  paradigm  has  a  not  a  C_talk  method  —  there  is  no  self  wants  to  repaint  the  entire  image,  and 
single  controller  that  talks  only  to  views,  to  refer  to  during  its  execution.  Accord-  handles  the  archiving  of  the  image, 
and  the  models  are  passive  (only  re-  ingly,  main  creates  a  new  instance  of  SketchView  handles  the  user  inter- 
sponding  to  messages  from  view  objects).  Sketch App,  then  uses  Sketch  Vieufs  face  for  the  sketch  program.  It  is  rather 

The  Views  controller  is  essentially  a  simple  in  structure,  primarily  because 

virtualization  of  the  event  system.  There-  ^  r.  t  of  Views’ menu  handling  and  C_talk’s 

fore,  it  does  not  talk  directly  to  models.  1  tOG  pClTClCll^TYl  CD0S6YI  polymorphism.  The  initialize  method 

The  events  are  processed  by  a  view  i  ■  r  J  •  (see  Listing  Two,  page  110)  tells  the 

which  gives  meaning  to  the  events  in  to  be  implemented  in  model  to  clear  (initializing  it  to  a  known, 

that  view’s  context.  r  empty  state),  create  a  Port  object  (the 

The  Views  paradigm  is  simpler,  but  the  Vl6WS  ClClSS  libTdTV  Views  class,  which  virtualizes  the  draw- 
does  have  a  few  drawbacks.  You  can  *  ing  surface),  and  set  up  a  menu  of 

have,  and  often  want,  multiple  views  s,  windifirntinvi  thp  functions  —  not  in  that  order.  A  Views 

to  the  same  model.  The  problem  is  that  ^  W  t  til  U  1  UJ  l  Jc  menu  is  made  up  of  3-tuples  [name, 

all  the  views  that  use  the  model  have  rlnccir  Ct-m n  11  tn lb  accelerator,  method].  When  a  menu  item 

to  know  about  each  other,  in  order  to  CUAbdlL  oWICHUCUk  is  selected,  the  associated  method  is 

let  each  other  know  when  a  change  is  ,,  ,  //t  v  Is-*  ,  11  activated  for  the  object  associated  with 

made.  Future  versions  of  Views  may  NlOUel/ VieW/LiOntVOlleV  the  menu  (in  our  case,  the  SketchView 

change  models,  so  that  a  model  keeps  object). 

track  of  all  views  using  it  and  notifies  metUpbOV  The  three  graphic  “shapes”  in  the 

them  when  there  is  a  change  in  the  current  Sketch  program  are  lines,  boxes, 

model.  and  free-hand  drawing,  each  of  which 

is  selected  from  a  menu  item.  The 

Using  MVC  create^  ViewOf_  class  method  to  create  method  associated  with  each  menu  item 

It  takes  a  little  extra  development  time  a  new  SketchView  with  the  new  is  almost  identical  and  is  simple.  In 
to  use  MVC.  You  have  to  decide  upon  SketchApp  as  the  model.  general,  the  method  unchecks  any 

formal  models  for  the  concepts  your  In  the  current  implementation,  checked  items  on  the  menu  (in  order 
program  works  with.  Then  you  will  SketchApp  models  the  behavior  of  the  to  clear  the  current  shape  indicator), 
create  views  that  use  the  formal  in-  image  memory  for  the  sketch  pad.  New  sets  the  drawClass  instance  variable  to 
terface  to  the  model.  Windows/PM  pro-  objects  are  drawn  on  the  SketchView,  the  class  for  subsequent  shapes,  and 
grammers  tend  to  intertwine  windows  which  sends  an  add_  message  to  the  checks  the  menu  item  for  that  shape, 
(views)  and  the  concepts  they  repre-  model.  The  model  records  all  of  this  (See  Example  1.)  When  a  mouse-down 

sent  (models).  Even  the  developers  of  _ 

C_talk/Views  have  done  this.  Only  a 
couple  of  the  sample  programs  use  the 
MVC  model,  and  even  then  use  it  some¬ 
what  loosely.  All  of  the  rest  handle 
model  issues  as  part  of  the  view,  mak¬ 
ing  it  more  difficult  to  provide  alternate 
views  to  the  same  information,  change 
the  model  without  changing  the  view, 
and  vice  versa. 

A  Cjalk/Views  Example 

C_talk/Views  comes  with  a  range  of 
sample  programs,  from  a  simple  doo¬ 
dle  application  to  a  couple  of  simula¬ 
tions.  One  of  those  programs,  Sketch 
(an  object-oriented  sketch  pad),  has 
been  a  staple  of  mine  at  lectures,  and 
in  fact  has  undergone  a  number  of 
changes  either  at  my  hand  or  at  my 
request.  It  has  never  used  MVC,  how¬ 
ever,  or  the  Archiver  class.  Until  now, 
that  is! 

Sketch  is  made  up  of  a  few  key  classes 
(not  counting  dialogs  or  normal  foun¬ 
dation  classes,  such  as  collections,  used 
in  most  OO  programs):  SketchApp  (the 
MVC  model),  SketchView  (the  MVC 
View),  Notifier  (the  MVC  controller), 
and  a  small  GraphOhj  family. 

SketchApp  is  the  model,  and  is  where 
I’ve  put  the  main  method  (see  Listing 
One,  page  109),  that  current  versions 
of  C_talk/Views  use  as  a  dummy  to 
hold  the  main( )  function.  It  is  im- 
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event  occurs,  the  view  will  create  a 
new  instance  from  drawClass  and  send 
mouse  messages  to  it;  drawing  is  virtu¬ 
alized  by  the  classes  installed  in 
drawClass. 

SketchView,  which  is  the  Views  ob¬ 
ject  in  our  MVC  model,  receives  events 
from  the  controller.  The  Views  notifier 
gives  us  control  over  a  number  of  things, 
one  of  which  is  the  ability  to  capture 
the  mouse.  Sketch Vieuls  mouseDnX_Y_ 
method  is  sent  mouse-down  events 
from  the  notifier.  If  there  is  a  current 
drawing  class,  we  will  turn  mouse  cap¬ 
ture  on,  and  enable  tracking  of  mouse 
movement  (otherwise  Views  doesn’t 
waste  time  dispatching  those  events). 
Then  a  new  drawing  object  is  created, 
added  to  the  model,  associated  with 
the  drawing  port  for  our  window,  and 
given  the  mouse-down  event  for  class- 
specific  handling.  Similarly,  mouse  move¬ 
ment  and  mouse  button  up  events  will 
first  be  processed  by  the  SketchView , 
then  passed  to  the  drawing  object. 
Sketch  View  handles  the  interaction  with 
the  controller,  but  leaves  all  of  the  draw¬ 
ing  to  the  drawing  object.  In  order  to 
add  a  new  shape,  all  you  have  to  do  is 
create  a  class  for  it  and  add  it  to  the 
menu. 

All  of  these  drawing  classes  are 
grouped  under  the  GraphObj class.  Each 
subclass  specializes  the  mouseDnX_  Y_, 
drawOn_,  mouseMvX_Y_Bt_,  mouse- 
UpX_  Y_,  and  setPort_  methods,  which 
are  invoked  from  SketchView.  Also 
added  are  the  getFrom_  and  putTo_ 
methods  for  the  Archiver  class. 

Archiving  is  rather  straightforward, 
once  you  get  the  hang  of  it.  Each  class 
must  implement  getFrom_  and  putTo_ 
methods  that  are  only  to  be  called  from 
the  archiver  — -  never  directly!  These 
methods  take  an  instance  of  Archiver 
as  the  parameter  and  are  usually  re¬ 
sponsible  for  restoring  or  saving  the 
classes  instances  variables.  (If  there  are 
no  new  instance  variables,  the  meth¬ 
ods  inherited  from  the  parent  class  are 
usually  sufficient.)  A  typical  method 
first  sends  the  message  to  super  to  af¬ 
fect  inherited  instance  variables,  then 
handles  those  specific  to  its  subclass. 

Sketch  View  has  been  enhanced  with 
menu  items  and  methods  ( open ,  save, 
and  saveAs_)  for  interacting  with  the 
user  and  sending  the  user’s  request  to 
the  model.  Sketch App  implements  load- 
From_  and  save  methods  (save As  just 


sets  the  file  name  and  invokes  save), 
which  it  uses  to  archive  the  collection 
of  GraphObj  instances. 

Archivers  are  easy  to  use.  There  are 
two  primary  methods,  getObject  and 
putObject_,  which  are  sent  to  an  in¬ 
stance  of  Archiver  to  get  the  next  ob¬ 
ject  from  the  archive  or  to  put  another 
one  in.  SketchApp  uses  them  to  save 
and  restore  the  objects  instance  vari¬ 
able.  Some  of  the  GraphObj  classes 
have  objects  as  instance  variables; 
those,  too,  are  sent  to  the  Archiver 
with  putObject_  and  retrieved  with 
getObject.  Other  instance  variables  are 
integers,  longs,  or  other  base  types. 
There  are  A rchiver  methods  for  these, 
too,  such  as  putlnt_  and  getlnt. 

This  covers  the  high  points  in  the 
implementation  of  the  new  Sketch  pro¬ 
gram.  The  key  changes  in  this  new 
version  are  the  move  towards  MVC, 
and  the  use  of  the  Archiver  c lass. 

One  major  change  in  the  Sketch  pro¬ 
gram  was  made  prior  to  the  first  public 
release,  but  it  bears  mentioning  here. 
The  first  version  I  saw,  prior  to  adopt¬ 
ing  the  program  for  my  own  uses,  didn’t 
use  GraphObj  to  virtualize  the  draw¬ 
ing,  and  didn’t  have  a  persistent  image  — 
if  you  moved  the  window,  the  image 
was  erased.  Instead,  the  menu  items 
set  an  instance  variable  ivar  to  indicate 
which  shape  was  being  drawn,  and 
SketchView’s  mouse  handling  methods 
used  //statements  to  check  the  ivar  and 
do  the  appropriate  things.  The  change 
to  using  GraphObj  and  an  ivar  that 
pointed  to  the  current  class  not  only 
provided  better  polymorphism,  but  led 
the  way  to  a  persistent  image,  MVC, 
and  archived  graphics.  Polymorphism 
and  virtualization  are  key  concepts  and 
cannot  be  too  highly  emphasized. 

On  the  Downside 

C_talk/Views  is  certainly  not  a  perfect 
tool.  For  one  thing,  it  is  not  written  in 
C++.  That’s  both  good  and  bad.  C++ 
has  a  lot  of  inertia  behind  it  as  it  rolls 
towards  being  a  standard,  but  it  has 
limitations,  some  of  which  I  discussed 
at  the  beginning  of  this  article. 

C_talk  does  not  allow  you  to  build 
DLLs  from  C_talk  code,  although  you 
can  use  DLLs  written  in  C  or  MASM. 
Views  neither  implements  nor  provides 
help  for  implementing  MDI.  These  are 
not  expected  to  change  in  the  near 
future. 


***  Generic  "shape"  method  for  SketchView  *** 
<shape>_  aMenuItem 

id  aMenuItem;  /*  id  of  selected  menu  item  */ 
{ 

8self->fMenu  uncheckAllg; 
self->drawClass  -  <ShapeClass>; 

@aMenuItem  check®; 

} 


Example  1:  A  generic  shape  method 
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(continued  from  page  72) 

Another  problem,  which  is  expected 
to  be  fixed  in  the  version  available 
before  this  article  is  published,  is  that 
all  C_talk  source  files  currently  have 
to  be  located  in  the  same  directory. 
The  new  version  of  C_talk  will  allow 
you  to  keep  standard  classes  in  one 
directory  and  application-specific  classes 
in  another. 

Finally,  there  are  some  annoying  lit¬ 
tle  quirks  in  the  browser.  For  example, 
there  is  a  lack  of  keyboard  accelerators 
for  some  of  the  menu  items.  Also,  the 
.DEF  file  generated  by  the  browser 
doesn’t  have  the  EXETYPE  WINDOWS 


entry  required  by  current  versions  of 
the  Linker.  These  are  expected  to  be 
addressed  in  the  next  release. 

On  the  Upside 

C_talk/Views  permits  rapid  develop¬ 
ment  of  commercial  quality  Windows 
programs.  This  is  partially  because  of 
the  nature  of  the  language,  but  is  mostly 
due  to  the  robust  class  library.  Even 
such  things  as  printing  are  standard  in 
the  C_talk/Views  package.  The  Views 
classes  simplify  many  Windows-related 
tasks,  particularly  menu  handling  and 
the  repositioning  of  child  windows 
when  resizing  their  parent. 


What's  Next? 

Part  of  the  promise  of  OOP  is  portabil¬ 
ity,  not  just  ease  of  development.  Fu¬ 
ture  versions  of  C_talk/View.s  are  tar¬ 
geted  for  other  platforms  besides  Mi¬ 
crosoft  Windows.  Presentation  Manager, 
Macintosh,  and  X  Windows  are  all  be¬ 
ing  considered.  Also,  Views  will  be 
ported  to  other  languages,  such  as  C++ 
and  Actor. 

Personally,  I  like  the  possibilities  of 
starting  work  in  Actor/Views,  working 
in  a  completely  interactive  environment, 
then  porting  the  code  to  C_talk/Views 
to  take  advantage  of  improved  mem¬ 
ory  and  CPU  utilization.  The  languages 
provide  similar  constructs;  the  major 
reason  not  to  do  it  today  is  that  you 
would  have  to  change  your  window¬ 
ing  model,  but  an  Actor  version  of  Views 
would  eliminate  that  problem.  Smalltalk/ 
Views  or  Object/1  Views  would  be  simi¬ 
larly  interesting. 

All  in  all,  programmers  who  harness 
the  power  of  the  C_talk/Views  package 
should  reap  today’s  all-important  harvest, 
with  even  better  yields  in  the  future. 


Products  Mentioned 

C_talk/Views 
CNS,  Inc. 

Software  Products  Dept. 

7090  Shady  Oak  Road 
Eden  Prairie,  MN  55344 
Price:  $450.00 
Requirements:  MS-DOS  2.0, 

MS  Windows 
Microsoft  C  5.0 

MS  Windows  Software  Development 
Kit  2.0. 

Suggested:  80286-based  computer, 
minimum  1 -Mbyte  RAM 


Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  109.) 


Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  6. 


74 

144 


Dr.  Dobb’s  Journal,  February  1990 


PROGRAMMER'S  WORKBENCH 


Stalking  GP  Faults: 
Part  II 

The  hunt  continues 


Andrew  Schulman 


Conventional  wisdom  says  that 
when  a  protected-mode  pro¬ 
gram  commits  a  general-pro¬ 
tection  (GP  fault)  violation,  it 
is  “evidence  that  the  program’s 
logic  is  incorrect,  and  therefore  it  can¬ 
not  be  expected  to  fix  itself  or  trusted 
to  notify  the  user  of  its  ill  health.”  This 
is  a  quote  from  OS/2’s  principal  archi¬ 
tect,  Gordon  Letwin.  In  Part  I  of  this 
article  I  tried  to  show  that  this  state¬ 
ment  is  false.  For  a  large  class  of  pro¬ 
grams,  which  execute  some  form  of 
“user  code”  or  script  (a  programmable 
data  base  or  a  Basic  interpreter  with 
PEEK  and  POKE  commands,  for  exam¬ 
ple),  GP  faults  are  caused  by  the  user 
code,  not  the  program  itself.  An  extra 
module  should  be  written  to  catch  GP 
faults  when  such  programs  are  ported 
to  protected  mode  (either  through  a 
DOS  extender  or  OS/2). 

In  Part  I  of  this  article,  I  showed  how 
to  catch  GP  faults  under  a  286-based 
DOS  extender  such  as  Rational  Sys¬ 
tems’s  DOS/16M.  I  used  a  rather  silly 
“GP  fault  interpreter,”  a  program  that 
allows  the  user  to  commit  GP  faults. 
In  this  article,  I  will  show  how  to  do 
the  same  thing  using  32-bit  C  compil¬ 
ers  and  386 1  DOS-Extender.  Then  I  will 
show  how  GP  faults  can  be  caught 
under  the  OS/2  operating  system  on 
16-bit  machines.  It  is  often  said  that 
GP  faults  can’t  be  caught  under  OS/2, 
but  they  can  (and  must!). 


Andrew  is  a  software  engineer  in  Cam¬ 
bridge,  Mass.,  where  he  is  writing  a 
network  CD-ROM  server.  Andrew  can 
be  reached  at  32  Andrew  St.,  Cam  - 
bridge,  MA  02139. 


32-bit  MS-DOS 

Like  a  16-bit  DOS  extender,  Phar  Lap 
Software’s  386 1  DOS-Extender  runs  code 
in  protected  mode,  occasionally  switch¬ 
ing  back  to  real  mode  to  call  MS-DOS 
or  some  other  real-mode  service.  In 
many  ways,  programming  for  this  32- 
bit  environment  is  similar  to  1 6-bit  pro- 
tected-mode  programming. 

There  are  important  differences,  how¬ 
ever.  In  a  32-bit  C  compiler,  such  as 
Meta  Ware  High  C  v.  1.5  for  MS-DOS 
386  or  Watcom  C  7.0/386,  an  int  is  a 
4-byte  quantity.  A  near  pointer  is  also 
a  4-byte  quantity.  This  means  the  pro¬ 
grammer  almost  never  have  to  deal 
with  far  pointers.  When  a  segment  takes 
a  4-byte  offset,  a  program  only  needs 
one  segment  for  all  its  data,  and  an¬ 
other  segment  for  code.  Once  loaded, 
DS  and  CS  stay  constant.  In  effect,  this 
is  a  linear  address  space. 

Though  it  is  no  longer  needed  for 
data  and  code,  segmentation  is  still  es¬ 
sential  for  sharing  and  to  enforce  pro¬ 


tection.  In  a  DOS  extender,  segmenta¬ 
tion  is  also  needed  for  communicating 
with  real-mode  services.  On  those  oc¬ 
casions,  when  both  a  segment  and  an 
offset  are  needed,  a  far  pointer  is  a 
6-byte  quantity  (an  FWORD). 

The  basic  difference  between  work¬ 
ing  in  32-bit  versus  16-bit  mode  is  that 
there  are  fewer  restrictions.  It  takes 
longer  for  an  int  to  overflow,  the  regis¬ 
ters  (EAX,  EBX,  and  so  on)  are  twice 
as  wide,  there  are  more  registers  (FS, 
GS),  and  offsets  can  be  so  large  that 
they  are  full-fledged  addresses.  All  these 
quantitative  differences  add  up  to  a 
major  qualitative  change.  Some  of  the 
flavor  of  386  protected-mode  program¬ 
ming  appears  in  a  sample  session  with 
a  32-bit  version  of  the  GP  fault  inter¬ 
preter,  compiled  with  Watcom  C  7.0/ 
386,  and  running  under  386 1  DOS-Ex¬ 
tender,  as  shown  in  Figure  1. 

Except  for  the  extra  386  registers,  Fig¬ 
ure  1  resembles  the  DOS/16M  GP  Fault 
interpreter  shown  in  Part  I.  As  in  the 


C:_PHARLAP>run386  gpf386 

'Q'  to  quit,  T  to  reinstall  default  GP  fault  handler 

0014:000038a4  is  a  legal  address  to  poke 

0014:000038a0  is  not  a  legal  address  to  poke 

$  1234:00005678  66666666 

Protection  violation  at  0000:00000111! 
Error  code  1 234 

<DS  0014>  <ES  000C>  <FS  0014> 

<GS  0014> 

<EDI  0O003CC0>  <ESI  66666666> 

<FLAGS  00010297> 

<EAX  00005678>  <EBX  00005678> 

<ECX  00001 234>  <EDX  00001 234> 

$  000c:00000111  66666666 

Protection  violation  at  0000:00000127! 
<DS  001 4>  <ES  000C>  <FS  000C> 

<GS  001 4> 

<EDI  00000000>  <ESI 66666666> 

< FLAGS  0001 021 2> 

<EAX  0000001 9>  <EBX  00000111> 

<ECX  0000000C>  <EDX  0000000c> 

$  0034:000b80a0  70217021 
poked  0034:000b80a0  with  70217021 

Figure  1:  A  sample  session  with  a  32-bit  version  of  the  GP  fault  interpreter 
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(continued  from  page  76) 

16-bit  version,  trying  to  poke  at  segment 
1234  failed,  though  this  time  the  faulting 
instruction  (EIP=000001 1 1)  was: 

mov  fs,dx 

Trying  to  write  into  the  program’s  code 
space  also  failed.  The  faulting  instruc¬ 
tion  at  EIP=00000127 was: 

mov  fs:[ebx],  esi 

The  last  POKE  command  in  Figure  1 
succeeded,  though.  In  386 1  DOS-Ex- 
tender,  0x34  is  a  writeable  data  seg¬ 
ment  that  maps  the  entire  first  mega¬ 
byte  of  memory.  The  entire  MS-DOS 
address  space  occupies  a  tiny  portion 
of  one  386  protected-mode  segment! 
Thus,  0034: 000B80A0  is  equivalent  to 
the  real-mode  address  B800.  00A0,  and 
points  into  video  display  memory.  Pok¬ 
ing  the  integer  0x70217021  into  this 
address,  after  GPF386.EXP  scrolls  the 
screen,  leaves  two  reverse  video  (at¬ 
tribute  0x70)  exclamation  marks  ( char 
0x21)  in  the  upper-left  corner  of  the 
screen. 

Listing  Four,  page  112,  is  the  Wat- 
com  C  version  of  GPF386.C.  Listing 
Five,  page  112,  is  the  Meta  Ware  High 
C  version.  The  object  file  produced  by 
the  compiler  is  passed  to  Phar  Lap’s 
386LINK.  As  the  example  shows,  the 
resulting  file,  GPF386.EXP,  runs  under 
RUN386.  Those  who  purchase  a  redis¬ 
tribution  package  from  Phar  Lap  can 
bind  RUN386  into  a  protected-mode 
application,  thus  producing  the  stand¬ 
alone  executable  file  GPF386.EXE.  The 
process  is  similar  in  DOS/16M. 

386 1  DOS-Extender  requires  Set  Vec¬ 
tor  to  handle  32-bit  offsets;  placing  the 
address  of  a  protected-mode  interrupt 
handler  in  DS:EDX,  or  using  EBX  to 
hold  the  entire  address  of  a  real-mode 
handler.  MS-DOS  INT  21  function  25 
won’t  work  here,  so  Phar  Lap  provides 
its  own. 

Phar  Lap  makes  INT  21  function  25, 
the  gateway  for  all  386 1  DOS-Extender 
system  calls.  For  example,  AX=2504  is 
used  to  set  a  protected-mode  interrupt 
vector  and  AX=2505  is  used  to  set  a 
real-mode  interrupt  vector.  Other 
386 1  DOS-Extender  system  calls  let  the 
programmer  call  a  real-mode  proce¬ 
dure,  issue  a  real-mode  interrupt,  alias 
a  segment,  change  the  attributes  for  a 
segment,  and  so  on. 

Phar  Lap  provides  several  different 
system  calls  for  setting  interrupt  han¬ 
dlers.  The  most  useful  one  for  catching 
GP  faults  is  the  “Set  Interrupt  to  Always 
Gain  Control  in  Protected  Mode”  call 
( AX=2506 ).  Because  this  call  expects 
the  address  of  a  protected-mode  han¬ 
dler  in  DS.EDX,  this  is  one  of  those 
times  that  DS  has  to  temporarily  change. 


The  function  setvect( ),  shown  in  List¬ 
ings  Four  and  Five,  demonstrates  this 
process. 

High  C  provides  a  C  interface  file, 
msdos.cf,  with  declarations  for  calldosO 
and  for  a  global  Registers  structure.  This 
is  similar  to  using  intdosx( )  and  union 
REGS  V  when  accessing  DOS  from  a 
Microsoft  C  or  Turbo  C  program. 

Watcom  C7. 0/386  goes  further.  Wat- 
com  C  is  a  32-bit  compiler  that  is  highly 
compatible  with  the  Microsoft  C  1 6-bit 
standard.  Watcom  C’s  dos.h  # include 
file  contains  functions  such  as  _dos_ 
getvectf  /and  _dos_setvect( ).  These  func¬ 
tions  invoke  Phar  Lap  system  calls  for 
protected-mode  handlers.  Such  as  their 
Microsoft  C  equivalents,  they  use  far 
pointers,  except  that  a  far  pointer  in 
Watcom  C  is  48  bits.  Like  the  standard 
C  library  MS-DOS  interfaces,  Watcom 
C7.0/386  includes  the  intdosxO  func¬ 
tion  and  union  REGS  'declaration,  but 
these  manipulate  the  32-bit  registers 
expected  by  386 1  DOS-Extender. 

I  didn’t  use  these  functions  for  the 
program  shown  in  Listing  Four.  Instead, 
I  used  Watcom’s  #pragma  aux,  a  high- 
level  facility  for  inline  machine  code. 
It  is  different  from  other  machine-code 
facilities,  such  as  Turbo  Pascal’s  dreaded 
inline( ),  which  returns  programmers 
to  the  days  before  there  were  even 
assemblers.  One  way  #pragma  aux  can 
be  used  is  to  specify  how  a  function 
takes  its  parameters,  and  how  it  returns 
a  value  to  its  caller.  John  Dlugosz  dis¬ 
cusses  this  facility  in  his  September 
1989  DDJ  review  of  Watcom  C7.0.  I 
will  be  discussing  it  some  more  in  a 
forthcoming  DDJ  review  of  Watcom’s 
7.0/386  compiler.  Listing  Four  gives  an 
extended  example. 

For  the  GP  Fault  interpreter,  a  seg¬ 
ment  and  an  offset  must  be  merged 
into  a  far  pointer.  Because  C  does  not 
have  any  built-in  FWORD  data  types, 
it  is  tricky  to  write  a  386  version  of  the 
MK_FP()  macro.  In  High  C,  I  set  the 
segment  and  offset  portions  of  the  far 
pointer  separately,  using  the  FP_SEG() 
and  FP_OFF( )  macros  in  GPFAULT.H 
(see  Listing  Two  in  Part  I).  Watcom 
C7.0  386  uses  the  #pragma  aux  facility 
to  provide  a  48-bit  MD_FP( )  that  is 
analogous  to  the  32-bit  MK_FP()  macro 
provided  in  Turbo  C. 

There  is  one  more  area  where  Wat¬ 
com  C  made  it  a  lot  easier  to  port  the 
GP  Fault  interpreter  to  the  386  than  did 
High  C.  While  both  Watcom  C  and 
High  C  have  facilities  to  write  interrupt 
handlers,  Watcom  C  pushes  FS  and 
GS  onto  the  stack  of  a  386  interrupt 
handler. 

Catching  OS/2  Faults  with  DosPTrace 

Because  it  runs  in  protected  mode, 
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(continued  from  page  78) 

OS/2  has  some  resemblances  to  1 6-bit 
DOS  extenders.  Except  for  system  calls, 
code  that  runs  in  a  DOS  extender  such 
as  DOS/1 6M  also  runs  under  OS/2. 
Many  features  of  OS/2  have  nothing 
to  do  with  Microsoft,  IBM,  or  OS/2  per 
se.  They  are  features  of  Intel’s  286. 
OS/2  is  very  much  a  286  operating 
system,  even  when  running  on  a  386 
machine.  Programming  for  OS/2  has 
more  in  common  with  programming 
for  DOS/16M  than  does  programming 
for  386 1  DOS-Extender. 

There  are,  however,  crucial  differ¬ 
ences  between  OS/2  and  a  DOS  exten¬ 


der.  A  DOS  extender  is  only  a  front- 
end  to  MS-DOS,  whereas  OS/2  is  a 
full-fledged  operating  system.  Because 
they  made  a  clean  break  from  DOS, 
rather  than  extending  it,  OS/2’s  design¬ 
ers  were  able  to  junk  the  INT  21  inter¬ 
face.  OS/2  system  calls  are  invoked  by 
putting  arguments  on  the  stack,  and 
doing  a  far  CALL.  No  more  stuffing 
registers. 

With  DOS  extenders,  INT  OD  han¬ 
dlers  are  installed  with  INT  21,  function 
25.  In  OS/2,  interrupt  handlers  are  in¬ 
stalled  by  calling  the  DosSetVec( /func¬ 
tion.  There  is  a  problem,  however:  Dos- 
SetVec( )  only  allows  certain  excep¬ 


tions,  and  the  GP  fault  isn’t  one  of  them. 
Another  function,  DosSetSigHandleK ), 
might  be  expected  to  work  for  SIGSEGV, 
but  it  doesn’t.  Even  though  Microsoft 
C  for  OS/2  includes  SIGSEGV  in  <sig- 
nal.h>,  it  doesn’t  do  anything. 

This  is  not  an  OS/2  bug  or  oversight, 
but  a  conscious  design  decision  and, 
some  feel,  an  important  design  flaw. 
In  his  book  Inside  OS/2 ,  Gordon  Letwin, 
Microsoft’s  chief  architect  for  system 
software,  flatly  states,  “Applications  can¬ 
not  intercept  general  protection  fault 
errors.  .  .  .  The  OS/2  design  does  allow 
almost  any  other  error  on  the  part  of 
an  application  to  be  detected  and  han¬ 
dled  by  that  application.  For  example, 
‘Illegal  filename’  is  an  error  caused  by 
user  input,  not  by  the  application.” 

This  overlooks  applications  in  which 
illegal  memory  access  is  as  easy  for  the 
user  as  illegal  file  access.  This  is  par¬ 
ticularly  ironic  because,  in  other  re¬ 
spects,  OS/2  invites  one  to  write  such 
programming-on-the-fly  environments. 
I  have  heard  that  in  the  386  version  of 
OS/2  (OS/3?),  DosSetVect( )  will  allow 
installation  of  a  normal  interrupt  han¬ 
dler  for  INT  OD.  This  is  just  a  rumor 
and,  in  any  case,  OS/3  won’t  be  avail¬ 
able  for  some  time. 

In  the  meantime,  there  must  be  some 
mechanism  in  OS/2  to  catch  GP  faults. 
In  fact,  there  is  such  a  mechanism  and, 
if  you ’ve  ever  used  protected-mode  Code¬ 
View  (CVP),  you’ve  probably  seen  it 
in  operation.  Take  a  buggy  application 
such  as  the  one  at  the  beginning  of  this 
article  and  run  it  under  CVP.  Instead 
of  OS/2  displaying  its  familiar  GP  fault 
register  dump,  CVP  displays  the  mes¬ 
sage  “Segmentation  violation.”  You  can 
reassemble  the  faulting  instruction,  or 
move  different  values  into  the  regis¬ 
ters,  and  resume  execution. 

If  CodeView  can  catch  GP  faults, 
why  can’t  we?  I  asked  this  question  on 
CompuServe  about  a  year  and  a  half 
ago,  when  I  was  porting  David  Betz’s 
XLISP  to  OS/2.  Ray  Duncan  and  Char¬ 
les  Petzold  supplied  the  answer:  Any¬ 
thing  that  CVP  can  do,  including  catch¬ 
ing  GP  faults,  other  OS/2  applications 
can  also  do.  CVP  is  built  on  top  of  an 
OS/2  kernel  function,  DosPT race( ),  and 
this  function  —  the  CodeView  engine  — 
is  available  to  all  OS/2  programs.  There 
are  better  OS/2  debuggers  than  CVP, 
but  these  too  are  undoubtedly  written 
using  DosPTrace. 

Unix  programmers  will  recognize  that 
DosPTrace  is  process  trace  ( ptracef )), 
used  to  implement  breakpoint  debug¬ 
gers  such  as  sdb.  In  the  “bad  old  days” 
of  the  $3000  OS/2  SDK,  when  devel¬ 
opers  asked  for  information  on  DosP¬ 
Trace,  Microsoft  referred  them  to 
ptrace( )  in  the  Unix  manual.  Even  to- 
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day,  while  DosPTrace  does  appear  in 
the  OS/2  programmer’s  reference,  the 
best  source  of  information  about  it  is 
an  untitled  Microsoft  document, 
PTRACE.DOC,  which  is  available  on  a 
number  of  bulletin  boards. 

A  process  (usually  a  debugger)  uses 
DosPTrace  to  trace  another  process. 
To  write  a  program  that  can  catch  its 
own  GP  faults,  though,  I  will  use  DosP¬ 
Trace  in  a  control/event  loop.  Using  a 
technique  devised  by  Ray  Duncan,  the 
GP  Fault  interpreter  will  run  itself  under 
DosPTrace.  Unfortunately,  one  thread 
of  a  process  running  DosPTrace  can¬ 
not  trace  another  thread  in  the  same 
process,  so  the  program  is  split  into 
two  processes.  OS2TRACE.C  appears 
in  Listing  Six,  page  114. 

DosPTrace  takes  one  parameter,  a 
pointer  to  a  PTRACEBUF.  This  struc¬ 
ture  is  declared  in  an  OS/2  header  file, 
and  is  available  if  INCL_DOSTRACE ap¬ 
pears  in  a  #define  directive  before  the 
Hnclude  os2.h  statement.  A  PTRACE¬ 
BUF  contains  fields  for  all  the  286  reg¬ 
isters,  fields  to  specify  the  process  ID 
and  thread  ID  and,  most  importantly, 
a  field  used  to  issue  DosPTrace  com¬ 
mands  and  get  back  DosPTrace  event 
notifications.  Symbolic  names  for  these 
commands  and  events  are  in  PTRACE.H 
(Listing  Seven,  page  115). 

There  are  many  DosPTrace  com¬ 
mands,  including  SINGLE_STEP, 
WRITEI _SPA  CE  (write  instruction 
space,  that  is,  make  code),  WRITE_D_ 
SPACE  (write  data  space),  and  so  on; 
the  one  used  here,  GO,  simply  runs  the 
child  process.  All  threads  of  the  child 
process  run  until  something  “interest¬ 
ing”  happens.  At  that  point,  DosPTrace 
returns  and  the  caller  can  see  what 
event  took  place.  In  Listing  Six,  natu¬ 
rally,  I  am  mainly  interested  in  EVENT_ 
GP_FAULT. 

There  is  very  little  performance  over¬ 
head  when  a  program  is  run  under 
DosPTrace  using  the  GO  command  (us¬ 
ing  SINGLE_STEP,  the  debugger  would 
run  as  slowly  as  molasses).  A  GP  fault, 
though,  is  a  very  expensive  operation. 
In  one  test  under  OS/2,  I  could  only 
commit  about  200  GP  faults  per  sec¬ 
ond.  This  is  acceptable,  because  GP 
faults  should  take  place  infrequently. 

When  a  user  runs  OS2TRACE,  the 
program  execs  another  instance  of  it¬ 
self  under  DosPTrace  and,  using  a  com¬ 
mand-line  argument,  tells  this  second 
process  that  it  is  the  second  OS2TRACE 
process  and  therefore  should  run  the 
GP  fault  interpreter  rather  than  the 
DosPTrace  loop.  If  the  user  causes  the 
interpreter  to  fault,  DosPTrace  returns 
EVENT_GP_FAULT,  and  the  process  run¬ 
ning  DosPTrace  detects  that  the  inter¬ 
preter  process  has  GP  faulted. 


The  DosPTrace  process  must  com¬ 
municate  this  fault  back  to  the  inter¬ 
preter  process,  so  that  the  interpreter 
can  resume  execution  at  a  different 
CSTP.  When  the  trace  process  detects 
a  GP  fault,  it  uses  the  DosPTrace 
WR1TE_REGISTERS  command  to  alter 

Extensible  systems  need 
to  react  to  and  recover 
from  errors  after  they 
happen,  or  after  some 
underlying  system  has 
detected  them.  Protected 
mode  is  just  such  an 
underlying  system,  and 
we  should  take 
advantage  of  it 


the  CSTP  of  the  interpreter  process. 
When  the  tracer  next  tells  the  inter¬ 
preter  to  GO,  the  interpreter  resumes 
at  a  new  location. 

Where  should  the  interpreter  jump? 
In  C,  it  is  difficult  to  get  the  address  of 
an  arbitrary  line  of  code.  Because  there 
is  no  equivalent  to  the  $  location  counter 
used  in  MASM  and  other  assemblers, 
OS2TRACE.C  uses  the  address  of  a  para¬ 
meterless  function.  This  one-liner  long- 
jmps  to  the  interpreter’s  top-level  input 
loop.  The  trace  process  does  not  call 
this  function  in  the  interpreter  process. 
The  tracer  tells  the  interpreter  to  call 
( goto )  this  function. 

Even  though  the  two  processes  share 
the  same  code,  they  are  different  pro¬ 
cesses.  The  tracer  knows  the  address 
of  this  function  in  the  interpreter’s  ad¬ 
dress  space  because  of  OS/2’s  “disjoint 
LDT  space”  - —  the  code  segment  con¬ 
taining  this  function  is  mapped  to  the 
same  slot  in  each  process’s  Local  De¬ 
scriptor  Table. 

Despite  this,  in  the  program  shown 
in  Listing  Six  I  decided  to  use  still  an¬ 
other  DosPTrace  command,  SEG_NUM_ 
TO_SELECTOR.  Given  a  logical  segment 
number  (such  as  that  found  in  a  .MAP 
file)  and  a  process  ID,  this  operation 
returns  the  actual  segment  selector  for 
the  process.  I  know  that  the  function 
catch _sig_segv( )  is  in  segment  #1.  In 
the  trace  process,  the  function 
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send_sig_segv( )  first  calls  selector_ 
from_segment( )  to  get  the  new  CS  for 
the  interpreter  process,  and  then  calls 
set_csip( )  to  change  the  interpreter’s 
registers. 

Being  able  to  catch  GP  faults  under 
OS/2  is  still  important  even  for  devel¬ 
oping  applications  that  do  not  run  user 
code.  Even  for  normal  applications 
where  a  GP  fault  is  the  sign  of  an 
internal  bug,  OS/2’s  GP  fault  register 
dump  is  unattractive,  makes  little  sense 
to  most  users,  and  can’t  be  redirected 
to  a  file.  The  code  in  Listing  Six  can  be 
modified  to  have  the  GP  fault  handler 
dump  the  register  state  to  a  file  instead 
of  attempting  recovery.  The  DosPTrace 
READ_I_SPACE  command  can  be  used 
to  disassemble  the  faulting  instruction 
at  CS:IP.  Then,  if  the  program  ever  GP 
faults,  it  could  ask  the  user  to  please 
send  you  this  “core  dump”  file. 

Faulting  Inside  OS/2  DLLs 

Because  OS/2  is  a  far  richer  and  more 
complicated  environment  than  a  DOS 
extender,  simple  peeks  and  pokes  are 
not  an  adequate  test  for  catching  GP 
faults.  What  happens  if  the  user  of  an 
OS/2  interpreter  uses  an  illegal  address 
while  calling  a  routine  in  a  dynamic 
link  library  (DLL),  or  while  making  a 
DosXxxC )  call  to  the  OS/2  kernel?  Lug- 
aru’s  Epsilon  EMACS  editor,  OS2XLISP, 
UR/Forth,  and  the  mini-interpreter  I  built 
in  the  November  1989  DDJ  (“Linking 


While  the  Program  Is  Running”),  are 
all  OS/2  programs  that  let  the  user  call 
DLL  routines  at  run  time,  and  all  can 
fall  prey  to  the  protected-mode  inter¬ 
preter  problem. 

In  the  OS/2  GP  fault  interpreter  in 
Listing  Six,  instead  of  poking  at  ad¬ 
dresses,  the  user  types  in  a  number 
from  0  to  7.  Each  corresponds  to  a 
different  line  of  bad  code.  Figure  2 
shows  a  sample  session,  with  the  lines 
of  code  appended  as  comments. 

The  first  two  pieces  of  bad  code 
hold  few  surprises.  In  the  first  case,  the 
NIL  pointer  Ifint  far  *)  OP)  was  loaded 
into  ES:BX,  but  trying  to  dereference  it 
caused  a  GP  fault.  In  the  second  case, 
trying  to  peek  at  {.(int far  *)  -IP)  faulted 
earlier:  The  processor  refused  to  load 
ES  with  FFFF.  The  error  code  is  FFFC, 
not  FFFF,  because  while  one  of  these 
processor  error  codes  looks  like  a  seg¬ 
ment  selector,  the  bottom  two  bits  are 
used  for  other  purposes. 

The  next  piece  of  bad  code  does  not 
cause  a  GP  fault.  I  wanted  this  code  to 
illustrate  an  attempt  to  poke  the  code 
segment.  However,  I  coded  the  exam¬ 
ple  incorrectly  so  that  instead  of  fault¬ 
ing,  it  successfully  pokes  an  “x”  some¬ 
where  in  the  data  space.  Strings  that 
go  first,  and  for  the  rest  of  this  session, 
the  word  “violation”  is  printed  out  as 
“vxolation”  This  illustrates  the  limits 
of  protection.  The  Intel  processor  was 
powerless  to  stop  this  “vxolation”  of 


C  :_OS2\PTRACE>os2trace  -v 
$  0  ;;  x  =  *((int  far  *)  0L); 

GP  fault  (error  0000)  at  0047:01  CO 

AX-0030  BX-0000  CX-0000  DX-0087 

SI-0087 

DI-0001 

BP-0CBE 

DS-0087  ES-0000  IP-01  CO  CS-0047 

FL-2246 

SP-0C5A 

SS-0087 

General  Protection  violation! 

$1  ;;  x  =  *((int  far  *)  -1 L); 

GP  fault  (error  FFFC)  at  0047:01  BE 

AX-0031  BX-FFFF  CX-0000  DX-0087 

SI-0087 

DI-0001 

BP-0CBE 

DS-0087  ES-0087  IP-01  BE  CS-0047 

FL-2202 

SP-0C5A 

SS-0087 

General  Protection  violation! 

$2  ;;  *((char  *)  main)  = ’x’; 

Executed  statement  2 
$  3  ;;  x  =  VioWrtTTYfOL,  100,  0); 

GP  fault  (error  0000)  at  00D7:27F1 

AX-0000  BX-02C4  CX-0051  DX-0000 

SI-0087 

DI-0051 

BP-0C34 

DS-00DF  ES-0000  IP-27F1  CS-00D7 

FL-2246 

SP-0C26 

SS-0087 

Faulted  inside  DLL  code 

General  Protection  vxolation! 

$7  ;;  x  =  DosGetlnfoSeg(1L,  2L); 

Thread  1  dying 

Process  79  dying 

C:\OS2\PTRACE> 

Figure  2:  A  sample  session  using  the  OS/2  GP  fault  interpreter 


Session  Title:  CVP  app  0S2TRACE.EXE 
The  system  detected  a  general  protection 
fault  (trap  D)  in  a  system  call. 

CS-0047  IP-0237  S-0087  SP-0C5A 
ERRCD-0000  ERLIM=*‘"  ERACC-** 
Arguments  used  in  system  call  (high  to  low): 
0000  0001  0000  0002 
End  the  program 


Figure  3 ■'  An  OS/2  message,  different  from  a  normal  GP fault  dump 
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(continued  from  page  82) 
data  space. 

In  the  next  example,  a  bad  pointer 
is  passed  to  VioWnTTYO.  OS2TRACE 
detects  that  the  fault  took  place  inside 
DLL  code.  DLL  code  uses  its  own  data 
segment,  but  uses  its  caller’s  stack.  Look¬ 
ing  at  the  function  set_csip( )  in  Listing 
Six.  If,  at  the  time  of  a  GP  fault,  the 
interpreter  process’  does  not  equal  SS, 
it  means  this  small  program  was  using 
someone  else’s  DS.  This  means  DS  must 
be  reset  to  a  proper  value  before  re¬ 
suming  execution  of  the  interpreter. 
longjmp( )  can’t  be  relied  on  to  restore 
DS,  because  the  jmp_ buf  itself  resides 
in  the  process’s  data  segment.  Before 
the  interpreter  can  run  again,  DS  must 
be  pointed  back  to  the  correct  data 
segment.  This  small  program  did  this 
by  using  SS,  but  in  a  larger  program 
with  multiple  data  segments,  the  trace 
process  probably  would  have  to  keep 
a  list  of  valid  data  segments. 

In  the  final  example,  bad  pointers 
are  passed  to  an  OS/2  kernel  routine, 
DosGetlnfoSegC ).  A  GP  fault  is  gener¬ 
ated,  but  in  this  case  OS2TRACE  is  not 


able  to  catch  it.  This  is  a  limitation  of 
DosPTrace( ),  not  OS2TRACE.  If  this 
same  code  is  run  under  CVP,  CVP  won’t 
catch  the  fault  either.  Instead,  OS/2 
displays  a  somewhat  different  message 
than  its  normal  GP  fault  dump,  as  shown 
in  Figure  3.  All  CVP  can  do  is  display 
the  message  “Thread  terminated  nor¬ 
mally  (13).”  The  thread  returns  OxOD 
to  indicate  that  it  has  GP  faulted.  It’s  a 
shame  that  OS2TRACE  can’t  catch  this 
fault,  but  it  is  somewhat  consoling  that 
CVP  can’t  either.  This  is  a  limitation  of 
DosPTrace.  Any  OS/2  debugger  (such 
as  Logitech’s  MultiScope)  will  undoubt¬ 
edly  have  the  same  limitation. 

One  line  of  bad  code  in  OS2TRACE 
was  not  executed  in  the  sample  ses¬ 
sion.  VioWrtTTY(OL),  in  which  I  acci¬ 
dentally  left  off  the  last  two  arguments 
to  VioWrtTTY,  doesn’t  GP  fault.  Instead, 
it  hangs  OS/2!  I  have  only  found  one 


Figure  4:  Detecting  INT  OC  under  OS/2 


way  to  make  this  fault  inside  VioWrtTTY 
without  hanging  the  machine,  and  that 
is  to  single-step  through  the  code  in 
CVP.  In  that  case,  OS/2  detects  INT  OC, 
the  stack  exception,  as  shown  in  Fig¬ 
ure  4.  CodeView  prints  out  “Thread 
terminated  normally  (12).” 

ON  ERROR  and  ESTAE 

Having  figured  out  how  to  use 
DosPTrace  to  catch  most  GP  faults  in 
OS/2,  it  becomes  clear  that  DosPTrace 
is  a  powerful  part  of  OS/2  and  could 
probably  be  used  for  all  sorts  of  tricky 
programming.  On  the  other  hand,  why 
is  it  so  much  more  difficult  to  catch 
GP  faults  in  OS/2  than  when  using  a 
DOS  extender?  Part  of  the  reason  is 
that  OS/2  is  a  far  more  ambitious  un¬ 
dertaking  than  a  DOS  extender.  A  DOS 
extender  doesn’t  have  to  worry  about 
GP  faulting  inside  a  dynamic-link  li- 


SYS1942:  A  program  attempted  to  reference  storage 
outside  the  limits  of  a  stack  segment.  The  program 
was  ended. 

TRAP  000C 


Lessons  from  History: 

IBM  Mainframe  Error  Handling 


Gordon  Letwin’s  assumption,  that  a 
GP  fault  is  evidence  that  the  program’s 
logic  is  incorrect,  is,  according  to  Karl 
Finkemeyer  of  IBM  ASD,  the  same 
mistake  the  early  OS/360  designers 
made.  It  ignores  the  fact  that  there  are 
situations  where  risking  a  fault  condi¬ 
tion  is  definitely  preferable  to  check¬ 
ing  each  and  every  pointer  before 
using  it.  So  when  PL/I  came  along, 
and  with  it  pointers  in  a  high-level 
language,  OS/360  had  to  add  a  facil¬ 
ity  for  the  PL/I  run-time  environment 
to  clean  up  after  a  user  program 
bombed  with  a  stray  pointer.  The  only 
alternative  would  have  been  to  do 
validity  checking  of  every  pointer  be¬ 
fore  every  usage,  and  that  was  intol¬ 
erable  performance  wise. 

So  OS/360  first  extended  the  exist¬ 
ing  SPIE  macro  (SPecify  Interruption 
Exit)  which  originally  was  only  meant 
for  arithmetic  errors  (divide  under¬ 
flow,  floating  point  significance  check, 
and  so  on.).  When  SPIE  became  more 
and  more  unwieldy  because  it  had 
to  handle  more  and  more  error  condi¬ 
tions,  the  non-arithmetic  error  condi¬ 
tions  were  taken  out  again  and  put 
into  the  new  STAE  (Specify  Task  Ab¬ 


normal  termination  Exit)  macro  in  MVT 
(Multiprogramming  with  a  Variable 
number  of  Tasks,  introduced  in  1967). 
Abnormal  termination  of  a  task  can 
be  intercepted  through  the  use  of 
STAE. 

The  syntax  ON  ERROR  could  have 
originated  in  PL/I  under  MVT.  The 
PL/I  compiler  under  MVT  translated 
the  ON  into  a  simple  STAE  exit  rou¬ 
tine.  So  STAE  and  ON  ERROR  prob¬ 
ably  are  not  just  similar;  they  may 
turn  out  to  be  the  same. 

In  IBM’s  MVS  (Multiple  Virtual  Stor¬ 
age  operating  system,  introduced  in 
mid-1974,  for  the  larger  System  370 
model,  and  their  followons  such  as 
the  3090s),  STAE  was  extended,  so  it 
became  the  ESTAE  macro.  Inside  an 
ESTAE  exit  routine,  you  can  do  nearly 
everything  you  want  (even  restart  the 
task)  as  long  as  you  don’t  bump  into 
another  abnormal  termination  condi¬ 
tion.  So  this  makes  it  easy  for  a  pro¬ 
gram  to  try  dangerous  things,  clean 
up  after  the  fact  if  something  went 
wrong,  and  continue. 

Because  ESTAE  is  too  unwieldy  for 
high-performance  system  code,  an¬ 
other  mechanism  was  introduced 


there:  FRRs  (Functional  Recovery  Rou¬ 
tines)  that  can  be  used  only  inside  the 
MVS  kernel,  mainly  because  they  use 
fixed  control  blocks  so  that  the  over¬ 
head  of  activating  and  deactivating 
them  remains  small.  By  now,  every 
MVS  routine  is  either  associated  with 
an  FRR  or  is  covered  by  its  caller’s 
FRR. 

According  to  A.L.  Scherr  (“IBM  Sys¬ 
tems  Journal,”  Vol.  12,  No.  4),  “An 
interesting  footnote  to  this  design  is 
that  now  a  system  failure  can  usually 
be  considered  to  be  the  result  of  two 
program  errors:  The  first,  in  the  pro¬ 
gram  that  started  the  problem;  the 
second,  in  the  recovery  routine  that 
could  not  protect  the  system.”  If  a 
system  module  bombs  and  the  FRR 
runs  into  problems  and  none  of  the 
more  general  FRRs  higher  up  on  the 
FRR  stack  can  resolve  the  problem, 
only  then  MVS  crashes.  The  result  of 
this  architecture  is  MVS’s  “continuous 
operation:”  There  are  many  installa¬ 
tions  where  MVS  just  keeps  running 
(even  when  one  or  more  of  the  pro¬ 
cessors  die,  and  are  restarted  after 
repair)  until  it  is  taken  down  for  apply¬ 
ing  maintenance. 
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(continued  from  page  84) 

brary,  because  DOS  extenders  don’t 

provide  dynamic  linking. 

The  major  reason  for  the  difficulty, 
however,  is  that  OS/2  does  not  provide 
much  support  for  exception  handling 
by  applications.  This  is  surprising  for 
two  reasons.  First,  with  Microsoft’s  pre¬ 
dilection  for  Basic,  one  might  have  ex¬ 
pected  the  company  to  at  least  provide 
OS/2  with  something  such  as  one  of 
Basic’s  most  powerful  features,  ON  ER¬ 
ROR  (from  the  ON  statement  in 
PL/I).  Second,  and  more  important,  if 
anything  from  IBM  was  going  to  rub 
off  on  Microsoft  and  OS/2,  it  should 
have  been  the  strong  emphasis  on  er¬ 
ror  handling,  exception  handling,  and 
fault  recovery  found  in  large  IBM  oper¬ 
ating  systems.  (See  the  sidebar,  “Les¬ 
sons  from  History,”  for  a  brief  discus¬ 
sion  of  the  ESTAE  and  FRR  error-han¬ 
dling  facilities  in  IBM’s  MVS.) 

In  Conclusion 

Having  spent  so  much  time  talking  about 
intermpts,  errors,  faults,  traps,  and  ex¬ 
ceptions,  by  now  the  reader  must  feel 
that  protected  mode  is  “The  Promised 
Land  of  Error”  (the  subtitle  of  a  book 
that  has  nothing  to  do  with  Intel  pro¬ 
cessors).  Nonetheless,  this  discussion 
of  catching  GP  faults  has  only  scratched 
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the  surface  of  protected-mode  inter¬ 
rupt  handling.  For  example,  this  article 
never  explained  the  difference  between 
an  exception  and  an  interrupt.  In  addi¬ 
tion  to  the  standard  Intel  literature,  three 
good  books  for  more  information  on 
protected-mode  programming  are  John 
H.  Crawford  and  Patrick  P.  Gelsinger’s 
Programming  the  80386 ( Sybex,  1987), 
Edmund  Strauss’s  Inside  the 80286 ( Pren¬ 
tice-Hall,  1986),  and  Phillip  Robinson’s 
Dr.  Dobb's  Toolbook  of  80286/80386 
Programming  (M&T  Publishing,  1988). 

Errors,  exceptions,  and  faults  are  an 
extremely  important  part  of  program¬ 
ming.  One  author  distinguished  be¬ 
tween  “good”  exceptions  and  “bad” 
exceptions,  saying  that  with  good  ex¬ 
ceptions,  “the  corrective  actions  you 
perform  are  an  integral  part  of  your 
system”  and  that  good  exceptions  “are 
the  ones  you  expect  to  occur,”  whereas 
bad  exceptions  indicate  a  program  bug 
(Strauss,  Inside  the  80286).  Using  this 
definition,  I  hope  I  have  shown  that 
the  GP  fault  can  be  a  “good”  excep¬ 
tion,  that  many  systems  should  expect 
it  to  occur,  and  that  catching  and  re¬ 
covering  from  it  should  be  an  integral 
part  of  many  (but  by  no  means  all) 
systems. 

Flexible,  extensible  systems  don’t 
need  more  error  checking.  They  need 


error  handling.  The  more  flexible  the 
system,  the  less  it  knows  about  the 
types  it  operates  on,  and  the  less  up¬ 
front  checking  it  can  do.  Extensible 
systems  need  to  E>e  able  to  react  to,  and 
recover  from  errors  after  they  happen, 
or  after  some  underlying  system  has 
detected  them.  Protected  mode  is  such 
an  underlying  system,  and  we  should 
take  advantage  of  it. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  112.) 

Vote  tor  your  favorite  feature/article. 

Circle  Reader  Service  No.  7. 
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Listing  One  (Text  begins  on 

page  78, 132 
?PLM  =  0 

page  16.) 

freelist  =  0; 
cwSegs  =  MINPSEGS; 

DefineHandleTable (SegmentTable) ; 
segDgroup  =  HIWORD ((void  FAR  *) SsegDgroup) ; 

.xlist 

include  CMACROS.INC 

PSEG  FAR  PASCAL  SegmentAlloc (DWORD  size) 

.  list 

;Use  C  calling  convention 

PSEG  pseg; 

HANDLE  handle; 

.model  medium 

.code 

if  (freelist) 

cProc  memcpyifp, <PUBLIC>, <ds, si,  di> 

if  (! (handle  =  GlobalAlloc (GMEM  MOVEABLE, 

size) ) ) 

parmD  Destlfp 
parmD  Sourcelfp 

return ( (PSEG) 0) ; 

parmW  cb 

pseg  =  freelist; 

cBegin 

freelist  =  (PSEG) *f reelist; 

mov  bx, SEG_DestIfp 

mov  dx,bx 

;pSeg  is  high  word  of  return  value 

I 

else 

mov  es,ds:[bx] 

mov  bx,SEG  Sourcelfp 

; Segment  of  destination 

( 

if  (cwSegs  >=  MAXPSEGS) 

mov  ds,ds:[bx) 

mov  si, OFF  Sourcelfp 

.•Segment  of  source 

return ( (PSEG) 0) ; 

mov  di,OFF  Destlfp 

if  ( ! (handle  =  GlobalAlloc (GMEM  MOVEABLE, 

size) ) ) 

mov  ax,di 

mov  cx,cb 

;Low  word  of  return  value 

return ( (PSEG) 0) ; 

; Source  in  dsrsi 

pseg  =  &SegmentTable[cwSegs+2] ; 

destination  in  es:di 
; Count  in  cx 

cwSegs++; 

I 

shr  cx, 1 

;Move  by  words 

*pseg  =  GlobalSegment (handle) ; 

rep  movsw 

return (pseg) ; 

jnc  EvenBytes 

;Was  it  an  even  number? 

I 

movsb 

;Move  the  odd  byte 

EvenBytes: 

void  FAR  PASCAL  SegmentFree (PSEG  pseg) 

; return  value  is  destination  IFP  in  d> 

:ax 

lif  DEBUG 

if  ( ! VALID  VARIABLE  PSEG(pseg)) 

cEnd 

SegmentError ( ) ; 

end 

lendif 

End  Listing  One 

if  (*pseg) 

Listing  Two 

1 

lif  DEBUG 

if  ( (*pseg  %  2)  ==  0) 

/*  segtable.c  */ 

SegmentError () ; 

lendif 

linclude  "windows. h" 

Idefine  GLOBAL 

GlobalFree( (HANDLE) GlobalHandle (*pseg) ) ; 

1 

linclude  "segtable.h" 

* (PSEG  *)pseg  =  freelist; 
freelist  =  pseg; 

static  PSEG  NEAR  freelist; 

} 

void  FAR  PASCAL  Segmentlnit (void) 

void  FAR  PASCAL  DataFree (PSEG  pseg) 

i 

1  (continued  on  page  90) 
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Listing  Two  (Listing  continued,  text  begins  on  page  16.) 

#if  DEBUG 

if  ( ! VALIDPSEG (pseg)  II  (*pseg  %  2)  ==  0) 

SegmentError () ; 

#endif 

GlobalFree( (HANDLE) GlobalHandle (*pseg) ) ; 

*pseg  =  0; 

} 

BOOL  FAR  PASCAL  SegmentRealloc (PSEG  pseg,  DWORD  size) 

{ 

HANDLE  handle; 

#if  DEBUG 

if  (! VALIDPSEG (pseg) ) 

SegmentError () ; 

lendif 

if  (*pseg) 

{ 

#if  DEBUG 

if  ((*pseg  %  2)  ==  0) 

SegmentError () ; 

#endif 

return  (  (BOOL)  GlobalReAlloc (  (HANDLE) GlobalHandle (*pseg) ,  size, 
GMEM  MOVEABLE) ) ; 

} 

else 

( 

if  ( ! (handle  =  GlobalAlloc (GMEM_MOVEABLE,  size))) 
return (FALSE) ; 

*pseg  =  GlobalSegment (handle) ; 
return (TRUE) ; 

) 

) 

#if  DEBUG 

void  FAR  PASCAL  SegmentError (void) 

( 

FatalExit (-1) ; 

1 

lendif 


End  Listing  Two 


Listing  Three 

/*  segtable.h  */ 

Idefine  MAXPSEGS  9 

Idefine  MINPSEGS  1 

Idefine  cwSegs  SegmentTable [0] 

Idefine  cwClear  SegmentTable [1] 

Idefine  segDgroup  SegmentTable [2] 

lifndef  GLOBAL 
Idefine  GLOBAL  extern 
lendif 

typedef  WORD  BOOLEAN; 
typedef  WORD  SEG; 
typedef  SEG  NEAR  *PSEG; 
typedef  unsigned  long  IFP; 

Idefine  FARPTR (of f ,  seg)  (  (void  FAR  * ) MAKELONG (off ,  seg)  ) 

Idefine  MAKEIFP (of f , pseg)  (  ( IFP) MAKELONG (of f,  pseg)  ) 

Idefine  IFP2SEG(ifp)  (  * (PSEG) HIWORD (ifp)  ) 

Idefine  IFP2PTR(ifp)  FARPTR (LOWORD (ifp) ,  IFP2SEG (ifp) ) 

Idefine  GlobalSegment (handle)  ((SEG)  HIWORD (GlobalHandle (handle) )  ) 

void  FAR  PASCAL  Segmentlnit (void) ; 

PSEG  FAR  PASCAL  SegmentAlloc (DWORD  size); 
void  FAR  PASCAL  SegmentFree (PSEG  pseg); 
void  FAR  PASCAL  DataFree (PSEG  pseg); 

BOOL  FAR  PASCAL  SegmentRealloc (PSEG  pseg,  DWORD  size); 
void  FAR  PASCAL  Def ineHandleTable (WORD  NEAR  *segtable) ; 
void  FAR  PASCAL  SegmentError (void) ; 

GLOBAL  SEG  NEAR  SegmentTable [MAXPSEGS  +  2]; 

Idefine  VALIDPSEG (pseg)  \ 

(pseg  >  &SegmentTable [1]  &&  \ 
pseg  <  SSegmentTable [MAXPSEGS  +  2]  &&  \ 

( (WORD) pseg  %  2)  ==  0) 

Idefine  VALID_VARIABLE_PSEG (pseg)  \ 

(pseg  >  SSegmentTable [MINPSEGS  +  1]  &&  \ 
pseg  <  &SegmentTable [MAXPSEGS  +2]  &&  \ 

((WORD) pseg  %  2)  ==  0) 


End  Listings 
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Listing  One  (Text  begins  on  page  28.) 

/*  example. c  -  An  example  of  three  dimensional  graphics  using  Xlib.  */ 


register  int  i,  j,  k;  /*  index  variables  */ 

Transform  temporary;  /*  a  temporary  result  */ 

/*  Using  a  temporary  result  allows  a  single  transform  to  be  passed  in 
*  as  both  one  of  the  original  transforms  and  as  the  new  result.  */ 


♦include  <X11/Xlib.h> 
#include  <X11/Xutil.h> 
finclude  <math.h> 

♦include  <stdio.h> 
finclude  "double  buffer. h" 


typedef  double  Transform[4] [4] ; 
typedef  double  Point [3]; 


Display  ‘display; 
Window  window; 

GC  gc; 

XColor  colors [4]; 
double_buf fer_state 
double_buf fer  =  1; 
unsigned  int  width, 
Transform  model; 
Transform  view; 
Transform  device; 
Transform  composite; 
Transform  motion; 


/*  display  connection  */ 

/*  window  identifier  */ 

/*  graphics  context  */ 

/*  colors  to  draw  with  */ 

*dbuf_state;  /*  state  record  for  double  buffer  utilities*/ 
/*  Whether  to  use  double  buffering  */ 

height;  /*  last  known  window  size  */ 

/*  transform  from  world  to  modelling  coordinates*/ 
/*  transform  from  modelling  to  VDC  coordinates  */ 
/*  transform  from  VDC  to  device  coordinates  */ 

/*  transform  from  world  to  device  coordinates  */ 

/*  transform  for  modelling  motion  */ 


identity (transform) 

/*  Set  a  Transform  matrix  to  an  identity  matrix.  */ 
Transform  transform;  /*  transform  to  operate  on  */ 

{ 

register  int  i,  j; 


for 


1 


(i  =  0;  i  <  4;  i++) 

for  (j  =  0;  j  <  4;  j++) 
transform[i] [ j] 


(i  ==  j); 


rotate_X (transform,  angle) 

/*  Set  a  Transform  matrix  to  a  rotation  around  the  X  axis.  */ 
Transform  transform;  /*  transform  to  operate  on  */ 
double  angle;  /*  angle  in  radians  to  rotate  by  */ 

{ 

identity (transform) ; 

transform[l) [1]  =  transform[2] [2]  =  cos (angle); 
transform(2) [1]  =  - (transform(l] [2]  =  sin(angle)); 

} 

rotate_Y (transform,  angle) 

/*  Set  a  Transform  matrix  to  a  rotation  around  the  Y  axis.  */ 
Transform  transform;  /*  transform  to  operate  on  */ 
double  angle;  /*  angle  in  radians  to  rotate  by  */ 

{ 

identity (transform) ; 

transform[0] [0]  =  transform[2] [2]  =  cos (angle); 
transform[0] [2)  =  - (transform[2] [0]  =  sin(angle)); 

} 

transform_point (transform,  p,  tp) 

/*  Apply  a  Transform  matrix  to  a  point.  */ 

Transform  transform;  /*  transform  to  apply  to  the  point  */ 

Point  p;  /*  the  point  to  transform  */ 

Point  tp;  /*  the  returned  point  after  transformation  */ 

( 


int  i, 

j; 

double 

homogeneous [4] ; 

double 

sum; 

for  (i 

=  0; 

i  <  4;  i++) 

{ 

sum 

=  0.0; 

for 

(j  =  0;  j  < 

3;  j++) 

sum  += 

p[j]  *  transforml j] [i] ; 

homogeneous [i] 

=  sum  +  transform[3] [i] ; 

for  (i  =  0;  i  <  4;  i++)  { 

for  (j  =  0;  j  <  4;  j++)  { 

temporary [i] [ j]  =  0.0; 
for  (k  =  0;  k  <  4;  k++)  { 

temporary [i] [j]  +=  transforml [i] [k] 
*  transform2 [k] [ j] ; 

) 

} 


for 


» 


(i  =  0;  i  <  4;  i++) 

for  (j  =  0;  j  <  4;  j++) 

result [i][j]  =  temporary [i][j]; 


init_X(argc,  argv) 

/*  Initialize  the  X  window  system  */ 
int  argc;  /*  the  number  of  program  arguments  */ 
char  *argv[];  /*  an  array  of  pointers  to  program  arguments 
I 

XEvent  event; 

static  XSizeHints  xsh  =  {  /* 

(PPosition  I  PSize  !  PMinSize) 

300, 

300, 

200, 

200, 

5, 


); 

static  XWMHints  xwmh  =  {  / 

(InputHint  \  StateHint) 
False, 

NormalState, 

0, 

0, 

0,  0, 

0, 

0, 

}; 

static  XClassHint  xch  =  (  / 

"example", 

"Example" 

}; 

XGCValues  gcvalues; 


holds  X  server  events  */ 

Size  hints  for  window  manager*/ 
/*  flags  */ 

/*  height  */ 

/*  width  */ 

/*  minimum  height  */ 

/*  minimum  width  */ 

/*  x  coordinate  */ 

/*  y  coordinate  */ 

More  hints  for  window  manager  */ 

/*  flags  */ 

/*  input  */ 

/*  initial_state  */ 

/*  icon  pixmap  */ 

/*  icon  window  */ 

/*  icon  location  */ 

/*  icon  mask  */ 

/*  Window  group  */ 

Class  hints  for  window  manager  */ 

/*  name  */ 

/*  class  */ 


if  ((display  =  XOpenDisplay (NULL) )  ==  NULL)  ( 

fprintf (stderr,  "Can't  open  %s\n",  XDisplayName (NULL) ) ; 
exit  (1)  ; 

) 


window  =  XCreateSimpleWindow (display, 

DefaultRootWindow (display) , 

xsh.x,  xsh.y,  xsh. width,  xsh. height,  2, 

WhitePixel (display,  DefaultScreen (display) ) , 

BlackPixel (display,  DefaultScreen (display) ) ) ; 

XSetStandardProperties (display,  window,  "Example",  "Example", 
None,  argv,  argc,  &xsh) ; 

XSetWMHints (display,  window,  &xwmh); 

XSetClassHint (display,  window,  4xch) ; 

XSelectlnput (display,  window, 

StructureNotifyMask  ! 

ExposureMask  : 

ButtonPressMask  I 
ButtonlMotionMask  I 
PointerMotionHintMask) ; 


for 


(i  =  0;  i 
tp[i] 


3;  i++) 

homogeneous [i]  /  homogeneous [3] ; 


cross_product (vl,  v2,  c) 

/*  Compute  the  cross  product  of  two  vectors.  */ 

Point  vl,  v2;  /*  the  vectors  to  take  the  cross  product  of  */ 
Point  c;  /*  the  result  */ 

{ 

c [0]  =  vl[l]  *  v2 [2]  -  vl [2]  *  v2 [ 1 ] ; 

c  [  1 )  =  vl  [2]  *  v2  [0]  -  vl  [0]  *  v2  [ 2 ]  ; 

c  (2 ]  =  vl  [0]  *  v2  [1]  -  vl  [1]  *  v2  [ 0 ) ; 

} 


backface(pl,  p2,  p3) 

/*  Determine  if  a  polygon  is  a  back  face  of  an  object  */ 

Point  pi,  p2,  p3;  /*  the  first  three  vertices  of  a  polygon  */ 

{ 

Point  vl,  v2,  c; 

/*  This  relies  on  the  first  three  vertices  of  each  face  being  clockwise 

*  around  a  convex  angle  or  counter-clockwise  around  a  concave 

*  angle  as  viewed  from  the  front  of  the  face.  */ 
vl [0]  =  P2 [0]  -  pi [0] ; 

vl [1]  =  p2 [ 1 ]  -  pi [1] ; 
vl [2]  =  P2 [2]  -  pi [2] ; 
v2[0]  =  P2 [0]  -  p3 [0] ; 
v2[l]  =  P2 [ 1 ]  -  P3 [1] ; 
v2[2]  =  p2 [2]  -  P3 [2] ; 
cross_product (vl,  v2,  c) ; 
return (c [2]  >  0); 


XMapWindow (display,  window); 

XFlush (display) ; 

do  ( 

XNextEvent (display,  fievent); 

}  while  (event. type  !=  MapNotify  !!  event. xmap. window  !=  window); 

gc  =  XCreateGC (display,  window,  0,  Sgcvalues); 

XSetState (display,  gc, 

WhitePixel (display,  DefaultScreen (display) ) , 

BlackPixel (display,  DefaultScreen (display) ) , 

GXcopy,  AllPlanes) ; 

/*  black  */ 
colors [0] . red  =  0; 
colors [0] .green  =  0; 
colors (0J .blue  =  0; 

/*  white  */ 

colors [1] . red  =  65535; 
colors (1) .green  =  65535; 
colors [ 1 ) .blue  =  65535; 

/*  green  */ 
colors [2] . red  =  0; 
colors [2] .green  =  40000; 
colors [2] .blue  =  0; 

/*  yellow  */ 
colors [3] . red  =  65535; 
colors [3] .green  =  65535; 
colors [3] .blue  =  0; 


concatenate_transforms (transforml,  transform2,  result) 

/*  Use  matrix  multiplication  to  combine  two  transforms  into  one.  */ 
Transform  transforml,  transform2;  /*  the  transforms  to  combine  */ 
Transform  result;  /*  the  new  combined  transform  */ 

{ 


dbuf_state  =  start_double_buf fer (display, 

DefaultColormap (display,  DefaultScreen (display) ) ,  2,  colors); 
if  (dbuf_state  ==  NULL)  { 

fprintf (stderr,  "Couldn't  allocate  resources  for  double 

buffering\n") ; 

exit  111 ;  (continued  on  page  94) 
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Listing  One  ( Listing  continued,  text  begins  on  page  28.) 


i 

XSetPlaneMask (display,  gc,  dbuf_state->drawing_planes) ; 


init_transforms () 

/*  Initialize  transformations  for  modelling,  viewing,  and  device  mapping.  */ 

{ 

Window  root; 
int  x,  y; 

unsigned  int  b,  d; 


-2.0, 

-4.0, 

2.0, 

2.0, 

-4.0, 

2.0, 

-2.0, 

0.0, 

2.0, 

2.0, 

0.0, 

2.0, 

}; 

Point  transformed_points [POINTS] ; 
static  int  polygons []  =  { 


10,  11,  9,  8, 

12,  13,  15,  14, 

9,  11,  15,  13, 

11,  10,  14,  15, 

10,  8,  12,  14, 


10,  END_POLYGON, 
12,  ENDJPOLYGON, 

9,  END_POLYGON, 

11,  END_POLYGON, 

10,  END_POLYGON, 


identity (model) ; 

identity (view) ; 
view[2] [2]  =  2.0; 
view[2] [3]  =  1.0; 
view [3] [2]  =  29.0; 
view[3] [3]  =  15.0; 

XGetGeometry (display,  window,  &root,  &x,  &y,  Swidth,  Sheight, 
identity (device) ; 

device[0][0]  =  device[3][0]  =  width  /  2.0; 
device[l][l]  =  device[3]|lj  =  height  /  2.0; 


concatenate_transforms (model,  view,  composite); 
concatenate_transforms (composite,  device,  composite); 


&d) ; 


♦define  POINTS  16  /*  The  total  number  of  unique  points  */ 

♦define  POLYPOINTS  12  /*  The  maximum  number  of  vertices  in  a  polygon  */ 

♦define  PARTIALS  6  /*  The  maximum  number  of  partial  polygons  in  a  polygon*/ 


0, 

4, 

5, 

1, 

0, 

END 

PARTIAL  POLYGON, 

8, 

12, 

13, 

9, 

8, 

end' 

’polygon, 

0, 

1, 

3, 

2, 

0, 

END 

POLYGON, 

6, 

7, 

5, 

4, 

6, 

end’ 

'POLYGON, 

5, 

7, 

3, 

1, 

5, 

end' 

'polygon, 

7, 

6, 

2, 

3, 

7, 

end' 

'polygon, 

6, 

4, 

0, 

2, 

6, 

end' 

'polygon, 

END_POLYGONS, 

) ; 

XPoint  buffer [POLYPOINTS] ;  /* 
int  partials [PARTIALS] ;  /* 

int  num_partials;  /* 

int  src;  /* 

int  dest;  /* 

int  i;  /* 

int  at_start_of_polygon;  /* 

int  skip_polygon;  /* 


a  set  of  Xlib  coordinate  vertices  */ 
starting  points  of  partial  polygons  */ 
number  of  partial  polygons  in  a  polygon*/ 
an  index  into  buffer!]  */ 
an  index  into  polygons!]  */ 
an  index  into  partials []  */ 
flags  the  start  of  each  polygon  */ 
flags  a  backface  polygon  */ 


♦define  END_POLYGON  -2  /*  designates  the  end  of  one  polygon  */ 

♦define  END_POLYGONS  -3  /*  designates  the  end  of  all  polygons  */ 

♦define  END_PARTIAL_POLYGON  -1  /*  designates  the  end  of  a  partial  polygon  */ 


redraw  () 

/*  Draw  the  3d  object  using  the  current  composite  transform.  */ 


Point 

points 

[POINTS] 

-4.0, 

-4.0, 

-4.0, 

4.0, 

-4.0, 

-4.0, 

-4.0, 

4.0, 

-4.0, 

4.0, 

4.0, 

-4.0, 

-4.0, 

-4.0, 

4.0, 

4.0, 

-4.0, 

4.0, 

-4.0, 

4.0, 

4.0, 

4.0, 

4.0, 

4.0, 

-2.0, 

-4.0, 

-2.0, 

2.0, 

-4.0, 

-2.0, 

-2.0, 

0.0, 

-2.0, 

2.0, 

0.0, 

-2.0, 

XSetForeground (display,  gc,  colors [0] .pixel) ; 

XFillRectangle (display,  window,  gc,  0,  0,  width,  height); 

for  (i  =  POINTS  -  1;  i  >=  0;  i— ) 

transform_point (composite,  points [i],  transformed_points [i] ) ; 

dest  =  0; 

at_start_of_polygon  =  True; 
partials [0]  =  0; 
num_partials  =  1; 

for  (src  =  0;  polygons [src]  !=  END_POLYGONS;  src++)  ( 
if  (at_start_of_polygon)  { 

skip_polygon  =  backface ( 

transformed_points [polygons [src] ] , 
transformed_points [polygons [src+1] ] , 
transformed_points [polygons [src+2] ] ) ; 
at_start_of_polygon  =  False; 

> 

switch  (polygons [src] )  { 

(continued  on  page  96) 
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Listing  One  (Listing  continued,  text  begins  on  page  28.) 

case  END_POLYGON : 
if  ( !skip_polygon)  ( 

XSetForeground (display,  gc,  colors [2] .pixel) ; 

XFillPolygon (display,  window,  gc,  &buffer[0],  dest, 
Complex,  CoordModeOrigin) ; 

XSetForeground (display,  gc,  colors [1] .pixel) ; 
partials [num_partials]  =  dest; 
for  (i=0;  i<num_partials;  i++) 

XDrawLines (display,  window,  gc,  sbuffer [partials [i] ] , 
partials [i+1]  -  partials [i],  CoordModeOrigin); 

1 

dest  =  0; 

at_start_of_polygon  =  True; 
break; 

case  END_PARTIAL_POLYGON : 

partials [num_partials++]  =  dest; 
break; 
default : 

buffer [dest] .x  =  transformed_points [polygons [src] ] [0] ; 
buffer [dest++] .y  =  transformed_points (polygons [src] ] [ 1 ] ; 
break; 


if  (double_buffer)  { 

double_buf fer_switch (dbuf_state) ; 

XSetPlaneMask (display,  gc,  dbuf_state->drawing_planes) ; 

)  else  ( 

XSetPlaneMask (display,  gc,  AllPlanes) ; 

) 

XFlush (display) ; 


main(argc,  argv) 
char  *argv[]; 

( 

XEvent  event; 
int  x,  y; 
int  new_x,  new_y; 
unsigned  int  mask; 
unsigned  int  dummy; 

init_X(argc,  argv) ; 
init_transforms () ; 

printfC'Drag  button  1  to  rotate  the  object.Xn"); 

printf ("Press  button  2  to  toggle  double  buffering  on  and  off.Xn" ); 

printf ("Press  button  3  to  stop  the  program. \n") ; 

for  (;  ;  )  { 

XNextEvent  (display,  Seventh- 
switch  (event. type)  ( 
case  DestroyNotify : 

XCloseDisplay (display); 


/*  holds  X  server  events  */ 

/*  the  last  X  pointer  position  */ 

/*  a  new  X  pointer  position  */ 

/*  mask  of  button  and  modifier  key  state  */ 
/*  placeholder  for  unwanted  return  values  */ 


exit (0) ; 
break; 

case  Expose: 

if  (event .xexpose. count  ==  0)  ( 
redraw () ; 

) 

break; 

case  ConfigureNotify : 

if  ( (event .xconfigure .width  !=  width)  !! 

(event .xconfigure. height  !=  height))  { 
width  =  event .xconfigure. width; 
height  =  event. xconfigure. height; 

device[0][0]  =  device[3][0]  =  width  /  2.0; 
device[l][lj  =  device[3][l]  =  height  /  2.0; 

concatenate_transforms (model,  view,  composite); 
concatenate_transforms (composite,  device,  composite); 
redraw ( ) ; 

) 

break; 

case  MotionNotify : 

XQueryPointer (display,  window, 

& dummy,  & dummy, 

& dummy,  & dummy, 

&new_x,  &new_y, 

Smask) ; 

if  ( ! (mask  &  ButtonlMask) ) 
break; 

rotate_X (motion,  M_PI  /  360.0  *  (new_y  -  y) ) ; 
concatenate_transforms (model,  motion,  model); 
rotate_Y (motion,  -M_PI  /  360.0  *  (new_x  -  x)); 
concatenate_transforms (model,  motion,  model); 
x  =  new_x; 
y  =  new_y; 

concatenate_transforms (model,  view,  composite); 
concatenate_transforms (composite,  device,  composite); 
redraw () ; 
break; 

case  ButtonPress: 

x  =  event. xbut ton. x; 
y  =  event .xbutton .y; 
if  (event .xbutton .button  ==  2) 
double_buf fer  A=  1; 
if  (event .xbutton. button  ==  3) 
exit  (0)  ; 

break; 

default : 

break; 

End  Listing  One 


(Listings  continued  on  page  98) 


3-D-USING  X 


Listing  Two  ( Listing  continued,  text  begins  on  page  28.) 

/*  double  buffer.h  -  declarations  for  an  Xlib  double  buffering  utility.  */ 

/*  double  buffering  state  record  */ 
typedef  struct  { 

Display  ‘display; 

Colormap  cmap; 

long  drawing_planes;  /*  planes  currently  drawn  to  */ 
int  buffer;  /*  which  buffer  to  show,  even  or  odd  */ 

XColor  *colormaps[2] ;  /*  color  maps  for  even  and  odd  buffers  */ 

int  map  size;  /*  number  of  entries  in  color  maps  */ 

long  masks [2];  /*  write_enable  masks  for  odd  and  even  */ 

long  *planes;  /*  individual  planes  */ 

long  pixel;  /*  pixel  base  value  of  double  buffering  */ 

}  double_buffer_state; 

/*  double  buffering  procedures  */ 
extern  double_buffer_state  *start_double_buffer () ; 
extern  void  double_buffer_switch () ; 
extern  void  end_double_buffer () ; 


End  Listing  Two 


Listing  Three 

/*  double_buffer .c  -  an  Xlib  double  buffering  utility.  */ 

#include  <X11/Xlib.h> 

# include  <malloc.h> 

♦include  <stdio.h> 

♦include  "double_buffer.h" 

static  void  release (state) 
register  double_buffer_state  ‘state; 

/*  Release  a  possibly  partially  allocated  double  buffer  state  record.  */ 

{ 

if  (state  !=  NULL)  { 

if  (state->colormaps [0]  !=  NULL)  free (state->colormaps [0] ) 
if  (state->colormaps[lj  !=  NULL)  free (state->colormaps [1] ) 
if  (state->planes  !=  NULL)  free (state->planes) ; 
free (state) ; 

) 

} 

static  long  color (state,  simple_color) 
register  double_buffer_state  ‘state; 
register  long  simple_color; 

/*  Map  the  supplied  color  into  the  equivalent  color 
*  using  the  double  buffered  planes.  */ 


register  long  i,  plane,  computed_color; 
computed_color  =  state->pixel; 

for  (plane  =  1,  i  =  0;  simple_color  !=  0;  plane  «=  1,  i++)  ( 
if  (plane  &  simple_color)  { 

computed_color  !=  state->planes [i] ; 
simple_color  &=  “plane; 


return (computed_color) ; 


double_buffer_state  *start_double_buffer (display,  cmap,  planes,  colors) 

Display  ‘display; 

Colormap  cmap; 

long  planes;  /*  how  many  planes  for  each  buffer  */ 

XColor  ‘colors;  /*  color  settings  for  buffers  */ 

/*  Start  double  buffering  in  given  number  of  planes  per  buffer. 

*  If  resources  can  be  allocated,  then  set  color  pixels  in  colors  parameter 

*  and  return  the  address  of  a  double_buffer_state  record. 

*  Otherwise,  return  NULL.  */ 

l 

register  double_buffer_state  ‘state; 
register  long  i,  high_mask,  low_mask; 

/*  Allocate  memory.  */ 

state  =  (double_buffer_state  *)  malloc (sizeof (double_buffer_state) ) ; 
if  (state  ==  NULL) 

return  (NULL) ; 

state->map_size  =  1  «  (2  *  planes) ; 

state->colormaps (0)  =  (XColor  *)  malloc (state->map_size  ‘sizeof (XColor) ) ; 
state->colormaps [ 1 ]  =  (XColor  *)  malloc (state->map_size  ‘sizeof (XColor) ) ; 
state->planes  =  (long  *)  malloc ((2  *  planes)  *  sizeof (long) ) ; 
if  (state->colormaps (I]  ==  NULL  !!  state->colormaps [0]  ==  NULL 
! !  state->planes  ==  NULL)  ( 
release (state) ; 
return (NULL) ; 

} 

state->display  =  display; 
state->cmap  =  cmap; 

/*  Get  colors  to  double  buffer  with.  */ 
if  (XAllocColorCells (state->display,  state->cmap,  False, 

state->planes,  2*planes,  &state->pixel,  1)  ==  0)  f 
release (state) ; 
return (NULL) ; 


/*  Prepare  the  write  enable  masks.  */ 
state->masks [0]  =  AllPlanes; 
state->masks[l]  =  AllPlanes; 

/*  Mask  0  won't  write  in  the  "low"  planes.  */ 

/*  Mask  1  won't  write  in  the  "high"  planes.  */ 
for  (i  =  0;  i  <  planes;  i++)  ( 

state->masks [0]  &=  “state->planes [i] ; 
state->masks [1]  &=  “state->planes (planes  +  i] 


/*  Prepare  the  flags  and  pixel  values  for  each  color.  */ 
for  (i  =  0;  i  <  (1  «  planes);  i++)  { 

colors [i] .pixel  =  color(state,  i  !  (i  «  planes)); 
colors (ij . flags  =  DoRed  I  DoGreen  I  DoBlue; 


/*  Prepare  the  two  color  map  settings.  */ 

/*  Colormap  0  displays  the  "low"  planes.  */ 

/*  Colormap  1  displays  the  "high"  planes.  */ 

low_mask  =  (1  «  planes)  -  1; 

high_mask  =  lowmask  «  planes; 

for  (i  =  state->map_size  -  1;  i  >=  0;  i — )  ( 

state->colormaps [0] [i]  =  colors[i  &  low_mask]; 
state->colormaps [0] (i] .pixel  =  color (state,  i); 

state->colormaps [1] [i]  =  colors [ (i  &  highjnask)  »  planes]; 
state->colormaps [1] [i] .pixel  =  color (state,  i); 


/*  Set  up  initial  color  map  and  write_enable .  */ 
state->buffer  =  0; 

state->drawing_planes  =  state->masks [state->buf fer] ; 
XStoreColors (state->display,  state->cmap, 

state->colormaps [state->buf fer] ,  state->map_size) ; 

return (state) ; 


void  double_buffer_switch (state) 
register  double_buf fer_state  ‘state; 

/*  Change  double  buffering  buffer. 

*  Return  the  new  planes  mask  for  double  buffering.  */ 

1 

/*  Toggle  the  buffers.  */ 
state->buffer  A=  1; 

/*  Adjust  the  color  map  and  write  enable  mask.  */ 

XStoreColors (state->display,  state->cmap, 

state->colormaps (state->buf fer] ,  state->map_size) ; 

state->drawing_planes  =  state->masks [state->buf fer] ; 

} 

void  end_double_buf fer (state) 
register  double_buf fer_state  ‘state; 

{ 

XFreeColors (state->display,  state->cmap, 

&state->pixel,  1,  ~(state->masks [0]  &  state->masks [1] ) ) ; 
release (state) ; 


End  Listings 
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Listing  One  (Text  begins  on  page  38.) 

MODULE  Mtest  ; 

FROM  MENU  IMPORT  MenuType, Menu  ; 

FROM  InOut  IMPORT  WriteString,  WriteLn  ; 

PROCEDURE  CLS  ; 

BEGIN 

WriteString(CHR(12) )  ; 

END  CLS  ; 


PROCEDURE  Header  ; 
BEGIN 

WriteLn  ; 
WriteLn  ; 
WriteLn  ; 
WriteLn  ; 
WriteString (' 
WriteLn  ; 
WriteString (' 
END  Header  ; 


MAILING  LIST  MENU'); 

(Press  Esc  key  to  leave  progam) ' )  ; 


PROCEDURE  EnterData  ; 

END  EnterData  ; 

PROCEDURE  PrintZip  ; 

END  PrintZip  ; 

PROCEDURE  Modify  ; 

END  Modify  ; 

PROCEDURE  DelData  ; 

END  DelData  ; 

PROCEDURE  Browse  ; 

END  Browse  ; 

PROCEDURE  Backup  ; 

END  Backup  ; 

PROCEDURE  PrintNZip  ; 

END  PrintNZip  ; 

PROCEDURE  Setup  ; 

END  Setup  ; 

PROCEDURE  test  ; 

VAR 

test  :  MenuType  ; 
i  :  CARDINAL  ; 

BEGIN 

LOOP 


END  ; 

END  test  ; 
BEGIN 

test  ; 
END  Mtest. 


CLS  ; 
Header  ; 
test [0] 
test [1] 
test [2] 
test [3] 
test [4] 
test [5] 
test [6] 
test  [7] 


'1.  Enter  new  mail  list  data.'  ; 

'2.  Print  a  Zip  code  sorted  mail  list.'  ; 
'3.  Change  existing  data.'  ; 

'4.  Delete  a  single  address  from  the  list.' 
'5.  Browse  through  the  existing  data.'  ; 

' 6.  Backup  data. '  ; 

'7.  Print  a  mail  list  not  sorted  by  ZIP.'  ; 
'8.  Perform  other  functions.'  ; 


:=  Menu (test, 8) 
CASE  i  OF 
0 
1 
2 
3 


END  ; 
*  LOOP 


EXIT 

EnterData 
PrintZip 
Modify 
:  DelData 
:  Browse 
:  Backup 
:  PrintNZip 
:  Setup 
CASE  *) 


Listing  Two 


End  Listing  One 


DEFINITION  MODULE  READA; 

(*  EscType  determines  whether  an  esc  will  exit  a  field.  The  values  are: 

Esc  which  allows  an  escape  to  exit  a  field. 

NoEsc  which  prevents  exit  from  a  field  on  an  escape  char.*) 

FROM  SYSTEM  IMPORT  AX, BX, CX, DX, BP, CODE, SETREG  ; 

FROM  Terminal  IMPORT  Write  ; 

FROM  InOut  IMPORT  EOL  ; 

EXPORT  QUALIFIED  Grab,  ClearField,  gotoxy,  EscType  ; 

TYPE 

EscType  =  (Esc, NoEsc)  ; 

PROCEDURE  Grab (VAR  String  :  ARRAY  OF  CHAR  ;  EscFlag  : EscType)  ; 

PROCEDURE  ClearField (VAR  String  :  ARRAY  OF  CHAR  ;  Column, Row  :  CARDINAL); 
PROCEDURE  gotoxy (x,y  :  CARDINAL  )  ; 

END  READA. 


Listing  Three 


End  Listing  Two 


Name:  READA 

Purpose:  Usefull  String  routines 

ClearField  wipes  out  a  data  entry  field  on  screen 
Grab  accepts  characters  up  to  length  of  length  of  string  array 
then  refuses  to  accept  any  more  chars  until  Enter  is  pressed, 
gotoxy  positions  the  cursor. 

Entry:  ClearField (VAR  String:  ARRAY  OF  CHAR  ;  Column, Row  :  CARDINAL) 
Grab (VAR  String: ARRAY  OF  CHAR  ;  EscFlag  :  EscType) 
gotoxy (x,y  :  CARDINAL)  x  =  column  y  =  row. 

Exit:  ClearField  -  String  is  zeroed,  cursor  left  at  position 
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Column, Row 

Grab  -  String  is  filled  in  with  user  entered  characters. 
Global  Variables  used:  Passed  String  array. 

Revision  number: 

1.2  10/3/88  Escape  type  added  to  Grab. 

1.1  11/30/87  Escape  key  exit  for  String  0. 

1.0  11/8/87 


**) 


IMPLEMENTATION  MODULE  READA  ; 

FROM  SYSTEM  IMPORT  AX, BX, CX, DX, BP, CODE, SETREG  ; 

FROM  Terminal  IMPORT  Write,  Read  ; 

FROM  InOut  IMPORT  EOL  ; 

VAR 

Index  :  CARDINAL  ; 

Ch  :  CHAR  ; 

PROCEDURE  gotoxy (x, y  :  CARDINAL  )  ; 

VAR 

a  :  CARDINAL  ; 

BEGIN 

IF  {  x  >=  0)  AND  (  x  <=  79)  AND  (  y  >=0)  AND  (  y  <=24)  THEN 
IF  (  x  #  79)  OR  (y  #  24  ) 

THEN 

CODE (  55H)  ;  (*  PUSH  BP  *) 

a  :=  200H  ; 

SETREG  (  AX  ,a  )  ; 

CODE (  50H  )  ;  (*  PUSH  AX  *) 

a  :=  OH  ; 

SETREG (  BX  ,  a)  ; 

CODE {  53H)  ;  (*  PUSH  BX  *) 

SETREG (  DX, x  +  256  *  y)  ; 

CODE (  5BH  )  ;  (*  POP  BX  *) 

CODE (  58H  )  ;  (*  POP  AX  *) 

CODE (  0CDH, 10H)  ;  (*  INT  10H  *) 

CODE (  5DH  )  ;  (*  POP  BP  *) 

END  ; 

END  ; 

END  gotoxy  ; 

PROCEDURE  ClearField(VAR  String  :  ARRAY  OF  CHAR  ;  Column, Row  :  CARDINAL)  ; 
(*  This  procedure  wipes  the  appropriate  field  on  the  screen  out  *) 

BEGIN 

gotoxy (Column, Row)  ;  (*  Position  Cursor  *) 

FOR  Index  :=  0  TO  HIGH (String)  DO 
Write  ('  ')  ; 

END  ;  (*  FOR  *) 

gotoxy (Column, Row)  ;  (*  Reposition  Cursor  *) 

END  ClearField  ; 


PROCEDURE  Grab (VAR  String  :  ARRAY  OF  CHAR  ;  EscFlag  :  EscType  )  ; 

(*  This  procedure  assumes  that  the  cursor  has  already  been  moved  to  a  position 
either  by  a  direct  gotoxy  call  or  by  a  call  to  ClearField  *) 

BEGIN 


FOR  Index  :=  0  TO  HIGH (String)  DO 
String [Index]  :=  CHR(0)  ; 

END  ;  (*  FOR  *) 

Index  :=  0  ; 

LOOP 

Read(Ch)  ; 

IF  Ch  =  EOL  THEN  EXIT  END  ; 

IF  EscFlag  =  Esc  THEN 

IF  Ch  =  CHR (27)  THEN 

String [0]  :=  Ch  ; 

EXIT  ; 

END  ; 

END  ; 

IF  Ch  =  CHR (8)  THEN 

IF  Index  =  0  THEN 

Write (CHR (7) )  ;  (*  Honk  at  Barney  *) 

ELSE 

Write (CHR (8) )  ;  (*  Backspace  *) 

Write (CHR (32) )  ;  (*  Space  *) 

Write (CHR (8) )  ;  (*  Backspace  *) 

Index  :=  Index  -  1  ; 

String [Index]  :=  CHR(0)  ; 

END  ;  (*  IF  *) 

ELSIF  Ch  <  CHR (32)  THEN 

Write (CHR (7) )  ;  (*  Honk  at  Barney  *) 

ELSE 

IF  Index  =  (HIGH (String)  +1)  THEN 
Write (CHR (7))  ; 

ELSE 

String [Index]  :=  Ch  ; 

Write (Ch)  ; 

Index  :=  Index  +  1  ; 

END  ;  (*  IF  *) 

END  ;  (*  IF  *) 

END  ;  (*  LOOP  *) 

END  Grab  ; 

END  READA  . 


Listing  Four 


End  Listing  Three 


DEFINITION  MODULE  MENU  ; 

EXPORT  QUALIFIED  MenuType.Menu  ; 

TYPE  MenuType  -  ARRAY [0..59],  [0..79)  OF  CHAR  ; 

PROCEDURE  Menu (VAR  A  :  MenuType  ;  NumberOfMenuEntries  :  CARDINAL)  : CARDINAL 
END  MENU. 


End  Listing  Four 

(Listings  continued  on  page  102) 
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Listing  Five  (Listing  continued,  text  begins  on  page  38.) 

gotoxy (k, (j+m) )  ;  (*  Position  cursor  to  string  position  *) 
WriteString (A [m] )  ; 

END  ;  (*  FOR  *) 

(************************************************************************** 

FOR  m  :=  n  TO  2*n-l  DO 

Name:  MENU 

gotoxy (p, (j+m-n) )  ;  (*  Position  cursor  to  string  position  *) 

Purpose:  Automatic  screen  layout,  and  response  error  checking  for 

WriteString (A[m] )  ; 

Pick-a-number  menus. 

END  ;  {*  FOR  *) 

Entry:  Menu (VAR  A  :  MenuType  ;  NumberOfMenuEntries  :  CARDINAL):  CARDINAL  ; 

FOR  m  :=  2*n  TO  i  DO 

Exit:  Qualified  acceptance  of  menu  item  or  escape  key. 

gotoxy (r, (j+m-2*n) )  ;  (*  Position  cursor  to  string  position  *) 

Revision  Number: 

WriteString (A [m] )  ; 

1.1  10/3/88  Escape  key  output  changed  to  =  0 

END  ;  (*  FOR  *) 

1.0  9/26/88 

END  ThreeColumns  ; 

PROCEDURE  FourColumns (VAR  A  :  MenuType  ;  i  :  CARDINAL)  ; 

IMPLEMENTATION  MODULE  MENU  ; 

VAR 

FROM  READA  IMPORT  gotoxy,  Grab,EscType  ; 

j, k, l,m, n, o, p, q, r, s, t  :  CARDINAL  ; 

FROM  Strings  IMPORT  Length  ; 

BEGIN 

FROM  NumberConversion  IMPORT  StringToCard  ; 

(*  First  we  center  the  strings  to  be  displayed  vertically  *) 

FROM  InOut  IMPORT  WriteString  ; 

i  :=  i  -  1  ;  (*  Convert  from  one  base  to  zero  based  *) 

n  :=  i  DIV  4  ; 

PROCEDURE  OneColumn (VAR  A  :  MenuType  ;  i  :  CARDINAL)  ; 

j  :=  i  MOD  4  ; 

VAR 

IF  j  =  3  THEN  INC  (n)  END  ; 

j, k, l,m  :  CARDINAL  ; 

j  :=  (5  +  ((15  -  n)  DIV  2))  ; 

BEGIN 

(*  Now  we  center  the  strings  horizontally  *) 

i  :=  i  -  1  ;  (*  Convert  from  one  base  to  zero  based  *) 

1  :=  0  ; 

(*  First  we  center  the  strings  to  be  displayed  vertically  *) 

FOR  m  :=  0  TO  n-1  DO 

j  :=  (5  +  ((15  -  i)  DIV  2))  ; 

k  :=  Length (A [m] )  ; 

(*  Now  we  center  the  strings  horizontally  *) 

IF  (k  >  1)  THEN  1  :=  k  END  ;  (*  get  longest  string  length  *) 

1  :=  0  ; 

END  ;  (*  FOR  *) 

FOR  m  :=  0  TO  i  DO 

k  :=  (16  -(1  DIV  2))  ; 

k  :=  Length (A [m])  ; 

(*  Now  set  up  the  second  column  centered  on  position  40  *) 

IF  (k  >  1)  THEN  1  :=  k  END  ;  (*  get  longest  string  length  *) 

o  :=  0  ; 

END  ;  (*  FOR  *) 

k  :=  (40  -(1  DIV  2))  ; 

p  :=  Length (A [m] )  ; 

IF  (p  >  o)  THEN  o  :=  p  END  ;  (*  get  longest  string  length  *) 

(*  Now  print  the  menu  *) 

END  ;  (*  FOR  *) 

FOR  m  :=  0  TO  i  DO 

p  :=  (32  -(o  DIV  2))  ; 

gotoxy (k, (j+m) )  ;  (*  Position  cursor  to  string  position  *) 

(*  Now  set  up  the  third  column  centered  on  position  60  *) 

WriteString (A(m] )  ; 

q  o  ; 

END  ;  (*  FOR  *) 

FOR  m  :=  2*n  TO  3*n-l  DO 

END  OneColumn  ; 

r  :=  Length (A [m] )  ; 

IF  (r  >  q)  THEN  q  :=  r  END  ;  (*  get  longest  string  length  *) 

PROCEDURE  TwoColumns (VAR  A  :  MenuType  ;  i  :  CARDINAL)  ; 

END  ;  (*  FOR  *) 

VAR 

r  :=  (48  - (q  DIV  2))  ; 

j, k, l,m, n, o, p  :  CARDINAL  ; 

s  :=  0  ; 

BEGIN 

FOR  m  :=  3*n  TO  i  DO 

(*  First  we  center  the  strings  to  be  displayed  vertically  *) 

t  :=  Length (A [m] )  ; 

i  :=  i  -  1  ;  (*  Convert  from  one  base  to  zero  based  *) 

IF  (t  >  s)  THEN  s  :=  t  END  ;  (*  get  longest  string  length  *) 

n  :=  i  DIV  2  ; 

END  ;  (*  FOR  *) 

j  :■=  (5  +  ( (15  -  n)  DIV  2) )  ; 

(*  Now  we  center  the  strings  horizontally  *) 

t  :=  (64  -(s  DIV  2))  ; 

1  :=  0  ; 

(*  Now  print  the  menu  *) 

FOR  m  :=  0  TO  n-1  DO 

FOR  m  :=  0  TO  n-1  DO 

k  :=  Length (A(m] )  ; 

gotoxy (k, (j+m) )  ;  (*  Position  cursor  to  string  position  *) 

IF  (k  >  1)  THEN  1  :=  k  END  ;  (*  get  longest  string  length  *) 

WriteString (A [m] )  ; 

END  ;  (*  FOR  *) 

END  ;  (*  FOR  *) 

k  :=  (20  -(1  DIV  2))  ; 

FOR  m  :=  n  TO  2*n-l  DO 

(*  Now  set  up  the  second  column  centered  on  position  60  *) 

gotoxy (p, ( j+m- (n) ) )  ;  (*  Position  cursor  to  string  position  *) 

o  :=  0  ; 

WriteString(A[m] )  ; 

FOR  m  :=  n  TO  i  DO 

END  ;  (*  FOR  *) 

p  :=  Length (A [m] )  ; 

FOR  m  :=  2*n  TO  3*n-l  DO 

IF  (p  >  o)  THEN  o  :=  p  END  ;  (*  get  longest  string  length  *) 

gotoxy (r, (j+m- (2*n) ) )  ;  (*  Position  cursor  to  string  position  *, 

END  ;  (*  FOR  *) 

WriteString (A [m] )  ; 

p  :=  (60  -(o  DIV  2))  ; 

END  ;  (*  FOR  *) 

FOR  m  :=  3*n  TO  i  DO 

(*  Now  print  the  menu  *) 

gotoxy (t, (j+m- (3*n) ) )  ;  (*  Position  cursor  to  string  position  *) 

FOR  m  :=  0  TO  n-1  DO 

WriteString ( A [m] )  ; 

gotoxy (k, (j+m) )  ;  (*  Position  cursor  to  string  position  *) 

END  ;  (*  FOR  *) 

WriteString (A [m] )  ; 

END  ;  (*  FOR  *) 

END  FourColumns  ; 

FOR  m  :=  n  TO  i  DO 

PROCEDURE  Menu (VAR  A  :  MenuType  ;  NumberOfMenuEntries  :  CARDINAL):  CARDINAL  ; 

gotoxy (p, (j+m- (n) ) )  ;  (*  Position  cursor  to  string  position  *) 

VAR 

WriteString (A [m] )  ; 

i, j, k, 1  :  CARDINAL  ; 

END  ;  (*  FOR  *) 

input  :  ARRAY [0..1]  OF  CHAR  ; 

done  :  BOOLEAN  ; 

END  TwoColumns  ; 

BEGIN 

(*  'A'  is  actually  an  array  of  character  strings  (  an  array  of  array  of  char) 

PROCEDURE  ThreeColumns (VAR  A  :  MenuType  ;  i  :  CARDINAL)  ; 

Menu  displays  'A'  and  waits  for  up  to  a  two  character  response  with  a  trailing 

VAR 

carriage  return.  Menu  returns  100  if  escape  is  pressed,  otherwise  returns 

j,k,l,m,n,o,p;q,r  :  CARDINAL  ; 

BEGIN 

number  entered  by  user  as  menu  response. (0..60) .  *) 

(*  First  we  center  the  strings  to  be  displayed  vertically  *) 

i  :=  NumberOfMenuEntries  ; 

i  :=  i  -  1  ;  (*  Convert  from  one  base  to  zero  based  *) 

IF  (i  <=  15  )  THEN  OneColumn (A, i)  END  ; 

n  :=  i  DIV  3  ; 

IF  ( (i  >  15)  AND  (i  <=  30))  THEN  TwoColumns (A,  i)  END  ; 

j  :=  i  MOD  3  ; 

IF  ((i  >  30)  AND  (i  <=  45  ))  THEN  ThreeColumns (A, i)  END  ; 

IF  j  =  2  THEN  INC (n)  END  ; 

IF  (i  >  45)  THEN  FourColumns (A, i)  END  ; 

j  :=  (5  +  ((15  -  n)  DIV  2))  ; 

(*  Allow  a  maximum  of  15  items  per  column  on  displayed  menu.*) 

(*  Now  we  center  the  strings  horizontally  *) 

LOOP 

•  1  :=  0  ; 

gotoxy (5, 24)  ; 

FOR  m  :=  0  TO  n-1  DO 

WriteString (' Enter  the  number  of  your  selection  and  press  Enter  key:  ')  ; 

k  :=  Length (A[m) )  ; 

WriteString (CHR (08) )  ; 

IF  (k  >  1)  THEN  1  :=  k  END  ;  (*  get  longest  string  length  *) 

WriteString (CHR (08) )  ; 

END  ;  (*  FOR  *) 

Grab (input, Esc)  ; 

k  :=  (20  -(1  DIV  2))  ; 

(*  If  Esc  is  pressed  instead  of  a  number  exit  with  an  impossible  value  *) 

(*  Now  set  up  the  second  column  centered  on  positibn  40  *) 

IF  (input [0]  =  CHR (27) )  THEN  RETURN  0  END  ; 

o  :=  0  ; 

StringToCard (input, j, done)  ; 

FOR  m  :=  n  TO  (2*n)-l  DO 

(*  Return  only  legal  values  of  input  *) 

p  :=  Length (A (mj)  ; 

IF  done  THEN 

IF  (p  >  o)  THEN  o  :=  p  END  ;  (*  get  longest  string  length  *) 

IF  (j  >  0)  AND  (  j  <=i)  THEN  RETURN  j  END  ; 

END  ;  (*  FOR  *) 

END  ;  (*  IF  *) 

p  :=  (40  -(o  DIV  2))  ; 

END  ;  (*  LOOP  *) 

(*  Now  set  up  the  third  column  centered  on  position  60  *) 

END  Menu  ; 

q  :=  0  ; 

FOR  m  :=  2*n  TO  i  DO 

r  :=  Length (A [m] )  ; 

IF  (r  >  q)  THEN  q  :=  r  END  ;  (*  get  longest  string  length  *) 

END  ;  (*  FOR  *) 
r  :=  (60  -(q  DIV  2))  ; 

(*  Now  print  the  menu  *) 

END  MENU  . 

FOR  m  :=  0  TO  n-1  DO 

End  Listings 
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Listing  One  (Text  begins  on  page  44.) 

Listing  Two 

{***  Singly  linked  move-to-the  front  list 

***} 

{***  Move  To  The  Front  Splay  Tree  *** 

) 

{***  Contents:  "LInsert",  "Mtffind"  ***} 

{***  Contents:  SplaySearch,  BSInsert, 

BSDelete  ***) 

{  Data  Structure: 

{  Data  Structure: 

ptr=Anode; 

ptr=Anode; 

node=RECORD  rec:item;  next:ptr;  END;  } 

node=RECORD  data:key;  left, right :ptr;  END;  ) 

PROCEDURE  LInsert (arg: item;  VAR  root:ptr) 

FUNCTION  SplaySearch (x: key;  VAR  p:ptr) :boolean; 

VAR  p:ptr;  { 

To  generate  storage  ) 

TYPE  noderec=RECORD 

{  Temporary  Tree  Pointer  Def.  ) 

BEGIN 

left, right :ptr; 

NEW (p) ;  { 

Allocate  ) 

END; 

pA.rec:=arg;  { 

Add  data  } 

VAR  l,r:noderec; 

{  Temporary  Trees  ) 

pA .next :=root;  ( 

Place  at  front  of  list  } 

done: boolean; 

f  TRUE  if  NIL  encountered  in  search  ) 

root:=p;  { 

Point  to  new  front  of  list  ) 

END; 

PROCEDURE  RRot (VAR  p:ptr); 

VAR  temp, tempi :ptr; 

{  Temporary  pointers  } 

FUNCTION  Mtffind (arg: item;  VAR  root :ptr; ) :boolean; 

BEGIN 

VAR  tempi, temp2 :ptr; 

{  Search  pointers  J 

IF  poNIL  THEN 

{  Don't  rotate  if  nothing's  there  ) 

found: boolean; 

{  TRUE  if  found  ) 

IF  pA  .  leftONIL  THEN 

(  No  left  edge  -  don't  rotate  ) 

BEGIN 

BEGIN 

tempi :=root; 

{  Get  a  copy  of  starting  location  ) 

temp:=p;  tempi :=pA . leftA . 

right;  (  Copy  root  &  2ndary  child  ) 

temp2 :=root; 

{  Secondary  copy  } 

p:=tempA . left;  pA. right := 

temp;  (  Rotate  root  ) 

found :=false; 

(  Nothing  found  yet  } 

tempA . left : =templ ; 

{  Reattach  2ndary  child  ) 

END; 

WHILE  (templONIL)  AND  (NOT  found)  DO 

END; 

BEGIN 

IF  tempi A  .  recoarg  THEN 

{  Found  it?  } 

PROCEDURE  LRot (VAR  p:ptr); 

BEGIN 

(  Nope ...  } 

VAR  temp, tempi :ptr; 

(  Temporary  pointers  ) 

temp2 :=templ; 

{  Move  trailing  pointer  } 

BEGIN 

tempi : =templ A . next ; 

(  Move  search  pointer  ) 

IF  pONIL  THEN 

(  Don't  rotate  if  nothing's  there  } 

END 

IF  pA  .  rightoNIL  THEN 

(  No  right  edge  -  don't  rotate  ) 

ELSE  found :=true; 

{  Yup...  ) 

BEGIN 

END; 

temp:=p;  tempi :=pA . right A 

.left;  {  Copy  root  &  2ndary  child  ) 

p:=tempA . right;  pA.left:=temp;  {  Rotate  root  ) 


IF  found  THEN  {  Move  item  to  front  of  list  ) 

tempA . right : =templ ; 

(  Reattach  2ndary  child  ) 

BEGIN 

END; 

temp2  A . next : =templ A . next ; 

END; 

IF  temploroot  THEN  tempi A  .next  :=root; 
root : ■tempi; 

PROCEDURE  LnkRight (VAR  p:ptr;  VAR  r 

:noderec) ; 

END; 

VAR  temp:ptr; 

(  Temporary  pointer  ) 

Mtffind:=found; 

BEGIN 

IF  pA.  leftONIL  THEN 

{  No  left  child  -  don't  cut  &  link  } 

END; 

BEGIN 

temp:=pA . left;  pA.left:=NIL 

(  Remember  left  child  &  break  link  ) 

IF  r . left=NIL  THEN 

(  Attach  to  temporary  tree  ) 

BEGIN  r.left:=p;  r. right: 

=p;END  {  Empty  tree?  ) 

ELSE 

(  Just  add  to  bottom  leftmost  ) 

BEGIN  r.rightA.left:=p;  r 

right :=r. right A . left;  END; 

p:=temp; 

f  New  root  is  left  child  ) 

End  Listing  One 

END; 

END; 

(Listing  continued  on  next  page) 
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Listing  Two  (Listing  continued,  text  begins  on  page  44.) 

PROCEDURE  LnkLeft (VAR  p:ptr;  VAR  l:noderec); 

VAR  temp:ptr;  {  Temporary  pointer  } 

BEGIN 

IF  pA.right<>NIL  THEN  {  No  right  child  -  don't  cut  &  link  } 

BEGIN 

temp : =pA . right;  pA . right :=NIL; {  Remember  right  child  &  break  link  } 
IF  l.left=NIL  THEN  {  Attach  to  temporary  tree  } 

BEGIN  l.left:=p;  1. right :=p; END  {  Empty  tree?  } 

ELSE  {  Just  add  to  bottom  rightmost  } 

BEGIN  l.rightA. right :=p;  1. right :=1. right A. right;  END; 
p;=temp;  {  New  root  is  right  child  ) 

END; 

END; 

PROCEDURE  Assemble (VAR  prptr;  VAR  1, r :noderec) ; 

VAR  temp, tempi :ptr; 

BEGIN 

temp:=p".left;  tempi :=pA .right;  (  Hold  onto  subtrees  } 

IF  l.leftONIL  THEN 
BEGIN 

pA.left:=l.left;  (  Attach  temporary  left  subtree  } 

1. right A. right :=temp;  (  Reattach  orginal  left  subtree  } 

END; 

IF  r.leftONIL  THEN 
BEGIN 

pA . right : =r . lef t ;  (  Attach  temporary  right  subtree  } 

r. right". left: “tempi;  (  Reattach  original  right  subtree  } 

END; 

END; 


(  Initialize  temp  trees  1 

{  Init  to  "item  maybe  there"  ) 
{  No  search  if  tree's  empty  } 


{  Item  on  left  subtree?  > 


BEGIN 

1. left: “NIL;  1. right: “NIL; 
r.left:=NIL;  r. right :=NIL; 
done: “false; 

IF  pONIL  THEN 
BEGIN 
REPEAT 

IF  (x<pA .data)  THEN 
IF  (pA .  leftONIL)  THEN 
BEGIN 

IF  X=PA. left A. data  THEN  LNKRIGHT (p, r) 

ELSE 

IF  x<pA . leftA .data  THEN  BEGIN  RRot (p) ;  LNKRIGHT (p, r) ;  END 
ELSE 

IF  x>pA. left A. data  THEN  BEGIN  LNKRIGHT (p, r) ; LNKLEFT (p,  1) ; END; 
END  ELSE  done: “TRUE 

ELSE 

IF  (x>pA .data)  THEN  {  Item  on  right  subtree?  ) 

IF  (pA .  rightONIL)  THEN 
BEGIN 

IF  x=pA . right A . data  THEN  LNKLEFT (p,l) 

IF  x>pA . right A . data  THEN  BEGIN  LRot(p);  LNKLEFT (p, 1) ;  END 

IF  x<pA. right". data  THEN  BEGIN  LNKLEFT (p,  1) ; LNKRIGHT (p, r) ; END; 
END  ELSE  done: “TRUE; 

UNTIL  (x=pA .data)  OR  DONE; 

ASSEMBLE (p,l,r) ;  SplaySearch:= (x=pA .data) ; 

END  ELSE  SplaySearch:=FALSE; 

END; 

PROCEDURE  BSInsert (x:key;  VAR  root:ptr); 

VAR  p:ptr; 

BEGIN 
NEW (p) ; 
p".data:=x; 

pA . left :=NIL;  p" . right : “NIL; 

IF  root=NIL  THEN  root:=p 
ELSE 
BEGIN 

IF  NOT  SplaySearch (x, root)  THEN 
IF  x<rootA.data  THEN 
BEGIN 

pA. right: “root; 
pA .  left : =root A . lef t ; 
root". left: “NIL;  root:=p; 

END 
ELSE 

IF  x>rootA.data  THEN 
BEGIN 

pA. left: =root; 
pA .right : “root A . right; 
root". right: “NIL;  root:=p; 

END; 

END; 

END; 


{  No  tree,  just  insert  ) 


{  Is  it  already  there?  ) 

{  Less  than?  } 

{  Root  item  greater  than  } 

{  Link  up  left  child  } 

(  Break  link;  root=new  item 


{  Greater  than?  } 

{  Root  item  less  than  ) 

{  Link  up  right  child  ) 

{  Break  link;  root=new  item 


Move  To  The  Fron  Splay  Tree  ***) 

Contents: SplaySearch,  BSInsert,  BSDelete  ***} 


1  maxkey  user  example 


PROCEDURE  BSDelete (x: key;  VAR  root:ptr); 

CONST  maxkey=MAXINT ; 

VAR  tempi, temp2,temp4:ptr; 
temp3:key; 
fig: boolean; 

BEGIN 

IF  SplaySearch (x,  root)  THEN 
BEGIN 

tempi :=root". left;  temp2:=root". right;  {  Save  subtrees  } 

IF  templONIL  THEN  {  Is  there  a  left  subtree?  ) 

BEGIN 

fig: “SplaySearch (temp3, tempi) ; 

tempi" . right :=temp2;  {  Attach  right  subtree  ) 

END  ELSE  tempi :=temp2;  (  Just  attach  right  tree  } 

dispose (root) ; 

root: “tempi;  {  Return  new  tree  } 

END; 


END; 


End  Listing  Two 


Listing  Three 


{***  Self-adjusting  heap  ***} 

(***  Contents:  Merge,  Min,  Insert,  DeleteMin  routines  ***) 

{  Data  Structure: 
ptr="node; 

node=RECORD  data: item;  left, right :ptr;  END;  } 

FUNCTION  Merge (ql,q2:ptr) :ptr; 

TYPE  Qrec=RECORD 

front, rear:ptr; 

END; 

VAR  Q:Qrec; 

PROCEDURE  Enqueue (VAR  ql:ptr;  VAR  Q:Qrec) ; 

VAR  temp:ptr; 

BEGIN 

temp:=ql;  {  Save  top  of  heap  ) 

ql:=ql". right;  {  Point  to  next  top  of  heap  ) 

temp". right :=temp". left;  {  Swap  right  child  to  left  ) 

temp" .left: “NIL;  {  Make  sure  left  link's  broken  } 

IF  q. front=NIL  THEN  (  Empty  merge  queue  ) 

BEGIN 

q. front: “temp;  q. rear: “temp; 

END 

ELSE  (  Oops,  just  add  to  last  leftchild 

BEGIN 

q . rear" . left : “temp;  q . rear : “temp; 

END; 

END; 

BEGIN 

q. front: “NIL;  q. rear: “NIL;  {  Init  merge  queue  ) 

WHILE  (qloNIL)  AND  (q2<>NIL)  DO  I  Pairwise  compare  and  merge  ) 

IF  al" .data<=q2".data  THEN  Enqueue (ql, q) 

ELSE  Enqueue (q2, q) ; 

IF  (qlONIL)  AND  (q2=NIL)  THEN 
BEGIN 

IF  q.rearONIL  THEN  q. rear" . left :=ql 
ELSE  q. front :=ql; 

END 

IF  (ql=NIL)  AND  (q2<>NIL)  THEN 
BEGIN 

IF  q.rearONIL  THEN  q.  rear"  .  left  :=q2 
ELSE  q. front :=q2; 

END; 

Merge :=q. front ; 

END; 

FUNCTION  Min (ql :ptr;  VAR  x:ptr) :boolean; 

BEGIN 
x : =ql ; 

Min :=  (qloNIL)  ; 

END; 

PROCEDURE  Insert (x: item;  VAR  q:ptr); 

VAR  p:ptr; 

BEGIN 

NEW (p) ;  {  Allocate  } 

p".data:=x;  {  Fill  it!  ) 

p". left: “NIL;  p". right: “NIL;  (  No  children  ) 

q: “Merge (q, p) ;  (  Add  it  to  heap  } 

END; 

FUNCTION  DeleteMin (q:ptr;  VAR  x:ptr) :ptr; 

BEGIN 

IF  Min (q, x)  THEN  (  Is  there  a  min  to  delete?  ) 

DeleteMin : “Merge (q" . left , q" . right) 

ELSE  DeleteMin: “NIL;  {  Nothing  at  all  ) 

END; 

{  Pairing  Heaps  as  described  by  Tarjan,  et  al  from  Algorithmica: 

Data  Structure: 

TYPE  hptr="node; 
node=RECORD 

wt:  integer; 

parent, left, right :hptr; 

END;  } 


2  Queues  to  merge? 


FUNCTION  Merge (argl, arg2 :hptr) :hptr; 

BEGIN 

IF  (arglONIL)  AND  (arg2<>NIL)  THEN 
BEGIN 

IF  argl".wt<arg2".wt  THEN  (  Which  is  minimal?  } 

BEGIN 

arg2". parent :=argl;  {  Who's  the  parent?  } 

arg2" .right :=argl" . left;  {  Point  to  argl's  child  } 

argl" . left :=arg2;  (  It's  officially  a  child 

Merge :=argl; 

END 

ELSE 

BEGIN 

argl" .parent : =arg2;  (  Who's  the  parent?  } 

argl". right :=arg2" . left;  (  Point  to  arg2's  child  } 

arg2" . left :=argl;  {  It's  officially  a  child 

Merge:=arg2; 

END; 

END 

ELSE 

IF  (arglONIL)  THEN  Merge:=argl  {  Just  argl's  queue  } 

ELSE  Merge :=arg2  {  Anything  else  ) 

END; 

PROCEDURE  Insert (al,a2,x:integer;  VAR  root:hptr); 

VAR  p:hptr; 

BEGIN 

New (p) ;  (  Allocate  } 

p".vl:=al;  p".v2:=a2; 

p".wt:=x;  p" .parent : “NIL;  (  Set  key  } 

p". left: “NIL;  p" . right : “NIL;  {  Set  pointers  ) 
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root :=Merge (p, root) ;  {  Add  it...  } 

END; 

FUNCTION  Min (root :hptr;  VAR  minitemihptr) :boolean; 

BEGIN 

minitem:=root;  {  What's  at  the  root?  } 

Min:=  (minitemoNIL)  ;  (  Anything  there?  ) 

END; 

FUNCTION  DeleteMin (root :hptr;  VAR  ininitem: hptr) :hptr; 

VAR  argl, arg2,pl:hptr; 

BEGIN 

IF  Min (root, minitem)  THEN 
BEGIN 

root :=NIL;  {  Relnit  root  } 

pi :=minitemA .left;  {  Save  kids  ) 

WHILE  plONIL  DO  (  For  all  subtrees  ) 

BEGIN 

argl:=pl;  {  First  Subtree  } 

pi :=plA. right;  (  Move  along  ) 

arg2:=pl;  {  Next  potential  subtree  ) 

IF  plONIL  THEN  pi  :=plA  .right;  (  If  not  NIL,  move  on  } 

root :=Merge (Merge (argl,arg2) , root) ;  {  Merge  result  with  current  } 

END; 

IF  rootoNIL  THEN  rootA .  right  :=NIL; 

DeleteMin :=root; 

END  ELSE  DeleteMin: =NIL; 

END; 

FUNCTION  LinkSearch(prhptr) :hptr; 

VAR  temp: hptr; 

BEGIN 

temo : =p A . parent A . lef t ; 

WHILE  (tempop)  AND  (tempA .  rightop)  AND  (tempA .  rightoNIL)  DO 
temp : =tempA . right  ; 

LinkSearch : =temp; 

END; 

FUNCTION  DecreaseKey (change: integer;  p, root :hptr) : hptr; 

VAR  temp : hptr; 

BEGIN 

IF  (pONIL)  AND  (rootONIL)  THEN 
BEGIN 

pA .wt :=pA .wt-ABS (change) ; 

IF  p=root  THEN  DecreaseKey :=root 

ELSE 

BEGIN 


temp:=LinkSearch (p) ; 

IF  temp=p  THEN  pA .parent A . left :=pA .parent A .left A . right 
ELSE  tempA . right :=pA . right ; 

DecreaseKey :=Merge (p,  root) ; 

END; 

END; 

END; 

FUNCTION  Delete (p, root : hptr) :hptr; 

VAR  temp : hptr; 

BEGIN 

IF  (pONIL)  AND  (rootONIL)  THEN 
BEGIN 

IF  p=root  THEN  Delete :=DeleteMin (root, temp) 

ELSE 

BEGIN 

temp:=LinkSearch (p) ; 

IF  temp=p  THEN  pA .parent A . left :=pA .parent A . left A . right 
ELSE  tempA. right :=pA. right ; 

Delete :=Merge (DeleteMin (p,temp) , root) ; 

END; 

END  ELSE  Delete :=root; 

END; 


End  Listings 
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Listing  One  (Text  begins  on  page  60.) 

/* - 

ERR_CODE.C  Written  by:  William  J.  McMahon 

This  module  contains  the  functions  used  to  manipulate  error  codes. 
Global  Functions  Defined  Herein: 

err_combine ( ) ,  err_format ( ) ,  err_print ( ) 


♦include  <stdio.h> 
♦include  <limits.h> 


/ 


♦define  ERR_BUMPER  10 

♦define  ERRJTHRESHOLD  (UINT_MAX/ERR_BUMPER)  /*  ...  for  overflow.  */ 

/*  -  Local  Functions  Defined  Herein:  -  */ 

unsigned  err_pop ( ) ; 
void  err_push(); 

♦  ifdef  TEST  /* - Test  Harness -  */ 

♦define  FIRST_ARG  0  /*  Varies  with  compiler  (0  or  1) .  */ 

♦define  NCODES  32 


main(argc,  argv) 


int  argc, 

char  *argv[]; 

unsigned 

err_combine  () 

void 

err_format () ; 

void 

err_print () ; 

unsigned 

err_code; 

int 

adder  =  1; 

int 

i; 

if  (argc 

>  FIRST_ARG) 

/*  Override  default  starting  code.  */ 
adder  =  atoi (argv [FIRST_ARG] ) ; 

err_code  =  adder; 

printf ("\nlnput  should  be  a  mirror  image  of  output . \n") ; 
printf("\n  Input  sequence:  %d",  err_code) ; 

for  (i  =  0;  i  <  NCODES;  ++i)  /*  Build  an  error  code,  using  */ 

(  /*  multiple  err_combine ()  calls.*/ 

++adder; 

if  (adder  >=  ERR_BUMPER) 
adder  =  1; 

printf  ("%d",  adder);  /*  Output  RAW  codes.  */ 

err_code  =  err_combine (err  code,  adder); 

} 


printf ("\nOutput  sequence:  "); 
err_print (stdout,  err_code) ; 


) 

♦endif 

/* - 

ERR_COMBINE  Combines  a  new  individual  error  code  with  an  existing  one. 
Returns:  Combined  error  code. 

-  */ 

unsigned  err_combine ( 

unsigned  original,  /*  Original  error  code.  */ 

unsigned  to_add)  /*  Code  to  be  added  to  it.  */ 

{ 

if  ( (original  I  ERR_BUMPER)  ==  0)  /*  Some  special  codes  are  not  */ 

return  (original);  /*  changed.  */ 

to_add  %=  ERR_BUMPER;  /*  Make  sure  its  in  range.  */ 


if  (original  >  ERRJTHRESHOLD) 
{  /*  Prevent  overflow.  */ 

err_push (original) ; 
original  =  0; 


return  (original  *  ERR  BUMPER  +  to  add) ; 

} 


ERR_FORMAT  Decode  and  format  an  error  code  (and  any  overflow) 
into  a  string.  Returns:  Nothing. 

-  */ 

void  err_format( 

char  *buffer,  /*  Buffer  to  put  formated  code  into.  */ 

unsigned  err_code)  /*  Error  code  to  format.  */ 

{ 

char  *p; 
p  =  buffer; 
while  (err_code) 

{ 

do 

{ 

sprintf (buffer,  "%d",  err_code  %  ERR_BUMPER) ; 
buffer  +=  strlen (buffer) ; 

} 

while  ( (err_code  /=  ERRJ3UMPER)  >  0) ; 
err_code  =  err_pop(); 

} 

} 

/*  - 

ERR_PRINT  Decode  and  output  an  error  code  (and  any  overflow) . 
Returns:  Nothing. 

- - -  */ 

void  err_print ( 

FILE  *stream,  /*  Streem  to  output  formated  code  to.  */ 

unsigned  err_code)  /*  Error  code  to  output.  */ 

{ 

while  (err_code) 

{ 

do 

{ 

fprintf (stream,  "%d",  err_code  %  ERR_BUMPER) ; 

) 

while  ( (err_code  /=  ERR_BUMPER)  >  0) ; 
err_code  =  err_pop(); 

) 


/*  =================  Local  stack  for  overflow  codes.  ==================  */ 

♦define  MAX  OVERFLOWS  10 


static  unsigned  err_stack [MAX_OVERFLOWS] ; 
static  unsigned  err_stack_top  =  0; 

/*  - 

ERR_POP  Returns:  Combined  error  code  of  most  recent  overflow,  0  if  none. 

-  */ 

static  unsigned  err_pop() 

{ 

if  (err_stack_top  <=  0) 
return  (0); 

— err_stack_top; 

return  (err_stack [err_stack_top] ) ; 


/*  - 

ERR_PUSH  Push  error  code  onto  stack. 

Returns:  Nothing. 

-  */ 

static  void  err_push( 

unsigned  err_code)  /*  Error  code  to  save.  */ 

{ 

if  (err_stack_top  <  MAX_OVERFLOWS) 

( 

err_stack [err_stack_top]  =  err_code; 

++err_stack_top; 

> 


End  listing 
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EXAMINING  ROOM 


Listing  One  (Text  begins  on  page  66.) 

ISketchApp  subclass  of:  Object  ! 
className:  SketchApp 
superclass:  Object 
header:/*  Class  name:  SketchApp  */ 

/*  Super  name:  Object  */ 

/*  File  name:  Sketchpp  */ 

/*  header  */ 

#include  "objtypes.h" 
extern  id  Object; 
extern  id  Archiver; 
extern  id  Notifier; 

classVariables:/*  class  variables  */instanceVariables:id  objects; 
id  filename;  /*  Filename  string  */ 
int  changed;  /*  changed  flag  */ 
fileName: Sketchpp  ! 

ISketchApp  class  methods  ! 

! SketchApp  instance  methods  ! 

add_  drawObj 
id  drawObj; 

{ 

@self->objects  add_  drawObj@;  /*  add  to  collection  */ 
@self  changed@; 

} 

asCollect 

{ 

return  self->objects; 

} 

changed 

{ 

self->changed  =  TRUE; 

J 

clear 

/*  Erase  the  objects  in  our  collection.  */ 

{ 

extern  id  OrdCollect; 

if  (self->filename)  self->filename  =  @self->filename  free@; 
if  (self->objects)  @self->objects  freeAll@; 
self->objects  =  @OrdCollect  new@; 

@self  changed@; 

if  (self->objects)  return  TRUE;  else  return  FALSE; 


getFname 

{ 

return  self->filename; 

| 

loadFrom_  fname 
id  fname; 

{ 

id  fstr,  arc; 

if  (fname) 

{ 

arc  =  @Archiver  openForLoad_  fname@; 
if  (arc) 

{ 

if  (@self  clear@)  @self->objects  freeAll@; 
self->objects  =  @arc  getObject@; 

@self  changed@; 

@arc  free@; 

self->filename  =  fname; 
return  TRUE; 

} 

) 

return  FALSE; 


main 

{ 

} 

main  () 

{ 

id  aView,  aModel; 
extern  id  SketchView; 
aModel  =  @ SketchApp  new@; 

aView  =  GSketchView  create_  "Sketch"  ViewOf_  aModel@; 
if  (aView) 

{ 

@aView  show@; 

@Notifier  start@; 

} 


save 

{ 

id  arc; 

if  (arc  =  @Archiver  openForStore_  self->filename@) 

( 

@Notifier  beginWait@; 

@arc  putObject_  self->objects@; 

@arc  free@; 

self->changed  =  FALSE; 

@Notifier  endWait@; 

) 

} 

saveAs_  filename 
id  filename; 

{ 

(continued  on  page  110) 
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Listing  One  ( Listing  continued,  text  begins  on  page  66.) 

if (self->filename)  @self->filename  freeG; 
self->filename  =  filename; 

Gself  save@; 


End  Listing  One 


Listing  Two 

***  New  Point Array  methods: 
getFrom_  anArchive 

/*  restore  the  receiver's  size,  recSize  and  size  objects  from  the  archive.  */ 
id  anArchive;  /*  id  of  an  Archiver  object  to  store  the  receiver  to  */ 

{ 

id  anld; 
unsigned  i; 

Gsuper  getFrom_  anArchiveG; 
self->howMany  =  GanArchive  getlnt@; 

} 

putTo_  anArchive 

/*  Store  the  receiver's  size,  recSize  and  size  objects  to  the  archive.  */ 
id  anArchive;  /*  id  of  an  Archiver  object  to  store  the  receiver  to  */ 

{ 

id  anld; 
unsigned  i; 

@ super  putTo_  anArchiveG; 

@anArchive  putlnt_  self->howMany@; 

) 

***  New  Rect  methods: 
getFrom_  anArchiver 
{ 

self->left  =  GanArchiver  getlntG; 
self->top  =  GanArchiver  getlntG; 
self->right  =  GanArchiver  getlntG; 
self->bottom  =  GanArchiver  getlntG; 

} 

putTo_  anArchiver 

{ 

GanArchiver  putlnt_  self->leftG; 

GanArchiver  putlnt_  self->topG; 

GanArchiver  putlnt_  self->rightG; 

GanArchiver  putlnt_  self->bottomG; 

} 

***  New  PolyLine  methods: 
getFrom_  anArchiver 
{ 


self->ptArray  =  GanArchiver  getObjectG; 

} 

putTo_  anArchiver 

( 

GanArchiver  putObject_  self->ptArrayG; 

) 

***  New  Line  methods: 
getFrom_  anArchiver 
{ 

self->xO  =  GanArchiver  getlntG; 
self->yO  =  GanArchiver  getlntG; 
self->xl  =  GanArchiver  getlntG; 
self->yl  =  GanArchiver  getlntG; 

} 

putTo_  anArchiver 

{ 

GanArchiver  putlnt_  self->xOG; 

GanArchiver  putlnt_  self->yOG; 

GanArchiver  putlnt_  self->xlG; 

GanArchiver  putlnt_  self->ylG; 

) 

***  New  Box  methods: 
getFrom_  anArchiver 
{ 

self->rec  =  GanArchiver  getObjectG; 

) 

putTo_  anArchiver 

{ 

GanArchiver  putObject_  self->recG; 

) 

***  New  or  changed  SketchView  methods: 

*  Add  external  ids  for  SketchApp,  String,  and  FileSelect  to  SketchView  class. 

*  Also  remove  instance  variable  "objects"  and  the  main  method. 

erase 

/*  Erase  the  objects  drawn  on  the  receiver.  */ 

{ 

if  (self->model) 

{ 

Gself->model  clearG; 

Gself  updateG; 

) 

} 

initialize 

/*  Initialize  receiver  by  creating  a  port  to  scribble  on.  */ 

( 

id  aMenu; 

extern  id  Port,  Menu,  PopupMenu; 
extern  char  *scribNmes [ ) ; 
extern  int  scribSels[],  scribKeys[]; 
if  (aMenu  =  GMenu  newG) 

| 

if  (self->fMenu  =  GPopupMenu  new  "&Functions"G) 

1 
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@self->fMenu  setNames_  scribNmes  sels_  scribSels  keys_  scribKeys  for_self@; 

@aMenu  append_  self->fMenu@; 

@self  setMenu_  aMenu@; 
if  (@self->model  clearQ) 

if  (self->aPort  =  @Port  createOn_  self(?)  /*  make  receiver  graphics  port*/ 
return  self; 

} 

} 

return  NIL; 

} 

char  *scribNmes[]  =  {"S&ketch\tFl",  "&Line\tF2",  "&Box\tF3",  "E&rase\tF4", 

"&Save\tF5",  "Save&As\tF6",  "&0pen\tF7",  NULL} ; 


int 

scribKeys [ ] 

{  K_F1 , 

K  F2, 

K_F5, 

K  F3, 

K_F6, 

K  F4, 

K_F7,  K_NULL ) 

int 

scribSels []  = 

{ 'sketch  ' 

,  'line  ' 

'save ', 

,  'box_', 

'saveAs ', 

'erase ', 

'open',  0); 

mouseDnX_  x  Y_  y 

/*  Method  to  respond  to  mouse  DOWN  events.  */ 

int  x,y;  /*  position  in  receiver  where  mouse  down  event  occured  */ 

{ 

if  (self->drawClass) 

{ 

@Notifier  captureMouseFor_  self@;  /*  capture  all  mouse  events  to  window  */ 
@Notifier  mouseTrkOn@;  /*  enable  mouse  traking  =>  mouse  movement  events  */ 
self->drawObj  =  @self->drawClass  new@;  /*  new  instance  of  draw  object  */ 
@self->model  add_  self->drawOb j@;  /*  add  to  model  */ 

@self->drawObj  setPort_  self->aPort@; 

return  @self->drawObj  mouseDnX_  x  Y_  y@;  /*  pass  forward  mouse  event  */ 

} 

else  return  FALSE; 

} 

open 

{ 

id  fstr,  str; 

fstr  =  @String  newCStr_  "*.skh"@; 

str  =  @FileSelect  ask_  "Select  a  Sketch  file"  for_  fstr  of_  self@; 
if  (str) 

{ 

if  ( ! ! @self->model  loadFrom_  str@)  @str  free@; 

@self  update!?; 

) 

@fstr  free@; 

} 

paint 

/*  Draw  all  graphic  objects  contained  by  receiver  in  the  objects  ordered  */ 

/*  collection.  */ 

( 

int  sel  =  'drawOn_'; 
id  retainedObjs; 

if  (retainedObjs  =  @self->model  asCollectl?) 

@retainedOb js  do_  sel  with_  self->aPort@; 
return  TRUE; 

} 

save 

{ 

if  (@self->model  getFnamel?)  @self->model  save@; 
else  @self  saveAs@; 

} 

saveAs 

{ 

id  fstr,  str; 

fstr  =  ^String  newCStr_  "*.skh"@; 

str  =  @FileSelect  ask_  "Select  a  Sketch  file"  for_  fstr  of_  self@; 
if  (str) 

{ 

@self->model  saveAs_  str@; 

} 

@fstr  free@; 


End  Listings 


Dr.  Dobb’s Journal February  1990 


111 

165 


PROGRAMMER'S  WORKBENCH 


Listing  Four  (Text  begins  on  page  76.) 

/*  GPF386.C — for  Phar  Lap  386!DOS-Extender  and  Watcom  C  386  7.0 
wcl386  -DPROT_MODE  -3r  -mf  -Ox  -s  gpf386 
wdisasm  gpf386  >  gpf386.asm 
run386  gpf386 

NOTE!  To  keep  this  example  short,  most  of  the  precautions  taken 
in  Listing  3  are  not  repeated  here.  Refer  to  Listing  3  (GPFAULT.C) 
for  how  the  interrupt  handler  should  really  be  written.  */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦include  <ctype.h> 

♦include  <setjmp.h> 

♦include  <dos.h> 

♦include  "gpfault.h" 

void  reset_pharlap (void) ; 

void  prot_far  *getvect_prot (short  intno); 

void  real_far  *getvect_real (short  intno); 

BOOL  setvect_prot (short  intno,  void  prot_far  ‘handler); 

BOOL  set vect_real (short  intno,  void  real_far  ‘handler); 

BOOL  setvect (short  intno,  void  prot_far  ‘handler); 

BOOL  set2vect (short  intno,  void  prot_far  ‘phandler,  void  real_far  ‘rhandler); 
void  revert (void) ;  //  reinstall  default  handler 

void  interrupt  far  intl3handler (REG_PARAMS  r); 
unsigned  xtoi(char  *s); 

void  prot_far  *old_intl3handler_prot; 
void  real_far  *old_intl3handler_real; 
jmp_buf  toplevel; 

unsigned  legal  =  0;  //  just  a  legal  address  to  bang  on 

BOOL  in_user_code  =  FALSE; 


♦define 

USE  16 

0x66 

♦define 

INT 

Oxcd 

♦define 

PUSH  DS 

Oxle 

♦define 

POP  DS 

Oxlf 

♦define 

MOV  AX 

USE16  0xb8 

♦define 

MOV  DS  ES 

0x8c  OxcO  0x8e  0xd8 

//  MOV  AX, ES/MOV  DS,AX 

♦define 

XOR  AL 

0x34 

♦define 

MOV  AX  C ARRYF L 

0x9c  0x58  XOR_AL  0x01 

//  PUSHF/POP  AX/XOR  AL, 1 

♦define 

STI 

Oxfb 

/*  directives  for  compiler  to  generate  inline  code  */ 

♦pragma  aux  reset_pharlap  =  MOV_AX  0x01  0x25  /*  0x2501  */  INT  0x21  ; 

♦pragma  aux  getvect_prot  =  MOV_AX  0x02  0x25  /*  0x2502  */  INT  0x21  \ 
parm  [cl]  value  [ebx  es]  ; 

/* 

explanation  of  ♦pragma  aux:  the  preceding  says  that  getvect_prot () 
takes  one  parameter  in  CL  register,  and  returns  value  in  ES:EBX. 

The  "function"  itself  sets  AX  to  0x2502  and  does  an  INT  0x21. 

When  called:  old_intl3handler_prot  =  getvect_prot (OxOD) ; 
the  compiler  generates: 
mov  cl,  Odh 
mov  ax,  2502h 
int  21h 

mov  old_intl3handler_prot+4,  es 
mov  old_intl3handler_prot,  ebx 

*/ 

♦pragma  aux  getvect_real  =  MOV_AX  0x03  0x25  /*  0x2503  */  INT  0x21  \ 
parm  [cl]  value  [ebx]  ; 

♦pragma  aux  setvect_real  =  \ 

MOV_AX  0x05  0x25  /*  0x2505  */  \ 

INT  0x21  \ 

MOV_AX_C ARRYF  L  \ 
parm  [cl]  [ebx]  value  ; 

♦pragma  aux  setvect_prot  =  \ 

PUSH_DS  \ 

MOV_DS_ES  \ 

MOV_AX  0x04  0x25  /*  0x2504  */  \ 

INT  0x21  \ 

POP_DS  \ 

MOV_AX_CARRYFL  \ 

parm  [cl]  [es  edx]  value  ; 

♦pragma  aux  setvect  =  \ 

PUSH_DS  \ 

MOV_DS_ES  \ 

MOV_AX  0x06  0x25  /*  0x2506  */  \ 

INT  0x21  \ 

POP_DS  \ 

M°V_AX_C ARRYF L  \ 

parm  [cl]  [es  edx]  value  ; 

♦pragma  aux  set2vect  =  \ 

PUSH_DS  \ 

MOV_DS_ES  \ 

MOV_AX  0x07  0x25  /*  0x2507  */  \ 

INT  0x21  \ 

POP_DS  \ 

MO V_AX_C ARRYF  L  \ 

parm  [cl]  [es  edx]  [ebx]  value  ; 

main  () 

{ 

char  buf [255]; 
unsigned  prot_far  *fp; 
unsigned  short  seg; 
unsigned  off,  data; 

old_intl3handler_real  =  getvect_real (OxOD) ; 
old_intl3handler_prot  =  get vect_prot (OxOD) ; 
setvect (OxOD,  (void  prot_far  *)  intl3handler); 

printf ("'Q'  to  quit,  '!'  to  reinstall  default  GP  Fault  handler\n"); 
printf("%Fp  is  a  legal  address  to  poke\n",  (void  far  *)  slegal); 
printf("%Fp  is  not  a  legal  address  to  poke\n",  (void  far  *)  (ilegal-1)); 


{ 

printf("$  "); 

*buf  =  ' \0' ; 
gets (buf) ; 

if  (toupper (*buf )  ==  'Q') 
break; 

else  if  (*buf  ==  ' ! ' ) 

( 

revert ( ) ; 
continue; 

} 

//  got  bored  of  using  sscanfO 
seg  =  xtoi (strtok (buf ,  ":  \t " ) ) ; 
off  =  xtoi (strtok (0,  "  \t")); 
data  =  xtoi (strtok (0,  "  \t " ) ) ; 
in_user_code  =  TRUE; 

fp  =  MK_FP(seg,  off);  //  is  this  really  user  code? 

*fp  =  data; 

printf ("poked  %Fp  with  %x\n",  fp,  *fp) ; 
in_user_code  =  FALSE; 

) 

revert ( ) ; 
printf ("Bye\n") ; 
return  0; 


void  revert (void) 

{ 

if  (!  set2vect (OxOd,  old_intl3handler_prot,  old_intl3handler_real) ) 
printf ("Can't  revert !\n"); 

) 

void  interrupt  far  int 1 3handler (REGP ARAMS  r) 

{ 

_enable ( ) ; 
reset_pharlap ( )  ; 
if  (in_user_code) 

{ 

in_user_code  =  FALSE; 

printf ("\nProtection  violation  at  %04X: %08X\n", 
r.cs,  r.ip); 
if  (r.err_code) 

printf ("Error  code  %04X\n",  r.err_code); 
printf ("<DS  %04X>  <ES  %04X>  <FS  %04X>  <GS  %04X>\n", 
r.ds,  r.es,  r.fs,  r.gs); 
printf ("<EDI  %08X>  <ESI  %08X>  <FLAGS  %08X>\n", 
r.di,  r.si,  r. flags); 

printf ("<EAX  %08X>  <EBX  %08X>  <ECX  %08X>  <EDX  %08X>\n", 
r.ax,  r.bx,  r.cx,  r.dx); 
long jmp (toplevel,  -1); 

/‘NOTREACHED*/ 

) 

else 

[ 

printf ("An  internal  error  has  occurred  at  %04X:%08X\n", 
r.cs,  r.ip); 
revert  ()  ; 

_chain_intr (old_intl3handler_prot) ; 

/‘NOTREACHED*/ 

) 

} 

//  convert  ASCIIZ  hex  string  to  integer 
unsigned  xtoi (char  *s) 

( 

unsigned  i  =0,  t; 

while  (*s  ==  '  '  !!  *s  ==  '\t')  s++; 
for  (;;) 

[ 

char  c  =  *s; 


if 

(c 

>= 

'O' 

&& 

c 

<= 

'9') 

t  =  48; 

else 

if 

(c 

>= 

'A' 

&& 

c 

<= 

'  F' 

t  =  55; 

else 

if 

(c 

>= 

'  a' 

&& 

c 

<= 

'f') 

t  =  87; 

else  break; 

i  =  (i  «  4)  +  (c  -  t)  ; 


s++; 

) 

return  i; 


Listing  Five 


End  listing  Four 


/*  GPF386.C — for  Phar  Lap  386 !DOS-Extender  and  MetaWare  High  C  for  386  MS-DOS 
set  ipath=\c386\inc\ 

\c386\hc386  gpfault  -define  PROT_MODE 
\pharlap\fastlink  gpfault  -lib  small\hce. lib 
\pharlap\run386  gpfault 

NOTE!  To  keep  this  example  short,  most  of  the  precautions  taken 
in  Listing  3  are  not  repeated  here.  Refer  to  Listing  3  (GPFAULT.C) 
for  how  the  interrupt  handler  should  really  be  written. 

*/ 


♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <ctype.h> 

♦include  <setjmp.h> 

♦include  "msdos.cf" 

♦include  "interrup.cf " 

♦include  "gpfault.h" 

BOOL  call_pharlap (unsigned  short  ax,  unsigned  short  cl); 
void  reset_pharlap (void) ; 

IPROC  get vect_prot (short  intno); 

void  real_far  ‘get vect_real (short  intno); 

BOOL  set vect_prot (short  intno,  void  prot_far  ‘handler); 

BOOL  setvect_real (short  intno,  void  real_far  ‘handler); 

BOOL  setvect (short  intno,  IPROC  handler); 

BOOL  set2vect (short  intno,  IPROC  phandler,  void  real_far  ‘rhandler); 
void  revert (void) ;  /*  install  old  handlers  */ 


set jmp (toplevel) ; 
for  (;;) 


♦pragma  Calling_convention (C_interrupt  !  _FAR_CALL) ; 
void  intl3handler (REG_PARAMS  r) ; 

♦pragma  Calling_convention () ; 
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IPROC  old_intl3handler_prot; 

void  real_far  *old_intl3handler_real; 

jmp_buf  top level; 

RE G_P ARAMS  r2  =  { 0 } ; 

BOOL  in_user_code  =  FALSE; 

main  () 

{ 

char  buf[255]; 
unsigned  prot_far  *fp; 
unsigned  short  seg; 
unsigned  off,  data; 

old_intl3handler_real  =  getvect_real (OxOD) ; 
old_intl3handler_prot  =  get vect_prot (OxOD) ; 
setvect (INT_GPFAULT,  intl3handler) ; 

printf ("'Q'  to  quit,  '!'  to  reinstall  default  GP  Fault  handler\n") ; 

if  (set jmp (toplevel)  ==  -1) 

l 

printf ("Protection  violation  at  %04X:%08X\n", 
r2.cs,  r2.ip); 
if  (r2 .err_code) 

printf ("Error  code  %04X\n",  r2 .err_code) ; 
printf ("<ES  %04X>  <DS  %04X>  <EDI  %08X>  <ESI  %08X>  <FLAGS  %08X>\n", 
r2.es,  r2.ds,  r2.di,  r2.si,  r2. flags); 
printf ("<EAX  %08X>  <EBX  %08X>  <ECX  %08X>  <EDX  %08X>\n", 
r2.ax,  r2.bx,  r2.cx,  r2.dx); 

) 

for  (;;) 

{ 

printf ("$  "); 

*buf  =  ' \0' ; 
gets (buf ) ; 

if  (toupper (*buf )  ==  'Q' ) 
break; 

else  if  (*buf  ==  ' ! ' ) 

{ 

revert () ; 
continue; 

} 

sscanf(buf,  "%04X:%08X  %x",  &seg,  &off,  Sdata) ; 

FP_SEG(fp)  =  seg; 

FP_OFF (fp)  =  off; 
in_user_code  =  TRUE; 

*fp  =  data; 

printf ("poked  %p  with  %x\n",  fp,  *fp) ; 
in_user_code  =  FALSE; 

} 

revert () ; 
printf ("Bye\n") ; 
return  0; 

} 

void  revert (void) 

{ 

set2vect (OxOd,  old_intl3handler_prot,  old_intl3handler_real) ; 

} 

tpragma  Calling_convention (C_interrupt  !  _FAR_CALL) ; 
void  intl3handler (REG_PARAMS  r) 

( 

if  (in_user_code) 

{ 

in_user_code  =  FALSE; 
r2  =  r; 

reset_pharlap() ; 

STI;  //  _inline (OxFB) :  reenable  interrupts 
long jmp (toplevel,  -1); 

} 

else 

( 

printf ("Internal  error  at  %04X:%08X\n",  r.cs,  r.ip); 
revert  ()  ; 

return;  //  let  the  fault  happen  again  (no  _chain_intr) 

} 

/*NOTREACHED*/ 

} 

fpragma  Calling_convention () ; 

BOOL  call_pharlap (unsigned  short  ax,  unsigned  short  cl) 

{ 

Registers. AX. W  =  ax; 

Registers. CX.LH.L  =  cl; 
calldos () ; 

return  ! (Registers .Flags  &  1); 

} 

void  reset_pharlap (void) 

( 

call_pharlap (0x2501,  0); 

} 

IPROC  getvect_prot (short  intno) 

{ 

IPROC  handler; 

call_pharlap (0x2502,  intno); 

/*  no  MK_FP  for  High  C  386  */ 

FP_SEG (handler)  =  Registers .ES .W; 

FP_OFF (handler)  =  Registers. BX.R; 
return  handler; 

} 

void  real_far  *getvect_real (short  intno) 

{ 

call_pharlap (0x2503,  intno); 

return  (void  real_far  *)  Registers. BX.R; 

} 

BOOL  set vect_prot (short  intno,  void  prot  far  ‘handler) 

{ 

Registers. DS .W  =  FP_SEG (handler) ; 

Registers. DX.R  =  FP_OFF (handler) ; 
return  call_pharlap (0x2504,  intno); 


(continued  on  page  114) 
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Listing  Five  (Listing  continued,  text  begins  on  page  76.) 

BOOL  setvect_real (short  intno,  void  real_far  ‘handler) 

{ 

Registers .BX.R  =  (unsigned)  handler; 
return  call_pharlap (0x2505,  intno); 

} 

BOOL  setvect (short  intno,  IPROC  handler) 

1 

Registers .DS.W  =  FP_SEG (handler) ; 

Registers .DX.R  =  FP_OFF (handler) ; 
return  call_pharlap (0x2506,  intno); 

} 

BOOL  set2vect (short  intno,  IPROC  phandler,  void  real_far  *rhandler) 

{ 

Registers. DS.W  =  FP_SEG (phandler) ; 

Registers. DX.R  =  FP_OFF (phandler) ; 

Registers. BX.R  =  (unsigned)  rhandler; 
return  call_pharlap (0x2507,  intno); 

) 


End  Listing  Five 


Listing  Six 

/*  OS2TRACE.C — catching  GP  faults  in  OS/2,  using  DosPTraceO 
compile  with: 

cl  -Lp  os2trace.c 

to  make  tiny  (less  than  3K)  .EXE  with  C  run-time  DLL,  compile  with: 
cl  -AL  -c  -Gs2  -Ox  -Lp  -I\msc\inc\mt  os2trace.c 

link  /nod/noi  crtexe.obj  os2trace,os2trace, ,crtlib.lib  \os2\lib\os2 . lib; 

*/ 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  <process.h> 

♦include  <signal.h> 

♦include  <setjmp.h> 

♦define  INCL_DOS 
♦define  INCL_DOSTRACE 
♦define  INCL_VIO 
♦include  "os2.h" 

♦include  "ptrace.h" 

♦define  LOCAL  static 
typedef  unsigned  WORD; 

LOCAL  VOID  NEAR  print_regs (void) ; 

LOCAL  VOID  NEAR  send_sig_segv (void) ; 

LOCAL  VOID  NEAR  catch_sig_segv (void) ; 

LOCAL  WORD  NEAR  trace (int  argc,  char  *argv[],  BOOL  verbose); 

LOCAL  VOID  NEAR  start_trace (char  *prog,  char  *cmdline) ; 

LOCAL  char  ‘progname (char  *s) ; 

LOCAL  char  *cmdline(int  argc,  char  *argv[]); 

LOCAL  WORD  NEAR  selector_f rom_segment (WORD  seg) ; 

LOCAL  VOID  NEAR  set_csip (WORD  cs,  WORD  ip); 

LOCAL  int  break_handler (void) ; 

PTRACEBUF  ptb; 
jmp_buf  top level; 

♦define  FP_OFF(fp)  ((unsigned)  (fp) ) 

♦define  JMP_GP FAULT  -1 

♦define  JMP_BREAK  -2 

main  (int  argc,  char  *argv[]) 

( 

char  buf [80] ; 

BOOL  do_trace  =  TRUE; 

BOOL  verbose  =  FALSE; 

WORD  x; 
int  i; 

for  (i=l;  i<argc;  i++) 

if  (argv[i] [0]  ==  '-') 
switch (argv[i] [1] ) 

{ 

case  'x':  do_trace  =  FALSE;  break; 
case  '  v':  verbose  =  TRUE;  break; 

) 

signal (SIGINT,  break_handler) ;  //  doesn't  work  with  CRTLIB.DLL 

if'  (do_trace) 

return  trace (argc,  argv,  verbose); 

//  if  (!  do_trace)  run  interpreter 

switch  (set jmp (toplevel) )  //  used  to  catch  multiple  events 

{ 

case  JMP_GP FAULT: 

printf ("General  Protection  violation! \n") ; 
break; 

case  JMP_BREAK: 

printf ("break\n")  ; 

signal (SIGINT,  break_handler) ; 

//  what  if  this  is  trace  process?? 
break; 

) 

for  (;;) 

I 


printf ("$  "); 
gets (buf) ; 

if  (toupper (*buf)  ==  'Q') 
break; 

//  cause  one  of  a  number  of  different  GP  faults 
switch  (*buf) 

( 


case 

'0' 

x  =  * ( (int  far  *)  0L) ; 

break; 

// 

GP  fault 

case 

'1' 

x  =  * ( (int  far  *)  -1L) ; 

break; 

// 

GP  fault 

case 

'2' 

*((char  *)  main)  =  'x' ; 

break; 

// 

bashes  data! 

case 

'3' 

x  =  VioWrtTTY (OL,  100,  0) ; 

break; 

// 

GP  fault  in  DLL 

case 

'4' 

x  =  VioWrtTTY (-1L,  100,  0) ; 

break; 

// 

GP  fault  in  DLL 

case 

'5' 

x  =  VioWrtTTY (0L) ; 

break; 

// 

boom! 

case 

'6' 

x  =  puts (-1L) ; 

break; 

// 

GP  fault 

case 

x  =  DosGetInfoSeg(lL,  2L) ; 

break; 

// 

thread  dies 

) 

printf ("Executed  statement  %c\n",  *buf ) ; 

) 

return  0; 

) 

/*  case  2  is  important  because,  though  the  operation  is  illegal,  it  does 
not  generate  a  GP  fault.  Consequently,  the  operation  is  successful. 
Depending  on  how  OS2TRACE.C  is  compiled,  sometimes  a  string  gets  bashed 
so  that  string  prints  out  "General  protection  vixlation, "  sometimes 
something  else  gets  bashed  so  that  when  we  exit,  C  run-time  puts  up  a 
message  about  null  pointer  assignment. 

*/ 

LOCAL  WORD  NEAR  trace(int  argc,  char  *argv[],  BOOL  verbose) 

{ 

start_trace(progname(argv[0]) ,  cmdline (argc,  argv) ) ; 

/*  DosPTrace  event  loop  */ 
for  (;;) 

{ 

ptb.tid  =  0; 
ptb.cmd  =  GO; 

DosPTrace (&ptb) ; 
switch  (ptb.cmd) 

{ 

case  EVENT_GP_FAULT : 
if  (verbose) 

[ 

printf ("GP  fault  (error  %04X)  at  %04X:%04X\n", 
ptb. value,  ptb.segv,  ptb.offv); 
print_regs () ; 

) 

send_sig_segv ( ) ; 
break; 

case  EVENT_THREAD_DEAD : 
if  (verbose) 

printf ("Thread  %u  dying\n",  ptb.tid); 
break; 

case  EVENT_DYING: 
if  (verbose) 

printf ("Process  %u  dying\n",  ptb.pid); 
return  0; 

) 

) 

/‘NOTREACHED*/ 

} 

LOCAL  VOID  NEAR  print_regs (void) 

( 

ptb.cmd  =  RE AD_REG I STERS ; 

DosPTrace (iptb) ; 

printf ("AX=%04X  BX=%04X  CX=%04X  DX=%04X  SI=%04X  DI=%04X  BP=%04X\n", 
ptb.rAX,  ptb.rBX,  ptb.rCX,  ptb.rDX,  ptb.rSI,  ptb.rDI,  ptb.rBP); 
printf ("DS=%04X  ES=%04X  IP=%04X  CS=%04X  FL=%04X  SP=%04X  SS=%04X\n", 
ptb.rDS,  ptb.rES,  ptb.rIP,  ptb.rCS,  ptb.rF,  ptb.rSP,  ptb.rSS); 

) 

LOCAL  VOID  NEAR  send_sig_segv (void) 

[ 

/*  because  of  OS/2  "disjoint  LDT  space,"  we  could  just  as  easily  say: 

WORD  cs  =  FP_SEG((void  far  *)  catch_sig_segv) ; 
it  will  be  mapped  to  same  selector  in  both  processes 
*/ 

WORD  cs  =  selector_from_segment (1) ;  //  catch_sig_segv ()  in  seg  1 

WORD  ip  =  FP_OFF((void  far  *)  catch_sig_segv) ; 
set_csip(cs,  ip); 

) 

LOCAL  WORD  NEAR  selector_f rom_segment (WORD  seg) 

{ 

ptb. value  =  seg; 

ptb.cmd  =  SEG_NUM_TO_SELECTOR; 

DosPTrace (&ptb) ; 

return  (ptb.cmd  ==  EVENT_ERROR)  ?  0  :  ptb. value; 

} 

LOCAL  VOID  NEAR  set_csip (WORD  cs,  WORD  ip) 

{ 

ptb.cmd  =  READ_REG I STERS ; 

DosPTrace (&ptb) ; 
ptb.rCS  =  cs; 
ptb.rIP  =  ip; 
if  (ptb.rDS  !=  ptb.rSS) 

{ 

printf ("Faulted  inside  DLL  code\n"); 
ptb.rDS  =  ptb.rSS;  //  very  important! 

) 

ptb.cmd  =  WRITE_REGISTERS; 

DosPTrace (&ptb) ; 

) 

LOCAL  VOID  NEAR  catch_sig_segv (void) 
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{ 

longjmp (toplevel,  JMP_GP FAULT ) ; 

/ 

//  shared  by  debugger  and  debuggee  processes 

LOCAL  int  break  handler (void) 

signal (SIGINT,  SIG  IGN) ; 

long jmp (toplevel,  JMP  BREAK); 

j 

LOCAL  VOID  NEAR  start  trace (char  *prog,  char  *cmdline) 

RESULTCODES  resc; 

if  (DosExecPgm (NULL,  0,  EXEC  TRACE,  cmdline,  NULL,  &resc,  prog)  !=  0) 

return; 

ptb.pid  =  resc.codeTerminate; 

ptb.tid  =  0; 

//  tacks  .EXE  after  program  name 

LOCAL  char  *progname (char  *s) 

static  char  str[128]; 

strcpy(str,  s); 

strcatfstr,  ".EXE"); 

return  str; 

) 

//  undoes  all  argc/argv  work, 

appends  -x  switch 

LOCAL  char  *cmdline(int  argc, 

char  *argv[]) 

static  char  str[128],  *t 

=  str; 

char  *s  =  argv[0]; 

register  int  arg  =  0; 

while  (arg  <  argc) 

while  (*s) 

*t++  =  *s++; 

*t++  =  (arg)  ?  '  '  : 

' \0';  //  '\0'  after  program  name 

s  =  argv[++arg]; 

*t++  =  ;  *t++  =  'x' ; 

//  append  -x  switch 

*t  =  ' \0' ; 

return  str; 

) 

End  listing  Six 

Listing  Seven 

//  ptrace.h 

//  DosPTrace  commands 

♦define  READ  I  SPACE 

0x0001 

♦define  READ  D  SPACE 

0x0002 

♦define  READ  REGISTERS 

0x0003 

#define  WRITE  I  SPACE 

0x0004 

♦define  WRITE  D  SPACE 

0x0005 

#def ine  WRITE  REGISTERS 

0x0006 

♦define  GO 

0x0007 

♦define  TERMINATE  CHILD 

0x0008 

♦define  SINGLE  STEP 

0x0009 

♦define  STOP  CHILD 

OxOOOA 

♦define  FREEZE  CHILD 

OxOOOB 

♦define  RESUME  CHILD 

OxOOOC 

♦define  SEG  NUM  TO  SELECTOR 

OxOOOD 

♦define  GET  FLOATINGPT  REGS 

OxOOOE 

♦define  SET  FLOATINGPT  REGS 

OxOOOF 

♦define  GET  DLL  NAME 

0x0010 

♦define  THREAD  STATUS 

0x0011  //  new 

♦define  MAP  READONLY  ALIAS 

0x0012 

♦define  MAP  READWRITE  ALIAS 

0x0013 

♦define  UNMAP_ALIAS 

0x0014 

//  DosPTrace  events 

♦define  EVENT  SUCCESS 

0 

♦define  EVENT  ERROR 

-1 

♦define  EVENT  SIGNAL 

-2 

♦define  EVENT  SINGLESTEP 

-3 

♦define  EVENT  BREAKPOINT 

-4 

♦define  EVENT  PARITYERROR 

-5 

♦define  EVENT  DYING 

-6 

♦define  EVENT  GP  FAULT 

-7 

♦define  EVENT  LOAD  DLL 

-8 

♦define  EVENT  FLOATPT  ERROR 

-9 

♦define  EVENT  THREAD  DEAD 

-10 

♦define  EVENT  ASYNC  STOP 

-11 

♦define  EVENT  NEW  PROCESS 

-12 

♦define  EVENT_ALIAS_FREE 

-13 

//  DosPTrace  error  types 

♦define  ERROR  BAD  COMMAND 

1 

♦define  ERROR  CHILD  NOTFOUND 

2 

♦define  ERRORJJNTRACEABLE 

5 

//  Thread  states 

♦define  THREAD  RUNNABLE 

0 

♦define  THREAD  SUSPENDED 

1 

♦define  THREAD  BLOCKED 

2 

♦define  THREAD_CRITSEC 

3 

//  Thread  debug  states 

♦define  THREAD  THAWED 

0 

♦define  THREAD_FROZEN 

1 

End  Listings 
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Programming  RISC 

Engines 

Instruction  sets  are  designed  for  fast,  pipelined  execution 


Neal  Margulis 


The  innovation  of  the  assembly 
line  revolutionized  manufactur¬ 
ing.  By  breaking  assembly  down 
into  simple  steps,  tremendous 
efficiency  is  gained.  Instead  of 
each  unit  taking  one  hour  to  produce, 
it  can  be  broken  down  into  six  steps 
of  ten  minutes  each.  This  results  in  a 
new  unit  produced  every  ten  minutes 
without  increasing  the  manufacturing 
machinery  needed.  As  long  as  each 
step  takes  about  the  same  time,  the 
assembly  line  is  kept  filled  and  the 
throughput  is  much  higher  than  if  all 
operations  are  done  serially. 

RISC  processors  rely  on  the  same 
concept.  They  define  an  instruction  set 
that  can  efficiently  move  through  the 
processor’s  pipeline.  To  do  this,  the 
instruction  set  must  meet  several  crite¬ 
ria.  First,  each  instruction  takes  only 
one  clock  to  execute.  Also,  each  in¬ 
struction  must  be  easily  fetched  and 
quickly  identified.  Unlike  their  CISC 
counterparts,  RISC  processors  expose 
some  of  their  pipeline  to  software  and 
allow  the  programmer  to  arrange  in¬ 
struction  sequences  to  avoid  pipeline 
freezes. 

Compilers  are  an  important  part  of 
developing  code  for  RISC  processors. 
RISC  instructions  are  highly  regular  in 
form  and  have  consistent  behavior,  al¬ 
lowing  compilers  to  generate  efficient 
code.  However,  the  opportunities  to 
further  tune  portions  of  a  program  by 
hand-coded  assembly  language  always 
exist.  Also,  hardware-specific  portions 
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of  device  drivers  are  convenient  to  write 
in  assembly  language.  This  article  shows 
how  RISC  instructions  operate  and  gives 
some  examples  including  C  compiler¬ 
generated  machine  code. 

The  Intel  i860  microprocessor  exem¬ 
plifies  a  modern  RISC  processor.  It  in¬ 
cludes  other  features  such  as  floating 
point,  memory  management,  and 
caches  on  one  chip,  but  at  its  heart  is 
an  efficient  RISC  core  that,  like  other 
RISC  processors,  is  easy  to  program. 
The  i860’s  RISC  core  architecture  will 
be  used  for  the  examples  in  this  article, 
but  the  concepts  discussed  extend  to 
most  other  RISC  processors  as  well. 
With  a  general  understanding  of  how 
the  RISC  core’s  pipeline  is  organized, 
you  will  gain  insight  into  how  to  order 
instruction  sequences. 

Programming  Goals 

The  technique  for  programming  RISC 
processors  involves  understanding  the 
instructions  and,  equally  important,  the 
interaction  between  instructions.  The 
acronym  “reduced  instruction  set  com¬ 
puter”  (RISC)  alerts  you  that  some  in¬ 
structions  are  no  longer  available.  While 
this  may  be  true,  they  have  been  re¬ 
placed  with  a  powerful  set  of  simple 
operations.  Together,  these  simple  op¬ 
erations  perform  the  same  functions 
as  the  more  complex  instructions  you 
are  used  to.  The  RISC  programming 
challenge  is  to  sequence  these  opera¬ 
tions  to  get  maximum  performance  from 
the  processor. 

If  each  instruction  takes  only  one 
clock  at  each  pipeline  stage,  then  the 
number  of  instructions  executed  per 
second  is  equal  to  the  processor’s  clock 
frequency.  After  adjusting  to  allow  for 
uncooperative  instructions,  a  measure 
that  is  often  called  the  “native  MIPS” 
rating  can  be  calculated  as  follows: 


Clock  Frequency 

Native  MIPS  =  - 

Clocks  per  Instruction 

This  number  has  little  meaning.  The 
native  MIPS  rating  has  been  compared 
to  RPMs  (revolutions  per  minute)  of  a 
car:  It  tells  you  how  fast  the  engine  is 
going,  but  not  how  fast  the  car  is  going. 
Instead,  the  native  MIPS  rating  needs 
to  be  normalized  to  a  common  metric 
that  indicates  what  you  really  want  to 
measure  —  the  time  per  task.  Such  as 
miles  per  hour  for  the  car,  the  VAX 
MIPS  rating  has  become  the  standard. 
The  most  common  method  for  calcu¬ 
lating  VAX  MIPS  is  through  benchmark¬ 
ing:  Compare  the  duration  of  a  task  on 
the  processor  with  its  duration  on  the 
VAX  11/780.  The  task’s  time  ratio  is  the 
VAX  MIPS  rating.  Do  not  attempt  to  gain 
information  on  a  processor’s  native  MIPS 
rating  from  its  VAX  MIPS  rating. 

The  time  per  task  can  also  be  calcu¬ 
lated  analytically  as  follows: 

time/task=  (instructions/task)  "  (clocks/ 
instruction)  *  (time/clock). 

While  RISC  processors  may  require  more 
instructions  per  task  than  traditional  pro¬ 
cessors,  they  more  than  make  up  for  it 
by  reducing  the  average  clocks  per  in¬ 
struction  and  increasing  the  clock  speed. 

Instruction  Processing 

In  order  to  execute  each  instruction 
efficiently,  processing  is  broken  into 
four  stages.  Each  stage  performs  a  des¬ 
ignated  operation  in  one  cycle  and 
passes  the  instruction  to  the  next  stage. 
The  stages  are  “Fetch,”  “Decode,”  “Exe¬ 
cute,”  and  “Write.” 

The  Fetch  stage  gets  the  instruction 
from  the  instruction  cache  into  an  in¬ 
ternal  storage  latch.  The  Decode  stage 
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accesses  the  source  registers  and  de¬ 
codes  the  instruction.  The  ALU  opera¬ 
tion  is  performed  in  the  Execute  stage. 
Address  calculation  is  done  here  for 
memory  operations.  The  results  of  the 
instruction  are  written  to  the  register 
file  in  the  Write  stage  if  the  instruction 
was  not  a  memory  operation.  The  data 
cache  access  is  accessed  here  for  mem¬ 
ory  operations. 

To  allow  each  stage  of  the  pipeline 
to  complete  in  one  cycle,  careful  atten¬ 
tion  is  paid  to  the  instruction  format. 
Figure  1  shows  the  general  format  for 
all  of  the  RISC  core  instructions.  All 
instructions  are  32  bits  long  with  desig¬ 
nated  fields  for  the  opcodes  and  regis¬ 
ters.  To  access  any  of  the  i860’s  32- 
integer  registers,  5  bits  are  used  for 
each  register  designator.  Without  hav¬ 
ing  to  decode  the  length  of  the  instruc¬ 
tion,  or  take  multiple  cycles  to  read  the 
instruction  into  the  processor,  the  Fetch 
stage  can  execute  in  one  cycle.  In  the 
Decode  stage,  the  source  register  ac¬ 
cesses  can  begin  before  the  instruction 
type  is  known,  because  the  field  within 
the  instruction  that  indicates  the  source 
register  is  always  in  the  same  place. 
By  allowing  only  instructions  that  can 
be  executed  in  one  stage,  the  Execute 
stage  is  always  performed  in  one  cycle. 
During  the  Write  stage,  the  result  is 
written  back  into  the  register  file. 

Besides  allowing  efficient  instruction 
execution,  the  four-stage  pipeline  al¬ 
lows  instructions  to  be  overlapped.  Over¬ 
lapping  the  instructions  allows  a  new 
instruction  to  start  with  each  clock  cy¬ 
cle.  Figure  2  illustrates  the  resulting 
speed-up  of  overlapping  instructions. 
With  sequential  (scalar)  execution,  each 
instruction  passes  through  all  four  stages 
of  the  pipeline  before  the  next  instruc¬ 
tion  starts.  With  pipelined  execution, 
instructions  start  as  soon  as  the  previ¬ 
ous  instruction  enters  the  second  stage. 
In  the  same  number  of  cycles  that  se¬ 
quential  execution  processes  three  in¬ 
structions,  pipelined  execution  pro¬ 
cesses  12  instructions,  a  fourfold  im¬ 
provement. 

To  maintain  performance,  the  pipe¬ 
line  needs  to  keep  all  of  the  stages 
active  all  of  the  time.  If  an  instruction 
were  to  take  two  cycles  in  any  of  the 
stages,  it  would  cause  the  other  three 
stages  to  wait  an  extra  cycle.  This  is 
referred  to  as  a  freeze  condition.  Al¬ 
though  all  instructions  are  designed  to 
take  only  one  cycle  in  each  stage,  freeze 
conditions  can  occur.  The  two  types 
of  instructions  that  are  most  likely  to 
cause  freezes  in  the  pipeline  are  mem¬ 
ory  operations  and  branch  instructions. 
RISC  processors  define  the  instructions 
to  allow  the  programmer  to  reduce  the 
occurrence  of  such  freeze. 


Load/Store  Instructions  is  in  the  on-board  cache.  Figure  3  shows 

Unlike  earlier  processors  that  allow  op-  a  pipeline  sequence  for  a  load  instruc- 
erations  on  data  in  memory,  the  only  tion  and  the  subsequent  two  instruc- 
memory  operations  permitted  on  RISC  tions.  The  data  from  the  load  operation 
processors  are  loads  and  stores.  All  is  available  at  the  end  of  the  load  in- 

other  operations  are  performed  directly  struction’s  Write  stage.  This  is  too  late 

on  the  values  in  the  registers.  The  load/  for  the  instruction  immediately  follow- 
store  architecture  simplifies  the  design  ing  the  load  to  use  the  data  as  a  source 
of  the  processor  and  allows  the  pro-  operand.  The  instruction  slot  following 
grammer  to  hide  the  delay  caused  by  a  load  is  called  the  “load-delay  slot.” 
memory  accesses.  The  i860  gives  the  programmer  two 

Loads  from  memory  always  have  at  options  for  the  load-delay  slot.  The 
least  a  one-clock  delay,  even  if  the  data  (continued  on  page  128) 

General  Format 

31 _ 25  20  15  10  0 


OPCODE/I 

SFtC2  DEST  SRC1  null/immediate/offset 

16  -  Bit  Immediate  Variant  (except  bte  and  btne) 

31  25  20  15  0 

OPCODE 

SRC2  DEST  IMMEDIATE 

CONSTANT  OR  ADDRESS  OFFSET 

31 

st,  bia,  bte  and  btne 

25  20  15  10  0 

OPCODE/I 

SRC2  SRC1  OFFSET  LOW 

HIGH  SRC13 

31 

bte  and  btne  with  5  -  Bit  Immediate 

25  20  15  10  0 

OPCODE 

SRC2  0FLSET  IMMEDIATE  OFFSET  LOW 

HIGH 

Figure  1:  The  general  format  for  all  of  the  RISC  core  instructions 


Sequential  (Scalar)  Instruction  Execution 

Instruction  1 

D  |  X 

w 

Instruction  2 

F  |  D  |  X  |  W 

Instruction  3 

F 

Id 

3 

W  | 

Pipelined  Instruction  Execution 

Instruction  1 

1  F 

D  X 

W 

Instruction  2 

F  D 

X  w 

Instruction  3 

F 

D  X  W 

Instruction  4 

F  D  X  W 

Instruction  5 

F  D  X  W 

Instruction  6 

F  D  X  W 

Instruction  7 

F  D  X 

w 

Instruction  8 

F  D 

X 

W 

Instruction  9 

F 

D 

X 

w 

Instruction  10 

F 

D 

X 

* 

Instruction  1 1 

F 

D 

* 

Instruction  12 

F 

* 

Figure  2:  The  speed-up  of  overlapping  instructions 


Figure  3:  A  pipeline  sequence  for  a  load  instruction  and  the  subsequent  two 
instructions 
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Four  Hundred  and 
Eighty-seven 


ON’T  stop  me  if  you’ve  heard 
this  one. 

A  man  is  sent  to  prison,  and 
during  his  first  supper  inside,  a 
fellow  prisoner  stands  up  and  says 
loudly,  “Five  thousand  nine  hundred 
and  thirty-three.”  Everybody  laughs.  The 
next  night,  a  different  convict  jumps 
up  and  shouts,  “Three  thousand  and 
ten,”  and  the  crowd  breaks  up.  This 
continues:  The  next  day  in  the  yard,  a 
prisoner  mutters,  “Two  sixteen,”  and 
the  prisoners  near  him  snicker  and  snort. 
Puzzled,  the  man  finally  asks  his  cell 
mate  what’s  going  on. 

“There’s  one  joke  book  in  the  prison 
library,”  his  cell  mate  explains,  “with 
the  ten  thousand  best  jokes,  all  num¬ 
bered.  Well,  a  lot  of  us  have  been  here 
long  enough  to  have  memorized  the 
jokes,  so  when  we  want  to  tell  one, 
we  just  use  its  number.  My  favorite  is 
four  hundred  and  eighty-seven.”  And 
he  chuckles  softly  to  himself. 

The  next  night  at  supper,  the  man 
stands  up  and  shouts,  “Four  hundred 
and  eighty-seven.”  His  fellow  prisoners 
stare  at  him  in  silence.  Crushed,  he  sits 
back  down  and  tries  to  finish  his  meal. 

“I  thought  you  said  four  hundred 
and  eighty-seven  was  a  good  joke,” 
he  snarls  at  his  cell  mate  later  that  night. 

“It’s  one  of  the  best,”  the  cell  mate 
drawls. 

“Then  why  didn’t  anybody  laugh?” 

“You  didn’t  tell  it  right.” 

If  you’re  wondering  right  now  what 
the  number  of  the  joke  I  just  told  is, 
you  have  the  right  mind-set  for  a  dis¬ 
cussion  of  representation  in  Lisp.  If, 

Michael  Swaine 

furthermore,  you  think  that  the  num¬ 
ber  of  that  joke  ought  to  be  four  hun¬ 
dred  and  eighty-seven,  and  if  you’ve 
thought  about  what  a  different  joke  it 
would  be  if  that  were  the  case,  you 
must  be  a  Lisp  hacker. 

Lisp  hackers  often  point  to  certain 
features  of  the  language  in  explaining 
why  they  choose  to  program  in  Lisp. 
These  include  recursion,  the  ability  to 


operate  on  code  as  data,  and  extensi¬ 
bility.  None  of  these  features  are  unique 
to  Lisp,  though,  and  none  of  them  gets 
across  why  Lisp  is  unique. 

In  this  month’s  column,  we’ll  take  a 
look  at  representation  in  Lisp,  and  try 
to  get  some  sense  of  the  power  inher¬ 
ent  in  Lisp’s  representation  scheme,  and 
we’ll  examine  the  wide  range  of  data 
structures  supported  by  the  Common 
Lisp  standard,  built  on  this  representa¬ 
tion  scheme. 

Notes  on  Notation 

“Author:  The  idea  is  to  imitate  Godel’s 
self-referential  construction,  which  as 
you  know  is  INDIRECT,  and  depends 
on  the  isomorphism  set  up  by  Godel- 
numbering. 

“Crab:  Oh.  Well,  in  the  program¬ 
ming  language  Lisp,  you  can  talk  about 
your  own  program  directly  .  .  .  because 
programs  and  data  have  exactly  the 
same  form.  Godel  should  have  just 
thought  up  Lisp.  ...”  —  Douglas 
Hofstadter,  a  fictional  character,  and 
Crab,  a  crab,  in  Godel,  Esher,  Bach,  by 
Douglas  Hofstadter. 

John  McCarthy  thought  up  Lisp  30 
years  ago  as  a  tool  for  manipulating 
symbolic  expressions,  which  is  essen¬ 
tial  for  tasks  like  symbolic  integration. 
But  the  real  point  was  to  make  it  possi¬ 
ble  for  a  program  to  talk  about  a  pro¬ 
gram,  with  an  eye  to  developing  prov- 
ably  correct  programs.  Toward  this  end, 
McCarthy  used  a  class  of  expressions 
called  “s-expressions,”  or  symbolic  ex¬ 
pressions,  based  on  Alonso  Church’s 
work  on  the  lambda  calculus.  S-ex- 
pressions  permit  programs  and  data  in 
Lisp  to  have  the  same  forrh.  Programs 
and  data  in  Lisp  are  both  coded  as 
s-expressions. 

What,  exactly,  are  s-expressions? 
That’s  really  two  questions:  What  do 
they  look  like  and  what  do  they  do,  or 
what’s  the  notation  and  what’s  the  in¬ 
terpretation?  Both  questions  are  fruitful. 

The  notation  McCarthy  used  for  s- 
expressions  was  list  notation,  and  the 
name  Lisp  is  an  acronym  for  LISt  Pro¬ 
cessing.  Roughly,  s-expressions  are  lists. 
But  the  matter  of  s-expression  notation 


goes  a  little  deeper  than  this. 

Formally,  an  s-expression  is  either 
an  atomic  symbol  (atom)  or  a  list  of 
s-expressions: 

<s-expr>  ::=  <atom>  ! 

<list-of-s-expressions> 

What’s  an  atomic  symbol?  An  atomic 
symbol,  or  atom,  is,  formally,  just  a 
string  of  characters  subject  to  certain 
constraints.  It’s  a  name,  a  symbol,  such 
as  a  name  for  a  variable  or  constant  or 
function  in  any  language.  Or,  as  we 
shall  see,  not  quite  like  a  name  in  any 
other  language. 

And  the  notation  for  lists?  A  list  can 
be  recursively  defined  to  be  either  the 
empty  list  (which  is  sometimes  written 
using  the  atom  NIL)  or  an  item  like  the 
thing  on  the  right  below: 

<list>  ::=  NIL  !  (  <s-expr>  <list>  ) 

In  other  words,  all  Lisp  lists  are  binary 
trees  with  all  their  (non-NIL)  atoms  hang¬ 
ing  off  their  left  terminal  branches,  and 
all  right  terminal  branches  containing 
NILs.  NIL  is  a  primitive  Lisp  object  (atom) 
used  for  several  purposes,  including 
to  represent  Boolean  false  and  the 
empty  list. 

An  alternative  notation  for  lists  used 
in  Lisp  is  called  “dot”  notation.  In  dot 
notation,  a  (dotted)  list  can  be  defined 
thus: 

<dotted-list>  ::=  (  <s-expr>.  <s-expr>  ) 

Some  examples  of  Lisp  s-expressions 
are: 

A 

(A.B) 

(A  .  NIL) 

(A  .  (B  .  NIL)) 

(A  .  (B  .  ((C  .  (D  .  NIL))  .  NIL))) 

Here  are  prose  descriptions  of  the  five 
s-expressions  above: 

A  is  not  a  list,  nor  even  a  dotted  list, 
but  is  both  an  atomic  symbol  and  an 
s-expression. 


118 

172 


Dr.  Dobb’s  Journal,  February  1990 


(A  .  B)  is  a  dotted  list,  but  not  a  true 
list,  because  it  has  a  non-NIL  right  ter¬ 
minal  branch. 

(A  .  NIL)  is  the  list  containing  one 
element:  The  atomic  symbol  A. 

(A  .  (B  .  NIL))  is  the  list  containing 
the  two  elements  A  and  B. 

(A  .  (B  .  ((C  .  (D  .  NIL))  .  NIL)))  is  the 
list  containing  three  elements:  A,  B, 
and  the  list  containing  the  two  ele¬ 
ments  C  and  D. 

Figure  1  shows  pictures  of  the  binary 
trees  that  the  s-expressions  represent. 
There  are  reasons  for  using  dot  nota¬ 
tion  in  low-level  programming,  but  for 
most  purposes  the  simpler  list  notation 
is  used.  In  this  shorthand  form,  the 
above  forms  are  written: 

(No  list  representation  for  A,  since 
A  is  not  a  list.) 

(No  list  representation  for  (A  .  B), 
since  (A  .  B)  is  not  a  “true”  list.) 

(A) 

(AB) 

(A  B  (C  D)) 

Lists  in  this  notation  can  have  any  num¬ 
ber  of  elements,  but  note  that  the  un¬ 
derlying  representation  is  still  the  bi¬ 
nary  tree  described  by  the  dotted  pairs 
of  the  corresponding  dot  notation.  This 
(non-dotted)  notation  is  the  form  in 
which  all  Lisp  programs  are  normally 
written.  Every  Lisp  program  or  subpro¬ 
gram  begins  and  ends  with  a  matched 
pair  of  parentheses,  usually  with  more 
pairs  inside  and  with  atomic  symbols 
inside  them.  Every  data  object  is  also 
expressed  as  one  of  these  parenthe¬ 
sized  lists  if  it  is  not  represented  as  an 
atomic  symbol. 

Lisp  students  early  on  decided  that  the 
acronym  Lisp  stood  for  “Lots  of  Insipid, 
Stupid  Parentheses.”  Little  wonder. 

How  Symbols  Symbolize 

“Author:  I  find  indirect  self-reference 
a  more  general  concept,  and  far  more 
stimulating,  than  direct  self -reference. 
Moreover,  no  reference  is  truly  direct — 
every  reference  depends  on  SOME  kind 
of  coding  scheme.  It’s  just  a  question 
of  how  implicit  it  is.  Therefore,  no  self¬ 
reference  is  direct,  not  even  in  Lisp.  ” 

—  ibid. 

We’ve  looked  at  the  notation  used 
to  write  Lisp  programs  (list  notation) 
and  at  the  more  elemental  dot  notation 
and  the  underlying  data  structure  that 
lists  form.  We’ve  seen  that  lists  contain 
other  lists  and/or  atomic  symbols,  and 
that  properly-formed  combinations  of 
lists  and  atomic  symbols  are  called  sym¬ 
bolic  expressions,  or  s-expressions,  and 
that  s-expressions  are  the  universal  form 
in  which  data  objects  and  programs  in 


Lisp  are  expressed.  So  far,  these  are  just  ject,  or  can  be  used  to  retrieve  the  data 

notational  issues,  and  don’t  get  at  the  object,  and  there  are  functions  for  em¬ 
power  of  Lisp  representation.  Now  let’s  ating  and  deleting  data  objects,  and  for 

consider  what  these  s-expressions  mean,  manipulating  their  property  lists.  The 

Atomic  symbols  are  named  data  ob-  tools  for  manipulating  symbols  are  pow- 

jects.  The  object  named  can  be  a  con-  erful,  but  the  real  power  of  Lisp  comes 

stant  or  a  variable,  and  the  structure  of  in  the  ability  to  treat  tools  themselves 

the  object  can  be  anything.  Each  sym-  symbolically,  and  operate  on  them.  A 

bol  has  associated  with  it  a  structure  Lisp  named  function  is  just  one  particu- 

called  its  “property  list,”  or  p-list,  which  lar  kind  of  named  data  object  that  atomic 

allows  it  to  be  treated  as  a  record  struc-  symbols  can  comprise, 
ture  with  an  extensible  set  of  compo-  The  difference  between  constants  and 
nents,  each  of  which  can  be  an  arbi-  variables  is  roughly  one  scope  of  bind- 

trarily  complex  named  data  object.  The  ing.  In  Lisp,  the  values  bound  to  con- 

name  can  be  retrieved,  given  the  ob-  stants  and  variables  are  maintained  in 

different  data  structures. 

A  Lisp  constant  is  an  atomic  symbol 
that  possesses  an  associated  constant 
value.  One  of  the  things  that  can  be 
stored  in  the  p-list  of  an  atomic  symbol 
is  what  is  called  an  “apval”  (constant 
value).  If  a  symbol  has  the  string  “apval” 
as  the  first  element  of  a  pair  of  values 
on  its  p-list,  the  symbol  is  a  constant, 
and  its  constant  value  is  the  second 
element  of  that  pair. 

Variables  in  Lisp  are  atomic  symbols, 
too,  but  they  don’t  have  apvals.  They 
get  their  values  via  a  different  list.  Lisp 
maintains  a  data  structure  called  the 
“a-list,”  or  association  list.  This  is  a  list 
of  symbol  value  pairs  representing  the 
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Figure  1:  Binary  trees  that 
s-expressions  represent 
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current  bindings  of  variables  and  of 
function  names.  At  any  point  while 
Lisp  is  running,  we  are  “inside”  an 
s-expression;  that  is,  an  s-expression 
is  being  evaluated.  The  function  that 
does  the  evaluation,  called  “eval,”  main¬ 
tains  the  a-list.  Constant  values  are  not 
affected  by  a-list  bindings,  and  the  p- 
list  is  checked  before  the  a-list  when 
retrieving  a  value  for  a  symbol. 

Named  functions  are  also  maintained 
by  eval,  and  the  binding  stored  on  the 
a-list.  It  is  worth  noting  that  functions 
are  Lisp  objects,  and  have  a  data  type. 
All  functions  are  of  type  function. 

The  meaning  of  a  list  is  generally 
dependent  on  the  meanings  of  its  con¬ 
stituent  atomic  symbols,  because  a  list 
is  a  data  structure.  One  use  of  lists, 
though,  attaches  quite  a  different  sort 
of  meaning  to  a  list.  This  is  the  use  of 
a  list  as  the  invocation  of  a  function. 
The  fundamental  unit  of  interaction  with 
Common  Lisp  is  the  form,  which  is  an 
s-expression,  ergo  a  data  object.  The 
form  is  handed  to  eval  to  be  inter¬ 
preted  as  a  function,  with  a  new  data 
object  to  be  returned.  In  this  interpreta¬ 
tion,  the  first  element  of  the  list  names 
a  function  to  be  applied  to  the  other 
elements  as  arguments.  (This  is  over¬ 
simplified.) 

Although  the  use  of  a  list  to  repre¬ 
sent  the  invocation  of  a  function  and  its 
use  to  represent  a  particular  data  object 
may  seem  very  different,  and  are  in 
truth  very  different,  the  style  of  Lisp 
programming  often  makes  the  two  uses 
seem  very  much  alike.  Consider  the 
function  FIRST,  which  takes  a  list  as  an 
argument  and  returns  the  first  element 
of  the  list  as  its  value.  When  you  write 

(FIRST  VENDOR_LIST) 

you  are  executing  a  function  on  the  list 
VENDORLIST.  But  it’s  obvious  that  you 
are  also  referring  to  a  particular  data 
object,  specifically  the  FIRST  of  VEN- 
DOR_LIST.  To  the  implementer  of  the 
Lisp  system,  it  matters  that  FIRST  is  a 
function,  but  for  most  purposes,  the 
user  can  think  of  it  as  a  way  of  referring 
to  a  particular  element  of  a  complex 
data  structure.  This  is  a  property  of 
functions  generally,  not  restricted  to 
Lisp,  but  the  complete  dependence  of 
Lisp  on  functions  makes  this  a  distinc¬ 
tive  aspect  of  the  “feel”  of  program¬ 
ming  in  Lisp. 

Common  Lisp  Data  Types 

In  Common  Lisp,  an  object  may  belong 
to  more  than  one  data  type,  so  it  is  not 
generally  meaningful  to  inquire  about 
the  data  type  of  an  object.  For  example: 
the  simplest  data  type  is  type  null.  It 
consists  of  exactly  one  item:  NIL.  NIL 
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is  both  list  and  atom,  it  means  both 
false  and  the  empty  list,  and  it  can  be 
written  NIL  or  (  ).  It  is  possible  to  in¬ 
quire  whether  an  object  belongs  to  a 
particular  type,  and  a  Boolean  function 
typep  is  provided  for  this  purpose.  It  is 
objects,  however,  and  not  variables, 
that  can  be  typed.  A  Lisp  variable  can 
have  any  Lisp  object  as  its  value. 

Dotted  lists,  true  lists,  and  trees  are 
all  different  ways  of  viewing  structures 
of  conses.  A  cons  is  a  Lisp  data  type, 
and  is  another  name  for  the  dotted 
pair:  (  <  s-expr  >  .  <  s-expr  >  ).  What 
we  have  been  calling  a  list  is  a  chain 
of  conses  branching  off  the  right-side 
s-expressions.  If  the  list  is  terminated 
by  NIL,  it’s  a  true  list,  if  by  some  other 
atom,  it’s  a  dotted  list. 

Many  Lisp  data  types  are  built  from 
conses.  The  data  type  list,  for  example, 
is  the  union  of  the  cons  and  null  data 
types,  so  it  includes  true  lists  and  dot¬ 
ted  lists.  Lists  are  supported  by  a  large 
number  of  list-manipulation  functions. 
Lists  can  also  be  used  as  sets,  and  there 
are  set  functions,  such  as  union,  inter¬ 
section,  and  the  like,  in  the  Common 
Lisp  definition.  The  a-list,  used  by  func¬ 
tion  eval  to  keep  track  of  bindings,  is 
a  list  of  conses. 

Common  Lisp  also  supports  se¬ 
quences  and  other  compound  data 
types,  hash  tables,  arrays,  vectors, 
strings,  streams,  and  structures,  among 
other  data  types.  Conceptually,  these, 
too,  can  be  viewed  as  being  built  of 
cons  cells,  although  some  of  them  may 
be  implemented  in  some  more  efficient 
fashion.  Type  sequence  includes  both 
lists  and  vectors,  which  are  one-dimen¬ 
sional  arrays.  An  array  is  an  object  with 
components  arranged  according  to  a 
Cartesian  coordinate  system.  Arrays  can 
have  their  sizes  adjusted  dynamically 
after  creation,  or  can  be  of  type  simple 
array,  and  not  permit  this.  Non-simple 
arrays  can  also  share  data  with  other 
non-simple  arrays.  Element  1,1  of  a 
two-dimensional  array  foo  is  specified 
via  the  array-reference  function  aref 
thus:  ( aref  foo  1  1).  The  data  type  vec¬ 
tor  is  a  subtype  of  type  array.  A  string 
is  a  vector  of  type  string-char.  A  struc¬ 
ture  is  an  instance  of  a  user-defined 
data  type  with  a  fixed  number  of  named 
components.  These  are  similar  to  Pas¬ 
cal  records. 

Some  Lisp  data  objects  are  what  is 
called  “self-evaluating  forms.”  Because, 
as  I  suggested  earlier,  Lisp  is  always 
evaluating  forms,  even  objects  such  as 
numbers,  characters,  and  the  empty  list 
get  evaluated.  These  objects  return  them¬ 
selves  as  values.  Common  Lisp  defines 
four  broad  kinds  of  numeric  data  types: 
integer,  ratio,  floating  point,  and  com¬ 
plex;  and  one-character  data  type,  with 


subtypes. 

Integers  can  be  of  any  length,  and 
are  implemented  by  means  of  two 
subtypes:  fixnums  and  bignums. 
Fixnums  are  limited  in  length  and  are 
more  efficient  to  use;  bignums  can  be 
any  length.  The  definition  of  Common 
Lisp  calls  for  the  distinction  between 
fixnums  and  bignums  to  be  hidden 
from  the  user  most  of  the  time.  The 
default  radix  is  decimal,  but  any  radix 
from  2  to  36  can  be  specified. 

The  ratio  data  type  permits  precise 
representation  of  rational  numbers,  such 
as  the  fraction  2/3.  Common  Lisp  al¬ 
ways  converts  a  ratio  to  lowest  terms, 
and  to  an  integer  if  possible. 

Common  Lisp  provides  names  but 
not  full  specifications  for  four  different 
floating-point  data  types.  These  are 
short,  single,  double,  and  long. 

Complex  numbers  are  represented 
in  Cartesian  form  as  pairs  of  numbers 
of  any  of  the  other  data  types;  thus  the 
actual  type  of  a  complex  number  is  the 
type  complex  and  the  type  of  the  com¬ 
ponents,  such  as  complex  short  float. 
The  components  are  coerced  to  have 
the  same  type. 

There  are  two  important  Common 
Lisp  character  data  subtypes,  stand ard- 
char  and  string-char.  The  former  is  in¬ 
tended  to  be  as  portable  a  character  set 
as  possible;  that  is,  programs  written 
in  it  should  port  easily.  This  is  impor¬ 
tant,  because  the  character-data  type 
provides  for  such  features  as  specifica¬ 
tion  of  font  attributes  and  various  modi¬ 
fying  flags,  the  latter  for  programmers 
with  terminals  from  Mars.  The  string- 
char  subtype  comprises  all  characters 
that  can  be  contained  in  strings.  These 
can’t  have  any  of  those  funny  flags  or 
font  attributes  attached  to  them. 

Next  month  we’ll  look  at  the  full 
hierarchy  —  although  one  author  has 
called  it  a  heterarchy  —  of  Common 
Lisp  data  types,  and  at  some  of  the 
object-oriented  extensions  to  Common 
Lisp.  Well  also  look  at  the  way  in  which 
Lisp  functions  are  interpreted,  which 
will  get  us  into  what  Douglas  Hofstadter 
has  called  a  double-entendre: 

.  .  double-entendre  can  happen  with 
Lisp  programs  that  are  designed  to  reach 
in  and  change  their  own  structure.  If 
you  look  at  them  on  the  Lisp  level,  you 
will  say  that  they  change  themselves; 
but  if  you  shift  levels,  and  think  of  Lisp 
programs  as  data  to  the  Lisp  inter¬ 
preter  .  .  .  then  in  fact  the  sole  program 
that  is  running  is  the  interpreter,  and 
the  changes  being  made  are  merely 
changes  in  pieces  of  data.” 
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TEXTSRCH 

Connections 


This  month  we  continues  with  the 
TEXTSRCH  project,  one  that 
started  two  months  ago.  To  build 
the  entire  project,  you  will  need 
the  express. c  source  file  from  Decem¬ 
ber,  the  exinterp.c  and  textsrch.c  files 
from  January,  and  the  several  source 
files  introduced  this  month. 

TEXTSRCH  is  a  text  retrieval  system 
that  provides  a  concordance-like  index 
into  a  text  data  base.  You  provide  the 
files  of  text,  and  TEXTSRCH  builds  an 
inverted  word  index  into  the  files.  Later, 
when  you  go  looking  for  some  forgot¬ 
ten  reference  to  something,  you  use 
the  TEXTSRCH  query  language  to  com¬ 
pose  a  query,  and  TEXTSRCH  finds 
and  reports  to  you  the  files  that  match 
your  search.  I  described  the  syntax  of 
the  query  two  months  ago  and  devel¬ 
oped  its  interpreter  last  month.  This 
month  we  build  index  files  and  con¬ 
nect  it  all  together. 

TEXTSRCH  consists  of  several  widely 
used  techniques.  Besides  its  usefulness 
as  a  text  management  tool,  it  provides 
examples  of  hashing,  binary  trees,  com¬ 
mand-line  parsing,  expression  parsing, 
infix  and  postfix  expression  notation, 
and  expression  interpreting. 

Listing  One,  page  140,  is  textsrch.h, 
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Version  3-  We  built  the  first  version  two 
months  ago  and  added  to  it  last  month. 
Most  of  this  month’s  additions  are  func¬ 
tion  prototypes  for  the  code  that  fol¬ 
lows,  but  there  is  one  other  notable 
addition.  The  MAXFILES  variable  will 
influence  the  size  of  your  data  base 
index.  It  specifies  the  maximum  num¬ 
ber  of  text  files  that  a  TEXTSRCH  index 


can  support.  If  you  change  this  num¬ 
ber,  you  will  change  the  size  of  the  bit 
map  that  the  expression  interpreter 
needs.  Remember,  the  bit  map  has  one 
bit  per  file  in  the  data  base.  When  the 
bit  map  size  changes,  so  does  the  size 
of  one  of  the  index  files.  The  file  named 
“TEXT.NDX”  includes,  among  other 
things,  a  copy  of  the  bit  map  that  corre¬ 
sponds  to  every  unique  word  in  the 
data  base. 

Before  we  get  into  the  index  code, 
let’s  look  at  two  general-purpose  func¬ 
tions  that  TEXTSRCH  uses  and  that  you 
might  find  useful  in  other  projects. 

Parsing  the  Command  Line 

Listing  Two,  page  140,  is  cmdline.c,  a 
source  file  that  contains  the  parse_ 
cmdline  function.  The  function  pro¬ 
cesses  a  program’s  command-line  pa¬ 
rameters  and  is  the  only  part  of 
TEXTSRCH  that  is  oriented  to  any  spe¬ 
cific  architecture  in  that  it  works  with 
MS-DOS  and  Turbo  C.  You  can  easily 
redo  it  for  another  compiler  or  a  differ¬ 
ent  architecture.  Its  purpose  is  to  parse 
file  name  specifications  from  the  com¬ 
mand-line  into  discrete  file  names  and 
to  call  a  specified  function  to  process 
each  file.  In  addition,  parse_cmdline 
will  sense  the  presence  of  command¬ 
line  option  switches  and  set  entries  in 
an  associated  array  to  logical  true  and 
false  states  accordingly.  TEXTSRCH  does 
not  use  this  last  feature,  but  parse_ 
cmdline  supports  it  nonetheless. 

When  your  program  first  begins,  it 
calls  parse_cmdline  and  passes  the  con¬ 
ventional  argc  and  argv  variables  that 
are  available  as  parameters  to  the  main 
function.  Your  program  also  passes  the 
address  of  a  128-byte  array  of  switches 
and  the  address  of  a  function.  The  func¬ 
tion,  provided  in  your  program,  will 


process  the  files,  one  by  one. 

The  option  array  contains  the  initial 
default  setting  for  the  command-line 
switches.  This  statement  tests  the  array: 

if  (arrayCa’)) 

If  the  command-line  had  +a  on  it,  this 
test  would  be  true.  If  the  parameter 
was  -a  or  if  the  default  had  a  zero  value 
in  the  6lst  (ASCII  assumed)  position, 
the  test  would  be  false. 

The  function  selects  each  file  specifi¬ 
cation  and  calls  the  function  addressed 
by  the  last  parameter  in  the  call  to 
parse_cmdline.  If  you  explicitly  name 
files  on  the  command-line,  each  of  these 
is  processed  in  turn.  You  can  use  wild 
cards  or  prefix  a  file  name  with  the  © 
character  to  specify  that  the  file  names  to 
be  processed  are  recorded  in  a  text  file. 

If  you  use  wild  cards,  the  files  that 
match  the  ambiguous  specification  are 
processed  in  the  order  in  which  the 
directory  scan  finds  them.  I  used  the 
Turbo  C  findfirst  and  findnext  func¬ 
tions  for  the  directory  scan.  Microsoft 
C  has  similar  but  different  ones  named 
_dos_ findfirst  and  _dos_  findnext. 
Other  compilers  have  their  own  ver¬ 
sions  of  these  functions  or,  at  least, 
ways  to  call  MS-DOS  directly  to  use  the 
MS-DOS  functions  that  perform  these 
operations.  If  you  use  a  different  oper¬ 
ating  system,  then  you  must  provide 
other  ways  to  get  the  same  result.  If 
you  use  an  operating  system  that  does 
not  support  a  directory  scan  or  am¬ 
biguous  file  name  specifications,  then 
you  must  use  the  @  prefixed  file  of  file 
names  supported  by  parse_cmdline. 

A  Binary  Tree 

Listing  Three,  page  141,  is  bintree.c.  It 
contains  the  functions  to  build  and 
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search  a  binary  tree.  The  tree  in  ques¬ 
tion  is  used  for  what  we  call  “noise” 
words,  and  I’ll  explain  that  feature  soon, 
but  first  you  need  to  consider  the 
addtree  and  srchtree  functions  and  bi¬ 
nary  trees  in  general. 

A  binary  tree  is  a  search  data  struc¬ 
ture  that  facilitates  fast  searches  of  key 
values.  Each  entry  in  the  tree  contains 
the  value  to  be  searched  and  two 
pointers  —  a  pointer  to  the  entries  with 
values  that  collate  higher  than  the  cur¬ 
rent  one,  and  a  pointer  to  the  entries 
that  are  lower.  Even  with  a  large  num¬ 
ber  of  entries,  the  number  of  compares 
needed  to  find  a  value  is  reasonably 
small. 

The  addtree  function  adds  entries 
to  the  tree,  which  is  empty  at  first.  It 
allocates  memory  for  the  entry  from 
the  heap  and  then  calls  srchtree  to  see 
if  the  entry  is  already  there  or,  if  not, 
where  it  should  be  inserted. 

After  the  tree  is  built,  we  use  the 
srchtree  function  to  tell  us  if  a  value  is 
in  the  tree.  In  this  implementation  of 
the  binary  tree  there  are  no  other  data 
values  in  an  entry.  We  use  the  tree  to 
determine  the  presence  or  absence  of 
a  value,  nothing  more. 

Binary  trees  are  most  efficient  when 
the  entries  are  added  to  the  tree  in 
random  sequence.  If  you  were  to  build 
one  from  an  ordered  list  of  entries,  the 
tree  would  have  one  long  branch,  and 
searches  would  be  inefficient.  There 
are  tree  balancing  algorithms  for  bi¬ 
nary  trees,  but  we  do  not  need  one  for 
our  use  here  because  we  build  the  tree 
once,  and  our  original  order  is  random. 

Noise  Words 

We  use  the  binary  tree  for  a  list  of  noise 
words.  Noise  words  are  those  words 
that  are  so  common  that  we  can  as¬ 
sume  that  they  appear  in  every  file.  The 
word  “the”  is  a  typical  noise  word. 
Because  we  can  make  that  assumption, 
we  can  bypass  such  words  when  we 
build  our  index,  thus  saving  index 
space.  Likewise,  we  can  bypass  search¬ 
ing  the  index  for  such  words  during 
retrievals,  thus  saving  time. 

The  build_noisewords  function  in  bin- 
tree. c  builds  the  binary  tree  from  a  text 
file  that  contains  all  the  noise  words. 
Listing  Four,  page  142,  is  noise. 1st,  a 
small  file  of  noise  words  that  I  arbitrar¬ 
ily  selected.  You  might  want  to  review 
the  list  and  modify  it.  The  more  words 
you  can  put  into  the  noise  word  list, 
the  more  efficient  your  index  will  be. 

Building  the  Index 

Last  month  we  stubbed  the  text  search 
process  by  using  the  GREP  utility  pro¬ 
gram  to  process  our  queries.  This  month 
we  toss  that  method  aside  and  build 


an  inverted  index  into  our  data  base. 
To  build  the  index  we  extract  each 
word  from  each  file  in  the  data  base. 
From  the  word  we  use  a  hashing  algo¬ 
rithm  to  compute  a  random  address. 
The  random  address  points  into  SLOTS 
.NDX,  a  file  of  slots  with  one  slot  avail¬ 
able  for  each  possible  random  address. 
For  this  project  we  will  assume  a  maxi¬ 
mum  of  64K  words,  so  there  will  be 
64K  slots. 

Each  slot  contains  a  long  integer  with 
the  value  -1  if  the  slot  is  not  in  use.  If 
the  slot  is  in  use,  it  contains  a  character 
offset  into  a  text  index  file,  named 
TEXT.  NDX.  The  offset  points  to  the 
first  character  of  a  variable-length  rec¬ 
ord  in  TEXT.  NDX.  The  record  contains 
the  matching  text  word,  a  file  bit  map, 
and  a  record  chain  pointer. 

The  bit  map  in  the  TEXT.  NDX  rec¬ 
ord  contains  one  bit  for  each  text  file 
in  the  data  base.  If  a  bit  in  the  bit  map 
is  one,  the  word  appears  in  the  file  that 
is  associated  with  the  bit. 

The  file  named  “FILELIST.NDX”  con¬ 
tains  the  names  of  the  text  files  in  the 
data  base.  The  bit  offset  in  the  bit  map 
and  the  name  offset  in  FILELIST.NDX 
are  the  same. 

The  chain  pointer  in  a  TEXT.  NDX 
record  manages  those  words  that  hash 
to  common  slots.  When  a  word  hashes 
to  a  slot  that  a  previous  word  used, 
we  have  a  collision.  We  will  add  a  new 
record  to  the  end  of  TEXT.NDX  and 
write  its  character  offset  into  the  pointer 
in  the  record  pointed  to  by  the  slot 
entry.  This  builds  a  chain.  The  slot 
points  to  the  first  word  that  hashed  to 
the  slot.  The  first  word’s  record  points 
to  the  second,  and  so  on.  Subsequent 
collisions  lengthen  the  chain. 

The  code  that  builds  and  searches 
these  files  is  contained  in  Listing  Five, 
page  142,  index.c. 

Building  the  index  is  managed  by 
the  program  that  starts  with  Listing  Six, 
page  144,  bldindex.c.  It  calls  the  parse_ 
cmdline  function  to  extract  file  names 
from  the  specifications  on  the  com¬ 
mand  line  and  to  execute  the  index_file 
function  for  each  file  to  be  indexed. 
The  index_  file  function  opens  the  speci¬ 
fied  file  and  calls  the  extract_word func¬ 
tion  (explained  next)  until  there  are 
no  more  words  in  the  file  to  be  ex¬ 
tracted.  The  srchtree  function  tells  us 
if  the  word  is  a  noise  word  recorded 
in  the  binary  tree.  If  not,  we  add  the 
word  to  the  index  by  calling  the  addin- 
dex  function,  found  in  index.c. 

Extracting  Words 

To  build  an  index  (and  to  build  the 
noise  word  binary  tree)  we  need  a 
function  that  extracts  each  word  from 
a  text  file  and  normalizes  it  into  a  form 


suitable  for  indexing.  The  extract_word 
function  in  text.c,  Listing  Seven,  page 
144,  does  just  that.  You  pass  it  the  FILE 
pointer  of  an  open  file  and  a  character 
pointer  where  it  will  copy  the  next 
word,  and  it  does  the  rest.  The  normali¬ 
zation  process  consists  of  skipping  char¬ 
acters  that  are  not  considered  to  be 
text  and  then  selecting  all  text  charac¬ 
ters  up  to  the  next  nontext  character. 
For  my  purposes,  I  select  character 
groups  that  include  alphabetic  charac¬ 
ters,  digits,  the  underscore  (_),  the 
plus  (+)  sign,  and  the  pound  (#)  sign. 
This  allows  me  to  index  text  words, 
references  to  C++,  function  names,  and 
preprocessor  directives.  The  extract_ 
word  function  converts  alphabetic  char¬ 
acters  to  lowercase.  Other  applications 
will  have  different  requirements,  so  the 
is-TEXT macro  in  text.c  allows  you  to 
define  your  own  select  criteria. 

The  Hashing  Algorithm 

Hashing  is  when  you  compute  a  ran¬ 
dom  number  from  a  key  argument. 
You  can  then  use  the  number  as  a 
random  address  into  a  file  where  the 
information  related  to  the  argument  ex¬ 
ists.  With  hashing  you  start  with  the 
key,  compute  the  address,  and  use  the 
address  to  find  the  record,  all  in  the 
blink  of  an  eye.  Or  so  it  would  seem. 
In  practice  there  is  a  bit  more  to  it. 

We  will  hash  a  random  number  from 
each  of  the  words  in  our  text  files  and 
later  from  the  words  we  use  as  argu¬ 
ments  in  our  queries.  The  algorithm  I 
chose  is  a  loose  adaptation  of  the  one 
that  appeared  in  Steve  Heller’s  “Exten¬ 
sible  Hashing”  article  in  the  November 
1989  issue  of  DDJ.  It  adds  the  seven-bit 
ASCII  value  of  each  character  in  the 
word  to  the  initially  zero  hash  total  and 
shifts  the  total  seven  bits  to  the  left. 
This  add-shift  loop  continues  for  each 
character  in  the  word. 

There  are  as  many  different  hashing 
algorithms  as  there  are  data  formats  to 
be  hashed.  The  idea  is  to  compute  a 
random  number  that  is  evenly  distrib¬ 
uted  across  a  defined  range  of  values. 
If  you  can  have  100,000  inventory  re¬ 
cords  in  a  data  base,  the  algorithm  must 
compute  from  the  inventory  control 
key  a  random  number  between  1  and 
100,000.  A  common  technique  is  to 
reduce  the  key  to  a  numerical  value 
and  divide  that  value  by  the  prime  num¬ 
ber  closest  to  the  range.  The  remainder 
of  that  division  is  used  as  the  random 
number. 

In  our  approach  we  have  decided 
that  the  range  goes  to  64K.  Therefore, 
the  16-bit  integer  that  we  compute  from 
a  text  string  should  suffice  as  a  random 
number.  Further  reduction  should  not 
be  necessary.  Our  64K  limit  approxi- 
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(continued  from  page  124) 
mates  the  number  of  different  words 
we  can  expect  to  find  in  a  text  data 
base.  Most  works  of  prose  will  have  far 
fewer  than  that  number  of  unique 
words.  Even  if  we  build  an  index  for 
some  tome  that  exceeds  that  number, 
then  our  collision  strategy  ensures  that 
every  word  has  a  place  in  the  index. 

The  compute_hash  function  in  in- 
dex.c  is  our  hashing  algorithm. 

TEXTSRCH  Retrievals 

We  established  our  query  language  and 
interpreter  in  earlier  installments.  Now 
that  we  can  build  real  indexes,  we  need 
to  replace  the  stubs  from  last  month 
with  a  real  search  process.  Listing  Eight, 
page  144,  is  search. c  and  it  replaces 
last  month’s  search.c  stub  program.  The 
real  thing  is  simpler  than  the  stub  be¬ 
cause  most  of  the  work  is  now  done 
in  index. c.  The  search  function  calls 
srchtree  to  see  if  the  word  is  in  the 
noise  word  list.  If  so,  the  search  func¬ 
tion  returns  a  bit  map  with  all  bits  set 
to  one  because  noise  words  are  as¬ 
sumed  to  exist  in  all  text  files  in  the 
data  base.  If  the  word  is  not  a  noise 
word,  the  search  function  calls  search_ 
index  in  index. c  to  derive  the  bit  map 
that  says  which  files  in  the  data  base 
contain  the  word. 


The  search_index  function  calls  com- 
putejoash  to  develop  the  random  ad¬ 
dress  of  the  word’s  entry  in  SLOT.NDX. 
That  entry  contains  the  character  offset 
to  the  first  word  that  uses  that  slot.  We 
read  the  offset  and  seek  to  that  record 
location  in  TEXT.NDX.  If  the  word  in 
that  record  is  the  same  as  the  one  we 
are  looking  for,  we  have  a  hit.  If  not, 
and  there  are  no  further  records  chained 
to  the  slot,  we  have  a  miss.  We  navi¬ 
gate  the  chain  if  it  exists  and  compare 
each  word  in  it  to  the  one  we  are 
searching  for.  If  we  get  a  hit,  the  bit 
map  associated  with  the  matching  rec¬ 
ord  is  the  one  returned.  Otherwise  an 
all-zero  bit  map  is  returned. 

The  search  process  just  described  is 
for  one  word  only.  The  expression  in¬ 
terpreter  from  last  month  combines  the 
searches  for  all  the  words  in  the  ex¬ 
pression  with  the  Boolean  operators 
and  develops  one  bit  map  that  repre¬ 
sents  the  result  of  the  full  search. 

The  search.c  file  also  contains  the 
processjresult  function,  which  is  no 
smarter  than  the  one  we  stubbed  last 
month.  All  it  does  is  display  on  the 
console  the  name  of  the  files  that  match 
the  search  criteria.  What  you  will  do 
with  that  list  is  up  to  you.  See  the 
discussion  on  Possible  Enhancements 
for  some  thoughts  on  the  matter. 


Running  TEXTSRCH 

To  build  an  index,  get  all  your  text  files 
together  and  figure  out  how  you  are 
going  to  specify  them  on  the  command¬ 
line.  If  they  are  scattered  throughout 
your  subdirectories,  you  might  want 
to  make  a  list  of  them  in  a  file.  Use  a 
text  editor  to  make  the  file  and  put 
each  file  name  on  a  separate  line.  These 
are  the  different  commands  for  build¬ 
ing  an  index: 

bldindex  *.txt 

bldindex  textfile.001  textfile.002 

textfile.003 

bldindex  @files.lst 

You  can  mix  these  formats  like  this: 

bldindex  *.txt  textfile.001  @files.lst 

The  file  specifications  can  have  paths. 

If  the  files  named  SLOTS.NDX,  TEXT 
.NDX,  and  FILELIST.NDX  already  exist, 
you  will  be  adding  to  an  existing  in¬ 
dex.  Try  not  to  add  files  that  you  al¬ 
ready  indexed  because  this  practice  re¬ 
sults  in  unnecessary  redundancy  in  your 
index  files.  If  the  files  do  not  exist,  you 
are  building  a  new  index. 

Building  an  index  takes  a  long  time, 
so  you  might  want  to  do  it  in  small 
increments,  a  few  files  at  a  time.  A 


126 


Dr.  Dobb’s  Journal,  February  1990 

177 


power  failure  could  make  you  start  all 
over.  The  text  files  need  to  be  accessi¬ 
ble  during  the  build  phase,  but  can  be 
elsewhere  during  retrievals.  The  retrieval 
process  only  identifies  the  file  specifi¬ 
cations  as  they  existed  when  the  index 
was  built.  Retrievals  do  not  involve  the 
text  files  themselves. 

To  perform  a  retrieval  run  the  textsrch 
program  from  where  the  three  .NDX 
files  can  be  read.  Enter  query  expres¬ 
sions  as  you  did  last  month,  and  review 
the  file  lists  that  result.  A  null  query 
expression  terminates  the  program. 

Possible  Enhancements 

TEXTSRCH  has  a  lot  of  power  and  it 
has  a  lot  of  potential.  As  published 
here,  it  is  a  subset  of  a  more  powerful 
text  processing  system  that  I  developed 
for  engineering  documentation  appli¬ 
cations.  I  use  the  version  you  see  here 
with  no  enhancements  for  personal  use, 
but  there  are  several  extensions  that  you 
might  consider.  Here  are  some  of  them. 

Phrase  Searches  —  TEXTSRCH  retriev¬ 
als  are  based  on  word  searches  because 
the  index  is  built  from  discrete  words. 
You  can  approximate  a  phrase  search 
by  combining  all  the  words  in  a  phrase 
into  a  query  expression  with  the  AND 
Boolean  operator.  This  retrieval  would 
deliver  the  names  of  the  files  that  con¬ 
tain  all  the  words  in  the  phrase,  but  it 
would  not  tell  you  if  the  phrase  itself 
was  in  any,  all,  or  none  of  the  files.  You 
could  search  each  file  for  the  specific 
phrase  itself  by  using  Boyer-Moore  or 
a  similar  text-matching  algorithm.  This 
approach  would  require  modification 
of  the  expression  input  function  to  rec¬ 
ognize  the  difference  between  phrases 
and  individual  words.  The processjresult 
function  must  be  extended  to  do  the 
follow-up  search  of  the  text  files  them¬ 
selves. 

Wild  Card  Searches  —  TEXTSRCH 
searches  on  a  simple  case-insensitive 
word  pattern.  You  could  add  the  “?” 
wild  card  by  changing  the  search  func¬ 
tion  in  search,  c  to  perform  successive 
searches  using  every  possible  charac¬ 
ter  where  the  wild  card  appeared. 

Integrate  with  a  Word  Processor 

The  industrial  system  from  which 
TEXTSRCH  derives  is  integrated  with 
a  word  processor.  When  the  file  list  is 
presented  to  the  user,  he  or  she  selects 
one,  and  the  program  fires  up  the  word 
processor  telling  it  to  load  the  selected 
file  and  position  itself  to  the  first  occur¬ 
rence  of  the  matching  word  or  phrase. 
This  implementation  binds  the  two  ap¬ 
plications  together  and  is  beyond  the 
scope  of  this  column. 


What  Good  Is  It? 

How  might  you  use  TEXTSRCH?  I  spend 
a  lot  of  time  reading  and  writing  elec¬ 
tronic  mail  and  on-line  service  forum 
conversations.  Sometimes  I  need  to  go 
back  and  find  a  message  that  men¬ 
tioned  something  I  want  to  recall.  You 
know  how  it  goes.  Someone  makes  a 
comment  about  something  that  barely 
catches  your  attention.  A  few  months 
later  you  are  working  on  a  new  project 
and  that  comment  would  be  helpful  if 
only  you  could  remember  who  made 
it  and  what  they  said.  With  TEXTSRCH 
indexes  into  my  old  mail  I  can  usually 
find  the  messages  that  pertain  to  the 
subject  in  question. 

I  keep  all  my  columns,  articles,  and 
book  manuscripts  stored  away  in  TEXT¬ 
SRCH  data  bases.  That’s  right,  I  can’t 
always  remember  what  I  wrote,  when 
I  wrote  it,  or  where,  and  TEXTSRCH 
helps  my  failing  memory  (always  the 
second  thing  to  go). 

I  do  another  indexing  trick  with 
TEXTSRCH.  I  build  dummy  manuscripts 
that  simulate  the  dozens  of  articles, 
manuals,  and  books  I  read  every  month. 
The  dummy  manuscripts  contain  noth¬ 
ing  more  than  key  words  from  the  arti¬ 
cles  and  books.  The  subsequent  TEXT¬ 
SRCH  indexes  help  me  find  the  hard 
copies  where  the  material  appears.  Some¬ 
day  when  books  and  articles  are  avail¬ 
able  in  machine-readable  media,  or 
when  I  have  a  reliable  OCR  scanner,  I’ll 
be  able  to  build  the  indexes  directly  and 
bypass  the  dummy  manuscript  process. 

There  is  one  other  use  that  will  be 
of  interest  to  C  programmers.  If  you 
put  only  the  C  keywords  ( int,  long, 
typedef  and  so  on)  into  the  noise  word 
list  and  build  an  index  from  the  source 
code  for  a  huge  project,  you  have  in 
TEXTSRCH  the  beginnings  of  a  handy 
cross  reference  of  the  functions  and 
variables.  It  isn’t  worth  the  trouble  if 
you  are  developing  a  new  system,  but 
if  you  have  inherited  one  of  those  be¬ 
hemoth  undocumented  applications  to 
maintain,  TEXTSRCH  might  save  you 
a  lot  of  GREP  time. 

Book  Review 

Programming  in  C++  by  Stephen  C. 
Dewhurst  and  Kathy  T.  Stark.  This  book 
is  a  must  for  anyone  who  embarks  on 
an  intensive  study  of  C++.  It  would 
help  if  you  already  had  an  exposure 
to  C++,  and  knowledge  of  C  is  a  pre¬ 
requisite.  I  think  I  would  have  found 
this  book  a  bit  overwhelming  a  few 
months  ago  before  I  began  to  study 
C++.  When  read  from  the  perspective 
of  prior  knowledge,  however,  this  book 
is  a  gem.  My  one  criticism  is  that  it 
shares  a  characteristic  found  in  most 
C++  and  object-oriented  literature.  It 


uses  fruit  for  examples.  If  I  have  to 
stomp  through  one  more  orchard  of 
apple  and  orange  objects,  I  fear  I  may 
be  felled  by  the  dreaded  canker.  To 
their  credit,  D&S  don’t  dwell  all  that 
much  on  the  ubiquitous  citrus  hierar¬ 
chies,  and  other  than  for  that  one  small 
lapse,  their  book  is  very  good.  To  my 
surprise  I  found  that  the  book  has  clear 
and  concise  explanations  of  procedural 
programming,  top-down  design,  and 
structured  programming,  not  OOP  sub¬ 
jects  at  all.  Most  OOP  books  simply 
assume  that  you  already  know  about 
these  things.  Well,  you  should,  but  if 
you  need  brief  explanations  of  them 
written  in  a  style  that  real  people  can 
understand,  this  book  does  the  job. 

And,  bless  them,  D&S  do  not  dwell 
on  object-oriented  programming  as  the 
be-all,  end-all  that  we  keep  hearing 
about.  No,  they  defer  any  detailed  men¬ 
tion  of  OOP  until  Chapter  6,  and  then 
spend  just  a  short  amount  of  space 
with  it.  Skip  that  chapter  and  you  might 
conclude  from  this  book  that  C++  is 
simply  an  improved,  extensible  C.  And 
that  conclusion  would  not  be  far  off 
the  mark.  Other  parts  of  the  book  dis¬ 
cuss  those  properties  of  C++  that  com¬ 
bine  to  make  it  embraceable  by  the 
OOP  ilk,  but  these  presentations  are 
not  OOP-thumping  paradigm  evangeli¬ 
zations  but  rather  mere  explanations 
of  the  features  of  the  paradigm  as  they 
are  implemented  in  C++. 

C  and  C++  will  converge.  Despite  the 
minor  differences  that  cause  incompati¬ 
bility  between  ANSI  C  and  C++,  a  com¬ 
mon  language  will  evolve  if  only  through 
usage.  C++  brings  too  many  improve¬ 
ments  to  C  for  that  not  to  happen. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  140.) 

Vote  for  your  favorite  feature/artiole. 

Circle  Reader  Service  No.  10. 
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( continued  from  page  117) 
most  beneficial  option  is  to  rearrange 
the  sequence  of  instructions  so  that  a 
useful  instruction,  which  does  not  de¬ 
pend  on  the  load  data,  is  placed  in  the 
load-delay  slot.  In  this  case  the  load 
instruction  takes  only  one  clock  and 
causes  no  disruption  to  the  pipeline. 
The  second  option,  if  no  suitable  in¬ 
struction  for  the  load-delay  slot  can  be 
found,  is  simply  to  order  the  instruc¬ 
tions  sequentially.  When  the  register 
operation  attempts  to  read  the  data  from 
the  register  being  loaded,  the  proces¬ 
sor  will  freeze  for  one  clock  and  then 
proceed.  The  i860  keeps  track  of  which 
register  has  a  load  pending  by  way  of 
a  scoreboard.  Although  most  loads  will 
be  cache  hits,  the  scoreboard  technique 
has  further  utility  in  the  case  of  a  cache 
miss.  Instructions  can  proceed  follow¬ 
ing  a  cache  miss  load  until  an  instruc¬ 
tion  specifies  the  pending  register.  Pro¬ 
grams  can  benefit  by  placing  the  load 
instructions  as  far  away  as  possible  from 
instructions  that  operate  on  the  data. 

The  store  instructions  write  data  from 
a  register  to  memory.  For  the  i860,  this 
can  result  in  a  write  to  the  cache  or  a 
write  to  main  memory.  In  both  cases, 
the  processor’s  pipeline  does  not  have 
to  wait  for  the  write  to  complete.  For 
cache  hits,  the  new  data  is  updated  in 
the  cache.  For  cache  misses,  the  data 
is  written  to  the  on-chip  write  buffers, 
and  the  bus  control  unit  carries  out  the 
memory  write. 

Addressing  Modes 

The  integer  load  and  store  instructions 
access  memory  with  one  addressing 
mode  that  emulates  several  common 
ones.  The  basic  load/store  instruction 
format  is  shown  in  Figure  4  where 
src2_reg  and  dest_regczx\  be  any  of  the 
32-integer  registers.  The  src2_reg  is  the 
base  address,  and  srcl,  the  offset,  is 
added  to  it.  For  store  instructions,  const 
is  a  1 6-bit  offset  constant  that  is  embed¬ 
ded  in  the  instruction.  Load  instruc¬ 
tions  also  allow  srcl  to  be  another  one 
of  the  registers. 

The  instruction  can  specify  data  of 


Figure  4:  Load/store  instruction  format 


8-,  16-,  and  32-bit  values.  For  8-  and 
1 6-bit  values  the  operation  occurs  with 
the  lower  bits  of  the  register.  The  .x 
designator  in  the  instruction  is  set  to 
.b,  .s,  and  ./,  according  to  the  data  size. 
Data  must  be  aligned  in  memory  to 
correspond  to  the  effective  address 
boundary  (that  is,  32-bit  values  on  32- 
bit  address  boundaries). 

The  integer  register  rO  always  con¬ 
tains  the  value  0.  This  aids  in  imple¬ 
menting  multiple  addressing  forms  with¬ 
out  different  instructions.  The  load  in¬ 
structions  in  Figure  5  show  direct  mode, 
register  indirect  mode,  based  mode, 
and  based  index  mode  addressing. 

Table  1  is  a  complete  list  of  the  i860 
core  instructions.  The  i860’s  RISC  core 
is  also  responsible  for  performing  the 
memory  operations  for  the  floating¬ 
point  registers.  This  allows  the  RISC 
core  to  keep  the  floating-point  execu¬ 
tion  units  fed  with  data,  as  the  proces¬ 
sor’s  architecture  allows  both  a  core 
and  a  floating-point  instruction  to  be 
executed  each  clock.  Floating-point  mem¬ 
ory  access  has  an  additional  address¬ 
ing  mode. 

Integer  Operations 

Once  data  has  been  loaded  into  the 
integer  registers,  any  of  the  integer  op¬ 
erations  can  be  performed.  These  reg¬ 
ister  operations  are  performed  in  one 
clock,  and  the  result  can  be  used  as  a 
source  in  the  instruction  that  immedi¬ 
ately  follows.  The  i860  includes  arith¬ 
metic,  shift,  and  logical  instructions  and 
uses  the  form  operation  srcl,  src2_reg, 
dest_reg.  The  three  operand-style  in¬ 
structions  allow  the  operation  to  spec¬ 
ify  two  source  registers  (or  a  source 
register  and  an  immediate  for  srcl )  and 
to  store  the  result  to  a  third  register 
without  destroying  any  of  the  source 
values.  This  saves  the  program  from 
copying  a  source  value  to  a  temporary 
register  before  the  operation. 

The  add  and  subtract  instructions  al¬ 
low  an  immediate  value  to  be  used  as 
the  subtractend  or  the  minuend.  For 
example,  r6  =  2  -r5  is  encoded  as  subs 
2,  r5,  r6  and  r6  =  r5  -  2  is  encoded  as 


Core  Unit 

Mnemonic  Description 

Load  and  Store  Instructions 

Id.x 

Load  integer 

st.x 

Store  integer 

fld.y 

F-P  load 

pfld.z 

Pipelined  F-P  load 

fst.y 

F-P  store 

pst.d 

Pixel  store 

Register  to  Register  Moves 

ixfr 

Transfer  integer  to 

F-P  register 

fxfr 

Transfer  F-P  to 
integer  register 

Integer  Arithmetic  Instructions 

addu 

Add  unsigned 

adds 

Add  signed 

subu 

Subtract  unsigned 

subs 

Subtract  signed 

Shift  Instructions 

shl 

Shift  left 

shr 

Shift  right 

shra 

Shirft  right  arithmetic 

shrd 

Shift  right  double 

Logical  Instructions 

and 

Logical  AND 

andh 

Logical  AND  high 

andnot 

Logical  AND  NOT 

andnoth 

Logical  AND  NOT  high 

or 

Logical  OR 

orh 

Logical  OR  high 

xor 

Logical  exclusive 

OR 

xorh 

Logical  exclusive 

OR  high 

Control-Transfer  Instructions 

trap 

Software  trap 

intovr 

Software  trap  on 
integer  overflow 

br 

Branch  direct 

bri 

Branch  indirect 

be 

Branch  on  CC 

bc.t 

Branch  on  CC  taken 

bnc 

Branch  on  not  CC 

bnc.t 

Branch  on  not  CC  taken 

bte 

Branch  if  equal 

btne 

Branch  if  not  equal 

bla 

Branch  on  LCC  and  add 

call 

Subroutine  call 

calli 

Indirect  subroutine  call 

System  Control  Instructions 

flush 

Cache  flush 

Id.c 

Load  from  control 
register 

st.c 

Store  to  control  register 

lock 

Begin  interlocked 
sequence 

unlock 

End  interlocked 
sequence 

Table  1:  i860  core  instructions 


Id.x  srcl  (src2  reg),  dest  reg 

;  dest_reg  <-  memory[src1  +  src2_reg] 

st.x  dest_reg,  const(src2_reg) 

;  memory  [const+src2_reg]  <-  rdest 

Id.l  8(r0),  r15 

;  rl  5  <-  memory[8] 

Id.l  0(r14),  r15 

;  rl  5  <-  memory[r14] 

Id.l  8(r14),  rl  5 

;  rl  5  <-  memory[8  +  rl  4] 

Id.l  r13(r14),  r15 

;  rl  5  <-  memoryjrl  3  +  rl  4] 

Figure  5:  Direct  mode,  Register  indirect  mode,  Based  mode ,  and  Based  index 
mode  addressing  load  examples 
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(continued  from  page  128) 
adds  -2,r5,r6. 

Both  signed  and  unsigned  versions 
of  each  instruction  are  available.  Add 
and  subtract  are  also  used  to  imple¬ 
ment  the  compare  function  by  specify¬ 
ing  rO  as  the  destination.  For  example 
subs  r4,  r5,  rO  will  set  the  condition 
code  (CC)  if  the  contents  of  r5  are 
greater  than  those  of  r4.  The  CC  is  used 
for  the  conditional  branch  instructions 
that  are  discussed  later. 

The  logical  instructions  include  the 
AND ,  ANDNOT,  OR,  and  XOR  opera¬ 
tions  and  can  be  used  to  implement  bit 
operations.  For  bit  operations  an  im¬ 
mediate  is  used  as  srcl  with  a  1  in  the 
bit  position  to  be  operated  on  and  ze¬ 
ros  in  the  other  bit  positions.  In  addi¬ 


tion  to  performing  the  operation,  the 
logical  instructions  set  the  CC  if  the 
result  is  zero. 

Because  an  instruction  has  only  32 
bits,  32-bit  constants  cannot  be  embed¬ 
ded  in  a  single  instruction.  Moving  a 
32-bit  value  into  a  register  uses  the 
special  high  version  of  the  logical  in¬ 
structions  that  is  indicated  by  the  b.  For 
example,  the  32-bit  hex  value 
9A9A5B5BH  is  moved  into  r5  by  first 
loading  the  lower  half  of  the  register 
and  then  using  the  orb  instruction  to 
modify  the  upper  half  of  the  register. 

or  Ox5B5B,  rO,  r5  ;  r5  <-  5B5BH 
orh  0x9A9A,  r5,  r5  ;  r5  <-  9A9A5B5BH 

The  final  class  of  integer  operations  is 
made  up  of  the  shift  instructions.  The 


i860  can  barrel  shift  up  to  31  bit  posi¬ 
tions  in  one  cycle.  The  number  of  bit 
positions  to  shift  is  specified  in  srcl. 
The  shift  right  instruction  also  loads 
the  srcl  into  a  special  field  in  a  control 
register.  This  field  is  used  by  the  dou¬ 
ble  shift  instruction  which  concatenates 
two  registers  and  shifts  them  into  a 
third  register.  A  rotate  operation  is  per¬ 
formed  by  designating  the  same  regis¬ 
ter  as  both  srcl  and  src2  for  the  double 
shift. 

Although  the  assembler  allows  you 
to  specify  a  move  instruction,  the  i860 
does  not  need  a  separate  move  op¬ 
code.  A  shift  instruction  is  used  to  im¬ 
plement  the  register-to-register  move 
as  it  does  not  affect  the  condition  code. 
The  assembler  will  allow  you  to  spec- 


Religious  Artifacts  and  Code  Museums 

Hal  Hardenbergh 


In  the  newer  generation  of  U.S.- 
made  micros,  there  is  not  a  single 
CISC  chip.  The  latest  x86  and  680x0 
chips  are  in  fact  code  museums,  not 
CISC  chips,  intended  to  support  their 
enormous  software  bases.  (The  ex¬ 
cellent  term  “code  museum”  was  ap¬ 
parently  coined  by  Gordon  Bell.)  The 
reason  they  have,  for  instance,  fewer 
registers  than  one  would  like  in  1990 
is  because  they  have  to  provide  bi¬ 
nary  compatibility  for  code  written 
for  the  8088  and  68000  back  in  1980. 
The  32532  is  a  code  museum  for  code 
developed  for  the  16032,  and  the 
Z80000  is  a  code  museum  for  Z8000 
code. 

The  chief  competitors  of  the  code 
museums,  we  are  led  to  believe,  are 
the  artifacts  of  a  new  religion  called 
RISC.  The  two  processors  (SPARC  and 
29000)  that  most  closely  follow  the 
RISC  religion  thereby  require  32  mul- 
tiply-step  instructions  to  perform  an 


Hardware  engineer  Hal  Hardenbergh 
follows  developments  in  microproces¬ 
sor  technology  closely.  He  also  ( but 
not  often  enough)  writes  about  his 
conclusions,  which  are  always  enter¬ 
taining,  frequently  outrageous,  and 
usually  right  on  target.  The  following 
essay  on  RISC,  CISC,  and  the  Intel 
i860  came  to  us  shortly  after  Hal  had 
a  chance  to  evaluate  the  i860. 


integer  multiply,  plus  up  to  eight  more 
clocks  for  a  trap  or  function  call.  Re¬ 
member,  nothing  else  can  happen  in 
those  40  clocks.  Some  programmers 
working  with  the  latest  “high  perfor¬ 
mance”  SPARC  unit,  the  330,  say  that 
it  is  a  Pig  when  doing  integer  arith¬ 
metic. 

Other  chips  usually  called  RISC  pro¬ 
cessors  do  not  in  fact  follow  the  RISC 
philosophy  with  respect  to  integer 
multiplies.  The  MIPS  chip  has  a  spe¬ 
cial  functional  unit  that  performs  the 
multiply  independently  (other  instruc¬ 
tions  can  proceed  during  this  multi¬ 
ply)  with  a  latency  of  eight  clocks. 
The  88000  uses  its  floating-point  unit 
to  perform  integer  multiplies;  again, 
instructions  can  proceed  in  parallel. 
By  not  following  the  RISC  philoso¬ 
phy,  MIPS  and  the  88000  gain  a  sig¬ 
nificant  performance  advantage. 

The  RISC  followers  would  have  you 
believe  that  they  alone  try  to  make 
instructions  run  in  the  fewest  clocks. 
Bull  puckey.  Worse,  RISC  zealots  brag 
about  their  super-efficient  load-store 
architectures.  Hah.  The  i486,  a  mere 
code  museum,  performs  push/pop  op¬ 
erations  2.5  times  faster  than  Sun’s 
latest  and  highest-performing  SPARC 
system  (the  330).  Why?  One  reason 
is  that  the  i486  uses  part  of  its  budget 
of  1.2  million  transistors  to  perform 
the  register  increment/decrement  in 


parallel.  This  violates  the  RISC  phi¬ 
losophy,  so  the  SPARC  and  other  RISC 
chips  don’t  do  it. 

In  other  words,  some  of  the  “RISC 
features”  are  not  exclusive  to  RISC, 
and  some  of  the  features  that  are  ex¬ 
clusive  to  RISC  degrade  performance. 

Are  the  i486  and  68040,  then,  the 
fastest  possible  chips?  No;  they’re  the 
fastest  code  museums  that  Intel  and 
Motorola  could  make.  Because  they 
have  a  huge  number  of  active  de¬ 
vices,  they  are  almost  as  fast  as  the 
conventional  32-bit  RISC  chips,  which 
have  the  significant  advantage  of  larger 
register  sets  and  an  instmction  set 
optimized  for  the  32-bit  world  rather 
than  a  16-  or  8-bit  world. 

The  simple  fact  is,  if  you  use  that 
1.2  million  transistor  budget  to  build 
a  device  that  does  not  have  to  sup¬ 
port  ancient  code,  you  can  build  a 
hell  of  a  fast  device.  Much  faster  than 
the  SPARC,  MIPS,  88000,  or  29000,  all 
of  which  have  comparatively  modest 
silicon  budgets.  Intel  has  proved  this 
point  with  the  i860.  The  i860  is  not  a 
religious  artifact  or  code  museum,  but 
a  very  fast  processor,  looking  some¬ 
times  like  a  RISC  chip,  sometimes  like 
a  CISC  chip,  and  sometimes  like  a 
DSP  chip. 

The  Intel  i860  routinely  performs 
single-precision  floating-point  math 
from  four  to  twelve  times  faster  than 
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ify  mov  r3,  r4  and  implement  it  as  shl 
rO,  r3,  r4. 

Branch  and  Call  Instructions 

Instructions  that  change  the  sequence 
of  program  execution  have  long  been 
the  nemesis  of  pipelined  machines.  For 
many  processors,  these  branch  instruc¬ 
tions  require  that  the  pipeline  be  flushed 
and  restarted  from  the  new  branch  tar¬ 
get  address.  Because  branches  happen 
frequently,  RISC  processors  use  a  de¬ 
layed  branch  instruction  where  the  in¬ 
struction  following  the  branch  is  exe¬ 
cuted  before  the  branch  takes  effect. 
This  allows  the  processor  to  continue 
the  execution  of  a  useful  instruction 
while  it  begins  fetching  the  new  in¬ 
struction  from  the  branch  target.  The 


branch  delay  slot  can  be  filled  with  a 
useful  instruction  from  the  block  of 
code  leading  up  to  the  branch;  other¬ 
wise  the  target  of  the  branch  instruc¬ 
tion  can  be  moved  to  the  delay  slot  and 
the  target  adjusted.  The  operation  of 
delayed  branches  causes  the  execution 
order  of  code  to  differ  from  the  assem¬ 
bly  language  sequence,  as  shown  in 
Figure  6. 

The  i860  includes  four  unconditional 
delayed  branches:  br,  bri,  call,  and  calli. 
The  br  (branch)  and  call  instructions 
allow  a  26-bit  offset  as  part  of  the  in¬ 
struction.  The  offset  is  in  units  of  in¬ 
structions,  not  in  bytes,  allowing  a  256- 
Mbyte  range.  The  bri  (branch  indirect) 
and  calli  (call  indirect)  instructions  use 
the  contents  of  a  register  as  the  target, 


thus  allowing  a  full  32-bit  address  speci¬ 
fication.  In  addition  to  changing  the 
instruction  flow,  the  call  instructions 
save  in  rl  the  address  of  the  second 
instruction  after  the  call  (the  one  di¬ 
rectly  after  the  call  is  the  delay  instruc¬ 
tion).  This  is  used  as  the  return  address 
for  the  subroutine  by  specifying  bri  rl. 

The  conditional  branches  that  rely 
on  the  CC  are  the  be  (branch  on  condi¬ 
tion)  and  the  bnc  (branch  on  not).  These 
include  both  delayed  and  non-delayed 
versions;  the  delayed  version  is  indi¬ 
cated  with  a  T.  At  compile  time,  the 
programmer  can  usually  predict  if  a 
conditional  branch  is  going  to  be  taken 
or  not  taken  more  frequently.  If  a  con¬ 
ditional  branch  instruction  is  more  likely 
to  be  taken,  such  as  at  the  bottom  of  a 


the  MIPS  or  the  88000,  even  though 
both  of  those  chips  are  capable  of 
initiating  a  single-precision  floating¬ 
point  operation  on  every  clock  cycle. 

How  can  this  be? 

How  to  Build  a  Fast  Chip 

The  answer  to  that  question  is  the 
real  issue  facing  the  next  generation 
of  microprocessors.  The  answer  is  con¬ 
currency.  To  run  fast,  you  want  a  hell 
of  a  lot  of  concurrency.  You  get  a 
hell  of  a  lot  of  concurrency  by  having 
a  huge  silicon  budget.  The  i860  has  a 
huge  silicon  budget.  The  i860  has  a 
hell  of  a  lot  of  concurrency. 

Why  are  the  MIPS  and  88000  chips 
limited  to  a  throughput  of  about  seven 
single-precision  MFLOPS  at  best,  even 
though  they  are  in  principle  capable 
of  issuing  instructions  at  a  25-MFLOP 
rate?  Simple.  On  those  clocks  where 
they  issue  a  load  or  store,  they  cannot 
issue  a  math  operation.  And  because, 
in  conformance  with  RISC  theory,  they 
don’t  have  an  autoincrement  address 
mode,  they  also  don’t  issue  a  math 
operation  when  incrementing  the  ad¬ 
dress  pointer  or  index.  (There  are 
other  issues:  Slower  clock,  32-bit  ex¬ 
ternal  data  bus,  no  on-board  data 
cache.  But  the  biggie  is  the  lack  of 
concurrency.) 

The  i860,  which  is  sampling  now 
at  33  MHz  and  will  run  at  40  MHz  in 
its  production  version,  can  perform 
all  of  the  following  in  a  single  clock: 

1.  Execute  a  32-bit  floating-point 
multiply 

2.  Execute  a  32-bit  floating-point 
add  or  subtract 

3a.  Initiate  a  64-bit  floating-point 
register  load  or  store  that  will 
take  two  clocks,  or 


3b.  Initiate  a  128-bit  floating-point 
load  or  store,  taking  four  clocks 
to  finish 

4.  Increment,  by  an  arbitrary 
amount,  the  address  pointer  that 
was  just  used  for  the  load  or 
store  operation  in  (3a)  or  (3b) 

As  a  result  of  the  above,  the  i860  can 
do  21 -bit  convolutions  (a  common 
image-processing  task)  at  78  MFLOPS 
throughput.  Not  six  or  seven.  Seventy- 
eight.  Performing  back  propagations, 
FFTs,  or  matrix  inversions,  it  will  run 
at  about  36  MFLOPS. 

The  fastest  SPARC  workstation  that 
Sun  is  now  shipping,  the  model  330, 
takes  about  40  clocks  to  perform  an 
integer  multiply.  The  model  330  runs 
at  25  MHz,  so  that’s  1.6  microsec¬ 
onds.  During  those  40  clocks,  noth¬ 
ing  else  goes  on  in  the  integer  execu¬ 
tion  unit.  In  that  same  1.6  microsec¬ 
onds,  the  i860  can: 

•  perform  64  32-bit  multiplies 

•  perform  64  32-bit  floating-point  adds 

•  do  256  bytes  of  memory  I/O 

•  and  perform  all  autoincrement  ad¬ 
dressing  to  support  that  memory  I/O 

And  get  this:  If  you  use  128-bit  load/ 
stores  for  your  I/O,  the  integer  unit 
has  48  clocks  left  over  to  do  some¬ 
thing  else  while  all  this  is  going  on. 
All  this  while  the  SPARC  is  executing 
one  integer  instruction.  Isn’t  RISC  won¬ 
derful? 

True,  the  i860  is  only  good  for 
floating-point  number-crunching  and 
(mostly)  3-D  graphics  acceleration. 
But  Intel  is  coming  out  with  a  new 
chip,  the  superscalar  i960.  This  is  a 
completely  new  design,  with  a  64-bit 
external  data  bus,  some  elaborate  sched¬ 


ulers,  and  three  on-board  integer- 
only  execution  units.  This  gives  the 
new  i960  a  peak  performance  of  66 
MIPS  at  a  33  MHz  clock  rate.  No, 
those  two  numbers  are  not  reversed; 
the  i960  will  perform  two  instructions 
per  clock.  The  third  execution  unit  is 
provided  so  that  the  unit  can  catch 
up  if  the  scheduler  postpones  an  instruc¬ 
tion  because  of  a  resource  (register) 
conflict. 

You’ll  be  able  to  purchase  a  work¬ 
station  that  uses  the  i960  for  the  main 
CPU  and  an  i860  for  floating-point 
and  graphics  for  under  $15K. 

Intel  paid  for  the  performance  of 
the  i860  in  cash.  With  its  R&D  budget 
of  86.6  million  dollars  per  quarter, 
Intel  is  spending  $780  million  dollars 
per  generation  of  microprocessors  out 
of  its  own  pocket.  Intel  has  also  re¬ 
ceived  substantial  funds  ($100  mil¬ 
lion  or  so)  from  Siemens  to  develop 
the  original  i960  chip.  That’s  why  In¬ 
tel  was  able  to  introduce  two  micro¬ 
processor  designs,  each  with  about 
1.2  million  active  transistors,  in  a  two- 
month  period.  And  the  new  super¬ 
scalar  i960  will  be  introduced  later 
this  year.  Where  did  the  money  come 
from?  Why,  from  profits  generated  by 
the  386  family  of  chips,  of  course. 


Hal  called  after  writing  to  us  about 
the  i860  to  tell  us  about  the  processor 
recently  announce  by  Sharp.  What 
he  had  to  say  was  preliminary,  but 
sounded  interesting:  800,000  transis¬ 
tors,  4K  internal  scratchpad  RAM, 
and  ...  a  throughput  of  400  single¬ 
precision  MFLOPS??  That’s  just  ten 
times  the  throughput  Hal  says  you 
can  expect  from  an  i860.  —  Eds. 


Dr.  Dobb’s  Journal,  February  1990 


131 

181 


RISC 


loop,  the  delayed  form  should  be  used. 
For  cases  in  which  the  branch  is  likely 
not  to  be  taken,  the  non-delayed  ver¬ 
sion  allows  more  efficient  coding.  Dur¬ 
ing  execution,  when  the  delay  version 
is  taken  or  the  non-delay  version  is  not 
taken,  no  disruptions  are  caused  in  the 
pipeline.  A  one  clock  penalty  is  incurred 
when  the  code  guesses  incorrectly. 

By  choosing  an  integer  or  a  logical 
operation  followed  by  a  fee  or  a  bnc 
instruction,  all  of  the  needed  branch 


/*  convert  days  &  hours  into  hours  *7 

/*  C  code  *7 

int  convert (days,  hours) 

register  unsigned  int  days,  hours; 

{ 

unsigned  int  total; 
total  =  days  *  24  +  hours; 


return  (total); 

) 

/*  Compiler  generated  asm  code  */ 


_convert : 

.  file 

"hours.c" 

shl 

2,rl6,r28 

subs 

r28, rl6, rl6 

shl 

3, rl6, rl6 

bri 

rl 

adds 

rl7, rl6, rl6 

//_total 

rl6 

local 

//_days 

rl6 

local 

//"hours 

rl7 

local 

Example  1:  This  conversion  routine 
converts  days  and  hours  into  total 
hours 


main() 

(  int 

sum,  summer  ( ) ,  n, a [] ; 

* 

* 

sum= 

summer (a,  8) ; 

* 

* 

int  summer  (a,n) 

int  *a,n; 

t 

int  i,sum=0; 

for  (i  - 

n-l;  i  >=0  ;  i— ) 

sum 

=  sum  +  a [i] ; 

return (sum) ; 

.  file 

"sum.c" 

* 

mov 

r7,rl6 

call 

summer 

or 

8, rO, rl7 

mov 

rl6, rl7 

* 

* 

summer: 

mov 

r0,rl8 

adds 

-1, rl7, rl7 

shl 

2,rl7,r28 

adds 

rl6, r28, r28 

adds 

1,  rl7, rl7 

adds 

-1, rO, r20 

bla 

r20, rl7, .L65 

mov 

r28,rl6 

.L65: 

bla 

r20, rl7, .L43 

nop 

br 

.L42 

nop 

.  L43: 

Id.  1 

0 (rl6) , rl9 

adds 

-4, rl6, r!6 

bla 

r20, rl7, .L43 

adds 

rl9,rl8,rl8 

.  L42 : 

bri 

rl 

mov 

rl8, rl6 

//  a 

rl6 

local 

//  n 

rl7 

local 

Example  2:  A  subroutine  called  sum. 
ints  that  adds  a  series  of  integers 


idioms  can  be  implemented.  There  is 
also  a  non-delay  branch  instruction  that 
branches  on  a  compare-for-equality  op¬ 
eration.  The  fete  (branch  if  equal)  and 
btne  (branch  if  not  equal)  operations 
do  register-to-register  comparisons  (or 
a  register  compare  with  a  5-bit  im¬ 
mediate).  Either  of  these  branches  can 
replace  two  instructions  where  appro¬ 
priate,  but  at  the  expense  of  the  offset 
being  reduced  to  16  bits. 

Finally,  there  is  a  loop  control  in¬ 
struction,  called  bla,  that  uses  its  own 
condition  code  called  Loop-Condition- 
Code  (LCC).  The  bla  instruction  is  a 
delayed  branch  that  performs  a  condi¬ 
tional  branch-on-LCC,  an  add,  and  up¬ 
dates  the  LCC  in  the  same  instruction. 

Programming  Examples 

Now  that  we  have  looked  at  the  basic 
instructions  and  instruction  sequences, 
we  can  look  at  some  simple  yet  reveal¬ 
ing  examples.  Example  1  lists  a  conver¬ 
sion  routine  that  converts  days  and 
hours  into  total  hours. 

The  first  optimization  is  that  the  pa¬ 
rameters  “days”  and  “hours”  are  passed 
in  the  registers  rl6  and  rl  7  instead  of 
being  passed  on  the  stack.  This  avoids 
having  a  pointer  frame,  or  any  entry 
or  exit  code.  Second,  the  multiply  by 
24  is  implemented  as  two  shifts  and  a 
subtract.  The  first  shift  left  by  2  imple¬ 
ments  a  multiply  by  4  and  the  subtract 
reduces  it  to  a  multiply  by  3.  The  sec¬ 
ond  shift  left  by  3  implements  a  multi¬ 
ply  by  8  giving  the  total  multiply  of  24 
(three  times  eight).  Note  that  the  first 
shift  left  takes  advantage  of  the  three 
operand  instruction  format,  not  destroy¬ 
ing  the  original  value  in  rl6.  This  elimi¬ 
nates  copying  rl6  into  a  temporary 
register  at  the  start  of  the  routine,  and 
allows  the  original  contents  of  rl6  to 
be  used  as  the  source  register  in  the 
subtract  instruction  that  immediately  fol¬ 
lows.  The  final  optimization  is  the  add 


ASSEMBLY  LANGUAGE  SEQUENCE 

instruction  1 

lnstruction2 

Instructions 

Delayed_branch  label  1 

lnstruction4 

Instructions 

label  1:  Instructions 

Instruction? 

EXECUTION  SEQUENCE 
Instruction  1 
lnstruction2 
Instructions 
lnstruction4 
Instructions 
Instruction? 

Figure  6:  The  operation  of  delayed 
branches  causes  the  execution  order 
to  differ  from  the  assembly  language 
sequence 


being  performed  in  the  branch-delay 
slot.  The  fen  rl  returns  control  to  the 
calling  routine  with  the  result  of  the 
call  returned  in  rl6. 

A  subroutine  called  sumjints  that 
adds  a  series  of  integers  is  shown  in 
Example  2.  Because  the  integers  to  be 
summed  are  likely  too  numerous  to  fit 
in  the  registers,  the  routine  is  called 
with  a  pointer  to  the  integers  in  rl6. 
The  other  parameter,  passed  in  rl  7,  is 
the  number  of  integers  in  the  series. 
The  example  shows  a  loop  where  the 
data  must  be  retrieved  from  memory. 

The  setup  prior  to  the  loop  initializes 
LCC  (with  the  bla  instruction),  checks 
that  at  least  one  loop  iteration  should 
occur,  and  moves  zero  into  the  sum 
register  rl8.  Although  the  setup  por¬ 
tion  of  the  program  may  be  slightly  less 
than  ideal,  the  routine’s  performance 
is  clearly  dominated  by  the  loop  por¬ 
tion.  The  loop  loads  the  data  from  mem¬ 
ory,  decrements  the  pointer  to  the  next 
integer,  performs  the  loop  control,  and 
accumulates  the  sum  of  the  integers. 
These  four  instructions  are  arranged 
to  avoid  any  freeze  conditions.  The 
data  from  the  load  is  not  operated  on 
until  the  branch-delay  slot.  The  use  of 
bla  replaces  the  two  or  three  separate 
instructions  that  would  be  required  for 
this  loop. 

Although  the  compiler  has  done  a 
good  job  of  arranging  the  inner  loop 
as  a  four-clock  loop,  it  is  not  ideal.  It 
is  possible  to  use  a  loop  index  directly 
as  the  memory  pointer  and  reduce  it 
to  a  three-clock  loop.  An  even  more 
aggressive  approach  would  be  to  un¬ 
roll  the  loop  to  perform  more  loads 
and  adds  for  each  pass  through  the 
loop.  This  amortizes  the  loop  over¬ 
head  over  a  greater  number  of  useful 
instructions.  For  the  i860,  a  feature  not 
discussed  in  this  article,  dual-instruc¬ 
tion  mode,  allows  the  load  and  loop 
control  to  be  overlapped  with  the  sum¬ 
mation  performed  in  the  floating-point 
registers. 

Summary 

In  this  article  we  have  seen  how  RISC 
instruction  sets  are  designed  for  fast, 
pipelined  execution.  We  have  seen  how 
simple  RISC  instructions  operate  and 
how  these  instructions  can  be  se¬ 
quenced  to  perform  various  functions 
and  reduce  freeze  conditions.  Although 
most  programs  will  be  written  in  high- 
level  languages,  there  is  always  the 
opportunity  to  check  the  compiler’s  out¬ 
put  for  efficiency,  or  to  code  the  most 
time-critical  routines  by  hand. 
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The  Day  the  Earth 
Wouldn’t  Sit  Still 


irst,  you  freeze. 

The  little  jitters  happen  out  here 
now  and  then.  They  only  last  a 
second,  and  most  of  us  just  stop 
where  we  are  and  wait.  At  5:04  I  was 
outside  on  the  new  redwood  front  steps 
with  a  tube  of  Plastic  Wood  in  my 
hands,  filling  in  a  syntax  error  I  had 
made  with  the  router. 

But  this  jitter  didn’t  pass.  Out  of  the 
earth  came  a  noise  unlike  anything  in 
creation,  a  thing  so  deep  and  so  perva¬ 
sive  that  it  bypassed  the  ears  and  went 
straight  to  the  guts.  What  was  a  jitter 
became  a  violent,  unending  spasm,  the 
earth  boiling  amidst  the  sound  of  two 
continents  dragged  one  over  the  other. 
I  dropped  the  plastic  wood  and  held 
onto  the  stairs.  From  inside  the  house, 
I  heard  things  begin  to  break:  First  glass, 
then  the  crockery  of  our  water  dis¬ 
penser,  then  something  large  and  heavy 
collapsing  in  the  garage.  Finally,  with 
the  horror  in  full  sway,  the  agony  of 
my  house  joined  the  agony  of  the  earth, 
and  it  went  on,  and  on,  and  on  . .  . 

Twenty  seconds  passed,  and  the 
world  grew  quiet  again. 

The  Machine  Stops 

Very  quiet.  Scotts  Valley  was  dead.  The 
silence  was  absolute,  made  sharper  by 
the  contrast  with  the  all-consuming  ca¬ 
cophony  that  had  come  before  it.  No 
birds,  no  cars  on  Highway  17,  no  tum¬ 
bling  burr  from  the  sawmill,  no  susurrus 
from  Seagate’s  many  nearby  buildings. 

My  three  dogs  stood  like  statues  on 
the  asphalt;  I  dove  for  them  just  as 
panic  broke  in  them,  and  caught  Mr. 
Byte  and  Chewy  in  time  to  throw  them 
into  the  back  of  the  Magic  Van.  Max, 
on  the  other  hand,  was  already  far  down 
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the  driveway  at  full  speed  and  was 
gone  for  many  hours. 

My  water  heater  had  broken  its  pipes, 
and  the  laundry  room  was  filling  with 
water. 

In  the  east,  a  plume  of  black  smoke 
was  roiling  into  the  sky.  Somewhere 
there  were  sirens.  I  heard  a  woman 
yell  in  the  distance.  Another  answered 


her.  By  5:06  the  silence  had  ended,  and 
the  long  night  had  begun. 

Being  four  miles  from  the  epicenter 
of  a  Richter  7.1  temblor  can  teach  you 
a  few  things.  Technology  is  fragile.  In 
an  instant  the  power  lines  and  phone 
lines  were  swept  away.  The  town  with 
more  computers  than  people  (and  more 
disk  drives  than  computers)  simply 
stopped.  No  TV,  no  cable,  no  satellite 
downlinks.  Ever  the  prepared  radio  ama¬ 
teur,  I  hooked  a  gel  cell  to  an  FM  radio 
and  tuned  the  dials.  The  local  stations 
were  not  there.  What  did  I  think  they 
ran  on,  wood  stoves?  A  distant  station 
crackled  to  me  that  unconfirmed  re¬ 
ports  of  a  violent  earthquake  in  San 
Francisco  were  being  investigated. 

Right. 

Over  the  days  we  learned  the  extent 
of  the  damage:  Borland  International’s 
main  building  was  deemed  too  danger¬ 
ous  to  occupy.  Much  of  Seagate’s  pre¬ 
cision  equipment  was  rendered  use¬ 
less.  Hundreds  of  houses  were  utterly 
destroyed,  including  the  home  of  Jack 
Davis,  CEO  of  Metagraphics,  maker  of 
the  MetaWindow  graphics  library.  Thou¬ 
sands  more  were  severely  damaged.  Down¬ 
town  Santa  Cruz  was  nearly  destroyed. 

A  New  Paradigm 

Over  the  week  we  spent  cleaning  up, 
I  did  a  lot  of  thinking.  Our  urban  para¬ 
digm  is  very  much  one  of  the  main¬ 
frame  and  the  terminal.  We  are  termi¬ 
nals  connected  to  the  power  company 
mainframe,  the  telephone  company  main¬ 
frame,  the  natural  gas  line  mainframe. 
It  doesn’t  take  much  to  make  the  main¬ 
frame  go  down,  and  when  it  goes  down, 
the  terminals  go  dead. 

We  need  to  stop  being  terminals  and 
start  being  PCs.  We  need  to  plate  every 
roof  with  amorphous  silicon  pho¬ 
tovoltaic  panels,  and  perfectly  sealed 
battery  technology  to  the  point  where 
a  water  heater-sized  unit  can  operate 
the  household  for  several  days  on  a 
full  charge  and  not  cost  as  much  as  the 
house  to  buy.  Homes  should  be  power 
exporters  during  the  day,  charging  their 
own  cells  to  capacity  and  then  feeding 
surplus  energy  onto  a  peer-to-peer 
power  grid  to  mn  smaller  installations 
without  their  own  cells.  If  the  grid  goes 
down,  the  homes  themselves  remain 


livable  refuges. 

Similarly,  every  home  should  have  a 
12-inch  precision  parabolic  dish  antenna 
on  the  roof,  aimed  at  a  geosynchronous 
satellite  with  the  bandwidth  to  handle 
an  entire  state  at  one  gulp.  Communi¬ 
cation  with  the  outside  world  should 
not  hang  from  a  fragile  copper  wire. 

Home  heating  is  a  problem.  Perhaps 
the  answer  is  to  break  down  water  into 
hydrogen  with  solar  current  during  the 
day  and  then  burn  the  hydrogen  for 
heat  at  night.  We  need  to  set  the  meth¬ 
ane  and  propane  and  yes,  my  fellow 
Sixties  radicals,  even  the  “clean”  wood 
stoves  aside.  Burning  carbon  —  any 
carbon  —  feeds  the  greenhouse. 

It  makes  you  grin  with  the  kind  of 
grin  that  hurts:  For  the  last  hundred 
years  we’ve  been  using  technology  to 
tie  ourselves  to  abject  dependence  upon 
one  another;  now  it’s  pretty  plain  that 
we’d  better  use  that  same  technology 
to  help  each  household  stand  alone. 
For  the  Earth  he  done  spoke,  as  he 
does  now  and  then.  Even  if  it  takes 
another  hundred  years,  we  need  to 
change  our  paradigm  to  take  the  Earth 
into  account. 

Let’s  consider  this  one  —  the  Pretty 
Big  One  —  a  warning. 

Why  Is  There  Modulo? 

It  took  the  Mighty  U.S.  Post  Office  three 
days  to  resume  the  mails,  but  Federal 
Express  was  making  deliveries  the  next 
day.  We  were  still  living  out  of  the 
Magic  Van  when  the  FedX  lady  roared 
up  the  drive  and  dropped  a  box  in  my 
hands.  In  the  box  was  a  truly  remark¬ 
able  thing:  Stony  Brook  Modula-2. 

Now,  at  last  count  I  had  nine  DOS- 
based  Modula-2  compilers  on  my 
shelves  here.  All  work;  most  work  well; 
some  work  beautifully,  and  one  — 
TopSpeed  Modula-2  —  works  spectacu¬ 
larly.  But  perhaps  latecomers  have  the 
edge,  because  there  is  a  certain  crackle 
of  excellence  that  sets  Stony  Brook 
apart,  even  from  the  formidable  Top- 
Speed.  Stony  Brook  is  worth  a  closer 
look,  in  the  interest  of  understanding 
the  Vice  President  of  structured  lan¬ 
guages:  Modula-2. 

I’ve  given  Modula  short  shrift  in  this 
column,  because  President  Pascal  keeps 
hogging  the  spotlight.  Modula-2  freaks 
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keep  waiting  for  the  Prez  to  kick  off 
and  let  their  man  ascend  to  the  top 
spot,  but  the  Prez  lives  on.  (Lordy,  now 
there  are  even  two  of  them.) 

It  won’t  happen.  Turbo  Pascal 
brought  Pascal  to  the  same  sort  of  criti¬ 
cal  mass  that  Cobol  and  OS/360 
achieved  many  years  ago.  It  will  liter¬ 
ally  never  go  away  because  there  is  so 
much  of  it  out  there.  Fortunately,  Pas¬ 
cal  continues  to  evolve,  and  today  it 
serves  needs  unimagined  18  years  ago 
at  its  birth.  Pascal  may  in  fact  absorb 
Modula-2  over  time  by  stealing  its  best 
features  one  by  one.  The  last  chapter 
has  definitely  not  been  written. 

(And  Pascal’s  not  the  only  one.  I 
heard  not  long  ago  that  a  committee 
has  convened  to  add  object-oriented 
extensions  to  —  hold  your  breath  — 
Cobol.  I  can  see  it  now:  “File:  Go  read 
yourself.  Record:  Go  write  yourself.”  It 
is  to  boggle  the  mind.) 

So  why  is  there  Modula?  What  good 
is  it?  And  why  hasn’t  it  done  better? 

Good  questions.  Let’s  talk. 

No  Ambiguities 

If  I  were  to  choose  the  #1  imperative 
of  Modula-2,  it  would  be  this:  Let  there 
be  no  ambiguities.  This  imperative 
works  in  the  small  and  in  the  large. 

For  example,  in  Pascal  it’s  sometimes 
impossible  to  tell  whether  an  element 
in  an  expression  is  a  variable  or  a  func¬ 
tion.  Like  this:  Is  MaskedMarauder  a 
variable  or  a  function? 

Zorro  :=  MaskedMarauder;  {  Pascal 

code  I 

The  answer,  of  course,  is  that  you  can’t 
tell.  You  have  to  go  look  further  up  the 
source  code  to  see. 

In  Modula-2,  a  function  identifier  is 
always  followed  by  a  pair  of  parenthe¬ 
ses,  even  when  it  takes  no  parameters. 
Like  so: 

Zorro  :=  MaskedMarauder?  ); 

(*  Modula-2  code  *) 

Now  the  marauder  loses  his  mask  a 
little.  C  does  this  as  well,  which  is  one 
of  C’s  few  advantages  over  Pascal.  (And 
a  small  one  it  is,  too;  rather  like  a 
diamond  ring  dropped  into  a  fifty-year- 
old  outhouse.  You  dig  for  it .  .  .) 

In  the  larger  view,  Modula-2  always 
lets  you  know  where  every  program 
element  is  defined.  Apart  from  a  small 
suite  of  standard  functions  and  control 
structures,  everything  used  by  a  Modula- 
2  program  must  be  listed  at  the  top  of 
each  module,  in  statements  that  de¬ 
scribe  where  each  element  comes  from: 

FROM  SuperHeroes  IMPORT 


MaskedMarauder;  This  doesn’t  tell  me  where  the  identi- 
FROM  Japan  IMPORT  fier  SmallMinds  comes  from,  though 

Rice, Cars, VCRs;  depending  on  your  politics  you  might 
FROM  LawSchool  IMPORT  intuit  either  Japan  or  LawSchool.  (I  didn’t 

SmallMinds;  use  unit  Congress  here  or  it’d  be  a 
no-brainer.)  In  Modula  you  don’t  have 
Sometimes,  in  a  largish  module  of  a  to  intuit,  or  look  it  up  in  the  interface 
largish  program,  there  may  be  dozens  section  of  every  module  you  use.  The 
of  such  statements.  importer  tells  all.  And  in  a  complex 

This  is  one  very  full  step  past  the  program  this  can  save  enormous 
modularity  mechanisms  of  Turbo/Quick-  amounts  of  source  code  scanning! 
Pascal,  which  tells  you  which  modules  Sometimes  this  quest  for  unambiguity 
(in  Pascal,  units)  are  referenced  but  makes  things  a  little  bit  inconvenient, 
not  what  was  taken  from  them:  In  Modula-2,  the  type  and  number  of 

parameters  in  a  procedure  can  never 
PROGRAM  UnholyMess;  change.  Out  goes  Pascal’s  Read  and 

USES  SuperHeroes  Japan, LawSchool;  Write ,  which  can  take  any  number  of 
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parameters  in  numerous  modes.  Instead, 
you  have  a  separate  output  and  input 
procedure  for  each  data  type,  such  as 
WriteString,  Readlnt,  ReadCard  (for  the 
CARDINAL  unsigned  integer  type),  and 
so  on.  What  might  be  done  in  a  single 
Writeln  statement  in  Pascal  becomes  a 
conga  line  of  WriteThis,  Writelhat,  and 
WriteTOther,  one  for  each  different  type 
you  need  to  output.  Whether  this  is  a 
bug  or  a  feature  depends  on  whether 
you  write  applications  or  compilers; 
Pascal’s  open-ended  I/O  routines  make 
matters  lots  trickier  for  compiler  architects. 

So  Modula-2  eliminates  a  great  many 
of  Pascal’s  ambiguities,  but,  oddly,  it 
doesn’t  go  nearly  as  far  in  one  respect 


as  it  might.  Numerous  control  structures 
end  in  the  identical  word  END,  what 
Wirth  should  have  used  is  a  unique  ter¬ 
minator  for  each  structure,  such  as  END- 
FOR,  ENDCASE,  ENDWHILE,  and  so  on. 
Wirth  wisely  added  an  END  word  to  the 
end  of  every  IF .  .  THEN  statement: 

IF  Richter  <  8.0  THEN 
GrabSomething; 

HangOn; 

ELSE 

GrabSomething; 

SayPrayers 

END; 


(Note  the  welcome  absence  of  redun¬ 
dant  /JEGZ/Vwords.)  Still,  what  he  should 
have  added  was  a  unique  terminator 
word  such  as  ENDIF.  This  would  have 
added  tremendously  to  the  readability 
of  heavily  nested  control  structures.  Ahh, 
well.  Maybe  Modula-3. 

Flexibility  Without  Ambiguity 

One  of  the  critics’  numerous  gripes 
against  Pascal  is  its  rigid  type  checking. 
If  you  want  to  pass  an  array  to  a  proce¬ 
dure,  the  formal  parameter  must  be 
identical  in  type  to  the  actual  parame¬ 
ter.  In  other  words,  if  you  want  to 
create  a  general-purpose  routine  for 
sorting  arrays  of  records,  in  Pascal  you 
must  declare  the  formal  parameter  as 
having  specific  bounds.  When  called, 
the  array  passed  to  the  sort  procedure 
as  its  actual  parameter  must  not  only 
have  elements  of  the  same  type  as  the 
formal  parameter  but  identical  bounds 
as  well.  A  variable  defined  as 

ARRAY10  .  .  10231  OF  MyRecord 

cannot  be  passed  as  an  actual  parame¬ 
ter  to  a  sort  procedure  defined  as 

PROCEDURE  SortEmCVAR  Target : 

RecArray); 

where  RecArray  has  this  definition: 

ARRAY10..255]  OF  MyRecord 

Rigid  indeed.  And  not  entirely  true, 
even  of  Pascal.  Standard  Pascal  con¬ 
tains  a  feature  that  is  implemented  so 
rarely  (and  not  in  either  Turbo  or  Quick- 
Pascal,  though  present  in  MS  Pascal  as 
its  “super  array”)  that  most  people  have 
just  plumb  forgot  about  it:  The  confor¬ 
mant  array. 

Modula-2  supports  conformant  ar¬ 
rays,  though  it  uses  the  far  more  de¬ 
scriptive  term  “open  array.”  A  formal 
array  parameter  of  a  procedure  is  an 
open  array  when  it  is  defined  without 
bounds: 

PROCEDURE  SortEmCVAR  Target : 

ARRAY  OF  MyRecord); 

Only  one-dimensional  arrays  may  be 
open  arrays.  Within  the  procedure,  the 
high  bound  may  be  returned  by  calling 
the  standard  procedure  HIGH.  The  low 
bound  is  always  assumed  to  be  0.  This 
way,  you  can  pass  an  array  of  MyRe¬ 
cord  of  any  size  to  SortEm,  and  simply 
ask  the  HIGH  procedure  for  the  index 
of  the  last  element.  Open  arrays  are  an 
excellent  example  of  how  Modula-2 
can  simultaneously  be  more  flexible 
than  Pascal  while  remaining  less  am¬ 
biguous. 
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Modula-2  also  provides  standard  port 
for  coroutines,  which  try  as  I  might 
defy  description  in  anything  smaller 
than  a  column  unto  themselves.  We’ll 
take  them  up  again  in  the  future.  For 
now,  suffice  it  to  say  that  coroutines 
amount  to  poor-man’s  multitasking,  and 
are  of  minimal  usefulness  —  but  are  a 
giant  step  in  the  right  direction. 

And  Some  Boo-boos 

The  news  on  Modula-2  is  almost  en¬ 
tirely  good.  Just  to  make  sure  we  were 
all  awake,  however,  old  Nick  Wirth 
threw  in  some  zingers.  Worst  of  these 
is  the  rather  ridiculous  restriction  on 
the  number  of  elements  in  a  set.  A 
standard  Modula-2  set  may  have  only 
16  elements.  Wirth  says  he  did  this  to 
make  compiler  implementation  easier, 
which  is  an  explanation  but  not  an 
excuse.  Somebody  has  to  use  these 
damned  things,  Dear  Doctor!  Probably 
90  percent  of  all  sets  used  in  Pascal  are 
sets  of  Char ;  in  which  there  must  be 
255  slots.  Out  the  window.  (In  stan¬ 
dard  Modula-2,  at  least.  More  later  .  .  .) 
My  hunch  is  that  this  restriction  has 
sunk  more  conversions  to  Modula-2 
than  all  its  other  peccadillos  put  to¬ 
gether. 

Compared  to  that,  other  irritations 
are  minor.  Modula-2  is  case  sensitive. 
I  don’t  like  it  in  C,  and  I  don’t  like  it  in 
Modula  .  .  .  but  programmers  can  and 
will  live  with  it.  Comments  must  be 
bracketed  with  the  (*  *)  comment  de¬ 
limiters  rather  than  the  simpler  curly 
brackets  used  almost  universally  in  Pas¬ 
cal.  Open  arrays  are  limited  to  one 
dimension.  There  is  no  double-preci¬ 
sion  real  number  type,  like  Double  or 
Extended  in  Turbo  Pascal.  In  general, 
with  regard  to  numeric  calculations, 
Modula-2  is  type-poor  compared  to 
Turbo  Pascal. 

But  by  and  large,  Modula-2  is  a  con¬ 
siderable  improvement  over  Pascal.  This 
is  especially  true  when  large  projects 
must  be  broken  up  into  modules.  Mod¬ 
ules,  after  all,  were  what  drove  the 
design  of  Modula  and  gave  it  its  name. 
So  why  hasn’t  Modula  done  better  than 
it  has?  There  are  two  fundamental  rea¬ 
sons: 

•  Turbo  Pascal  got  there  first;  and 

•  Wirth  forgot  to  define  standard 
libraries 

Overdue  at  the  Standard  Library 

The  first  of  these  problems  was  simple 
fate,  and  a  reflection  of  the  power  of 
momentum  and  source  code  critical 
mass.  Had  Philippe  Kahn  brought  a 
super  fast  Modula-2  to  America  in  his 
gym  bag  in  1982,  Pascal  would  prob¬ 
ably  be  about  as  popular  today  as  JO¬ 


VIAL  or  SNOBOL.  Turbo  Pascal  is  now 
Standard  Pascal,  regardless  of  how 
much  those  ISO  people  grind  their  teeth. 
When  Microsoft  anointed  the  Turbo 
Pascal  Standard  with  QuickPascal  last 
May,  the  game  was  over  in  the  Pascal 
standards  business. 

The  second  problem  was  totally  avoid¬ 
able.  When  Wirth  released  the  Modula 
spec  back  in  1980,  he  deliberately  made 
it  lean  and  mean  —  about  as  lean  as  a 
language  could  be  without  lapsing  into 
anorexia.  Pure  Modula-2  is  all  bones 
and  no  flesh.  Wirth  defined  the  stan¬ 
dard  data  types,  modularity  mecha¬ 
nisms,  control  structures,  a  handful  of 
standard  procedures  and  functions 
.  .  .  and  stopped. 

Why?  Portability,  of  all  things,  which 
in  today’s  world  of  philosophically  in¬ 
compatible  operating  platforms  isn’t 
even  as  valuable  as  your  average  city 
planner  and  drops  to  the  usefulness  of 
a  tobacco  lobbyist.  It’s  silly  to  argue 
with  portability  freaks  and  I  won’t  try. 
But  my  position  is  plain:  Drop-in  port¬ 
ability  is  impossible.  Least-common- 
denominator  portability  costs  more  than 
it  is  worth.  The  smart  thing  to  do  is 
choose  a  platform  and  make  the  most 
of  it.  When  you  must  jump  platforms, 
expect  to  rebuild  everything  you  own 
from  scratch,  or  you’re  strapping  on  a 
wooden  leg  and  tying  one  hand  be¬ 
hind  your  back. 

One  reason  that  Turbo  Pascal  caught 
on  so  quickly  is  that  it  made  the  most 
of  its  operating  environment,  DOS.  It 
had  built-in  support  for  parsing  and 
returning  DOS  command-line  parame¬ 
ters,  built-in  dynamic  string  support, 
built-in  8086  memory  addressing  and 
I/O  support,  and  plenty  more.  Version 
4.0  added  versatile  (if  not  lightning- 
quick)  graphics  and  the  fabulous  DOS 
unit.  The  value  in  such  libraries  is  al¬ 
most  immeasurable:  How  many  of  you 
could  duplicate  the  BGI  on  your  own? 
90  percent  of  you  with  your  hands  up, 
lower  your  eyes  and  go  to  confession. 

Programmer  man-hours  cost  more 
every  year.  Libraries  save  man-hours. 
Lots  of  them.  Once  he  was  satisfied 
with  the  basic  definition  of  Modula-2, 
Wirth  should  have  spent  six  months 
or  so  thinking  about  the  sorts  of  utility 
modules  that  programmers  spend  the 
most  time  building,  and  come  up  with 
specs  for  a  suite  of  libraries  to  serve 
those  needs.  With  a  little  thought,  most 
utility  libraries  can  be  divorced  almost 
completely  from  the  details  of  their  op¬ 
erating  platforms.  A  world-coordinate 
graphics  system,  for  example,  can  be 
made  to  operate  on  any  raster-based 
graphics  system.  Any  file  system  needs 
library  routines  to  scan  for  ambiguous 
file  names,  and  most  basic  I/O  opera¬ 


tions  can  be  specified  without  bowing 
to  the  details  of  a  particular  platform. 
Obviously,  the  details  of  implementa¬ 
tion  are  closely  tied  to  the  platform 
beneath  them,  but  the  spec  can  with 
cleverness  be  made  almost  entirely  plat- 
form-independent. 

What  bothers  me  most,  I  think,  is 
that  Wirth  didn’t  even  try. 

So  what  we’ve  seen  is  each  Modula- 
2  compiler  vendor  implementing  librar¬ 
ies  to  meet  the  needs  of  DOS  program¬ 
mers,  and  every  one  does  things  just  a 
little  bit  differently,  both  in  terms  of 
how  things  are  done,  and  also  in  terms 
of  what  is  done  and  what  is  left  out. 
The  kernel  of  Modula-2  is  so  compact 
and  simple  that  the  most  visible  por¬ 
tions  of  any  given  implementation  are 
its  libraries,  and  these  are  so  different 
from  vendor  to  vendor  that  each  im¬ 
plementation  begins  to  look  like  a  sepa¬ 
rate  language.  Modula-2  has  become  a 
Tower  of  Babel,  and,  sadly,  (with  a 
little  foresight)  Niklaus  Wirth  could  have 
prevented  most  of  that. 

Stony  Brook  Specifics 

Maybe  this  glum  view  will  scare  you 
away  from  Modula-2.  I  hope  it  won’t. 
If  you  choose  a  solid  implementation 
and  stick  with  it,  for  your  purposes  the 
Babel  Factor  ceases  to  be  a  problem. 
There  are  two  extremely  good  imple¬ 
mentations  for  DOS  these  days,  and 
either  will  serve  you  well.  I’ve  discussed 
TopSpeed  Modula-2  in  earlier  columns, 
and  I’d  now  like  to  focus  on  Stony 
Brook. 

Editors  and  writers  tend  to  notice 
documentation.  Mark  me  well:  Stony 
Brook  has  by  far  the  finest  documenta¬ 
tion  of  any  Modula-2  product  that  has 
ever  crossed  my  desk.  It  is  well  written 
and  well  organized,  and  while  I’ve 
found  plenty  of  small  quibbles  (mostly 
in  explanations  that  do  not  say  nearly 
enough)  the  total  effect  is  wonderful. 

Stony  Brook  goes  its  own  way  in 
terms  of  a  programming  environment. 
Instead  of  centering  on  a  single  text  file 
as  the  focus  of  a  project,  Stony  Brook’s 
environment  centers  on  a  subdirectory 
that  is  devoted  to  a  single  project  con¬ 
sisting  of  several  or  many  files.  “Home 
base”  in  the  environment  is  a  screen 
listing  of  all  component  files  belonging 
to  that  project.  Modula-2  tends  to  pro¬ 
duce  a  lot  of  files,  because  each  mod¬ 
ule  has  a  separate  implementation  and 
definition  file.  Stony  Brook’s  environ¬ 
ment  lines  them  all  up  vertically,  with 
a  highlight  bar  selecting  one  as  the 
current  focus.  By  pressing  enter,  the 
highlighted  file  may  be  edited.  By  press¬ 
ing  other  command  keys,  additional 
environment  tools  may  be  brought  to 
bear  on  the  highlighted  file. 
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For  example,  it’s  often  useful  to  know 
what  modules  are  used  by  a  given  mod¬ 
ule,  and  also  what  modules  use  that 
module.  Two  keystrokes  will  display 
any  given  module’s  import  list  (what  it 
uses)  or  client  list  (who  uses  it.)  When 
I  had  to  divide  my  attention  among  a 
great  many  separate  but  related  mod¬ 
ule  files,  I  found  that  this  system  works 
quickly  and  extremely  intuitively. 

Within  the  Professional  package, 
there  are  two  complete  compilers:  One 
designed  for  fast  compilation,  and  the 
other  designed  to  squeeze  the  last  bit 
of  performance  out  of  the  code.  The 
global  optimizations  are  impressive, 
both  in  terms  of  .EXE  size  and  speed. 
An  example:  The  non-optimized  .EXE 
file  for  JTerm  is  32,966  bytes  in  size. 
Run  it  through  the  optimizing  compiler 
and  it  shrinks  to  16,277.  Switching  from 
one  compiler  to  the  other  is  a  single 
command,  so  you  can  develop  rapidly 
by  using  the  fast  compiler,  then  gener¬ 
ate  a  user-testable  .EXE  file  by  invok¬ 
ing  the  optimizing  compiler. 

Exploring  the  Libraries 

Stony  Brook’s  excellent  documentation 
made  it  lots  of  fun  to  explore  the  librar¬ 
ies.  In  less  than  an  hour  I  rigged  up  a 
simple  interrupt-driven  telecomm  pro¬ 
gram  that  included  the  ability  to  cap¬ 
ture  incoming  characters  to  a  text  file 
on  disk  —  all  in  about  100  lines  of  code. 
The  program  is  shown  as  Listing  One, 
page  146,  and  it  illustrates  several  of 
Stony  Brook’s  utility  libraries. 

The  telecomm  session  runs  inside  a 
bordered  window.  The  window  occu¬ 
pies  the  entire  screen  in  JTERM ,  but  it 
doesn’t  have  to.  The  capture  file  is 
named  “CAPTURE.TXT,”  and  is  either 
created  (if  it  does  not  already  exist)  or 
opened  to  the  end  of  data  when  the 
program  is  run.  Function  key  F7  begins 
sending  incoming  characters  to  the  file, 
and  function  key  F8  suspends  data  cap¬ 
ture.  This  allows  you  to  “grab”  specific 
messages  of  interest  on  a  timesharing 
system  such  as  CompuServe  with  mini¬ 
mal  command-entry. 

CommPort  is  an  example  of  a  superb 
library  not  present  in  any  other  Pascal 
or  Modula-2  implementation  I  know 
of.  It  implements  a  suite  of  interrupt- 
driven  serial  port  support  routines  that 
would  be  an  unholy  hassle  to  imple¬ 
ment  independently.  (I’ve  done  it  and 
lost  some  hair  in  the  process.)  Basi¬ 
cally,  you  init  a  port,  turn  on  interrupts, 
and  check  a  buffer  for  incoming  char¬ 
acters.  Assuming  you  allocate  a  large 
enough  buffer  and  check  the  buffer 
regularly,  you  needn’t  worry  about  los¬ 
ing  characters.  The  hidden  interrupt 
machinery  saves  them  in  the  buffer, 
where  they  remain  ripe  for  the  picking. 
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JTerm  might  have  been  even  simpler 
had  the  Screen  library  supported  sim¬ 
ple  TTY-style  output  to  a  window.  TTY 
output  is  available  to  the  full  screen, 
but  within  a  window  I  had  to  fake  it 
by  using  Screen’s  various  cursor-ma¬ 
nipulation  procedures.  No  serious  prob¬ 
lem,  as  Listing  One  will  attest.  Screen 
has  excellent  support  of  colors  and 
attributes  for  text  windows.  Its  window 
borders  are  color  bars  rather  than  line- 
drawn  characters,  which  imparts  an  alto¬ 
gether  different  sort  of  look  to  Stony 
Brook’s  text  windows. 

The  range  of  Stony  Brook’s  standard 
libraries  is  absolutely  stellar,  and  I’ve 
used  only  the  most  basic  of  them  in 
JTerm.  Several  modules  are  provided 
to  support  all  the  most  useful  numeric/ 
string  conversions.  Another  module  pro¬ 
vides  exit  procedure  support  roughly 
equivalent  to  Turbo  Pascal’s.  Modules 
are  provided  to  query  time  and  date 
from  the  system  clock;  to  return  the 
command  line  and  the  environment 
variables;  to  create,  remove,  set,  and 
search  directories;  to  set  and  read  the 
logged  disk  drive  and  query  available 
disk  space;  to  support  the  standard  Mi¬ 
crosoft  mouse  API;  to  control  the 
speaker;  to  shell  out  to  DOS  or  run 
DOS  programs  and  commands;  to  sup¬ 
port  both  long  and  short  heaps;  to  sup¬ 
port  variable-length  strings  (ASCIIZ  with¬ 
out  a  length  byte,  sadly);  and  very  com¬ 
plete  support  of  long  integers  and  long 
cardinals,  including  transcendental  op¬ 
erations. 

A  graphics  library  is  provided,  but  it 
doesn’t  have  the  range  or  flexibility  of 
the  BGI.  Still,  for  simple  graphing  and 
charting  it’s  more  than  adequate. 

Modular  Multitasking 

One  of  the  most  intriguing  aspects  of 
Modula-2  is  its  hooks  to  multitasking 
platforms.  Both  TopSpeed  and  Stony 
Brook  have  similar  libraries  to  support 
preemptive  multitasking  of  processes. 
Under  DOS  this  is  done  out  of  whole 
cloth,  with  a  custom  scheduler  and  all 
the  attendant  baggage  glued  onto  DOS 
like  antlers  on  a  Doberman;  yes,  the 
beast  can  handle  it  but  it  looks  funny. 
Under  OS/2  (which  both  products  sup¬ 
port)  the  native  facilities  of  the  plat¬ 
form  are  used.  How  well  multitasking 
works  under  DOS  I  have  yet  to  test, 
but  I  will  test  it  and  report  on  it  in  a 
future  column. 

If  you  need  to  develop  for  OS/2, 
Modula-2  becomes  a  very  attractive  lan¬ 
guage.  Products  are  available  immedi¬ 
ately  (Turbo  Pascal’s  OS/2  schedule 
has  not  been  announced)  and  the  lan¬ 
guage  itself  presents  a  cleaner  interface 
to  multitasking  than  Pascal  or  even  C. 
Stony  Brook  bindings  to  the  OS/2  Pres¬ 


entation  Manager  SDK  are  well  along 
and  may  be  complete  by  the  time  you 
read  this.  Bindings  to  the  Microsoft  Win¬ 
dows  SDK  are  already  shipping,  and 
while  I  haven’t  tried  them  yet  I  hope 
to  take  a  shot  at  it  soon.  I  don’t  expect 
to  take  back  my  firm  opinion  that  OOP 
is  the  way  to  develop  for  both  Win¬ 
dows  and  PM,  but  certainly  Stony  Brook 
can’t  help  but  be  a  step  up  from  the 
Microsoft  SDK  under  C. 

More  Modula-2  code  next  time,  along 
with  further  experimentation  with  the 
Stony  Brook  compiler. 

Modula-2  Books 

I  have  three  shelves  full  of  books  on 
Pascal  (and  I  keep  by  no  means  all  of 
them)  but  only  seven  books  on  Modula- 
2,  including  a  couple  of  questionable 

Products  Mentioned 

Stony  Brook  Modula-2 
Stony  Brook  Software 
187  East  Wilbur  Rd.,  Ste.  9 
Thousand  Oaks,  CA  91360 
805-496-5837 

QuickMod  V2.0  for  DOS  $95 
QuickMod  V2.0  for  OS/2  $95 
Professional  Modula-2 
(includes  DOS  and  OS/2  optimizing 
compilers  plus  both  QuickMod 
compilers)  $295 

TopSpeed  Modula-2 
Jensen  &  Partners  International 
1101  San  Antonio  Rd.,  Ste.  301 
Mountain  View,  CA  94043 
415-967-3200 
DOS  compiler  $99.95 
OS/2  compiler  $195.00 

Programming  in  Modula-2, 

Fourth  Edition 
Niklaus  Wirth 
Springer- Verlag,  1988 
ISBN  0-387-50150-9 
Hardcover,  182  pages,  $29-95 

Modula-2  for  Pascal  Programmers 
Richard  Gleaves 
Springer- Verlag,  1984 
ISBN  0-387-96051-1 
Paper,  145  pages,  $23.50 

Modula-2  Programming 
John  W.  L.  Ogilvie 
McGraw-Hill,  1985 
ISBN  0-07-047770-1 
Hardcover,  304  pages,  $29.95 

Advanced  Programming  Techniques 
in  Modula-2 
Terry  A.  Ward 

Scott,  Foresman  &  Company,  1987 
ISBN  0-673-18615-6 
Paper,  300  pages,  $21.95 
Listings  diskette  $14.95 
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ones.  Wirth’s  own  defining  volume,  Pro¬ 
gramming  in  Modula-2,  is  not  terribly 
useful  unless  you  have  nothing  else. 
Too  dry,  too  short,  too  bereft  of  useful 
examples.  On  the  other  hand,  Richard 
Gleaves’  Modula-2  for  Pascal  Program¬ 
mers,  while  even  shorter,  has  a  unique 
mission:  To  teach  you  Modula-2  by 
way  of  its  similarities  to  and  differences 
from  Pascal.  This  shouldn’t  be  the  only 
book  you  use  to  pick  up  Modula,  but 
it  should  certainly  be  an  accessory. 

A  good,  general  first  book  for  learn¬ 
ing  Modula-2  is  Modula-2  Program¬ 
ming,  by  John  W.L.  Ogilvie.  The  style 
is  clean,  the  organization  rational,  and 
most  of  the  examples  are  printed  in  a 
dark  monospace  font  that  is  very  easy 
to  read.  This  book  and  the  Gleaves 
book  will  get  you  there.  Once  you’re 
there,  getting  better  often  comes  (in 
addition  to  coding  like  crazy)  from  read¬ 
ing  good  code  by  somebody  who 
knows  his  stuff.  One  book  to  pick  up 
is  Advanced  Programming  Techniques 
in  Modula-2  by  Terry  A.  Ward.  This 
book  is  mostly  code,  but  it’s  good  code, 
including  set,  string,  sort,  and  search 
libraries,  some  user  interface  tools,  and 
a  simple  expert  system.  (Publisher  de¬ 
tails  on  all  books  at  the  end  of  the 
column.) 

NOTE:  I  do  not  recommend  the  book 


Modula-2:  A  Seafarer’s  Guide  and  Ship¬ 
yard  Manual  by  Edward  J.  Joyce.  The 
type  will  make  your  eyes  fall  out,  the 
writing  is  indifferent  to  bad,  and  it  just 
doesn’t  contain  the  quantity  and  qual¬ 
ity  of  information  that  the  Ogilvie  book 
does. 

There’s  a  dearth  of  good  books  on 
Modula-2.  Most  of  the  titles  I  have  are 
between  two  and  five  years  old.  If  any 
publishers  reading  this  have  any  cur¬ 
rent  Modula-2  titles  in  print,  I’d  appre¬ 
ciate  seeing  them,  and  perhaps  will  let 
the  readers  of  this  column  know  about 
the  better  ones. 

Halloween  II:  From  Hell  to  Arizona 

Eek!  It’s  Halloween  night  again,  and  I 
just  remembered  that  I  finished  writing 
my  first  DDJ  column  exactly  one  year 
ago  today.  That  makes  this  my  13th 
column  (double  eek!),  most  appropri¬ 
ate  for  describing  earthquakes  and  other 
inappropriate  geological  behavior.  Don’t 
bother  looking  for  outhouses  to  knock 
over;  the  quake  beat  all  of  us  to  it. 

Carol  and  I  have  quaked  our  last, 
however,  and  as  soon  as  the  palace 
here  sells,  we  are  packing  up  dogs, 
books,  machine  shop,  radios,  and  386 
boxes  and  heading  for  Scottsdale,  where 
Keith  Weiskamp  and  I  will  be  launch¬ 
ing  our  new  magazine  PC  Techniques 


this  spring.  DDJ  editor-in-chief  Jon 
Erickson  has  graciously  allowed  me  to 
continue  this  column,  and  I  expect  I’ll 
be  here  again,  same  time  same  sta¬ 
tion  ...  if  here  would  just  sit  still  long 
enough  for  me  to  make  the  dash  to 
Arizona! 

Write  to  Jeff  Duntemann  on  MCI  Mail 
as  JDuntemann,  or  on  CompuServe  to 
ID  76117,1426. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listing  begins  on  page  146.) 

Vote  for  your  favorite  feature/artiole. 

Circle  Reader  Service  No.  11. 
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C  PROGRAMMING 


Listing  One  (Text  begins  on  page  123) 

/* - textsrch.h - - */ 

♦define  OK  0 
# define  ERROR  !OK 

♦define  MXTOKS  25  /*  maximum  number  of  tokens  */ 

♦define  MAXFILES  64  /*  maximum  number  of  files  */ 

♦define  MAXWORDLEN  25  /*  maximum  word  length  */ 

♦define  MAPSIZE  MAXFILES/16  /*  number  of  ints/map  */ 

♦define  SLOTINDEX  "slots. ndx" 

♦define  TEXTINDEX  "text. ndx" 

♦define  FILELIST  "filelist .ndx" 

/*  -  the  search  decision  bitmap  (one  bit  per  file)  -  */ 

struct  bitmap  { 

int  map [MAPSIZE]; 

}; 

/*  -  the  postfix  expression  structure  -  */ 

struct  postfix  { 

char  pfix;  /*  tokens  in  postfix  notation  */ 

char  *pfixop;  /*  operand  strings  */ 

}; 

/* - the  postfix  stack - */ 

extern  struct  postfix  pftokens[]; 
extern  int  xp_offset; 

/*  -  expression  token  values  -  */ 

♦define  TERM  0 

♦define  OPERAND  'O' 

♦define  AND 
♦define  OR  '  I ' 

♦define  OPEN  '  (' 

♦define  CLOSE  ')' 

♦define  NOT  ' ! ' 

♦define  QUOTE 

/* - textsrch  prototypes - */ 

struct  postfix  *lexical_scan (char  *expr); 
struct  bitmap  exinterp(void) ; 
struct  bitmap  search (char  ‘word); 
void  process_result (struct  bitmap); 

/* - binary  tree  prototypes - */ 

void  addtreefchar  *s); 
int  srchtree (char  *s); 
void  delete_tree (void) ; 
void  build_noisewords (void) ; 

/* - command  line  prototypes -  */ 

void  parse_cmdline (int, char  **,char  *,void  (*) (char  *)); 

/* - text  prototypes  - */ 

void  extract_word(FILE  *fp,  char  *s); 

/*  -  index  prototypes  - 

void  open_database (void) ; 
void  init_database (void) ; 
void  close_database (void) ; 
void  addindex(char  *word,  int  fileno); 
void  indexing(char  ‘filename); 
int  getbit (struct  bitmap  ‘rnapl,  int  bit) 
struct  bitmap  search_index (char  ‘word); 
char  *text_filename (int  fileno); 


Listing  Two 

/* - cmdline.c - */ 

♦include  <stdio.h> 

♦include  <dir.h> 

♦include  <string.h> 

♦include  "textsrch.h" 

/* 

*  Parse  a  command  line: 

*  filenamel  filename2  ...  filenamen 

*  @filelist 

*  wild  cards 

*  -+x  option  list  (-a  +b  -c  -xyz  +pdq) 

*  any  mix  of  the  above 
*/ 

/*  -  parse  a  command  line  for  options  and  file  names  -  */ 

void  parse_cmdline (int  argc,  char  *argv[],  char  ‘options, 
void  (*func) (char  *fn)) 

{ 

char  path [65] ; 

FILE  *fp; 

while  (argc —  >  1)  { 

switch  (**++argv)  { 

case  ' /'  : 
case  ' +' : 

/* - add  an  option - */ 

while  (options  &&  *++‘argv) 
options [**argv]  =  1; 
break; 
case  ' : 

/* - remove  an  option - */ 

while  (options  &&  *++*argv) 
options [**argv]  =  0; 
break; 
case  ' : 

/* - a  file  of  file  path/names - */ 


*/ 


End  Listing  One 
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if  ( (fp  =  fopen (*argv+l,  "rt"))  !=  NULL) 

while  ( (fgets (path,  65,  fp) )  !=  NULL)  { 
path [strlen (path) -1]  =  '\0'; 

(*func) (path) ; 

} 

break; 

default: 

/*  -  a  file  spec  on  the  command  line  -  */ 

if  (strchr (*argv,  '*')  I!  strchr (*argv,  '?'))  ( 

/* - an  ambiguous  file  spec - */ 

struct  ffblk  ff; 
char  *cp; 
int  rtn; 

/*  -  copy  the  ambiguous  file  spec  -  */ 

strcpy(path,  *argv) ; 

/* - find  the  filename  part - */ 

if  { (cp  =  strrchr (path,  '\\'))  ==  NULL) 

if  ( (cp  =  strrchr (path,  ':'))  ==  NULL) 
cp  =  path-1; 

cp++; 

/* - search  for  matches - */ 

rtn  =  findfirst (*argv,  &ff,  0); 
while  (rtn  ==  0)  ( 

strcpy(cp,  ff.ff_name); 

(*func) (path) ; 
rtn  =  findnext ( & f  f ) ; 

} 

1 

else 

/*  -  an  unambiguous  file  spec 

(*func) (*argv) ; 


listing  Three 

/* - bintree.c - */ 

#include  <stdio.h> 

♦include  <string.h> 

♦include  <stdlib.h> 

♦include  "textsrch.h" 

struct  bintree  { 

struct  bintree  ‘lower; 
struct  bintree  ‘higher; 
char  wd(l]; 

); 


*/ 


End  Listing  Two 


static  struct  bintree  ‘first,  ‘next; 

/* - add  a  string  to  a  binary  tree - */ 

void  addtree(char  *s) 

{ 

struct  bintree  *tp; 
int  intree; 

tp  =  malloc (sizeof  (struct  bintree)  +  strlen (s)); 
if  (tp  ==  NULL) 
return; 

strcpy (tp->wd,  s); 
tp->lower  =  tp->higher  =  NULL; 
if  ((intree  =  srchtree(s))  !=  0)  ( 

if  (first  ==  NULL) 
first  =  tp; 
if  (next  !=  NULL)  ( 
if  (intree  <  0) 

next->lower  =  tp; 

else 

next->higher  =  tp; 

} 

} 

) 

/*  -  Search  a  binary  tree  for  a  string. 

Return  0  if  the  string  is  in  the  tree. 

Return  <  0  or  >  0  if  not. 

If  not,  next  ->  the  node  where  insertion  may  occur.  —  */ 

int  srchtree (char  *s) 

( 

struct  bintree  ‘this; 
int  an  =  -1; 
this  =  next  =  first; 
while  (this  !=  NULL)  ( 

if  ((an  =  strcmp(s,  this->wd) )  ==  0) 
break; 

next  =  this; 

this  =  ((an  <  0)  ?  this->lower  :  this->higher) ; 

} 

return  an; 

) 

/* - delete  the  nodes  of  a  branch  of  the  tree - */ 

static  void  delete_nodes (struct  bintree  *nd) 

{ 

if  (nd->lower) 

delete_nodes (nd->lower) ; 
if  (nd->higher) 

delete_nodes (nd->higher) ; 
free (nd) ; 

} 


/* - free  all  memory  allocated  for  the  tree - */ 

void  delete_tree (void) 

( 

delete_nodes (first) ; 

}  ( continued  on  page  142) 
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C  PROGRAMMING 


Listing  Three  (Listing  continued,  text  begins  on  page  123  ) 


/* - build  a  binary  tree  of  noise  words - 

void  build_noisewords (void) 

{ 

FILE  *fp; 

char  word [MAXWORDLEN+1 ] ; 

/* - open  the  noise  word  file - */ 

if  ( (fp  =  f open ("NOISE. LST",  "rt") )  !=  NULL)  ( 

/*  -  extract  words  and  add  them  to  the  list  - 

while  (!feof(fp))  { 

extract_word(fp,  word); 

/* - search  the  noise  word  list - 

addtree (word) ; 

I 

f close (fp) ; 


Listing  Four 


End  Listing  Three 


so  very  what  he  she  her  both  there  if  above  only  it  again 
done  our  then  from  just  my  along  left  who  may  we  all  these 
them  us  after  once  need  through  onto  others  can  want  where 
would  nor  none  with  do  here  been  was  see  own  since  off  this 
not  will  which  itself  that  each  to  take  down  on  you  under  at 
their  however  the  an  as  even  have  whose  a  said  before  or 
nearly  below  are  those  possible  alike  begin  out  than  having 
two  know  when  way  often  together  by  many  thus  whatever  i  his 
past  another  though  other  entire  in  against  am  most  taken 
instead  him  because  for  might  too  rather  few  soon  either  near 
about  every  until  neither  beyond  your  better  must  usually 
several  does  such  something  using  put  more  whether  sent  any 
later  like  and  now  they  also  upon  close  be  use  of  is  should 
could  were  into  made  further  used  let  how  enough  its  himself 
known  never  become  sure  over  next  up  among  had  causes  has  no 
old  some  come  but  while  me 


End  listing  Four 


Listing  Five 

/* - index,  c 

♦include  <stdio.h> 
♦include  <stdlib.h> 
♦include  <string.h> 
♦include  "textsrch.h" 


static  void  setbit (struct  bitmap  *mapl,  int  bit); 
static  unsigned  compute_hash (char  *word) ; 

static  FILE  *slots,  *text,  *flist; 
static  char  path [65]; 
int  file_count  =  0; 

/*  -  open  or  create  the  index  files  for  building 

void  open_database (void) 


unsigned  ctr  =  Oxffff; 
long  empty  =  -1L; 
build_noisewords () ; 
if  ((slots  =  fopen (SLOTINDEX, 
slots  =  fopen (SLOTINDEX, 
if  (slots  !=  NULL)  { 

if  ((text  =  fopen (TEXTINDEX, 
text  =  fopen (TEXTINDEX, 
if  (text  !=  NULL)  { 

if  ((flist  =  fopen (FILELIST,  "rt"))  !=  NULL) 
while  (fread(path,  sizeof  path,  1,  flist)) 
file_count++; 
fclose (flist) ; 

flist  =  fopen (FILELIST,  "at"); 
return; 


"r+b"))  == 
"w+b")  ; 


NULL) 


"r+b"))  ==  NULL) 
"w+b") ; 


/*  -  if  fhe  file  list  does  not  exist, 

we  must  be  building  a  new  data  base  -  */ 

if  ((flist  =  fopen (FILELIST,  "wt"))  !=  NULL)  { 

/*  —  preset  the  slots  to  -1  values  —  */ 
printf ("\nBuilding  index.  Please  wait...\n"); 
while  (ctr — )  ( 

if  ((ctr  %  1000)  ==  0) 
putchar (' . ' ) ; 

fwrite (sempty,  sizeof (long) ,  1,  slots); 

) 

file_count  =  0; 
return; 

} 

fclose (text) ; 

) 

fclose (slots) ; 

} 

printf ("\nCannot  establish  index  files"); 
exit (1) ; 

} 

/* - open  an  index  data  base  for  retrieval - */ 

void  init_database (void) 

{ 

build_noisewords () ; 

/* - open  all  three  index  files - */ 

if  ((slots  =  fopen (SLOTINDEX,  "rb"))  !=  NULL)  ( 

if  ((text  =  fopen (TEXTINDEX,  "rb"))  !=  NULL)  { 
if  ((flist  =  fopen (FILELIST,  "rt"))  !=  NULL)  { 

/* - count  the  text  files - */ 

while  (fread(path,  sizeof  path,  1,  flist)) 
file_count++; 

printf ("\n%d  files  in  the  data  base.", 
file_count); 

return; 
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} 

f close (text) ; 

} 

fclose  (slots) ; 

} 

printf ("\nCannot  open  Index  Data  Base"); 
exit  (1) ; 


/* - close  the  index  files - */ 

void  close_database (void) 

{ 

delete_tree () ; 
fclose (slots) ; 
fclose (text) ; 
fclose (flist) ; 


/* - add  a  word  to  the  index 

or  add  the  file  number  to  the  existing  word  -  */ 

void  addindex (char  *word,  int  fileno) 

{ 

long  slotno; 

long  hash; 

struct  bitmap  mapl; 

long  ptr  =  -1L; 

char  wd [MAXWORDLEN+1 ] ; 

/* - compute  a  randon  address  from  the  word - */ 

hash  =  compute_hash (word) ; 
hash  *=  sizeof (long) ; 

/* - read  the  random  slot  value - */ 

fseek (slots,  hash,  SEEK_SET) ; 
fread(&slotno,  sizeof (long) ,  1,  slots); 
if  (slotno  ==  -1L)  { 

/*  —  empty  slot,  add  the  word  to  the  data  base  —  */ 
fseek(text,  OL,  SEEK_END) ; 
slotno  =  ftell(text); 

/* - set  the  bit  map  to  this  file  only - */ 

memset (&mapl,  0,  sizeof (struct  bitmap)); 
setbit (Smapl,  fileno); 

fwrite (&mapl,  sizeof (struct  bitmap),  1,  text); 

/*  --  set  the  chain  pointer  to  the  terminal  value  —  */ 
fwrite (&ptr,  sizeof (long) ,  1,  text); 
fwrite (word,  strlen (word) +1,  1,  text); 

/*  —  insert  the  text  address  into  the  slot  file  —  */ 

fseek (slots,  hash,  SEEK_SET) ; 

fwrite (sslotno,  sizeof (long) ,  1,  slots); 

return; 

} 

/* - the  hashed  slot  is  in  use - */ 

for  (;;)  ( 

/*  —  point  to  the  text  index  record  -  */ 

fseek(text,  slotno,  SEEK_SET) ; 
fread(&mapl,  sizeof (struct  bitmap) ,  1,  text); 
fread(&ptr,  sizeof (long) ,  1,  text); 
fgets  (wd,  MAXWORDLEN+1,  text); 

/*  —  see  if  the  entry  matches  the  word  —  */ 
if  (strcmp(wd,  word)  ==  0)  { 

/*  -  the  word  matches  this  entry, 

set  this  file's  bit  -  */ 

setbit (&mapl,  fileno); 

fseek (text,  slotno,  SEEK_SET) ; 

fwrite (&mapl,  sizeof (struct  bitmap),  1,  text); 

break; 

} 

/* - see  if  there  is  a  chain - */ 

if  (ptr  ==  -1)  ( 

/* - end  of  the  chain;  add  this  word - */ 

long  newslotno; 

/*  -  to  the  end  of  the  text  index  file  -  */ 

fseek (text,  OL,  SEEK_END) ; 
newslotno  =  ftell(text); 

/* - set  the  ^  map  t0  this  file  only - *j / 

memset (&mapl,  0,  sizeof (struct  bitmap)); 
setbit (&mapl,  fileno); 

fwrite (&mapl,  sizeof (struct  bitmap),  1,  text); 
fwrite (&ptr,  sizeof (long) ,  1,  text); 
fwrite (word,  strlen (word) +1,  1,  text); 

/* - chain  the  last  entry  to  this  one - */ 

fseek (text,  slotno+sizeof (struct  bitmap) ,  SEEK_SET) ; 

fwrite (&newslotno,  sizeof (long) ,  1,  text); 

break; 

} 

/*  -  the  text  record  is  chained 

(multiple  words  hash  to  the  same  slot)  -  */ 

slotno  =  ptr; 

} 

} 

/*  search  the  data  base  for  a  match  on  a  word  -  */ 

struct  bitmap  search  index (char  ‘word) 

( 

long  slotno  =  -1; 
long  hash; 
struct  bitmap  mapl; 
char  wd [MAXWORDLEN+1 ] ; 

/* - preset  the  bit  map  to  all  zeros - */ 

memset (Smapl,  0,  sizeof (struct  bitmap)); 

/*  -  compute  random  slot  address  for  the  word  -  */ 

hash  =  compute_hash(word) ; 

hash  *=  sizeof (long) ; 

fseek (slots,  hash,  SEEK_SET) ; 

fread(&slotno,  sizeof (long) ,  1,  slots); 

/* - navigate  the  chain - */ 

while  (slotno  !=  -1)  ( 

fseek (text,  slotno,  SEEK_SET) ; 
fread(&mapl,  sizeof (struct  bitmap) ,  1,  text); 
fread(&slotno,  sizeof (long) ,  1,  text) ; 
fgets (wd,  MAXWORDLEN+1,  text); 

(continued  on  page  144) 
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Listing  Five  ( Listing  continued,  text  begins  on  page  123  ) 

if  (strcmp(wd,  word)  ==  0) 

/*  -  the  word  matches  this  entry  -  */ 

break; 

memset (fimapl,  0,  sizeof (struct  bitmap)); 

} 

return  mapl; 


/*  -  compute  a  random  address  from  an  ASCII  string 

static  unsigned  compute_hash (char  *word) 


unsigned  hash  =  0; 
while  (*word) 

hash  =  (hash  «  7)  +  (hash  »  9)  +  *word++; 
return  hash; 


/* - sets  a  designated  bit  in  the  bit  map - */ 

static  void  setbit (struct  bitmap  *mapl,  int  bit) 

{ 

int  off  =  bit  /  16; 

int  mask  =  1  «  (bit  %  16); 

mapl ->map[ off ]  1=  mask; 


/* - tests  a  designated  bit  in  the  bit  map - */ 

int  getbit (struct  bitmap  *mapl,  int  bit) 

{ 

int  off  =  bit  /  16; 

int  mask  =  1  «  (bit  %  16); 

return  mapl->map [of f ]  &  mask; 

} 


/* - add  a  file  name  to  the  list - */ 

void  indexing (char  *filename) 

{ 

/* - add  the  file  path  to  the  index  file  list - */ 

memset (path,  '\0',  sizeof  path); 
strcpy(path,  filename); 
fwrite(path,  sizeof  path,  1,  flist); 
file_count++; 


/*  -  return  the  file  name  associated  with  an  offset  -  */ 

char  *text_filename (int  fileno) 

{ 

fseek (flist,  (long)  (fileno  *  sizeof  path),  SEEK_SET) ; 
fread(path,  sizeof  path,  1,  flist); 
return  path; 


Listing  Six 

/* - bldindex.c -  */ 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  "textsrch.h" 

static  void  index_file (char  ‘filename); 
void  main (int  argc,  char  *argv[]) 

( 

open  database ( )  ; 

printf ("\nTextSrch:  Building  a  TextSrch  Index  File"); 
parse  cmdline (argc,  argv,  NULL,  index_file) ; 
close_database ( ) ; 

} 


static  void  index_file (char  ‘filename) 

{ 

FILE  *fp; 

char  word[MAXWORDLEN+l  ] ; 
extern  int  file_count; 
int  wdctr  =  0; 

printf ("\nlndexing  %s",  filename); 
indexing (filename) ; 

/* - open  the  object  file - */ 

if  ( ( f p  =  fopen (filename,  "rt”))  ==  NULL)  { 
printf ("\nError:  No  such  file"); 
return; 

) 

put char (' \n' ) ; 

/*  -  extract  words  and  add  them  to  the  index  -  */ 

while  (!feof(fp))  { 

extract_word(fp,  word) ; 

/* - search  the  noise  word  list - */ 

if  (srchtree (word)  !=  0)  ( 

if  ((++wdctr  %  100)  ==  0) 

printf ("\r%5d  words",  wdctr); 

/* - add  the  word  to  the  index - */ 

addindex (word,  file_count-l) ; 

} 


) 

printf ("\r%5d  words",  wdctr); 
f close (fp) ; 


Listing  Seven 


End  Listing  Six 


text .c 


End  Listing  Five 


♦include  <stdio.h> 
♦include  <ctype.h> 
♦include  "textsrch.h" 


♦define  isTEXT(c)  (isalpha(c)  11  isdigit (c)  !!  \ 
c==' +'  : :  c==' #'  : :  c ) 


/* - extract  a  word  from  an  input  stream 

void  ext ract_word (FILE  *fp,  char  ‘s) 

{ 

int  i,  c; 


c  =  i  =  0; 
while  ( ! isTEXT  (c) ) 

if  ( (c  =  fgetc (fp) )  ==  EOF) 
break; 

while  (isTEXT (c) )  { 

if  (i++  <  MAXWORDLEN) 

*s++  =  tolower(c); 
if  ( (c  =  fgetc (fp))  ==  EOF) 
break; 


*s  =  ' \0' ; 

} 

End  Listing  Seven 

Listing  Eight 

/* - search. c - */ 


/* 

*  the  TEXTSRCH  retrieval  process 
*/ 


♦include  <stdio.h> 
♦include  <string.h> 
♦include  "textsrch.h" 


/*  -  process  the  result  of  a  query  expression  search  - 

void  process_result (struct  bitmap  mapl) 

( 


int  i; 

extern  int  file_count; 
for  (i  =  0;  i  <  file_count; 
if  (getbit (&mapl,  i) ) 
printf ("\n%s" ,  text 


i++) 

filename (i) ) ; 


*/ 


/* - search  the  data  base  for  a  word  match - */ 

struct  bitmap  search (char  ‘word) 

( 

struct  bitmap  mapl; 

memset (&mapl,  Oxff,  sizeof  (struct  bitmap)); 
if  (srchtree (word)  !=  0) 

mapl  =  search_index (word) ; 
return  mapl; 

)  End  Listings 
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Listing  One  (Text  begins  on  page  134.) 

MODULE  JTerm; 

(*  Stony  Brook  Modula-2  —  Last  modified  10/31/89  *) 

(*  by  Jeff  Duntemann  —  For  DDJ  2/90  *) 

FROM  CommPort  IMPORT  BaudRate,  Parity,  InitPort,  StartReceiving, 

StopReceiving,  SendChar,  GetChar,  CommStatus; 

FROM  Filesystem  IMPORT  Close,  File,  Length,  Lookup,  Reset,  SetPos,  WriteChar; 

FROM  Keyboard  IMPORT  GetKey,  CarriageReturn,  LineFeed,  AltX,  F7,  F8; 

FROM  Screen  IMPORT  CreateWindow,  CloseWindow,  Color,  DrawBorder, 
MakeColorAttr,  Position,  SetCursor,  Window, 

WriteString,  WriteLn,  Xpos,  Ypos; 

FROM  Terminal  IMPORT  Write,  CharAvail,  Read; 

CONST 

Blink  =  TRUE; 

NoBlink  =  FALSE; 

As Popup  =  TRUE; 

NotAsPopup  =  FALSE; 

CreateFile  =  TRUE; 

VAR 

CaptureOn 
CaptureFile 
ItsLength 
Status 
Ch 

OutString 
Keystroke 
w 

WhiteOnBlue 
BEGIN 

(*  First  set  up  the  window  to  hold  the  terminal  session:  *) 

WhiteOnBlue  :=  MakeColorAttr (White, Blue, NoBlink) ; 

W  :=  CreateWindow (0, 0,  80, 24, WhiteOnBlue, AsPopup) ; 

DrawBorder (W, MakeColorAttr (White, LightCyan, NoBlink) ) ; 

Position (W, 1,0); 

WriteString  (W, '  WWJTERMWW  by  Jeff  Duntemann 

MakeColorAttr (Black, LightCyan,  Blink) ) ; 

Position (W, 1, 1) ; 

SetCursor (W) ; 

(*  Here  we  look  for  the  capture  file  CAPTURE.TXT;  open  it  if  it  *) 

(*  exists,  and  create  it  if  it  doesn't:  *) 

Lookup (CaptureFile, "CAPTURE . TXT" ,  CreateFile) ; 

Length (CaptureFile, ItsLength) ;  (*  Find  out  how  long  file  is...  *) 

SetPos (CaptureFile, ItsLength) ;  (*  ...and  position  it  to  EOF.  *) 

CaptureOn  :=  FALSE;  (*  Default  to  NOT  capturing  text  *) 

(*  Next,  set  up  the  interrupt-driven  serial  port  and  turn  it  on:  *) 

Status  :=  InitPort (0,Baudl200, 7, 1, Even) ; 

Status  :=  StartReceiving (0, 256) ; 

(*  We  check  for  keystrokes,  then  check  for  incoming  data:  *) 

LOOP  (*  EXIT  the  loop  (and  the  program)  on  Alt-X  *) 

IF  CharAvail ()  THEN 

GetKey (Keystroke) ;  (*  Get  a  keystroke  from  the  buffer  *) 

CASE  Keystroke  OF 

CarriageReturn:  (*  If  CR  was  pressed,  send  CR  *AND*  LF:  *) 

SendChar (0,CHR (CarriageReturn) , FALSE) ; 

SendChar (0,CHR (LineFeed) , FALSE) ;  ! 

F7:  CaptureOn  :=  TRUE;  I  (*  F7/F8  toggle  capture  *) 

F8:  CaptureOn  :=  FALSE;  !  (*  on  and  off  *) 

AltX:  EXIT;  (*  Alt-X  quits  the  program  *) 

(*  Send  any  non-command  to  the  serial  port:  *) 

ELSE  SendChar (0,CHR (Keystroke) , FALSE) ; 

END; 

END; 

(*  If  a  char's  waiting  in  the  comm  buffer,  get  it  and  parse  it:  *) 

IF  GetChar (0,Ch)  =  Success  THEN 
OutString [0]  :=  Ch; 

CASE  ORD (Ch)  OF 

(*  This  is  how  we  fake  TTY  backspace:  *) 

8:  IF  Xpos (W)  >  0  THEN 

Position (W,Xpos (W) -1, Ypos (W) ) ; 

WriteString (W, '  ', WhiteOnBlue) ; 

Position (W, Xpos (W) -1 , Ypos (W) ) ; 

SetCursor (W) ; 

END;  : 

13:  WriteLn (W); 

SetCursor (W) ; 

IF  CaptureOn  THEN 

WriteChar (CaptureFile, Ch) 

END;  : 

10:  IF  CaptureOn  THEN 

WriteChar (CaptureFile, Ch) 

END; 

ELSE  WriteString (W,Ch, WhiteOnBlue) ; 

SetCursor (W) ; 

IF  CaptureOn  THEN 
WriteChar (CaptureFile, Ch) ; 

END; 

END; 

END; 

END; 

(*  Finally,  we  shut  down  the  interrupt-driven  input  buffer:  *) 

Status  :=  StopReceiving (0) ; 

Close (CaptureFile) ; 

END  JTerm. 


End  Listing 


:  BOOLEAN; 

:  File; 

:  LONG I NT; 

:  CommStatus; 

:  CHAR; 

:  ARRAY [0..1]  OF  CHAR; 
:  CARDINAL; 

:  Window; 

:  CHAR; 
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A  set  of  object-oriented  numerical  tools 
that  allows  you  to  do  complicated  op¬ 
erations  on  vectors  and  matrices  in  the 
same  manner  as  with  built-in  types  has 
been  announced  by  Rogue  Wave,  a 
Seattle  outfit  that  specializes  in  object- 
oriented  numerics.  All  of  the  standard 
C  arithmetic  operators  such  as  “+”  and 
“+=”  have  been  extended  to  include 
vectors  and  matrices,  and  so  have  the 
C  functions  such  as  cos(  )  and  abs(  ). 
The  set  also  includes  new  functions  for 
statistics  and  numerical  modeling  ap¬ 
plications,  as  well  as  a  complex  num¬ 
ber  class.  Fast  Fourier  Transform  server 
classes  allow  you  to  take  the  FFT  or 
inverse  FFT  of  any  length  series  (real 
or  complex).  By  using  the  inheritance 
property  of  C++,  the  company  claims, 
new  classes  can  be  created  from  the 
Rogue  Wave  classes  to  do  specialized 
tasks.  The  package  includes  a  user’s 
guide  and  reference  manual.  The  cost 
is  $150.  Reader  service  no.  21. 

Rogue  Wave 
P.O.  Box  85341 
Seattle,  WA  98145-1341 
206-523-5831 

The  C-scape  Interface  Management  Sys¬ 
tem  and  the  Look  &  Feel  Screen  De¬ 
signer  have  been  announced  by  the 
Oakland  Group.  C-scape,  Version  3.1, 
runs  in  either  text  or  graphics  mode, 
which  means  that  C-scape  menus,  win¬ 
dows,  and  so  on  can  appear  on  top  of 
VGA  graphics,  and  that  graphics  such 
as  a  PCX  file  image  can  appear  inside 
a  C-scape  window.  CGA,  VGA,  EGA, 
and  most  modes  of  Hercules  are  sup¬ 
ported.  C-scape  is  built  upon  the 
Oakland  Windowing  Library  (OWL), 
which  manages  windows  management, 
automatically  tracks  visible  and  hidden 
screen  portions,  supports  as  many  win¬ 
dows  as  RAM  can  allow,  and  lets  you 
write  hidden  windows. 

The  Look  &  Feel  is  new,  and  lets  you 
design  screens  and  run  them  in  simu¬ 
late  mode,  and  then  convert  them  to  C 
code  or  save  them  to  screen  files  that 
are  callable  at  run  time.  All  code  is 


portable  among  DOS,  OS/2,  QNX, 
Xenix,  Unix,  and  VMS. 

C-scape  supports  DOS  and  OS/2  (in 
the  same  package),  Microsoft  and 
Borland  C,  and  includes  source  code 
(for  Unix  and  Xenix  implementations, 
too).  The  Unix  version  supports  color, 
and  X  Windows  support  should  be  avail¬ 
able  by  the  time  this  issue  hits  the 
streets.  The  Phar  Lap  DOS  Extender 
and  Rational  Systems  DOS/16M  are  also 
supported,  as  well  as  Zortech’s  C++ 
2.0.  The  DOS  version  with  the  Look 
and  Feel  Screen  Designer  is  $399,  with¬ 
out  $299.  The  Unix/Xenix  version  costs 
$999  Reader  service  no.  22. 

Oakland  Group,  Inc. 

675  Massachusetts  Ave. 

Cambridge,  MA  02139-3309 
800-233-3733 

An  MS-DOS  advanced-overlay  linker 
that  supports  CodeView,  .RTLink/Plus, 
has  been  released  by  Pocket  Soft.  The 
nested  overlay  capability  of  this  prod¬ 
uct  supposedly  allows  the  creation  of 
substantially  smaller  memory  images 
than  are  possible  with  Microsoft’s  linker 
overlay  feature. 

.RTLink/Plus  also  provides  a  link¬ 
time  Profiler  for  performance  analysis 
at  user-adjustable  timing  intervals;  the 
.RTL  (run-time  library)  allows  a  group 
of  .EXEs  to  share  code  from  language 
libraries,  third  party  libraries,  and  user’s 
libraries,  which  prevents  duplicate  stor¬ 
age  of  common  code;  memory  caching 
in  extended  or  expanded  memory  for 
overlay  swapping  supposedly  increases 
the  speed  of  overlay  handling  on 
equipped  systems;  and  Periscope,  Soft- 
Ice,  and  MagicCV  are  supported.  The 
list  price  is  $495.  .RTLink  is  identical 
to  .RTLink/Plus,  except  that  .RTLink 
does  not  provide  the  CodeView  and 
Profiler  features,  and  costs  $295.  Reader 
service  no.  23. 

Pocket  Soft,  Inc. 

7676  Hillmont,  Ste.  195 
Houston,  TX  77040 
713-460-5600 

The  C  Programmer’s  Toolbox  for  Ap¬ 
ple’s  Macintosh  Programmer’s  Work¬ 
shop  (MPW)  has  been  announced  by 
MMC  AD  Systems.  The  Toolbox  has 
20  new  tools  that  complement  the  ex¬ 
isting  MPW  tools.  The  list  includes: 
CDecl,  which  translates  and  composes 
C  declaration  statements  and  cast  op¬ 
erators;  CFlow,  which  determines  a  pro¬ 
gram’s  function  hierarchy  and  the  com¬ 
position  of  a  program’s  run-time  library, 
and  includes  an  ANSI-compatible  C  pre¬ 
processor  that  allows  inactive  code  sec¬ 
tions  to  be  ignored.  CFlow  also  has  the 
ability  to  process  any  number  and  size 
of  C  source  files  through  a  virtual  mem¬ 


ory  system  that  uses  temporary  disk 
storage  space  when  main  memory  is 
exhausted.  CHilite  highlights  and  prints 
C  source  files,  as  well  as  comments, 
keywords,  Toolbox  calls,  function  calls, 
macro  calls,  and  definitions  and/or  user- 
defined  symbols.  And  CLint  checks  for 
latent  programming  errors,  including 
variable  type  usage,  conditional  and 
assignment  statement  usage,  arithme¬ 
tic  operations  in  conditional  expres¬ 
sions,  and  more.  Some  other  tools  are 
CPrint  for  reformatting,  CXref  for  cross 
referencing,  Cpp  for  preprocessing,  Cat 
for  concatenating  input  data  streams, 
and  CharCnt  for  counting  input,  char¬ 
acters,  and  so  on. 

The  Toolbox  works  with  any  Macin¬ 
tosh  with  MPW  3.0  or  later.  MPW  C  is 
not  required.  The  Toolbox  works  for 
C  code  generated  by  MPW  C  2,x/3.x, 
Lightspeed  C/Think  C,  Aztec  C,  all  com¬ 
mon  PC  C  compilers,  engineering  work¬ 
stations  and  Unix  C  compilers.  It  sells 
for  $295.  Reader  service  no.  24. 

MMC  AD  Systems 
Box  360845 
Milpitas,  CA  95035 
408-263-0781 

Version  3-0  of  Star  Sapphire  Common 
Lisp  is  now  being  shipped  by  Sapiens 
Software.  One  of  the  few  versions  avail¬ 
able  for  IBM  and  compatible  PCs,  Com¬ 
mon  Lisp  is  a  general  purpose,  modern 
programming  language,  and  the  com¬ 
pany  claims  it  is  “programmer  friendly,” 
encouraging  greater  productivity. 

Star  Sapphire  Lisp  supports  the  use 
of  up  to  8  Mbytes  of  extended  or  virtual 
memory,  and  includes  a  resident  Emacs 
editor  and  online  help  for  the  whole 
language.  The  built-in  incremental  com¬ 
piler  and  debugger  supposedly  speed 
program  development.  The  product  in¬ 
cludes  source  code  examples,  includ¬ 
ing  the  Towers  of  Hanoi  and  the  Colos¬ 
sal  Cave  Adventure,  which  demonstrate 
how  to  write  programs  in  Lisp.  An  IBM 
PC,  PS/2,  or  compatible  with  640K  mem¬ 
ory  and  a  hard  disk  are  required.  Ver¬ 
sion  3-0  is  available  for  $99-95.  Reader 
service  no.  25. 

Sapiens  Software 
P.O.  Box  3365 
Santa  Cruz,  CA  95063 
408-458-1990 

Two  new  control  packages  that  are 
designed  to  make  programming  in  Mi¬ 
crosoft  Windows  and  OS/2  Presentation 
Manager  more  efficient  are  Standard 
Control  Pak  and  Tools  Control  Pak,  by 
Eikon  Systems.  Each  of  these  prod¬ 
ucts  offers  three  graphical,  high-level, 
reusable  software  objects  for  use  in  the 
client  area  of  windows  or  dialog  boxes. 

(continued  on  page  1 57) 
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(continued  from  page  148) 

Jerry  Weldon,  one  of  Eikon’s  devel¬ 
opment  engineers,  claims  that  “high- 
quality  graphical  objects  such  as  these 
can  take  weeks  or  months  to  refine  and 
perfect,  especially  when  you  realize 
that  each  Control  Pak  consists  of  thou¬ 
sands  of  lines  of  source  code.” 

In  the  Standard  Control  Pak,  the  Ar¬ 
row  window  class  can  be  used  in  place 
of  the  push  buttons  provided  with  Win¬ 
dows  and  OS/2  PM.  The  Palette  win¬ 
dow  class  provides  a  displayed  set  of 
predefined  colors,  and  the  Picture  win¬ 
dow  class  offers  a  variety  of  border 
styles  for  displaying  bitmaps  and 
metafile  pictures. 

The  Tools  Control  Pak  includes  a 
Ruler  window  class  for  defining  the 
position  and  spatial  orientation  of  gra¬ 
phical  objects,  a  Slider  window  class 
for  selecting  values  from  a  range,  and 
a  Toolbox  window  class  for  selecting 
an  operating  mode  from  a  rectangular 
array  of  small  bitmaps,  the  limit  of  which 
is  determined  by  available  memory.  The 
Standard  Control  Pak  for  Windows  re¬ 
tails  for  $125  without  source  code,  and 
$475  with;  for  OS/2  PM  the  cost  is  $225 
without  code,  and  $675  with  code.  The 
Tools  Control  Pak  is  $175  without  source 
code,  $525  with  code.  If  a  control  is  to 
be  incorporated  into  any  publicly  dis¬ 
tributed  application,  the  source  code 
must  be  purchased  (but  is  royalty  free). 
Reader  service  no.  26. 

Eikon  Systems,  Inc. 

989  E.  Hillsdale  Blvd.,  Ste  260 
Foster  City,  CA  94404 
415-349-46 64 

The  Video  Electronics  Standards  As¬ 
sociation  (VESA),  a  group  of  hard¬ 
ware  and  software  companies  involved 
in  computer  graphics  and  displays,  has 
adopted  and  published  standards  for 
Super  VGA  BIOS  Extensions.  This  stan¬ 
dard  specifies  a  common  software  in¬ 
terface  for  Super  VGA  video  adapters, 
providing  a  simplified  means  of  ac¬ 
cessing  extended  video  modes  such 
as  640  x  480  resolution  in  256  colors. 
The  standard  follows  the  800  x  600 
16-color  mode  and  8514/A  standards 
approved  last  year.  Within  the  next 
couple  of  months,  DDJ  will  publish  an 
in-depth  discussion  of  the  VESA  BIOS 
Extensions,  along  with  related  articles 
on  1 6-bit  VGA  and  Super  VGA.  For 
copies  of  the  standard,  contact  in  writ¬ 
ing  (or  FAX)  the  VESA  office.  Reader 
service  no.  31- 
VESA 

1330  South  Bascom,  Ste.  D 
San  Jose,  CA  95128-4502 
408-971-7525  (voice) 

408-286-8988  (FAX) 


A  cooperative  development  effort  to 
provide  field-updatable  BIOS  capabil¬ 
ity  for  AT,  MCA,  and  EISA-based  per¬ 
sonal  computers  has  been  announced 
by  Intel  Corporation  and  Phoenix 
Technologies.  With  Intel’s  1-Mbit  ETOX 
(EPROM  tunnel  oxide)  flash  memories 
and  Phoenix’s  BIOS  and  utility  soft¬ 
ware,  the  need  to  open  the  PC  system 
case  to  swap  BIOS  chips  will  be  elimi¬ 
nated.  (Flash  memory  is  a  high-den¬ 
sity,  electrically  erasable,  nonvolatile 
semiconductor  memory  technology.) 

Dick  Pashley,  general  manager  of 
Intel’s  Flash  Memory  Operation,  claims 
that  users  “will  be  able  to  adapt  their 
existing  PCs  to  accommodate  new  pe¬ 
ripherals  requiring  BIOS  support,  such 
as  disk  drives,  screens,  and  keyboards.” 
Intel’s  28F010  1-Mbit  flash  memories 
have  been  available  since  late  in  1989, 
and  Phoenix’s  new  BIOS  updating  util¬ 
ity  program  should  be  shipping  by  now. 
Both  companies  promise  system  de¬ 
sign  documentation  and  applications 
support.  Reader  service  no.  27.  Contact 
Intel  for  information. 

Intel  Corp. 

Literature  Dept.  #6P19 

3065  Bowers  Ave.,  P.O.  Box  58065 

Santa  Clara,  CA  95052-8065 

A  structuring  utility  to  transform  For¬ 
tran  IV  and  Fortran-77  into  fully  struc¬ 
tured  code  (with  or  without  VAX  and 
Fortran-8x  extensions)  has  been  an¬ 
nounced  by  Cobalt  Blue.  FOR_STRUCT 
vl.l  will  replace  Goto  and  If-Goto  com¬ 
binations  with  If-Then-Else,  Do- While, 
and  Do-Enddos,  and  offers  style  con¬ 
trol  switches  to  allow  visual  customiza¬ 
tion  of  the  structured  code.  According 
to  the  company,  FOR_STRUCT  leaves 
original  programming  logic  intact,  does 
not  duplicate  code,  and  allows  you  to 
remove  dead  code  segments  during 
structuring. 

FOR_STRUCT  offers  three  levels  of 
structuring:  To  Fortran-77;  to  Fortran- 
77  with  VAX  Do- While  and  Do-Enddo 
extensions;  or  to  VAX  Fortran-77  with 
Fortran-8X  extensions.  FOR_STRUCT  is 
compatible  with  Cobalt  Blue’s  FOR_C 
and  FOR_C++  source  code  conversion 
packages.  The  Sun-3  and  Sun-4  ver¬ 
sions  cost  $1850,  Xenix/Unix  is  $1450, 
and  MS-DOS  is  $825.  These  prices  in¬ 
clude  two  months  of  free  technical  sup¬ 
port  and  upgrades.  Combined  product 
discounts  are  also  available.  Reader  ser¬ 
vice  no.  28. 

Cobalt  Blue 
2940  Union  Ave.,  Ste.  C 
San  Jose,  CA  95124 
408-723-0474 

DDJ 
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(continued  from  page  160) 

educational  campaign.  I’d  like  at  this  time  to  share  this  thought  from  one  great  American: 

“I  swore  off  computers  for  about  a  year  and  a  half —  the  end  of  the  ninth  grade  and  all  of  the 
tenth.  I  tried  to  be  normal,  the  best  I  could.  ”  —  Bill  Gates. 

I  know  you  are  with  me  in  praying  that  this  fine  young  man  gets  back  on  the  wagon. 

For  the  technical  community,  the  networks  are  going  to  continue  running  the  thought-provoking 
“This  is  your  CPU  on  bugs”  message.  But  we’re  going  to  keep  the  message  simple  for  the  folks  out 
there  in  the  heartland:  Bugs  Are  Bad. 

In  another  aspect  of  the  educational  prong  of  this  program,  I  am  proposing  the  building  of  8000 
new  jails  nationwide.  Never  underestimate  the  educational  value  of  six  months  in  the  slammer. 

Enforcement:  Get  the  bad  guys.  Education:  Bugs  Are  Bad. 

Third  prong:  Treatment.  I  will  be  presenting  at  SD90  a  budget  of  $600  for  bug  treatment  programs, 
Some  people  will  say  this  is  not  enough.  Some  people  think  you  can  solve  a  problem  by  throwing 
money  at  it,  but  I  think  there  are  better  things  to  throw. 

That’s  the  three-pronged  program.  I’m  pleased  to  announce  that,  to  carry  out  this  ambitious, 
comprehensive  program,  I  have  appointed  my  Cousin  Corbett  to  the  newly  created  post  of  Bug 
Czar.  As  head  of  the  nation’s  bug  eradication  program,  Corbett  will  have  broad  powers,  including 
the  right  to  search  files  without  warrant,  tap  phones,  disassemble  code,  and  break  shrink-wrap 
license  agreements.  I  call  this  the  CRime  And  Punishment,  or  CRAP,  program.  That’s  pronounced 
see-rap.  One  powerful  tool  that  I  am  placing  in  Corbett’s  hands  is  the  proposed  new  legislation 
supporting  mandatory  bug  testing  at  all  places  of  business. 

I  wish  I  could  tell  you  that  we’re  going  to  be  able  to  eliminate  all  bug  use  in  America,  but  that 
would  be  insincere.  We  will  spare  no  expense  to  wipe  out  computer  viruses,  which  are  responsible 
for  fully  one-hundredth  of  one  percent  of  lost  productivity  due  to  bugs.  And  you  can  rest  assured 
that  we  will  lean  heavily  on  the  cheapo  shareware  and  freeware  channels.  I  have  the  notorious 
Richard  Stallman  under  FBI  surveillance  right  now.  But  there  will  be  a  few  common  bugs  that  will 
not  come  under  the  jurisdiction  of  the  BEA.  We  have  no  intention  of  harassing  Microsoft, 
Ashton-Tate,  Lotus,  or  any  other  producer  of  the  fine  software  that  has  made  this  nation  what  it  is 
today.  After  all,  the  occasional  system  crash  is  not  really  a  bug.  We  will,  however,  continue  to 
restrict  use  of  their  products  on  commercial  air  flights. 

Michael  Swaine 
editor-at-large 
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The  War  on  Bugs 


S  W  A  I  N  E'  $  FLAMES 


The  gravest  domestic  threat  facing  our  nation  today  is  software  bugs. 

Oh,  I  could  talk  about  the  deficit,  the  situation  in  Central  America,  the  destruction  of  the 
tropical  rain  forests  and  the  ozone  layer,  the  homeless,  the  victims  of  last  year’s  natural 
disasters,  or  this  year’s  former  employees  of  former  Defense  contractors.  But  what’s  the  point?  I’m 
not  going  to  do  anything  about  any  of  those  problems.  But  when  it  comes  to  bugs,  I  have  a  program. 
Bugs  are  our  most  serious  problem  in  America  today.  Bugs  are  sapping  our  strength  as  a  nation. 
I’m  holding  in  my  hand,  right  now  as  I  type  this  column,  a  bug-infected  diskette,  seized  a  few 
days  ago  by  Bug  Eradication  Administration  (BEA)  agents  in  a  park  right  across  the  street  from  the 
White  House.  Now,  you  may  be  wondering  why  a  bug  pusher  would  be  doing  his  dirty  work  in 
such  an  unlikely  place.  I’ll  tell  you  why.  He  was  there  because  I  instructed  BEA  agents  to  lure  him 
there  and  make  their  bust  there  so  that  I  would  have  a  dramatic  story  to  tell  you. 

The  point  of  the  story  is  this:  Bugs  are  bad.  Bugs  cost  billions  of  dollars  in  lost  productivity.  Bugs 
threaten  the  strength  of  the  family  and  the  happiness  of  our  children.  Walk  into  any  arcade  in  any 
large  city  in  America  and  you’ll  see  innocent  children,  red-eyed  from  crying  because  their  high 
scores  were  erased  by  a  software  bug.  It  just  breaks  my  heart  to  see  that. 

To  combat  this  terrible  menace,  I  have  outlined  and  will  be  presenting  at  Software  Develop¬ 
ment  90  this  month  a  comprehensive  program,  based  on  the  broad  legislative  and  executive  powers 
that  you,  the  software  development  community,  voted  to  give  me  at  last  year’s  SD89. 1  promised 
two  things  last  year:  No  New  Paradigms,  and  to  make  the  streets  safe  for  your  sisters  and  daughters 
to  walk.  My  program,  which  employs  no  new  paradigms,  is  a  street-cleaning,  three-pronged  attack 
in  a  national  war  on  bugs. 

Prong  One:  Enforcement.  We’ve  got  to  make  it  hot  for  the  buglords.  We  know  who  they  are: 
They’re  software  developers.  They  are  the  people  responsible  for  these  terrible  bugs  invading  our 
systems.  Without  them,  there  wouldn’t  be  any  bugs. 

Too  many  people  make  excuses  for  these  bug  pushers.  “Oh,  that’s  not  a  bug,”  they  say,  “that’s 
an  undocumented  feature.”  Or,  “That’s  how  the  product  is  supposed  to  work;  it’s  in  the 
documentation.”  Well,  those  excuses  aren’t  going  to  work  any  more.  I  will  be  recommending 
passage,  by  the  attendees  of  the  conference,  of  the  Zero  Tolerance  Act  for  software  bugs.  Under 
this  act,  software  written  after  April  1, 1990  must  contain  no  bugs.  To  facilitate  this  plan,  I  will  be 
presenting  further  legislation  requiring  that  any  software  covered  by  the  legislation  and  released 
after  April  1, 1990,  be  written  in  Ada.  This  will,  my  advisors  tell  me,  guarantee  zero  software  bugs. 
This  legislation  calls  for  mandatory  jail  sentences  for  anyone  programming  in  any  other  language 
than  Ada.  This  will  be  implemented  in  an  innovative  six-and-six  program:  Six  months  on  arrest, 
and  another  six  months  if  convicted.  If  I’ve  heard  one  thing  from  the  law-enforcement  community, 
it’s  that  they’re  tired  of  having  the  courts  release  the  criminals  they  arrest.  This  program  should  be 
a  step  in  the  right  direction. 

Forth  programmers  will  be  shot. 

And  I’m  not  forgetting  the  victims  of  the  buglords:  The  users  of  buggy  software.  We’re  going  to 
get  them,  too.  I’m  also  presenting  at  SD90,  as  part  of  my  comprehensive  program,  a  far-reaching 
Victim  Incarceration  Program,  or  VIP,  that  will  make  it  a  criminal  offense  to  knowingly  use  buggy 
software.  That  ought  to  bring  the  message  home  to  everybody.  The  key  here  is,  we  all  have  to  take 
responsibility  for  our  actions. 

I’m  calling  on  all  patriotic  Americans  to  do  their  part.  If  you  suspect  someone  in  your  workgroup 
of  using  buggy  software,  call  this  toll-free  number:  1-800-BUG-ABOO. 

And  don’t  be  deterred  by  the  fact  that  the  user  is  a  member  of  your  family.  Sure,  we  can  clean 
up  the  streets  and  the  offices  of  America,  but  it  won’t  do  much  good  unless  we  clean  up  the  families, 
too.  Let’s  crush  those  bugs  and  put  family  values  back  into  the  family. 

Prong  Two:  Education.  I  have  outlined  and  will  be  presenting  at  SD90  a  comprehensive, 
broad-bandwidth  program  of  public  bug  education.  The  program  is  called  BAB:  Bugs  Are  Bad.  I 
am  gratified  to  announce  that  I  have  secured  the  cooperation  of  all  the  major  television  networks. 
This  next  season,  all  sitcoms,  all  miniseries,  and  all  docudramas  will  carry  the  message  to  the 
American  people:  Bugs  Are  Bad.  All  network  news  programs  will  concentrate  on  software  bug 
stories.  And  most  important,  major  sports  and  entertainment  figures  have  joined  with  me  in  this 

(continued  on  page  158) 
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Patent  Letter 
Suits 


L 


f  ark  Nelson’s  article  on  the  LZW  data  compression  algorithm  (DDJ  October,  1989)  sparked  a 
j\/|  forest  of  fires,  at  least  in  respect  to  patenting  algorithms.  The  first  spark,  if  you  recall,  was  a 
i  *  A  letter  from  Ray  Gardner,  pointing  out  that  the  LZW  algorithm  was  patented  by  Unisys  back 
in  1985  (see  “Letters,”  December  1989).  Mark’s  response  answered  a  few  questions  but  raised 
several  more. 

About  the  time  we  published  Ray’s  letter  and  Mark’s  reply,  the  U.S.  Court  of  Appeals  settled  a 
dispute  between  the  U.S.  Patent  Office  and  Sharp  Corporation  in  a  case  that  revolved  around  Sharp’s 
patent  application  for  a  voice-recognition  circuit.  The  Patent  Office  had  rejected  Sharp’s  original 
application  in  part  because  they  felt  the  circuit’s  only  purpose  was  to  execute  an  algorithm.  And, 
the  Patent  Office  insisted,  algorithms  can’t  be  patented  because  they  are  nothing  more  than 
mathematical  abstractions.  Furthermore,  the  Patent  Office  felt  that  Sharp  was  trying  to  patent  every 
possible  means  of  implementing  the  algorithm,  not  just  the  way  it  was  used  in  this  particular 
voice-recognition  circuit. 

As  it  turned  out,  the  Court  of  Appeals  didn’t  agree  with  the  Patent  Office.  The  court  said  that  an 
algorithm  can  be  safeguarded,  at  least  as  how  it  is  used  to  describe  a  physical  device  (like  a  circuit) 
or  in  terms  of  other  functional  equivalents  of  that  algorithm. 

To  better  come  to  grips  with  this  issue,  I  called  Charles  Gorenstein,  the  Falls  Church,  Virginia 
attorney  who  represented  Sharp.  Early  in  our  conversation,  Mr.  Gorenstein  stated  that  “a  purely 
mathematical  algorithm  is  probably  not  patentable”  but,  he  added,  the  specific  methods  of 
implementing  an  algorithm  are  patentable.  In  other  words,  what  is  patentable  is  the  method,  not 
the  math.  If  someone  developed  a  different  circuit  to  execute  Sharp’s  voice-recognition  algorithm, 
that’s  fine  and  dandy.  And  apparently  that’s  part  of  the  basis  of  the  Court  of  Appeal’s  decision. 

Key  to  any  patent  grant  is  the  concept  of  “new  and  unobvious,”  an  area  that  Mr.  Gorenstein  feels 
the  Patent  Office  has  overlooked.  Using  a  1979  patent  for  spreadsheets  as  an  example,  he  explained 
that  just  about  anyone  with  a  ledger,  a  pencil,  and  some  data  would  fill  out  the  rows  and  columns 
in  much  the  same  way  as  they  would  with  an  electronic  spreadsheet.  A  ledger  —  and  a  spreadsheet  — 
is  obvious.  He  therefore  questions  whether  the  spreadsheet  patent  should  ever  have  been  granted. 
This  question  of  “obvious”  raises  another  important  issue.  What  may  be  unobvious  to  those  in  the 
Patent  Office  may  very  well  be  obvious  to  technically  sophisticated  programmers  like  DDJ  readers. 

What  all  this  leads  up  to  is  a  letter  I  received  from  Bob  Bramson,  the  Unisys  patent  attorney  Mark 
mentioned  in  his  response.  I  won’t  give  a  blow-by-blow  account  of  the  letter,  you  can  read  it  for 
yourself  on  page  8,  the  first  entiy  in  this  month’s  “Letters”  section. 

I  will  say  that  the  letter  is  a  politely  worded  clarification  of  Unisys’s  patent  on  the  LZW  algorithm, 
with  only  a  slight  sense  of  the  steel  behind  it,  at  least  in  reference  to  Unisys’s  intention  of  going 
after  infringers. 

I’m  sorry,  but  I  still  don’t  understand.  It  seems  that  if,  as  I  think  the  court  ruled,  you  can  use 
Sharp’s  algorithm  to  design  a  different  voice-recognition  circuit,  you  should  be  able  to  use  Sharp’s 
(or  Unisys’s  or  anyone  else’s)  algorithm  for  an  entirely  different  purpose  than  it  is  used  in  the 
original  patent.  That  is,  you  should  be  able  to  use  the  LZW  algorithm  in  a  program  that  has  nothing 
to  do  with  telecommunications  or  modems.  This  assumes,  of  course,  that  Unisys’s  patent  is  for  the 
modem  and  the  algorithm  as  it  helps  define  the  modem.  I  agree  with  Mark.  Unisys  will  indeed  be 
very  busy  tracking  down  programmers  who  have  implemented  some  form  of  the  LZW  algorithm. 

I’m  all  for  any  company,  large  or  small,  taking  steps  to  protect  R&D  investments  that  give  it  a 
competitive  edge.  But  it’s  distasteful  for  large  companies  to  threaten  smaller  outfits  with  litigation 
that  can’t  be  won  in  the  courts,  but  can  be  outlasted  by  a  large  company  with  the  resources  to  do 
so.  Now  I’m  not  in  any  way  suggesting  this  is  Unisys’s  ploy,  nor  does  Mr.  Bramson  even  hint  at  this, 
it’s  far  too  often  the  way  the  world  works. 

In  his  response  to  the  letter  that  started  all  of  this,  Mark  suggested  that  software  developers  who 
intend  on  using  patented  algorithms  (like  LZW)  in  commercial  products  get  some  legal  advice 
before  proceeding.  Mr.  Gorenstein  seconded  this,  even  to  the  point  of  suggesting  that  programmers 
do  a  patent  search  prior  to  implementation.  While  this  advice  is  sound  and  safe,  it  is  also  lengthy 
and  expensive,  luxuries  that  software  developers  usually  can’t  enjoy. 

Today’s  mail  didn’t  bring  a  letter  from  a  lawyer,  but  it  did  include  a  letter  from  Dan  Abelow,  a 
Newton,  Massachusetts  reader  who  specializes  in  analyzing  emerging  technologies,  and  who, 
coincidentally,  proposes  to  write  an  article  on  “Enabling  Patents.”  He  calls  the  topic  a  “blossoming 
controversy  [that]  has  failed  to  germinate  positive  suggestions”  and,  from  what  I  can  tell,  he’s 
making  a  case  that  software  patents  may  actually  encourage  innovation  and  invention.  I  don’t  know 
that  I  agree  with  him,  but  I’m  curious  enough  to  give  him  a  call  and  find  out  what  he  has  in  mind. 


Jonathan  Erickson 
editor-in-chief 
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Patented  Algorithms 

Dear  DDJ , 

In  the  “Letters”  column  of  your  De¬ 
cember  1989  issue,  Mark  Nelson  dis¬ 
cusses  U.S.  Patent  4,558,302  entitled 
“High  Speed  Data  Compression  and 
Decompression  Apparatus  and  Method.” 
This  patent  was  developed  by  Terry 
Welch,  a  former  Unisys  employee,  and 
is  owned  by  Unisys.  According  to  Mr. 
Nelson,  I  have  been  quoted  as  saying 
that  Unisys  will  “license  the  algorithm 
for  a  one  time  fee  of  $20,000.”  As  a 
concession  to  the  modem  industry,  Uni¬ 
sys  has  agreed  to  license  the  patent  to 
modem  manufacturers  for  use  in  mo¬ 
dems  conforming  to  the  V42.bis  data 
compression  standard  promulgated  by 
CCITT,  for  a  one-time  fee  of  $20,000. 
This  $20,000  license,  however,  is  not  a 
general  license  under  all  applications 
of  our  patent  but  is  limited  to  the  spe¬ 
cific  application  discussed  above. 

Responding  to  the  second  paragraph 
of  Nelson’s  remarks,  Unisys  is  actively 
looking  into  the  possibility  that  a  large 
number  of  software  developers  may 
be  infringing  one  or  more  of  our  data 
compression  patents.  We  have  only  re¬ 
cently  become  aware  of  these  potential 
infringers  and  the  process  of  taking 
action  will  take  some  time. 

Unisys  is  happy  to  accept  inquiries 
from  persons  interested  in  acquiring  a 
license  to  U.S.  Patent  4,558,302.  If  your 
readers  have  any  further  questions,  they 
should  contact  Mr.  Edmund  Chung  of 
our  licensing  office,  at  313-972-7114. 

Robert  S.  Bramson 

Unisys 

Blue  Bell,  Penn. 

Say  It  Ain’t  So 

Dear  DDJ, 

Dan  W.  Crockett’s  assertion  in  the  Janu¬ 
ary  1990  DDJ  “Letters”  section  that  struc¬ 
tured  programming  requires  that  each 
functional  node  (or  implementation 
unit)  have  only  a  single  parent  is  alarm¬ 
ing,  and  damned  difficult  to  program 


in  the  real  world.  I  think  that  he  inter¬ 
prets  the  abstract  requirements  of  struc¬ 
tured  programming  a  little  too  literally 
when  it  comes  to  coding. 

As  an  example,  consider  a  Pascal 
function,  which  formats  dollar  amounts 
for  output.  The  function  might  take  a 
real  dollar  argument  and  translate  it  to 
a  “ $nnn,nnn,  .  .  .  ,nnn.nn"  format,  and 
be  declared  as  function  DollarFmt(v  : 
reaO.string;  The  whole  point  of  hav¬ 
ing  the  function  is  that  it  can  be  called 
from  any  procedure  or  function  in  a 
program;  if  the  dollar  amounts  are  for¬ 
matted  incorrectly  we  can  first  check 
to  see  if  the  error  lies  in  DollarFmt, 
because  it  is  solely  responsible  for  per¬ 
forming  the  task. 

This  is  structured  programming:  Break¬ 
ing  down  a  task  into  smaller  and  smaller 
(and  finally,  logically  indivisible)  subtasks. 
Subtasks  which  perform  similar  or  iden¬ 
tical  tasks  can  then  be  coded  as  a  single 
(probably  parameterized)  routine. 

Mr.  Crockett  wants  program  struc¬ 
ture  to  be  a  B,  Quad,  or  whatever  tree, 
which  is  fine,  but  reality  demands  that 
the  implementation  be  a  threaded  tree. 
Under  the  Crockett  scheme  we  would 
be  forced  to  write  a  separate  DollarFmt 
for  each  caller  ( Amount Due_DollarFmt, 
AmountPaid_DollarFmt,  ad  nauseam )! 
The  resulting  plethora  of  duplicate  rou¬ 
tines  would  produce  a  worse  debug¬ 
ging  situation  than  Mr.  Crockett  thinks 
he’ll  have  already  —  never  mind  the 
maintenance  nightmare. 

The  “single”  restriction  staictured  pro¬ 
gramming  is  the  requirement  that  a  sin¬ 
gle  functional  node  not  have  more  than 
one  entry  point  within  it-,  which  is  to 
say  that  all  callers  must  enter  through 
the  same  door.  It  is  perfectly  reason¬ 
able  for  a  routine  to  have  more  than 
one  caller  —  without  multiple  callers 
there  would  be  little  reason  for  build¬ 
ing  a  distinct  procedure  or  function  for 
performing  the  task. 

Going  back  to  the  DollarFmt  exam¬ 
ple:  The  structural  decomposition  of  a 
hypothetical  bill  printing  task  might  be 


List  Line  Items 
I 

Format  Line  Item 
I 

Format  Amt 
I 

Print  Item  &  Amt 


Print  Bill 


Calculate  Interest 
I 

Format  Interest 
I 

Print  Interest 
I 

etc. 


Calculate  Sum 
I 

Format  Sum 
I 

Print  Sum 
I 

etc. 


It  is  (hopefully)  obvious  that  “Format 
Amt,”  “Format  Interest, ’’and  “Format 
Sum”  should  be  programmed  as  calls 
to  a  single  formatting  routine,  even 
though  they  are  different  tasks  in  the 
abstract. 

There  are  dangers  in  interpreting  any 


abstraction  too  literally.  And  there  is 
that  other  thing,  in  the  word  of  Will 
Rogers:  “It’s  not  what  we  don’t  know 
that  hurts,  it’s  what  we  know  that  ain’t 
so.” 

Brook  Monroe 
Durham,  North  Carolina 

Locator  Fix 

Dear  DDJ, 

The  listing  of  Mark  Nelson’s  “Locate 
tool”  in  the  January  1990  issue  has  a 
bug  in  the  read_header_data  proce¬ 
dure:  It  occurs  in  his  calculation  of 
image_size.  The  line: 

image_size  =  (header.file_ 

size_in_pages  - 1)  *  512; 

should  be  replaced  with: 

if  (header.  image_length_mod_5 12 

=  =  0) 

image_size  =  header.file_ 

size_in_  pages  *  512; 

else 

image_size  =  (header.file_ 

size_in_pages  - 1)  *  512; 

The  bug  occurs  when  the  actual  image 
size  is  an  even  multiple  of  512  bytes. 
As  an  example,  consider  an  image  size 
of  1526  (512  *  3).  In  this  case, 
header_file_size_in_  pages  would  be 
three  and  header.image_length_mod_ 
572would  be  zero.  Mark’s  code  would 
produce  an  incorrect  size  of  1024  due 
to  the  decrement  of  header.file_size_ 
in_  pages. 

I  had  the  opportunity  of  stumbling 
into  this  when  writing  a  combination 
.EXE  loader/relocator/unrelocator  for 
a  non-DOS-based  embedded  control 
system. 

Thank  you  for  your  time  and  keep  the 
interesting  articles  like  Mark’s  coming. 
Bill  Trutor 
Holden,  Mass. 

Mark  responds:  Bill  has  correctly  iden¬ 
tified  a  mistake  in  my  program.  I  think 
I  might  have  avoided  this  mental  error 
with  better  naming  of  structure  mem¬ 
bers.  In  any  case,  this  is  one  of  those 
program  errors  that  occurs  so  infre¬ 
quently  (1  out  of  512  links)  that  it  can 
be  extremely  elusive,  so  thanks  to  Bill 
for  pointing  it  out. 

Data  Structure  Dream  Machine 

Dear  DDJ, 

In  Jeff  Duntemann’s  column  in  the  De¬ 
cember  1989  issue  of  DDJ,  he  men¬ 
tioned  his  dream  system  under  Win¬ 
dows  386. 1  have  a  question  about  this. 
I  understand  the  languages  and  the 
PageMaker  part,  but  could  he  expand 
(continued  on  page  12) 
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(continued  from  page  8) 
on  using  Paradox?  Do  I  understand 
him  to  mean  that  you  use  it  to  keep 
track  of  details  about  your  data  struc¬ 
tures?  Sounds  interesting;  could  he  elabo¬ 
rate? 

Guy  Townsend 

CIS  73040,1671 

Jeffs  response:  Hate  to  be  a  spoilsport, 
but  mostly  what  I  use  Paradox  for  is  to 
keep  my  various  contact  files  a  key¬ 
stroke  away.  The  notion  of  using  a 
real-relational  database  to  manage  the 
gritty  details  of  major  development  pro¬ 
jects  is  a  good  one,  but  the  language 
vendors  are  going  to  have  to  do  the 
integration  between  the  tools  and  the 
database.  Some  major  vendors  are  in¬ 
deed  working  on  this,  (still  secretly) 
and  you  ’ll  be  seeing  the  results  in  DDJ 
when  they  surface. 

Intek  Heard  From 

Dear  DDJ, 

From  time  to  time  you  must  hear  from 
disgruntled  companies  who  feel  that 
they  have  suffered  at  the  hands  of  one 
of  your  writers  performing  a  post¬ 
mortem  with  an  axe. 

Knowing,  however,  that  Al  Stevens 
is  a  venerable  pilgrim  to  the  hallowed 
halls  of  Bell  Labs  and  a  proponent  of 
the  object-oriented  paradigm,  we  sup¬ 
pose  that  his  summarial  execution  of 
our  product  was  caused  by  a  bit  of 
underdone  potato. 

In  his  November  “C  Programming” 
column,  just  after  explaining  to  his  read¬ 
ership  that  he  was  neither  rigorous  nor 
controlled,  he  set  about  to  describe  the 
available  C++  compilers  and  transla¬ 
tors  available  for  DOS.  Without  rigor 
or  control  he  dismissed  our  Intek  C++ 
product  without  evaluating  the  prod¬ 
uct  at  all!  He  chose  instead  to  fault  an 
example  program  that  we  provide  with 
our  distribution  of  the  AT&T  translator. 
This  example  program  (which  we  sup¬ 
ply  the  source  to  in  the  product  distri¬ 
bution)  invokes  the  C  preprocessor, 
the  C++  translator,  and  the  target  C 
compiler  in  succession.  We  supplied  it 
to  provide  our  customers  with  a  con¬ 
venient  method  of  progressing  from 
source  to  executable  if  they  were  in¬ 
voking  from  the  command  line.  The 
mentioned  bug  occurred  only  with  DOS 
3.3,  and  as  with  all  software  companies 
that  stand  behind  their  product  with 
integrity,  we  supplied  the  fix  to  all  of 
our  customers  long  before  Al’s  column 
went  to  print.  Of  course,  Al  didn’t  men¬ 
tion  that  other  translator  products  don’t 
offer  anything  like  this  and  certainly  don’t 
supply  the  source  to  such  a  program. 

Did  Al  mention  that  the  near,  far, 
huge,  pascal,  fortran,  and  cdecl  key- 
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words  don’t  work  with  the  AT&T  distri¬ 
bution  or  with  some  other  translator 
products  but  that  they  do  with  Intek 
C++?  No.  Ever  tried  to  use  a  third  party 
header  file  with  some  of  these  keywords 
in  it  or  try  to  link  to  a  library,  expecting 
the  results  of  these  modifiers,  Al? 

Did  Al  mention  that  if  one  tried  to 
compile  any  production  size  C++  source 
modules  with  other  products  that  they 
would  run  out  of  memory?  No.  Maybe 
he’d  rather  make  sure  that  all  of  his 
source  files  were  less  than  4K  in  size 
and  that  he  could  only  include  three 
or  less  header  files. 

Did  Al  benchmark  the  fact  that  the 
only  product  from  among  the  group 
that  he  mentioned  that  will  compile  the 
AT&T  C++  source  distribution  is  Intek 
C++?  No.  (That’s  AT&T’s  definition  of 
the  robustness  of  a  C++  translator  im¬ 
plementation  by  the  way.) 

Please  assure  Al  that  Intek  C++  will 
continue  to  have  a  future  in  the  PC 
world.  Our  client  list  has  many  of  the 
Fortune  500  firms  among  it.  We  also 
use  our  own  product  in  providing  fac¬ 
tory  automation  applications  to  the  ma¬ 
jor  workstation  and  computer  manu¬ 
facturers  in  the  country. 

We  feel  like  you  would  feel  if  in  a 
review  of  magazines  Dr.  Dobb's  was 
dismissed  as  not  being  a  quality  soft¬ 
ware  tools  magazine  because  it  sounds 
like  it  should  be  a  medical  journal. 

Mac  Cutchins 

Intek 

Bellevue,  Wash. 

Al  responds:  My  evaluation  of  Intek 
C++  consisted  at  first  of  the  seemingly 
simple  task  of  getting  it  to  compile  the 
hello. cpp  program  that  comes  with  the 
translator.  “Hello,  world,  "nothing  more, 
right  out  of  the  box.  That  simple  task 
involved  two  days  of  frustration  and 
several  phone  calls  to  Intek. 

The  Intek  technical  support  person 
at  first  insisted  that  there  was  some¬ 
thing  wrong  with  my  setup.  The  nature 
of  the  bug  —  the  translator  worked  ev¬ 
ery  other  time — encouraged  both  of 
us  to  believe  that.  The  compiler  failed, 
I  called,  he  made  a  suggestion,  the 
compiler  worked.  I  hung  up,  the  com¬ 
piler  failed,  I  called,  and  so  on.  One  of 
those  times  we  changed  operating  sys¬ 
tems,  and  the  technical  support  person 
concluded  that  my  copy  of  DOS  3-3 
was  the  culprit.  He  must  have  remem¬ 
bered  that  episode  and  subsequently 
convinced  you,  Mr.  Cutchins,  but  not 
me.  The  bug  was  identical  for  DOS 
Versions  3-0,  3-2,  3-3,  and  4.0.  Under 
3-1,  the  bug  is  different,  and  hello. cpp 
just  never  compiles.  When  I  reported 
these  findings,  your  technical  support 
person,  by  now  tired  of  hearing  from 


me,  curtly  announced  that  there  must 
be  some  problem,  that  it  would  get fixed, 
goodbye,  and  thank  you  very  much.  If 
you  fixed  that  bug,  I  never  heard  about 
it,  before  or  after  my  column  went  to 
print.  Until  now,  that  is.  I  guess  as  a 
pesky  magazine  columnist  with  a  free 
review  copy  of  your  pricey  product,  I 
don ’t  rate  an  upgrade.  Never  once  dur¬ 
ing  all  those  calls  did  Intek  suggest  that 
I  abandon  the  “example”  CPLUS pro¬ 
gram  and  use  the  lower-level  programs, 
which  I  now  see  is  the  obvious  solution. 

In  my  opinion,  Intek  C++  is  under¬ 
packaged  and  over-priced.  The  skimpy 
40-page  spiral-bound  manual  devotes 
only  10  pages  to  installing  and  using 
the  translator,  has  exactly  two  sentences 
about  using  it  with  Turbo  C,  has  some 
critical  typos  (the  C_COMPILER  envi¬ 
ronment  variable  is  misspelled,  for  ex¬ 
ample),  and  never  lets  on  that  the  CPLUS 
program  is  a  mere  example  to  be  used 
at  one’s  own  risk.  Intek  C++  fails  to 
measure  up  to  the  standards  of  quality 
that  PC  programmers  have  come  to 
expect  in  their  language  products.  My 
assessment  of  your  future  in  the  PC 
market  was  based  on  my  view  of  the 
cost  and  quality  of  the  Intek  C++  soft¬ 
ware,  documentation,  and  support  and 
of  the  expensive  hardware/software  foun¬ 
dation  necessary  to  use  it.  I  stand  by 
that  assessment.  If  you  believe  that  In- 
tekC++  has  improved  substantially  since 
my  evaluation  of  it,  I’ll  be  pleased  to 
give  it  another  look. 

Round  and  Round  We  Go 

Dear  DDJ 

Recently  I  completed  a  graphics  course, 
so  I  read  with  interest  the  January  issue 
article  by  Robert  Zigon  dealing  with 
generation  of  circles.  I  found  the  article 
to  be  a  clear  and  well  written  exposi¬ 
tion  of  the  problem.  However,  any  al¬ 
gorithm  based  upon  the  parametric  rep¬ 
resentation  of  a  circle  must  involve  sig¬ 
nificant  overhead  in  the  form  of  floating¬ 
point  calculations.  A  superior  algorithm 
developed  by  J.E.  Bresenham  some 
years  ago  avoids  such  overhead. 

The  Bresenham  algorithm  makes  use 
of  the  fact  that  screen  coordinates  are 
integer  valued,  so  it  should  be  possible 
to  select  the  circle’s  coordinates  using 
only  integer  arithmetic  as  well.  Use  of 
only  integer  arithmetic  is  the  key  to  the 
efficiency  of  the  algorithm.  The  algo¬ 
rithm  is  used  to  advance  along  the  pe¬ 
rimeter  of  the  circle,  selecting  the  adja¬ 
cent  pixel  which  is  nearest  to  the  circle 
at  each  step.  Because  of  circular  sym¬ 
metry,  it  suffices  to  determine  only  one- 
eighth  of  the  circle  using  this  tech¬ 
nique. 

An  excellent  derivation  of  the  algo- 
(continued  on  page  14) 

Dr.  Dobb’s  Journal,  March  1990 

203 


Dr.  Dobb’s 


JOURNAL 


PUBLISHER  Peter  Hutchinson 


SOFTWARE 


TOOLS  f  OR  THE 


PROFESSIONAL 


PROGRAMMER 


EDITORIAL 

EDITOR-IN-CHIEF  Jonathan  Erickson 
MANAGING  EDITOR  Monica  E.  Berg 
TECHNICAL  EDITORS  Michael  Floyd,  Ray  Valdes 
EDITORIAL  ASSISTANT  Janna  Custer 
CONTRIBUTING  EDITORS  Al  Stevens, 

Jeff  Duntemann,  Martin  Tracy,  David  Betz, 

Tom  Genereaux,  Andrew  Schulman 
COPY  EDITORS  Rhoda  Simmons, 

Pamela  Dillehay,  Nan  Fornal 
EDITOR-AT-LARGE  Michael  Swaine 


ART/PRODUCTION 

ART/PRODUCTION  DIRECTOR  Larry  L.  Clay 
ART  DIRECTOR  Michael  Hollister 
PRODUCTION  SUPERVISOR  Amy  Shulman  Lesovoy 
TECHNICAL  ILLUSTRATOR  Linda  Ann  Clark 
TYPOGRAPHERS  Teresa  Raines, 

Margaret  Anderson,  Charlene  Carpentier 
COVER  PHOTOGRAPHER  Michael  Carr 


CIRCULATION 

DIRECTOR  OF  CIRCULATION  Maureen  Kaminski 
CIRCULATION  MANAGER  Randy  Robertson 
CIRCULATION  PLANNING  MANAGER  Manny  Sawit 
DIRECT  MARKETING  MANAGER  Andrea  Weingart 
NEWSSTAND  MANAGER  Sarah  Forsman 
DIRECT  MARKETING  COORDINATOR  Francesca  Davies 
PROMOTION  COORDINATOR  Pam  Moore 
FULFILLMENT  COORDINATOR  Anne  Jean 


ADMINISTRATION 

VICE  PRESIDENT  OF  FINANCE  Kate  Deschamps 
CONTROLLER  Mary  Collopy 
CREDIT  MANAGER  Betty  Arsene 
ACCOUNTING  SUPERVISOR  Renate  Kernke 
ACCOUNTS  RECEIVABLE  Wendy  Ho 
ACCOUNTS  PAYABLE  LuAnn  Rocklewitz 


MARKETING/ADVERTISING 

DIRECTOR  OF  SALES  AND  MARKETING 
Karla  Spormann 

ADVERTISING  COORDINATOR  Laura  Stack  Pullen  . 
MARKETING  ASSISTANT  Sara  Noah  Ruddy 
ACCOUNT  MANAGERS  see  page  152 


M&T  PUBLISHING  INC. 

CHAIRMAN  OF  THE  BOARD  Otmar  Weber 
DIRECTOR  C.  F  von  Quadt 
PRESIDENT  Laird  Foshay 

VICE  PRESIDENT  OF  PUBLISHING  William  P.  Howard 
VICE  PRESIDENT/GROUP  PUBLISHER 
Randall  L.  Stickrod 


DR.  DOBBS  JOURNAL  (USPS  307690)  is  published  monthly,  ex¬ 
cept  semimonthly  in  December,  by  M&T  Publishing,  Inc.,  501 
Galveston  Dr.,  Redwood  City,  CA  94063:  415-366-3600.  Second- 
class  postage  paid  at  Redwood  City  and  at  additional  entry  points. 

ARTICLE  SUBMISSIONS:  Send  manuscripts  and  disk  (with  article 
and  listings)  to  the  editorial  assistant  415-366-3600. 

DDJ  ON  COMPUSERVE:  Type  GO  DDJ. 

DDJ  LISTING  SERVICE:  603-882-1599.  Supports  300/1200/2400 
baud,  8-data  bits,  no  parity,  1-stop  bit.  Type  listings  (use  lowercase) 
at  the  login  prompt. 

SUBSCRIPTION:  $29-97  for  1  year;  $56.97  for  2  years.  Foreign 
orders  must  be  prepaid,  including  the  additional  postage  (air  or 
surface)  in  U.S.  funds  drawn  on  a  U.S.  bank.  Add  $13  for  surface 
mail  to  all  addresses  out  of  the  U.S.;  add  $33  for  airmail  to  Canada 
and  Mexico;  or  $32  for  airlift  to  all  other  countries. 

POSTMASTER:  Send  address  changes  to  Dr.  Dobb's Journal ,  P.O. 
Box  56188,  Boulder,  CO  80322-6188.  ISSN  1044-789X 
CUSTOMER  SERVICE:  For  subscription  orders,  questions,  and 
changes  of  address  call  toll-free  800-456-1215  (U.S.  and  Canada) 
or  write  Dr  Dobb  's  Journal,  P.O.  Box  56188,  Boulder,  CO  80322- 
6188.  For  book/software  orders  call  800-533-4372  (in  California 
800-356-2002). 

FOREIGN  NEWSSTAND  DISTRIBUTOR:  Worldwide  Media  Ser¬ 
vice  Inc.,  115  E.  23rd  St.,  New  York,  New  York  10010;  212-420-0588 
FAX  212-420-1265. 

Entire  contents  copyright  ©1990  by  M&T  Publish-  __  The 

ing,  Inc.,  unless  otherwise  noted  on  specific  Audit 

articles.  All  rights  reserved.  -P  Bureau 


L  E  T  T  E  R  S 


(continued  from  page  12) 
rithm  is  given  in  the  text  Computer 
Graphics  by  Donald  Hearn  and  M. 
Pauline  Baker  (Prentice  Hall,  1986).  The 
derivation  depends  only  upon  elemen¬ 
tary  algebra,  but  may  require  some¬ 
what  greater  mathematical  maturity  due 
to  the  notation  used.  The  text  also  pre¬ 
sents  Pascal  code  for  the  algorithm. 
Another  reference,  which  gives  a  lim¬ 
ited  explanation  and  a  C  code  implemen¬ 
tation  of  the  algorithm,  but  which  does 
not  attempt  to  derive  the  algorithm,  is 
Graphics  Programming  in  C  by  Roger 
T.  Stevens  (M&T  Books,  1988). 

Joseph  M.  Hovanes  Jr. 

Pittsburgh,  Pennsylvania 


Forth  Fan 

Dear  DDJ , 

Here’s  20  cents  to  fan  the  Flames  of 
T.S.  Kuhn’s  book,  The  Structure  of  Sci¬ 
entific  Revolutions.  It  caused  me  to  go 
cold  turkey  re.  the  tube  for  three  days. 

Martin  Tracy  reaffirmed  my  belief  that 
Forth  in  its  dialects  offers  the  best  pres¬ 
ently  available  forum  for  discussion  of 
“discrete  mathematics”  and  the  founda¬ 
tions  of  computing  science.  But  I  would 
like  to  see  his  work  in  the  form  of  a 
bootable  operating  system  and  not  a  guest 
under  another  commercial  product. 

I  confess  that  my  own  present  work, 
“simpli-Forth,”  which  is  strongly  tied 
to  the  6502,  still  requires  a  fig-Forth 
boot  to  get  off  the  ground.  Perhaps  if  I 
work,  I  can  learn  enough  about  target 
compilers  to  create  my  own  boot  codes. 

It  seems  to  me  that  small  operating 
systems  with  too-early  emphasis  on  hid¬ 
ing  or  transportability  may  not  be  in 
the  best  interest  of  learners  who  seek 
to  know  in  detail  how  their  computing 
systems  work.  I  would  like  to  see  small 
Forth  systems  place  the  user  in  a  pro¬ 
gramming  environment  which  makes 
plain  the  processes  of  his  machine. 
That  is  why  calls  to  DOS  seem  mis¬ 
placed  to  me;  I’d  prefer  that  all  of  a 
small  Forth  system  be  available  to  the 
decompiler  and  user. 

Would  not  a  system  for  the  program¬ 
ming  of  “smart”  peripherals  be  more 
useful  and  general  by  omission  of  read¬ 
only  memory?  One  could  imagine  modi¬ 
fied  error-handling,  perhaps  by  redi¬ 
recting  the  error-message  stream  to  the 
calling  device  and  transmitting  a  raise- 
error-request  to  it.  But  I  remain  con¬ 
vinced  that  the  “smart”  external  should 
be  executing  a  standard  and  expand¬ 
able  Forth  kernel,  albeit  a  minimal  one, 
and  that  communication  with  it  should 
be  in  the  form  of  a  standard,  inter¬ 
preted  input  stream. 

The  user  of  such  a  device  could  then 
load  codes  indicating  how  the  forth¬ 


coming  data  is  to  be  handled,  followed 
by  the  commands  to  be  executed  and 
the  data  (e.g.,  80  PRINTLINE  THE 
QUICK  BROWN  FOX  JUMPS  OVER  .  ..). 
At  the  end  of  such  a  session,  some 
command  such  as  DONE  would  then 
forget  the  loaded  object-behavior  back 
to  that  formerly  executing.  Instead  of 
relying  on  ROM  to  make  our  machines 
robust  we  would  enter  a  new  arena  of 
opportunity  for  flexibility.  It  is  time  for 
a  generation  of  peripherals  which  can 
follow  the  lead  and  dance. 

On  another  subject,  Brodie  encour¬ 
ages  us,  “Use  dumb  words.”  One  of 
the  major  differences  between  fig-Forth 
and  Forth-83  is  in  the  use  of  the  STATE 
variable  and  its  effect  on  words  such 
as  ’  and  LITERAL.  In  the  process  of 
learning  to  use  STATE-sensitive  words 
correctly,  I,  too,  have  been  hopelessly 
confused  from  time  to  time.  But  the 
fully  interactive  capabilities  possible  in 
a  modern  Forth  machine  may  require 
STATE-sensitive  behavior. 

For  this  reason  I  chose  to  write  SIF 
(STATE  @  IF)  which  may  be  used: 

:  TEST  SIF  COMPILE  THEN  DO-IT  ; 

IMMEDIATE 

which  will  cause  TEST  to  compile  DO¬ 
IT  if  compiling  else  execute  it  (COM¬ 
PILE  is  not  IMMEDIATE).  Although  this 
example  makes  TEST  equal  to  DO-IT, 
more-useful  examples  can  be  drawn. 
Another  word  might  be  PCOMPILE  that 
would  combine  the  effects  of  SIF,  THEN, 
and  IMMEDIATE  and  be  used:  :  TEST 
PCOMPILE  DO-IT  ;  so  that  all  words 
using  PCOMPILE  would  automatically 
be  made  IMMEDIATE. 

“Use  dumb  words”  is  sound  advice. 
But  some  quite  interesting  capabilities 
arise  only  when  one  uses  correctly 
written  words  with  STATE-sensitive 
behavior. 

Jon  W.  Osterlund 

Greeley,  Colo. 

DDJ 

We  welcome  your  comments  (and  sug¬ 
gestions).  Mail  your  letters  (include  disk 
if  your  letter  is  lengthy  or  contains  code) 
to  DDJ,  501  Galveston  Dr.,  Redwood 
City,  CA  94063,  or  send  them  electroni¬ 
cally  to  CompuServe  76704,50  or  via 
MCI  Mail,  c/o  DDJ .  Please  include  your 
name,  city,  and  state.  We  reserve  the 
right  to  edit  letters. 
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Assembly  Language 

Lives! 


More  Speed,  Less  Filling 


Michael  Abrash 


here’s  an  old  joke  that  goes  something  like  this: 

Person  #1 :  Help!  My  brother  thinks  he’s  a  chicken,  and 
I  don’t  know  what  I  should  do. 

Person  #2:  Have  you  told  him  the  truth? 

Person  #1:  I  would,  but  I  need  the  eggs. 


Updated  for  the  modern  age  of  structured  languages  and 
object-oriented  programming,  that  joke  would  read: 


Manager  #1 :  Help!  My  programmers  think  assembly  lan¬ 
guage  is  a  viable  programming  language,  and  I  don’t 
know  what  I  should  do. 

Manager  *2-.  Have  you  told  them  the  truth? 

Manager  #1:  I  would,  but  I  need  the  speed. 


Assembly  language  beats  everything  else  hands  down 
when  it  comes  to  performance  —  especially  when  program¬ 
ming  for  the  80x86,  where  assembly  language  is  wild,  woolly, 
and  wondrous  —  yet  it  gets  no  respect.  When  you  flat-out 
need  performance,  there  simply  are  no  substitutes  for  as¬ 
sembly  language  —  so  why  doesn’t  anyone  seem  to  love  it? 

Assembly  Language  Isn't  Cheap 

Experts,  pundits,  and  management  types  have  been  beating 
the  drums  for  the  demise  of  assembly  language  for  years. 
There  are  many  good  reasons  for  wishing  it  dead.  Com¬ 
pared  to  compiled  code,  good  assembly-language  code  is 
harder  to  write,  is  more  bug  prone,  takes  more  time  to 
create,  is  harder  to  maintain,  is  harder  to  port  to  other 
platforms,  and  is  more  difficult  to  use  for  complex,  multi¬ 
programmer  projects.  That  makes  assembly  language  an 
expensive,  demanding,  and  time-consuming  development 
language.  Given  the  realities  of  time  to  market,  the  relative 
costs  of  good  assembly  language  and  high-level  language 
programmers,  programmer  turnover,  and  ever-increasing 


Michael  works  on  high-performance  graphics  software  at 
Metagraphics  in  Scotts  Valley ,  Calif.  He  is  also  the  author 
of  Zen  of  Assembly  Language  published  by  Scott,  Foresman 
&  Co.,  and  Power  Graphics  Programming,  from  Que. 
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software  complexity,  it’s  neither  surprising  nor  unreason¬ 
able  that  most  of  the  industry  wishes  assembly  language 
would  go  away. 

Assembly  language  lives,  though,  for  one  simple  reason: 
Properly  applied,  it  produces  the  best  code  of  any  language. 
By  far. 

Assembly  Language  Lives 

Don’t  believe  me?  Consider  this.  If  the  carbon-based  com¬ 
puter  between  your  ears  were  programmed  with  as  good  a 
compiler  as  Microsoft’s,  then  you’d  generate  much  better 
code  in  assembly  language  than  does  Microsoft  C,  because 
you  know  vastly  more  about  what  you  want  your  program 
to  do  and  are  marvelously  effective  at  integrating  that  knowl¬ 
edge  into  a  working  whole.  High-level  languages  are  artifi¬ 
cially  constrained  programming  environments,  able  to  pass 
relatively  little  of  what  you  know  along  to  the  ultimate 
machine  code.  There  are  good  reasons  for  that:  High-level 
languages  have  to  be  compilable  and  comprehensible  by 
humans.  Nonetheless,  there’s  no  way  for  a  high-level  lan¬ 
guage  to  know  where  to  focus  its  efforts,  or  which  way  to 
bias  code. 

For  example,  how  can  a  Pascal  compiler  know  that  one 
loop  repeats  twice,  on  average,  while  another  repeats  32,767 
times?  How  can  a  C  compiler  know  that  one  subroutine  is 
time  critical,  deserving  of  all  possible  optimization,  while 


another  subroutine  executes  in  the  background  while  wait¬ 
ing  for  the  next  key  to  be  pressed,  so  speed  matters  not  at 
all?  The  answer  is:  No  way.  (Actually,  #pragma  can  do  a 
little  of  that,  but  it’s  no  more  than  a  tiny  step  in  the  right 
direction.) 

Just  as  significantly,  no  compiler  can  globally  organize 
your  data  structures  and  the  code  that  manipulates  those 
structures  to  maximum  advantage,  nor  take  advantage  of  the 
vast  number  of  potential  optimizations  as  flexibly  as  you 
can.  (Space  forbids  even  a  partial  listing  of  optimization 
techniques  for  the  80x86  family:  The  list  is  astonishingly 
long  and  varied.  See  Tim  Paterson’s  article  in  this  issue  for 
a  small  but  potent  sample.)  When  it  comes  to  integrating  all 
the  information  about  a  particular  aspect  of  a  program  and 
implementing  the  code  as  efficiently  as  possible  given  the 
capabilities  of  a  particular  processor,  it’s  not  even  close: 
Humans  are  much  better  optimizers  than  compilers  are. 

Almost  any  processor  can  benefit  from  hand-tuned  as¬ 
sembly  language,  but  assembly  language  lives  most  vi¬ 
brantly  in  the  80x86  family.  The  80x86  instruction  set  is 
irregular;  the  register  set  is  small,  with  most  registers  dedi¬ 
cated  to  specific  purposes;  segments  complicate  everything; 
and  the  prefetching  nature  of  the  80x86  renders  actual 
execution  time  non-quantifiable  —  and  optimization  at  best 
an  art  and  at  worst  black  magic  —  making  the  80x86  family 
a  nightmare  for  optimizing-compiler  writers.  The  quirky 
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(and  highly  assembly  language  amenable)  instructions  of 
the  8086  live  on  in  the  latest  80x86-family  processors,  the 
80386  and  80486,  and  will  undoubtedly  do  the  same  for 
many  generations  to  come.  Other  processors  may  lend 
themselves  better  to  compilers,  but  the  80x86  family  is  and 
always  will  be  a  wonderland  for  assembly  language. 

Consider  this:  Well-written  assembly  language  provides 
a  50  to  300  percent  boost  in  performance  over  compiled 
code  (more  sometimes,  less  others,  but  that’s  a  conservative 
range).  An  8-MHz  AT  is  about  three  times  faster  than  a  PC, 
a  16-MHz  80386  machine  is  about  twice  as  fast  as  an  AT,  and 
a  25-MHz  80386  is  about  three  times  as  fast  as  an  AT.  There 
are  a  lot  of  PCs  and  ATs  out  there  - —  20  to  30  million,  I’d 

When  you  absolutely,  positively  need 
to  keep  program  size  to  a  minimum, 
assembly  language  is  the  way  to  go 


guess  —  and  there  is  a  horde  of  users  contemplating  the 
expenditure  of  thousands  of  dollars  to  upgrade. 

Now  consider  this.  Those  users  don’t  have  to  upgrade  — 
they  just  need  to  buy  better-written  software.  The  per¬ 
formance  boost  good  assembly  language  provides  is  about 
the  same  as  stepping  up  to  the  next  hardware  platform,  but 
the  assembly  language  route  is  one  heck  of  a  lot  cheaper. 

In  other  words,  better  software  can  eliminate  the  need  for 
expensive  hardware,  giving  the  developer  the  opportunity 
to  realize  a  healthy  profit  for  his  extra  development  efforts. 
Just  as  important  is  the  fact  that  good  assembly  language 
runs  perfectly  well  on  slower  computers,  making  the  market 
for  such  software  considerably  larger  than  the  market  for 
average  software.  If  you  make  your  software  snappy  on  an 
8088,  your  potential  market  doubles  instantly  and  the  com¬ 
petition  thins. 

Finally,  it’s  on  the  slower  computers  —  the  PC  and  AT  — 
that  assembly  language  optimization  has  the  most  effect 
(see  the  example  later  in  this  article),  and  that’s  precisely 
where  improved  performance  is  most  needed. 

Enter  the  User 

So  assembly  language  produces  the  best  code.  What  of  it? 
If  high-level  languages  make  it  easier  and  faster  to  create 
programs,  who  cares  if  those  programs  are  slower? 

The  user,  that’s  who.  Users  care  about  perceived  perfor¬ 
mance  —  how  well  a  program  seems  to  run.  Perceived 
performance  includes  lack  of  bugs,  ease  of  use,  and,  right 
at  the  top  of  the  list,  responsiveness.  Hand  users  a  whiz- 
bang  program  that  makes  them  wait  at  frequent  intervals, 
and  they’ll  leave  it  on  the  shelf  after  trying  it  once.  Give  users 
a  program  that  never  gets  in  their  way,  and  they  may  love  it 
without  ever  knowing  quite  why.  In  these  days  of  all-too- 
sluggish  graphical  interfaces,  the  performance  issue  is  cen¬ 
tral  to  the  usability  of  almost  every  program. 

What  users  don’t  care  about  is  how  a  program  was  made. 
Do  you  care  how  your  car  was  designed?  You  care  that  it’s 
safe,  that  it’s  reliable,  and  that  it  performs  adequately,  but 
you  certainly  don’t  care  whether  the  manufacturer  used 
just-in-time  manufacturing,  or  whether  mainframe  or  micro¬ 
computer  CAD  was  used  in  the  design  process.  Likewise, 
users  don’t  care  whether  a  programmer  used  OOP  or  C  or 
Pascal,  or  COBOL,  for  that  matter;  they  care  that  a  program 
does  what  they  need  and  performs  responsively.  That’s  not 


purely  a  matter  of  speed,  but  without  speed  the  user  will 
never  be  fully  satisfied.  And  when  it  comes  to  speed,  as¬ 
sembly  language  is  king. 

Use  Only  as  Directed 

When  you  need  it,  there’s  no  substitute  for  assembly  lan¬ 
guage,  but  it  can  be  a  drag  when  you  don’t  need  it  —  so 
know  when  to  use  it.  Humans  are  better  large-scale  design¬ 
ers  and  small-scale  optimizers  than  compilers,  but  they’re  not 
very  good  at  the  grunt  work  of  compiling,  such  as  setting  up 
stack  frames,  handling  32-bit  values,  allocating  and  ac¬ 
cessing  automatic  variables,  and  the  like.  Moreover,  humans 
are  much  slower  at  generating  code,  so  it’s  a  good  idea  to 
avoid  being  a  “human  compiler.”  Some  people  create  com¬ 
plex  macros  and  assembly  language  programming  conventions 
and  do  all  their  programming  in  assembly  language.  That 
works  —  but  what  those  macros  and  conventions  do  is 
make  assembly  language  function  much  like  a  high-level 
language,  so  there’s  no  great  benefit,  especially  given  that 
you  can  drop  into  assembly  language  from  a  high-level 
language  at  any  time  just  by  calling  an  assembly  language 
subroutine  (or,  better  yet,  by  using  in-line  assembly  lan¬ 
guage  in  a  compiler  that  offers  that  feature,  such  as  Turbo 
C).  Unless  you’re  a  masochist,  let  your  favorite  compiler  do 
what  it’s  best  at  —  compiling  —  and  save  assembly  lan¬ 
guage  for  those  small,  well-defined  portions  of  your  software 
where  your  efforts  and  unique  skills  pay  off  handsomely. 

A  relevant  point  is  that  assembly  language  alone  is  not  the 
path  to  performance.  If  you  have  a  program  that  takes  as 
long  as  a  second  to  update  the  screen,  you  have  problems 
that  assembly  language  alone  won’t  solve:  Proper  overall 
design  and  algorithm  selection  are  also  essential.  However, 
most  software  designers  consider  the  job  done  when  the 
design  and  algorithm  phases  are  complete,  leaving  the 
low-level  optimization  to  the  compiler.  I  repeat:  No  com¬ 
piler  can  match  a  good  assembly  language  programmer  at 
low-level  optimization.  Given  the  irregular  nature  of  the 
80x86  family  and  the  huge  PC  software  market,  it’s  well 
worth  the  time  required  to  hand-optimize  the  few  critical 
portions  that  control  perceived  performance.  Only  in  as¬ 
sembly  language  can  you  take  full  responsibility  for  the 
performance  of  your  code. 

Don't  Spit  into  the  Wind 

While  I  can’t  offer  a  cut-and-dried  dictum  on  when  to  use 
assembly  language,  the  practice  of  using  it  when  the  user 
would  notice  if  you  didn’t  is  a  good  rule  of  thumb.  While 
some  programmers  would  take  this  rule  too  far  and  use 
assembly  language  too  often,  the  vast  majority  of  program¬ 
mers  will  lean  over  backwards  the  other  way,  in  the  face  of 
all  evidence  to  the  contrary.  Hal  Hardenberg’s  late,  la¬ 
mented  DTACK  Grounded  reveled  in  the  folly  of  the  AT&T 
programmers  who  implemented  the  floating-point  routines 
for  a  super-micro  in  C  rather  than  assembly  language  — 
with  the  result  that  the  computer  performed  floating-point 
arithmetic  not  quite  so  fast  as  a  Commodore  VIC-20! 

Likewise,  I  once  wrote  an  article  in  which  I  measured  the 
performance  of  an  assembly-language  line-drawing  im¬ 
plementation  at  four  to  five  times  that  of  an  equivalent  C 
implementation.  One  reader  rewrote  the  C  code  for  greater 
efficiency,  ran  it  through  Microsoft  C  rather  than  Turbo  C, 
and  wrote  to  inform  me  that  I  had  shortchanged  C;  assembly 
language  was  actually  “only”  70  percent  faster  than  C.  As  it 
happens,  the  assembly-language  code  wasn’t  fully  opti¬ 
mized,  but  that’s  not  the  important  point:  What  really  mat¬ 
ters  is  that  when  programmers  go  out  of  their  way  to 
produce  code  that’s  nearly  twice  as  slow  (and  in  an  impor¬ 
tant  user-interface  component,  no  less)  in  order  to  use  a 
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(continued  from  page  18) 

high-level  language  rather  than  assembly  language,  it’s  the 
user  who’s  getting  shortchanged.  Commercial  developers 
in  particular  can’t  afford  to  ignore  this,  and  I  suspect  that 
most  such  developers  are  DDJ  readers.  If  you’re  aiming  to 
sell  hundreds  of  thousands  of  copies  of  a  program,  you’re 
guaranteed  to  have  stiff  competition.  If  you  don’t  go  the 
extra  mile  to  provide  snappy  response,  someone  else  will  — 
and  you’ll  be  left  out  in  the  cold. 

Assembly  language  lives,  though,  for 
one  simple  reason:  Properly  applied, 
it  produces  the  best  code  of  any 
language.  By  far 


On  the  other  hand,  assembly  language  code  is  harder  and 
slower  to  write,  and  pays  off  only  in  the  few  most  critical 
portions  of  any  program.  There  are  limits  to  the  levels  of 
complexity  humans  can  handle  in  assembly  language,  and 
limits  to  the  development  time  that  can  be  taken  before  a 
product  must  come  to  market.  Identify  the  parts  of  your 
programs  that  significantly  affect  the  performance  perceived 
by  the  user  (a  code  profiler  can  help  greatly  here),  and  focus 
your  efforts  on  that  code,  with  especially  close  attention  to 
oft-repeated  loops. 

80x86  Assembly  Language  in  Action 

Enough  talk.  Let’s  look  at  an  example  of  assembly  language 
in  action.  Listing  One,  page  94,  shows  a  C  subroutine, 
CopyUppercase,  that  copies  the  contents  of  one  far  zero- 
terminated  string  to  another  far  zero-terminated  string,  con¬ 
verting  all  lowercase  characters  to  uppercase  in  the  process. 
The  subroutine  consists  of  a  single,  extremely  compact  loop 
that  should  be  ideal  for  compiler  optimization.  In  fact,  I 
organized  the  loop  for  the  best  results  with  Microsoft  C  5.0, 
the  test  compiler,  and  used  the  intermediate  variable  Upper- 
SourceTemp  in  order  to  allow  for  more  efficient  compiled 
code.  There  may  be  a  more  efficient  way  to  code  this 
subroutine,  but  if  you’re  going  to  go  to  the  trouble  of  being 
compiler-specific  and  knowing  compiler  code  generation 
that  intimately,  why  not  use  assembly  language,  which 
provides  direct  control  and  gives  you  the  freedom  to  create 
the  best  possible  code?  Microsoft  C  5.0  generates  the  code 
shown  in  Figure  1  from  the  version  of  CopyUppercase  in 
Listing  One  when  maximum  optimization  is  selected  with 
the  /Ox  switch.  It’s  not  bad  code,  but  neither  is  it  great.  The 
far  pointers  are  stored  in  memory  and  must  be  loaded  each 
time  through  the  loop,  and  a  considerable  amount  of  work 
is  expended  on  determining  whether  each  character  is  up¬ 
percase,  although  the  case  check  is  done  with  a  table 
look-up,  which  is  generally  one  of  the  most  desirable  80x86 
programming  techniques.  A  serious  failing  is  that  none  of 
the  80x86  family’s  best  instructions  —  the  string  instructions  — 
are  used.  The  upshot  is  that  Listing  One  runs  in  the  times 
listed  in  Figure  2  on  various  PC-compatible  computers.  (All 
times  discussed  in  this  article  were  measured  with  the  Zen 
timer  described  in  my  book  Zen  of  Assembly  Language, 
from  Scott,  Foresman  &  Company,  modified  slightly  to  work 
with  Microsoft  C.) 

Can  we  do  better  in  assembly  language?  Indeed  we  can, 
as  Listing  Two  (page  94),  which  replaces  the  C  version  of 
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CopyUppercase  in  Listing  One  with  an  assembly  language 
version,  illustrates.  Listing  Two  simply  keeps  both  far  point¬ 
ers  in  registers  and  uses  string  instructions  to  access  both 
strings;  the  return  for  the  21  assembly-language  instructions 
that  do  that  is  a  performance  improvement  ranging  from 
two  to  three-plus  times,  as  shown  in  Figure  2.  If  this  code 
happens  to  be  in  a  performance-sensitive  portion  of  a  pro¬ 
gram,  that’s  quite  a  return  for  a  little  assembly  language. 

Now,  you  may  well  think  that  the  above  example  is 
biased  in  favor  of  assembly  language,  what  with  the  far 
pointers,  which  assembly  language  tends  to  handle  much 
better  than  do  compilers.  I  would  disagree:  Almost  every 
PC  program  now  takes  advantage  of  the  full  640K  of  mem¬ 
ory,  and  most  of  that  memory  must  be  accessed  via  far 
pointers,  so  access  to  far  data  is  a  most  important  issue  to 
PC  developers,  and  the  ability  of  assembly  language  to 
handle  /ardata  just  about  as  fast  as  near  data  is  a  substantial 
point  in  favor  of  assembly  language.  In  fact,  this  example  is 
representative  of  a  large  class  of  problems  developers  face, 
involving  data  copying,  data  transformation,  data  checking, 
pointers,  and  segments.  Nonetheless,  let’s  see  what  hap¬ 
pens  if  we  alter  CopyUppercase  to  use  near  pointers. 

Listing  Three  (page  94)  shows  Listing  One  changed  to  use 
near  pointers.  Listing  Three,  which  generates  the  code 
shown  in  Figure  3,  is  indeed  much  faster  than  Listing  One; 
it  still  takes  at  least  half  again  as  long  as  Listing  Two,  but  it’s 
closing  the  gap.  By  contrast,  Listing  Two  wouldn’t  much 
benefit  from  near  pointers,  because  it  already  keeps  the 
pointers  in  the  registers.  Does  that  mean  that  for  near  data 
C  almost  matches  assembly  language? 

Not  a  chance.  We  haven’t  optimized  the  assembly  lan¬ 
guage  implementation  yet;  Listing  Two  is  just  a  straight  port 
of  Listing  One  from  C  to  assembly  language.  Listing  Four 
(page  94)  shows  Listing  Two  converted  to  use  near  point- 


CopyUppercase 

proc  near 

push 

bp 

mov 

bp.sp 

sub 

sp,0002 

Label  1 : 

les 

bx,[bp+08] 

mov 

cl,es:[bx] 

inc 

word  ptr  [bp+08] 

mov 

ax,cx 

cbw 

mov 

bx,ax 

test 

byte  ptr  [bx-t-01 1 5],02 

je 

Label2 

mov 

ax,cx 

sub 

al,20 

jmp 

Label3 

Label2: 

mov 

ax,cx 

Label3: 

les 

bx,[bp+04] 

mov 

es:[bx],al 

inc 

word  ptr  [bp+04] 

or 

cl, cl 

jne 

Labe  11 

mov 

[bp-02], cl 

mov 

sp.bp 

pop 

bp 

ret 

CopyUppercase 

proc  near 

Figure  1:  The  code  generated  for  CopyUppercase  by  Micro¬ 
soft  C  5  0  when  Listing  One  is  compiled  with  the /Ox  switch 
(maximum  optimization) 


String  type/ 

Execution  time  in  microseconds  on 

Language 

(Listing) 

8088 

80286 

80386 

Far  strings/C 
(Listing  One) 

2258(1.0) 

466  (1.0) 

140  (1.0) 

Far  strings/ASM 
(Listing  Two) 

662  (3.4) 

150  (3.1) 

62  (2.3) 

Near  strings/C 
(Listing  Three) 

1183  (1.9) 

282  (1.7) 

95(1.5) 

Near  strings/ 

ASM 

574(3.9) 

115(4.1) 

50  (2.8) 

(Listing  Four) 

Near  strings/ 
optimized  ASM 
(Listing  Five) 

410(5.5) 

85  (5.5) 

46  (3.0) 

Figure  2:  The  execution  times  of  the  various  C  and  assem¬ 
bly  language  implementations  of  CopyUppercase  shown 
in  Listings  One  through  Five.  For  a  given  listing  running 
on  a  given  processor,  the  number  in  parentheses  represents 
the  performance  of  that  listing  relative  to  the  performance 
of  Listing  One  on  that  processor ;•  the  higher  the  value,  the 
better  the  performance.  8088  timings  were  performed  on 
an  IBM  XT;  80286  timings  were  performed  on  a  10-MHz 
one-wait-state  AT  clone;  and  80386 timings  were  performed 
on  a  20-MHz  zero-wait-state  32K-cache  Toshiba  T5200 


CopyUppercase 

proc  near 

push 

bp 

mov 

bp.sp 

sub 

sp,0002 

push 

di 

push 

si 

mov 

di, [bp+04] 

mov 

si,[bp+06] 

Labell : 

mov 

cl, [si] 

inc 

si 

mov 

ax,cx 

cbw 

mov 

bx.ax 

test 

byte  ptr  [bx+0115],02 

je 

Label2 

mov 

ax,cx 

sub 

al  ,20 

jmp 

Label3 

nop 

Label2: 

mov 

ax,cx 

Label3: 

mov 

[di],al 

inc 

di 

or 

cl, cl 

jne 

Label4 

mov 

[bp+04], di 

mov 

[bp+06],si 

mov 

[bp-02], cl 

pop 

si 

pop 

di 

mov 

sp.bp 

pop 

bp 

ret 

CopyUppercase 

proc  near 

Figure  3-‘  The  code  generated  forCopyUppevc3.se  by  Micro¬ 
soft  C  5.0  when  Listing  Three  is  compiled  with  the /Ox  switch 
(maximum  optimization) 
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ers,  plus  a  couple  of  twists.  First,  two  bytes  are  loaded, 
converted  to  uppercase,  and  stored  at  once,  cutting  the 
number  of  memory-accessing  instructions  in  half.  Second, 
the  value  used  to  convert  characters  to  uppercase  and  the 
upper-  and  lowercase  bounds  are  stored  in  registers  outside 
the  loop,  so  that  they  can  be  used  more  efficiently  inside  the 
loop.  These  are  simple  optimizations,  but  ones  that  I  doubt 
you’ll  find  a  compiler  using  —  and  they’re  highly  effective. 
As  Figure  2  indicates,  Listing  Four  is  approximately  20 
percent  faster  than  Listing  Two  and  about  two  times  faster 
than  the  near  C  implementation  of  Listing  Three. 

If  you  have  a  program  that  takes  as 
long  as  a  second  to  update  the  screen , 
you  have  problems  that  assembly 
language  alone  won!  solve 


We’re  not  done  optimizing  yet,  though.  We’ve  focused 
so  far  on  relatively  simple,  linear  optimization.  Let’s  pull  out 
all  the  stops,  throw  some  unorthodox  techniques  at  the 
problem,  and  see  what  comes  of  it. 

On  most  PC  compatibles,  the  key  is  this:  The  processor 
is  slow  at  fetching  instruction  bytes  and  branching  (in  fact, 
all  80x86  processors  are  relatively  slow  at  branching).  If  we 
can  keep  one  or  the  other  of  those  aspects  from  dragging 
the  processor  down,  we  can  often  improve  performance 
considerably.  As  it  happens,  we  can  attack  both  bottlenecks. 
Look-up  tables  shrink  code  size,  thereby  easing  the  instruc¬ 
tion  fetching  problem,  and  avoid  branches  as  well.  Well 
then,  why  not  simply  look  up  the  uppercase  version  of  each 
character?  While  we’re  at  it,  why  not  look  it  up  with  the 
remarkably  compact  and  efficient  xlat  instruction?  In  this 
way  we  can  convert  the  five  instructions  used  to  convert  to 
uppercase  in  Listing  Four  to  a  single  xlat.  We  can  also 
improve  performance  by  repeating  multiple  instances  of  the 
contents  of  the  loop  in-line,  one  after  the  other;  doing  this 
allows  virtually  all  of  the  conditional  jumps  to  fall  through, 
eliminating  branching  almost  entirely.  Both  changes  appear 
in  Listing  Five,  page  94.  As  Figure  2  indicates,  those  two 
changes  improve  performance  by  8  to  40  percent  —  and  the 
improvement  is  greatest  on  the  slower  8088  and  80286 
machines,  which  is  surely  where  speed  matters  most.  (Nor 
is  this  code  maxed  out  even  yet;  I  simply  had  to  draw  the 
line  somewhere  in  the  interests  of  keeping  the  code  readily 
comprehensible  and  this  article  to  a  reasonable  length.  For 
example,  we  could  use  lodsiv  to  speed  up  Listing  Five  much 
as  we  did  in  Listing  Four.  Never  assume  that  your  code  is 
fully  optimized!) 

Bear  in  mind,  too,  that  the  code  in  Listing  Five  can  handle 
far  pointers  as  easily  as  near  if  the  look-up  table  is  moved 
into  the  code  or  stack  segment  and  accessed  with  a  segment 
override,  a  change  that  would  scarcely  affect  performance 
at  all.  When  it  comes  to  handling  far  strings,  then,  we’ve 
improved  performance  by  three  to  five  and  one-half  times. 
To  put  that  in  perspective,  the  performance  improvement 
gained  by  running  the  original  C  code  on  a  20-MHz  zero-wait- 
state  32K-cache  80386  computer  rather  than  a  run-of-the- 
mill  10-MHz  one-wait-state  80286  computer  was  only  a  little 
over  three  times.  I  think  it’s  obvious  which  is  the  cheaper 
solution  to  improving  performance. 

(It’s  worth  noting  that  carefully  crafted  assembly  language 
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was  required  to  produce  the  massive  performance  improve¬ 
ment  measured  earlier.  Assembly  language  by  itself  guaran¬ 
tees  nothing,  and  bad  assembly  language,  which  is  easy  to 
write,  brings  new  meaning  to  the  word  bad.) 

Don’t  think  I’ve  picked  an  example  that  stacks  the  deck 
in  favor  of  assembly  language.  In  fact,  assembly  language 
would  do  considerably  better  if  we  worked  with  arrays  or 
fixed-length  Pascal-style  strings,  and  would  do  better  than 
compiled  code  in  cases  where  there  were  more  variables  to 
keep  in  the  registers.  We  also  weren’t  able  to  use  repeated 
string  instructions  in  the  earlier  example;  when  such  instruc¬ 
tions  can  be  used,  as  is  often  the  case  when  an  entire 
program’s  data  structures  are  organized  with  efficient  as¬ 
sembly  language  code  in  mind,  the  performance  advantage 
of  assembly  language  can  approach  an  order  of  magnitude. 
In  short,  we  looked  at  a  simple,  limited  example  (and  actually 
one  that  lends  itself  relatively  well  to  compiler  optimi¬ 
zation),  and  in  optimizing  it  we’ve  scarcely  begun  to  tap  the 
treasure  trove  of  assembly-language  tools  and  techniques. 

Yes,  compiler  library  functions  can  use  string  instructions 
and  other  assembly-language  tricks  as  readily  as  your  own 
assembly  language  code  can,  but  there’s  a  great  deal  that 
library  functions  can’t  do.  Don’t  assume  that  library  func¬ 
tions  are  well  written,  either  —  some  are,  but  many  aren’t. 
And  remember  that  the  author  of  the  library  knows  no  more 
than  the  author  of  the  compiler  about  when  you  most  need 
performance,  and  so  must  design  code  for  adequate  perfor¬ 
mance  under  all  circumstances.  You,  on  the  other  hand,  can 
precision-craft  your  code  for  best  performance  exactly  when 
and  where  you  need  it.  Also,  keep  in  mind  that  library 
functions  can  work  only  within  the  current  model.  When 
you’re  working  with  data  on  the  far  heap  in  a  program 
compiled  with  the  small  model  (an  efficient  arrangement  for 
programs  that  must  handle  a  great  deal  of  data),  library 
functions  can’t  help  you. 

Finally,  Microsoft  C  is  a  very  good  optimizing  compiler, 
considerably  better  than  most  of  the  compilers  out  there. 
There  are  a  few  compilers  that  generate  somewhat  better 
code  than  Microsoft  C,  but  I’m  willing  to  bet  that  most  of  the 
C  programmers  reading  this  use  either  Microsoft  or  Turbo 
C.  (Turbo  C  did  not  match  Microsoft  C  on  this  particular 
example,  so  I  used  Microsoft  C  in  order  to  give  C  every 
advantage.)  The  C  code  was  written  to  allow  for  maximum 
optimization  (the  loop  is  only  four  lines  long,  for  goodness’ 
sake)  and  uses  a  macro  —  not  a  function  call  —  that  ex¬ 
pands  to  a  table  look  up.  In  other  words,  the  cream  of  the 
C  crop,  given  readily  optimized  code  and  using  a  look-up 
table,  went  head-to-head  with  a  few  dozen  hand-optimized 
assembly-language  lines  —  and  proved  to  be  about  two  to 
five  times  slower. 

Size  Matters  Too 

I’ve  focused  on  performance  so  far  because  the  primary  use 
of  assembly  language  lies  in  making  software  faster.  Assem¬ 
bly  language  can  make  for  far  more  compact  programs  as 
well,  although  that’s  less  often  important  because  the  PC 
has  a  large  amount  of  memory  available  relative  to  process¬ 
ing  power  and  because  saving  space  is  a  diffuse  effort, 
requiring  attention  throughout  the  program,  while  enhanc¬ 
ing  performance  is  a  localized  phenomenon,  and  so  offers 
a  better  return  on  programming  time. 

There  are  cases  where  program  size  is  crucial  —  memory- 
resident  programs,  device  drivers,  utilities,  for  example  — 
and  assembly  language  can  work  wonders.  Of  course,  good 
assembly  language  code  is  very  tight,  and  hence  very  small, 
but  there’s  more  to  it  than  that.  It’s  easy  to  drive  programs 
with  compact  data  strings  in  assembly  language  (see  “Roll 


your  Own  Minilanguages  with  Mini-Interpreters”  which  I 
co-authored  with  Dan  Illowsky,  DDJ ,  September  1989).  It’s 
also  easy  to  map  in  code  sections  from  disk  as  needed; 
assembly  language  can  be  far  more  flexible  than  any  overlay 
manager.  Finally,  assembly  language  eliminates  the  need 
for  non-essential  start-up  and  library  code.  Co-workers  tell 
me  of  the  time  they  needed  to  distribute  a  program  to  accept 
a  keypress  from  the  user  and  return  a  corresponding  error 
level  to  a  batch  file.  Written  in  C,  the  program  was  8K  in  size; 
unfortunately,  the  distribution  disk  didn’t  have  that  much 
free  space.  Rewritten  in  assembly  language,  the  same  pro¬ 
gram  was  a  mere  50  bytes  long. 

When  you  absolutely,  positively  need  to  keep  program 
size  to  a  minimum,  assembly  language  is  the  way  to  go. 

Can  Live  with  It,  Can't  Live  without  It 

Assembly  language  isn’t  the  be-all  and  end-all  of  PC  pro¬ 
gramming,  but  it  is  the  only  game  in  town  when  either 
performance  or  program  size  is  paramount.  Assembly  lan¬ 
guage  should  be  used  only  when  needed  and,  used  wisely, 
offers  unparalleled  code  quality  and  an  excellent  return  for 
programming  time  invested. 

For  all  the  drawbacks  of  assembly  language,  eight-plus 
years  of  PC  software  development  have  proven  that  devel¬ 
opers  can  live  with  it;  programs  containing  assembly  lan¬ 
guage  have  been  written  in  an  expeditious  manner  and 
work  very  well,  indeed.  Those  same  years  have  shown  that 
developers  can’t  afford  to  live  without  assembly  language. 
I  suspect  you’d  be  hard  pressed  to  find  any  important  PC 
software  that  contains  no  assembly  language  at  all,  and  I  can 
assure  you  that  any  application  with  a  graphical  user  inter¬ 
face  either  contains  assembly  language  or  is  a  dog.  (Sure, 
Windows  applications  and  applications  that  link  in  third- 
party  libraries  may  not  contain  assembly  language,  but  that’s 
because  they’ve  passed  that  responsibility  off  to  other  devel¬ 
opers.  And  just  who  are  those  developers?  DDJ  readers, 
that’s  who.  Somebody  has  to  create  the  good  code  that 
top-notch  software  requires.) 

For  all  the  wishing,  80x86  assembly  language  isn’t  going 
away  soon;  in  fact,  it’s  not  going  to  go  away  at  all.  The  80x86 
architecture  lends  itself  beautifully  to  assembly  language, 
and  performance  will  always  be  at  a  premium,  no  matter 
how  fast  processors  get.  Back,  when  I  used  a  PC,  I  thought 
if  I  had  a  computer  that  was  ten  times  faster,  all  my  software 
would  run  so  fast  that  I’d  never  have  to  wait.  Well,  now  I 
use  just  such  a  computer,  and  much  of  the  software  I  use  is 
faster  as  well  (MASM,  for  example,  is  about  ten  times  faster 
than  it  used  to  be,  and  TASM  is  even  faster)  —  and  still  I 
spend  a  lot  of  time  waiting.  Software  is  never  fast  enough, 
and  better  software  is  one  heck  of  a  lot  cheaper  than  better 
hardware. 

Availability 

All  source  code  is  available  on  a  single  disk  and  online.  To 
order  the  disk,  send  $14.95  (Calif,  residents  add  sales  tax) 
to  Dr.  Dobb’s  Journal,  501  Galveston  Dr.,  Redwood  City, 
CA  94063,  or  call  800-356-2002  (from  inside  Calif.)  or  800-533- 
4372  (from  outside  Calif.).  Please  specify  the  issue  number 
and  format  (MS-DOS,  Macintosh,  Kaypro).  Source  code  is 
also  available  online  through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing  Service  (603-882- 
1599)  supports  300/1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the  system  answers,  type: 
listings  (lowercase)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  94.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  1. 
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Assembly  Language 

Tricks  of  the  Trade 

Hand-picked  code  for  smaller,  faster  programs 


Tim  Paterson 


It  is  the  nature  of  assembly  language  programmers  to 
always  look  for  ways  to  make  their  programs  faster  and 
smaller.  Over  the  years,  the  individual  programmer 
develops  a  personal  catalog  of  tricks  and  techniques 
that  squeeze  out  a  few  bytes  here  or  a  few  clocks  there. 
My  own  catalog  of  8086  tricks  has  been  13  years  in  the 
making,  including  a  few  from  the  8080  that  survived  the 
translation. 

One  of  the  original  motivations  for  finding  some  of  these 
alternatives  to  the  obvious  approach  is  the  severe  “branch 
penalty”  of  the  8086  and  8088.  When  a  conditional  jump  is 
taken  on  the  8086/8088,  four  times  as  many  clock  cycles  are 
required  (16)  as  when  the  jump  is  not  taken.  However,  this 
penalty  has  been  reduced  on  the  286  and  386.  When  taking 
a  conditional  jump,  the  newer  processors  require  only  seven 
clocks,  plus  one  clock  for  each  byte  in  the  instruction  at  the 
target  of  the  jump.  That  is,  if  you’re  jumping  to  an  instruction 
that  is  2  bytes  long,  the  conditional  jump  takes  nine  clocks. 
This  improvement  means  that  several  of  the  nine  tricks 
presented  here  are  of  little  or  no  value  on  the  286  and  386. 
However,  I  have  presented  them  anyway  so  you’ll  know 
what  they  do  if  you  see  them.  They  are  also  still  useful  for 
code  targeted  to  the  8086/8088. 

For  each  of  these  tricks,  I  have  compared  its  size  and 
speed  to  the  “direct”  approach.  Because  the  286  is  now  the 
largest  selling  processor  in  PCs,  I  have  used  286  clock 
counts  to  compare  timing.  When  conditional  jumps  branch 
out  of  the  presented  code  sequence,  I  assume  the  target 
instruction  is  2-bytes  long  so  that  the  branch  would  take 
nine  clocks. 


Tim  is  the  original  author  of  MS-DOS,  Versions  1.x,  which 
he  wrote  in  1980-  82  while  employed  by  Seattle  Computer 
Products  and  Microsoft.  He  was  also  the  founder  of  Falcon 
Technology,  which  was  eventually  sold,  to  Phoenix  Tech¬ 
nologies,  the  ROM  BIOS  maker.  He  can  be  reached  through 
theDD]  office. 


#  1  Binary-to-ASCII  Conversion 

Converts  a  binary  number  in  AL,  range  0  to  OFH,  to  the 
appropriate  ASCII  character. 


add 

al, "0" 

;  Handle  0-9 

cmp 

al, "9" 

;Did  it  work? 

jbe 

HaveAscii 

add 

al,  "A" -("9"  +  1) 

;Apply  correction  for  OAH  -OFH 

HaveAscii : 

Direct  approach:  8  bytes,  12  clocks  for  OAH-OFH,  15 
clocks  for  0-9. 


add 

al, 90H 

; 90H  -  9FH 

daa 

;  9 OH  -  99H,  00H  -05H  +CY 

adc 

al,40H 

;  ODOH  -  0D9H  +CY,  41H-46H 

daa 

; 30H  -  39H,  41H  -46H  =  "0"-"9",  "A"-"F' 

Trick:  6  bytes, 

12  clocks. 

#2  Absolute  Value 


Find  absolute  value  of  signed  integer  in  AX. 

or  ax, ax 

;  Set  flags 

jns  AxPositive 

/Already  the  right  answer  if  positive 

neg  ax 

AxPositive : 

;  It  was  negative,  so  flip  sign 

Direct  approach:  6  bytes,  7  clocks  if  negative,  11  clocks 

if  positive. 

cwd 

/Extend  sign  through  dx 

xor  ax,dx 

/Complement  ax  if  negative 

sub  ax,dx 

/  Increment  ax  if  it  was  negative 

Trick:  5  bytes,  6  clocks. 

(continued  on  page  32) 
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( continued  from  page  38) 


#6  Binary/Decimal  Conversion 


#3  Smaller  of  Two  Values  ("MIN") 


Given  signed  integers  in  AX  and  BX,  return  smaller  in  AX. 


cmp  ax,bx 
jl  AxSmaller 

xchg  ax,bx  ;  Swap  smaller  into  ax 

AxSmaller : 


Direct  approach:  5  bytes,  8  clocks  if  ax  >=  bx,  11  clocks 
otherwise. 


sub  ax,bx 
cwd 

and  ax,dx 
add  ax,bx 


;  Could  overflow  if  signs  are  different !  ! 
;  dx  =  0  i  f  ax  >=  bx ,  dx  =  OFFFFH  i  f  ax  <  bx 
/  ax  =  0  if  ax  >=  bx,  ax  =  ax  -  bx  if  ax  <  bx 
;  ax  =  bx  if  ax  >=bx,  ax  =  ax  if  ax  <  bx 


Trick:  7  bytes,  8  clocks.  Doesn’t  work  if  lax  -  bx  I  > 
32K.  Not  recommended. 


#4  Convert  to  Uppercase 

Convert  ASCII  character  in  AL  to  uppercase  if  it’s  lower¬ 
case,  otherwise  leave  unchanged. 

cmp  al,"aM 
jb  CaseOk 
cmp  al,"z" 
ja  CaseOk 

sub  al,  "a"  -  "A"  ;  In  range  "a"  -  "z",  apply  correction 
CaseOk: 

Direct  approach:  10  bytes,  12  clocks  if  less  than  “a” 
(number,  capital  letter,  control  character,  most  symbols), 
15  clocks  if  lowercase,  18  clocks  if  greater  than  “z”  (a  few 
symbols  and  graphics  characters). 


sub 

al, "a" 

; Lowercase  now  0  -  25 

cmp 

al, "z" 

-  "a"  +1  ;Set  CY  flag  if  lowercase 

sbb 

ah,  ah 

;ah  =  OFFH  if  lowercase,  else  0 

and 

ah, "a"  - 

"A"  ; ah  =  correction  or  zero 

sub 

al,  ah 

/Apply  correction,  lower  to  upper 

add 

al, "a" 

/Restore  base 

Trick:  13  bytes,  16  clocks.  Although  occasionally  faster, 
it  is  bigger  and  slower  on  the  average.  Not  recommended. 
Used  by  Microsoft  C  5.1  stricmp( )  routine. 


#5  Fast  String  Move 

Assume  setup  for  a  standard  string  move,  with  DS.SI 
pointing  to  source,  ES.DI  pointing  to  destination,  and 
byte  count  in  CX.  Double  the  speed  by  moving  words, 
accounting  for  a  possible  odd  byte. 


shr 

rep  movsw 

cx,  1 

/Convert  to  word  count 
/Move  words 

jnc 

movsb 

AllMoved: 

AllMoved 

/CY  clear  if  no  odd  byte 
/  Copy  that  last  odd  byte 

Direct:  7  bytes,  10  clocks  if  odd,  11  clocks  if  even  (plus 
time  for  repeated  move). 

shr 

rep  movsw 

cx,  1 

/  Convert  to  word  count 
/Move  words 

adc 

rep  movsb 

cx,  cx 

/Move  carry  back  into  cx 
/Move  one  more  if  odd  count 

Trick:  8  bytes,  9  clocks  if  even,  13  clocks  if  odd  (plus 
time  for  repeated  move).  Not  recommended. 


The  8086  instruction  AAM  (ASCII  adjust  for  multiplica¬ 
tion)  is  actually  a  binary-to-decimal  conversion  instruc¬ 
tion.  Given  a  binary  number  in  AL  less  than  100,  AAM 
will  convert  it  directly  to  unpacked  BCD  digits  in  AL  and 
AH  (ones  in  AL,  tens  in  All).  If  the  value  in  AL  isn’t 
necessarily  less  than  100,  then  AAM  can  be  applied  twice 
to  return  three  BCD  digits.  For  example: 


a  am 

mov  cl,al 
mov  al,ah 
a  am 


; al  =  ones,  ah  =  tens  &  hundreds 

/  Save  ones  in  cl 

;  Set  up  to  do  it  again 

;ah  =  hundreds,  al  =  tens,  cl  =  ones 


AAM  is  really  a  divide-by-ten  instruction,  returning  the 
quotient  in  AH  and  the  remainder  in  AL.  It  takes  16 
clocks,  which  are  actually  two  clocks  more  than  a  byte 
D1V.  However,  you  easily  save  those  two  clocks  and 
more  with  reduced  setup.  There’s  no  need  to  extend  the 
dividend  to  16  bits,  nor  to  move  the  value  10  into  a 
register. 

The  inverse  of  the  AAM  instruction  is  AAD  (ASCII 
adjust  for  division).  It  multiplies  AH  by  10  and  adds  it  to 
AL,  then  zeros  AH.  Given  two  unpacked  BCD  digits  (tens 
in  AH  and  ones  in  AL),  AAD  will  convert  them  directly 
into  a  binary  number.  Of  course,  given  only  two  digits, 
the  resulting  binary  number  will  be  less  than  100.  But 
AAD  can  be  used  twice  to  convert  three  unpacked  BCD 
digits,  provided  the  result  is  less  than  256.  For  example: 

;ah  =  hundreds,  al  =  tens,  cl  =  ones 

aad  ;  Combine  hundreds  and  tens 

mov  ah,al 

mov  al,cl  ; Move  ones  to  al 

aad  ;  Binary  result  in  ax,  mod  256 


AAD  takes  14  clocks,  which  is  one  clock  more  than  a 
byte  MUL.  Again,  that  time  can  be  saved  because  of 
reduced  setup. 


#7  Multiple  Bit  Testing 


Test  for  all  four  combinations  of  2  bits  of  a  flag  byte  in 
memory. 


mov 

al,  [Flag] 

test 

al, Bitl 

jnz 

BitlSet 

test 

al, Bit2 

jz 

BothZero 

Bit20nly : 

BitlSet : 

test 

al, Bit2 

jnz 

BothOne 

BitlOnly : 

Direct  approach:  15  bytes,  up  to  29  clocks  (to  BothOne). 

The  parity  flag  is  often  thought  of  as  a  holdover  from 
earlier  days,  useful  only  for  error  detection  in  communica¬ 
tions.  However,  it  does  have  a  useful  application  to  cases 
such  as  this  bit  testing.  Recall  that  the  parity  flag  is  EVEN 
if  there  are  an  even  number  of  “one”  bits  in  the  byte 
being  tested,  and  ODD  otherwise.  When  testing  only  2 
bits,  the  parity  flag  will  tell  you  if  they  are  equal  —  it  is 
EVEN  for  no  “one”  bits  or  for  2  “one”  bits,  ODD  for  1 
“one”  bit. 

The  sign  flag  is  also  handy  for  bit  testing,  because  it 
directly  gives  you  the  value  of  bit  7  in  the  byte.  The 
obvious  drawback  is  you  only  get  to  use  it  on  1  bit. 


(continued  on  page  34) 
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(continued  from  page  32) _ 

test  [Flag] , Bitl + Bit2 

jz  BothZero 

jpe  BothOne  /Bits  are  equal,  but  not  both  zero 

/One  (and  only  one)  bit  is  set 

.erre  Bitl  EQ  80H  /Verify  Bitl  is  the  sign  bit 

js  BitlOnly 

Bit20nly : 

Trick:  11  bytes,  up  to  21  clocks  (to  BitlOnly). 

Note  that  the  parity  flag  is  only  set  on  the  low  8  bits  of 
a  1 6-bit  (or  32-bit  386)  operation.  Suppose  you  test  2  bits 
in  a  1 6-bit  word,  where  1  bit  is  in  the  low  byte  while  the 
other  is  in  the  high  byte.  The  parity  flag  will  be  set  on  the 
value  of  the  1  bit  in  the  low  byte  —  EVEN  if  zero,  ODD 
if  one.  This  is  potentially  useful  in  certain  cases  of  bit 
testing,  as  long  as  you  are  aware  of  it! 

Another  example  of  using  dedicated  bit  positions  is  to 
assign  flags  to  bits  6  and  7  of  a  byte.  Then  test  it  by 
shifting  it  left  1  bit.  The  carry  and  sign  flags  will  directly 
hold  the  values  in  those  2  bits.  In  addition,  the  overflow 
flag  will  be  set  if  the  bits  are  different  (because  the  sign 
has  changed). 

Finally,  there  is  a  way  to  test  up  to  4  bits  at  once. 
Loading  the  flag  byte  into  AH  and  executing  the  SAHF 
instruction  will  copy  bits  0,  2,  6,  and  7  directly  into  the 
carry,  parity,  zero,  and  sign  flags,  respectively. 

#8  Function  Dispatcher 

Given  a  function  number  in  a  register  with  value  0  to 
n-  1,  dispatch  to  the  respective  one  of  n  functions. 

/Function  number  in  cx 


jcxz 

FunctionO 

dec 

cx 

jz 

Functionl 

dec 

cx 

jz 

Function2 

Direct  approach  1:  3*n  -  4  bytes,  5*n  clocks  maximum. 
Not  bad  for  small  n  (n<  10). 

/  Function  number  in  bx 
shl  bx,l 

jmp  tDispatch [bx] 

Direct  approach  2:  2*n  +  6  bytes,  15  clocks.  The  best 
approach  for  large  n  when  speed  is  a  consideration. 

/Function  number  in  cx 


jcxz 

FunctionO 

loop 

NotFuncl 

Functionl : 

NotFuncl : 

loop 

NotFunc2 

Function2 : 

NotFunc2 : 

loop 

NotFunc3 

Function3 : 

Trick:  2*n 

-  2  bytes,  10*n  -  16  clocks  maximum.  Slow, 

but  compact. 

#9  Skipping  Instructions 

Sometimes  a  routine  will  have  two  or  more  entry  points, 
but  the  only  difference  between  the  entry  points  is  the  first 
instruction.  For  example,  the  instruction  that  differs  from 
one  entry  point  to  the  next  could  be  initializing  a  register 
to  different  values  to  be  used  as  a  flag  later  on  in  the  routine. 

(continued  on  page  36) 
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Entryl : 

mov 

al,  0 

Entry2 : 

jmp 

Body 

mov 

al,  1 

Entry3 : 

jmp 

Body 

Body: 

mov 

al,  -1 

Direct  approach:  10  bytes,  11  clocks  (from  Entry  1). 

Instead  of  using  jump  instructions  to  skip  over  the 
alternative  entry  points,  a  somewhat  sleazy  trick  allows 
you  to  simply  skip  over  those  instructions.  The  technique 
goes  back  at  least  to  1975  with  the  first  Microsoft  Basic 
for  the  8080.  It  became  known  as  a  “LXI  trick”  (pro¬ 
nounced  “liksee”),  after  the  8080  mnemonic  for  a  16-bit 
move-immediate  into  register.  Essentially,  it  allows  you 
to  skip  a  2-byte  instruction  by  hiding  it  as  immediate  data. 
A  variation,  the  “MVI  trick”  (pronounced  “movie”),  uses 
an  8-bit  immediate  instruction  to  hide  a  1-byte  instruction. 

Applied  to  the  8086,  there  is  another  variation.  The 
skip  can  use  a  move-immediate  instruction  and  destroy 
the  contents  of  one  register,  or  it  can  use  a  compare- 
immediate  instruction  and  destroy  the  flags.  Using  the 
latter  case  the  example  above  could  be  code  such  as  this: 


SKIP2F 

MACRO 

db 

ENDM 

3DH 

/Opcode  byte  for  CMP  AX,  <immed> 

Entryl : 

mov 

SKIP2F 

al,  0 

/Next  2  bytes  are  immediate  data 

Entry2 : 

mov 

al,  1 

SKIP2F 

/Next  2  bytes  are  immediate  data 

Entry3 : 

mov 

al,  -1 

Body : 

The  effect  of  this  when  entered  at  Entry  1  is: 

Entryl : 

mov 
cmp 
cmp 

Body: 

Trick:  8  bytes,  8  clocks  (from  Etitryl). 

This  trick  should  always  be  hidden  in  a  macro.  Here 
is  a  more  complete  macro  that  requires  an  argument 
specifying  what  register  or  flags  to  destroy.  The  argument 
is  any  16-bit  general  register  or  “F”  for  flags. 


SKIP2 

MACRO 

ModReg 

IFIDNI 

<ModReg> , <f> 

/Modify  flags? 

db 

3DH 

/Opcode  byte  for  CMP  AX,  <immed> 

ELSE 

?_i 

= 

0 

IRP 

Reg, <ax, 

.  cx, dx, bx, sp, bp, si,  di> 

IFIDN 

<ModReg> ,<Reg> 

/  Find  the  register  in  list  yet? 

db 

0B8H  +  ? 

_i 

EXITM 

ELSE 

?  i 

= 

?_i  +  1 

END  IF 

/  IF  ModReg 

f  =  Reg 

ENDM 

/  IRP 

.errnz 

?_i  EQ  8 

/Flag  an  error  if  no  match 

ENDIF 

/  IF  ModReg 

[  =  F 

ENDM 

/ SKIP2 

/Examples 

SKIP2 

f 

/Modify  flags  only 

SKIP2 

ax 

/Destroy  ax,  flags  preserved 

DDJ 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  2. 


al,  0 

ax,01B0H  ;Data  is  MOV  AL,  1 
ax,  OFFBOH  ;Data  is  MOV  AL,  -1 
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68040 

Programming 

More  than  just  an  030  with  floating  point 


Stephen  Satchell 


|  he  newest  entry  in  the  CPU  chip 
wars  is  now  ready  for  the  sys¬ 
tem  builders:  The  Motorola 
68040.  The  first  available  chips 
will  work  at  25  MHz,  with  33 
MHz  and  faster  parts  becoming  avail¬ 
able  later  this  year.  Don’t  think,  though, 
this  is  just  a  faster  68030:  Motorola  built 
in  some  nifty  features  to  make 
multiprocessing  hardware  much  easier 
to  design  and  build. 


68000  Family  Overview 

Motorola  has  gone  to  great  pains  to 
make  a  line  of  compatible  32-bit  micro¬ 
computer  chips.  Like  IBM  did  with  the 
System/360  mainframe  computers  of  the 
mid-1960s,  Motorola  made  sure  that 
applications  code  written  for  the  earlier 
members  of  the  68000  family  would  run 
without  modification  on  later  chips.  This 
scheme  makes  the  assumption  that  pro¬ 
grammers  segregate  I/O  and  chip  con¬ 
trol  code  from  the  rest  of  the  system. 

The  general  programming  model  for 
the  68000  family  is  the  same:  Eight 
32-bit  data  registers,  seven  32-bit  ad¬ 
dress  registers,  one  32-bit  user  stack 
pointer,  one  32-bit  supervisor  stack 
pointer,  and  chip-specific  registers.  The 
68000  family  supports  operations  on  in¬ 
dividual  bits,  8-bit  bytes,  16-bit  words, 
32-bit  longwords,  and  packed  binary 
coded  decimal  (BCD)  data.  Address  calcula¬ 
tions  are  all  32  bits,  although  some  CPUs 


Steve  is  free-lance  writer  and  co-foun¬ 
der  of  Project  Notify,  a  non-profit,  emer¬ 
gency  communications  network.  He 
can  be  reached  at  P.O.  Box  8656,  In¬ 
cline  Village,  NV  89450  or  on  Compu¬ 
Serve  at  70007,3351. 


have  limited  addressing  capability. 

The  68008  (1980)  is  much  the  same 
as  the  Intel  8088  in  that  it  talks  to  the 
outside  world  over  a  20-bit  address  bus 
and  an  8-bit  data  bus. 

The  68000  0979),  the  first  CPU  in 
the  family,  and  the  low-power  CMOS 
68HC000  use  a  24-bit  address  bus  and 
1 6-bit  data  bus. 

The  68010  0982)  takes  the  68000 
and  adds  virtual  memory  support,  us¬ 
ing  an  external  memory  management 
unit  (MMU)  and  a  special  three-instruc¬ 
tion  “loop  mode”  that  lets  the  68010 
execute  a  tight  three-instruction  loop 
repeatedly  without  fetching  the  instruc¬ 
tions  from  memory  more  than  once. 

The  68020  (1984)  is  the  first  true 
32-bit  member  of  the  68000  family.  The 


address  and  data  busses  are  both  a  full 
32-bits  wide,  allowing  the  chip  to  di¬ 
rectly  access  four  gigabytes  (4096 
Mbytes)  of  memory,  up  to  32  bits  at  a 
time.  Memory  management  is  provided 
by  an  external  MMU.  Instead  of  the 
68010’s  “loop  mode,”  the  68020  imple¬ 
ments  a  256-byte  (64  x  4  direct 
mapped)  instruction  cache  so  that  most 
loops  run  out  of  on-chip  cache 
memory  —  improving  execution  time 
33  percent  and  reducing  the  load  on 
the  system  bus.  Bit-field  instructions  let 
you  deal  with  data  of  varying  bit  lengths. 
Instructions  for  multiprocessing  were 
added  into  the  68020  as  well. 

The  68030  (1987)  moves  demand- 
page  memory  management  on-chip, 
and  adds  a  256-byte  (64  x  4  direct 


38 

216 


Dr.  Dobb's Journal,  March  1990 


(continued  from  page  38) 
mapped)  data  cache  on-chip  to  com¬ 
plement  the  68020’s  256-byte  instruc¬ 
tion  cache.  The  data  cache  uses  a  write- 
through  philosophy.  The  bus  system 
implements  a  burst  transfer  mode,  that 
lets  the  chip  effectively  use  page-mode, 
nibble-mode,  and  static-column  DRAM 
to  load  data  and  instructions  into  cache 
memory  quickly. 

Enter  the  68040 

The  newest  member  of  the  68000  fam¬ 
ily,  the  68040,  essentially  combines  a 
beefed-up  68030  and  the  low-level  func¬ 
tions  of  the  68881  floating-point  copro- 
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cessor  onto  the  same  chip.  The  im¬ 
provements,  however,  go  much  beyond 
that.  Motorola’s  goal  appears  to  be  to 
make  the  68040  as  suitable  as  possible 
for  large-scale  multiprocessing  systems. 

Instead  of  one  MMU  trying  to  serve 
the  entire  chip,  the  68040  gives  you 
two:  One  for  instructions,  one  for  data. 
This  keeps  data  and  instruction  accesses 
from  causing  page  table  entry  faults 
(not  to  be  confused  with  page  faults) 
so  as  to  minimize  the  amount  of  time 
the  68040  has  to  go  to  RAM  to  fetch 
address  translation  information. 

The  two  on-chip  memory  caches  are 
completely  changed.  Not  only  do  you 


have  a  4-Kbyte  data  cache  and  a  4- 
Kbyte  instruction  cache,  but  the  cache 
system  —  particularly  the  data  cache  — 
is  designed  to  minimize  the  number  of 
times  you  have  to  go  to  the  system 
bus.  The  two  caches  are  organized  as 
64  four-way  associative  maps  (256  lo¬ 
cations),  with  16  bytes  of  data  in  each 
cache  location.  The  data  cache  can  be 
write  through,  as  it  is  in  the  68030,  or 
the  68040  can  use  a  copyback  philoso¬ 
phy  that  delays  the  write  to  memory 
until  the  chip  needs  the  cache  location 
for  something  else  or  the  CPU’s  super¬ 
visor  empties  the  cache. 

When  using  cache  in  a  multiprocessing 
system,  you  can  have  data  that  is  one 
value  in  cache  and  another  value  in 
main  memory.  This  problem  is  called 
“cache  coherency.”  The  68040  takes 
care  of  this  problem  with  “bus 
snooping”  —  the  chip  looks  at  the  sys¬ 
tem  bus,  and  when  a  write  memory 
cycle  is  detected,  any  on-chip  cache 
location  containing  data  for  the  changed 
location  is  marked  invalid. 

What  happens,  though,  when  one 
68040  has  changed  data,  but  hasn’t  writ¬ 
ten  it  back  to  DRAM  yet?  The  bus  snoop 
hardware  has  another  trick  up  its  sleeve. 
When  a  read  memory  cycle  is  detected, 
the  68040  checks  its  data  cache  to  see 
if  it  changed  the  requested  location;  if 
so,  it  inhibits  the  RAM  memory  cycle 
and  sends  the  correct  data  to  the  other 
CPU.  This  reduces  the  amount  of  work 
programmers  have  to  do  to  keep  data 
up-to-date. 

If  you  do  a  lot  of  scientific  work, 
watch  out  for  the  floating-point  unit. 
On  the  68040,  the  only  floating-point 
operations  supported  are  absolute  value, 
add,  branch  on  condition,  compare, 
decrement  and  branch  conditionally, 
divide,  move,  move  multiple,  multiply, 
negate,  nop,  restore  internal  state,  save 
internal  state,  set  on  condition,  square 
root,  subtract,  trap  on  condition,  and 
test.  Other  operations  supported  by  the 
68881,  such  as  the  trig  and  logarithmic 
functions,  have  to  be  handled  by  soft¬ 
ware  emulation. 

Assembler  Programming  Considerations 
Portability  When  writing  code  that 
needs  to  run  on  different  systems,  you 
need  to  limit  yourself  to  those  instruc¬ 
tions  common  to  all  the  68000  family. 
(See  Table  1  for  those  instructions  to 
avoid.)  In  particular,  pay  attention  to 
addressing  modes.  The  68020,  ’30,  and 
’40  support  some  additional  modes  not 
found  on  the  ’00,  ’08,  and  TO.  Also  try 
to  segregate  chip-dependent  functions 
from  the  rest  of  your  program.  This 
limits  how  much  code  has  to  be  re¬ 
placed  as  you  shift  from  CPU  to  CPU. 
The  majority  of  your  code  should  be 
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(continued  from  page  40) 
running  in  user  mode  anyway. 

Loops  The  loop  mode  of  the  '10 
is  of  limited  use,  being  composed  of  a 
loop-able  instruction  and  a  DBcc  instruc¬ 


tion.  Use  this  construct  when  you  can 
on  the  off  chance  you  end  up  running 
on  a  ’10,  such  as  one  of  the  older  Sun 
workstations.  Where  possible,  try  to 
keep  loops  under  256  bytes,  the  size 


68010  from  68000  and  68008 

Move  from  CCR 

Move  from  Condition  Code  register 

Move  from  SR 

Move  from  Status  register 

MOVEC 

Move  Control  register 

MOVES 

Move  Status  register 

RTD 

Return  and  Deallocate 

68020  from  68010 

|  Data  alignment  restriction  dropped 

Bcc 

Branch  conditionally  (allow  32-bit  displacements) 

BFCHG 

Test  Bit  Field  and  Change 

BFCLR 

Test  Bit  Field  and  Clear 

BFEXTS 

Bit  Field  Extract  Signed 

BFEXTU 

Bit  Field  Extract  Unsigned 

BFFFO 

Bit  Field  Find  First  One-bit 

BFINS 

Bit  Field  Insert 

BFSET 

Test  Bit  Field  and  Set 

BFTST 

Test  Bit  Field 

BKPT 

Breakpoint 

CALLM 

Call  Module 

CAS 

Compare  and  Swap  Operands 

CAS2 

Compare  and  Swap  Dual  Operands 

CHK2 

Check  register  against  upper  and  lower  bound 

CMP2 

Compare  register  against  upper  and  lower  bound  (between) 

opBco 

Branch  on  Coprocessor  condition 

cpDBcc 

Test  Coprocessor  condition  Decrement  and  Branch 

cpGEN 

Coprocessor  General  function 

cpRESTORE 

Coprocessor  Restore  functon 

opSAVE 

Coprocessor  Save  function 

opScc 

Set  on  Coprocessor  condition 

cpTRAPcc 

Trap  on  Coprocessor  condition 

DIVSL 

Long  signed  divide 

DIVUL 

Long  unsigned  divide 

EXTB 

Extend  byte  to  long 

PACK 

Pack  binary  coded  decimal  (BCD) 

RTM 

Return  from  Module  (‘not*  "Read  the  manual”) 

TRAPcc 

Trap  conditionally 

UNPK 

Unpack  binary  coded  decimal  (BCD) 

68030  from  68020 

(CALLM) 

PFLUSH 

Invalidates  specific  entry  in  the  address  translation  cache  (ATC) 

PFLUSHA 

Invalidates  all  entries  in  the  address  translation  cache  (ATC) 

PLOAD 

Load  an  entry  into  the  address  translation  cache 

PMOVE 

Load  an  entry  into  the  address  translation  cache 

PTEST 

Get  information  about  a  logical  address 

(RTM) 

68040  from  68030 

CINV 

Invalidate  cache  entries 

(cpBcc) 

(cpDBcc) 

(cpGEN) 

(cpRESTORE) 

(cpSAVE) 

(cpScc) 

(cpTRAPcc) 

CPUSH 

Push,  then  invalidate,  cache  entries 

Floating-point  instructions 

MOVE16 

Move  16-byte  block;  block  must  be  aligned 

(PFLUSHA) 

(PLOAD) 

(PMOVE) 

Table  1:  680x0 family  instruction  set  differences.  An  instruction  or  capability 
added  or  changed  is  in  the  open.  An  instruction  or  capability  removed  is  in 
parens.  For  example,  the  CALLM  instruction  was  removed  in  the  68030,  so  in 
the  table  it  shows  as  ( CALLM). 
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(continued  from  page  42) 
of  the  instruction  cache  on  the  ’20.  If  a 
much-repeating  loop  can’t  be  squeezed 
down  that  far,  move  seldom-executed 
code  such  as  exception  code  outside 
of  the  loop.  The  longer  you  can  stay  in 
the  cache,  the  faster  that  loop  executes. 

Loop  Data  In  assembler,  it  is  usu¬ 
ally  easier  to  whip  through  an  array 
word  by  adjacent  word,  so  most  as¬ 
sembler  language  programmers  won’t 
have  to  concentrate  on  what  order  data 
gets  accessed.  If  you  are  writing  a  table- 
driven  package,  though,  pay  attention 
to  how  table  information  makes  you 
access  data.  Where  possible,  the  table 
should  be  optimized  so  your  program 
sweeps  through  any  array.  This  is  some- 
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what  important  on  the  ’30,  and  much 
more  important  on  the  ’40  —  particu¬ 
larly  in  multiprocessing  systems. 

Tests  Many  times,  you  have  to  load 
one  of  two  values  into  a  register  or 
location  based  on  some  test  condition. 
The  “IF  .  .  .  THEN  .  .  .  ELSE  ..."  con¬ 
struction  is  easy  to  understand,  but  the 
multiple  branches  can  play  hob  with 
instruction  fetching.  Instead,  try  "...  IF 
.  .  .  THEN  ...”  where  you  set  the  less 
common  value,  perform  the  test,  and 
conditionally  branch  around  the  more 
common  value.  The  penalty  on  ’00, 
’08,  and  TO  CPUs  is  almost  zero,  but 
the  savings  on  the  ’20,  ’30,  and  ’40  can 
be  significant.  In  fact,  the  first  way  re¬ 
quires  at  least  five  instructions  (test, 


branch-false,  set-1 ,  branch,  set- 2)  while 
the  other  way  saves  one  instruction 
(set-2,  test,  branch-false,  set-1). 

High-Level  Language  Considerations 
Portability  Chip-dependent  functions 
usually  have  to  be  written  in  assem¬ 
bler,  so  make  sure  the  design  of  the 
system  routines  are  as  generic  as  possi¬ 
ble  so  you  don’t  have  to  change  appli¬ 
cations  code  when  the  next  gee-whiz 
feature  is  introduced  in  the  68050.  You’ll 
need  to  package  separate  interface  mod¬ 
ules  for  each  chip.  High-level  code 
should  always  be  run  in  user  mode. 

Loops  If  your  compiler  can  opti¬ 
mize  for  the  loop  mode  on  the  TO  or  if 
the  library  includes  routines  to  perform 
functions  using  loop  mode,  use  them. 
When  structuring  loops  that  are  exe¬ 
cuted  often  consider  dropping  struc¬ 
tured  programming  practices  to  pack 
the  loop  as  tight  as  possible.  The  goal 
is  to  get  the  loop  within  the  256-byte 
window  of  the  instruction  cache  of  the 
’20.  Branches  are  much  cheaper  than 
function  calls  to  get  the  seldom-used 
code  out  of  the  loop.  You  have  more 
latitude  with  the  larger  cache  on  the  ’30 
and  ’40. 

Loop  Data  Be  very  careful  when 
transversing  arrays  that  you  know  ex¬ 
actly  how  your  compiler  is  working. 
Fortran  programmers  need  to  remem¬ 
ber  that  they  have  to  vary  the  first  sub¬ 
script  first  in  order  to  walk  through 
data  sequentially.  For  PL/I  and  Pascal 
programmers,  most  compilers  require 
you  to  vary  the  last  subscript  first  to 
sweep  an  array.  C  programmers  need 
to  remember  that  when  accessing  a 
multidimensional  array  using  the  array 
operators  that  are  in  the  constaict  “a[i][j]”, 
the  fragment  “a[il”  loads  a  pointer,  then 
“<e>[j]”  loads  the  desired  word;  use 
an  intermediate  pointer  where  possi¬ 
ble  to  limit  the  amount  of  pointer  load¬ 
ing  when  the  first  subscript  is  held 
locally  constant. 

Tests  You  are  at  the  mercy  of  the 
compiler  when  it  comes  to  ordering 
tests  to  save  time.  Because  compilers 
vary  so  much  in  what  they  do,  it  prob¬ 
ably  isn’t  worth  it  to  change  the  way 
you  select  values. 

Conclusion 

The  68040  is  more  than  “just  a  68030 
with  floating  point"  and  more  than  Mo¬ 
torola’s  weapon  to  fight  the  Intel  80486. 
It  is  a  well-designed  product  in  its  own 
right.  Graphics  programmers  like  the 
support  for  manipulating  bits,  particu¬ 
larly  the  bit-field  instructions  introduced 
by  the  ’20  and  continued  in  the  ’40. 
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Homegrown 

Debugging  -386 Style! 

Use  hardware  breakpoints  to  sniff  through  your  C  and 

assembly  code 


Al  Williams 


Although  the  installed  base  of 
80386-based  machines  is  ever 
increasing,  most  use  this 
souped-up  machine  as  a  faster 
8086.  One  of  the  problems  in 
running  the  80386  under  DOS  is  that 
you  lose  many  of  the  advantages  of  the 
386.  In  addition,  many  of  the  80386’s 
powerful  features  are  only  usable  in 
protected  mode.  Of  course,  developers 
loath  to  use  special  80386  features  be¬ 
cause  this  can  shut  them  out  of  the 
large  8086/80286  market. 

Still,  some  features  are  usable  while 
the  80386  is  operating  as  an  8086  (the 
so-called  “real  mode").  For  instance,  the 
80386  has  powerful  on-board  hardware 
that  allows  sophisticated  debugging  tech¬ 
niques  that  require  hardware  debugging 
boards  on  other  processors.  This  on¬ 
board  hardware  is  available  in  real  mode 
(as  well  as  the  other  modes).  With  a  little 
ingenuity,  you  can  put  this  hardware  to 
work  while  debugging  programs. 

This  article  puts  a  little  of  that  kind 
of  ingenuity  in  your  hands  by  showing 
how  you  can  use  the  80386  hardware 
to  debug  your  programs.  I’ll  provide  a 
program  that  can  be  included  in  your 
assembly  code  to  establish  breakpoints 
for  the  purpose  of  debugging  either  C 
or  assembly  language  programs.  In  ad¬ 
dition,  I’ll  provide  an  example  program 
and  a  quick  utility  that  I’ll  explain  shortly. 


Al  Williams  is  a  staff  systems  engineer 
for  Quad-S  Consultants  Inc.  His  cur¬ 
rent  work  includes  a  hypertext  system, 
several  expert  systems,  and  a  386  DOS 
extender  package.  He  can  be  reached 
at  2525  South  Shore  Boulevard,  Suite 
309,  League  City,  TX  77573- 


All  examples  presented  in  this  article 
compile  under  either  MASM  5.0  or  Mi¬ 
crosoft  C  5.1. 

BREAK386 

BREAK386  (Listing  One,  BREAK386 
.ASM,  page  96)  is  not  a  traditional  de¬ 
bugger  in  the  sense  of,  say,  DEBUG  or 
CodeView.  By  adding  BREAK386  to 
your  assembly  language  code,  you  can 
study  it  with  code,  data,  and  single- 
step  breakpoints.  You  can  also  exam¬ 
ine  DOS  or  BIOS  interrupts  that  your 
program  calls.  In  addition,  BREAK386 
can  add  the  same  386  hardware  debug¬ 
ging  to  your  Microsoft  C  programs. 

BREAK386  provides  functions  to  set 
up  386  debugging  ( setup386( )),  set 
breakpoints  {break386( )),  and  reset 
80386  debugging  ( clear386(  )).  In  ad¬ 
dition,  BREAK386  provides  an  optional 
interrupt  handler  ( inti _386( ))  that  sup¬ 
ports  register,  stack,  and  code  dumps 
along  with  single  stepping.  You  can 
use  any  of  these  functions  from  either 
C  or  assembly  language. 

There  are  cases  where  you  may  wish 
to  modify  intl_386( )  or  write  your 
own  interrupt  handler.  For  example, 
you  may  want  to  send  the  register 
dumps  to  a  printer  and  automatically 
restart  your  program.  With  C,  you  will 
often  want  the  interrupt  handler  to  print 
out  variables  instead  of  registers.  I’ll 
provide  some  example  interrupt  han¬ 
dlers  in  C  in  a  later  section. 

Using  BREAK386 

You  must  assemble  BREAK386  before 
you  can  use  it.  Be  sure  to  change  the 
.MODEL statement  to  reflect  the  model 
you  are  using.  If  you  are  using  explicit 


segment  definitions  in  assembly,  you 
must  decide  how  to  integrate  BREAK- 
386’s  code  and  data  segments  with  your 
own.  Assemble  BREAK386  with  the  /Ml 
option  to  prevent  MASM  from  convert¬ 
ing  all  labels  to  uppercase.  The  result¬ 
ing  .OBJ  file  can  be  linked  with  your 
programs  just  as  with  any  other  object 
module. 

If  you  are  using  programs  (such  as 
memory  managers  or  multitaskers)  that 
also  use  386-specific  functions,  you  may 
have  to  remove  these  programs  before 
BREAK386  will  function.  The  other  pro¬ 
gram  will  usually  report  a  “privilege 
exception"  or  something  similar.  Sim¬ 
ply  remove  the  other  386  programs 
and  try  again. 

Adding  386  breakpoints  to  your  pro¬ 
gram  requires  three  steps: 

•  Call  setup386( )  to  set  the  debug  in¬ 
terrupt  handler  address 

•  Set  up  breakpoints  with  the  break- 
386(  )  call 

•  Call  clear386( )  before  your  program 
returns  to  DOS 

Note  that  when  calling  these  rou¬ 
tines  from  assembly,  the  routine  names 
contain  leading  underscores.  For  con¬ 
venience,  Listing  Two  (BREAK386.INC, 
page  102)  contains  the  assembly  lan¬ 
guage  definitions  to  use  BREAK386. 
Listing  Three  (BREAK386.H,  page  102) 
contains  the  same  definitions  for  C. 
BREAK386.INC  also  includes  two  mac¬ 
ros,  traceon  and  traceoff  which  are 
used  to  turn  single  stepping  on  and  off 
from  within  the  program. 

Figure  1  shows  the  output  from  a 
breakpoint  dump  when  using  intl_ 
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C continued  from  page  46) 

386( ).  The  hexadecimal  number  on 
the  first  line  is  the  contents  of  the  low 
half  of  the  DR6  register  at  the  time  of 
the  breakpoint.  The  display  shows  all 
1 6-bit  and  segment  registers  (except 
FS  and  GS).  Following  that  is  a  dump 
of  32  words  of  memory  starting  at  the 
bottom  of  the  stack  (1CB1:09FA  in  the 
example).  The  first  three  words  of  the 
stack  are  from  the  debug  interrupt.  The 
first  word  is  the  IP  register,  followed 
by  the  CS  register  and  the  flags.  A  sim¬ 
ple  change  in  the  interrupt  handler  can 
remove  this  extra  data  from  the  display 
(see  “Detailed  Program  Operation”  in 
the  next  section). 

Below  the  stack  dump  is  a  dump  of 
program  code.  This  dump  usually  con¬ 
sists  of  16  bytes;  8  bytes  before  the 


current  instruction  and  8  bytes  at  the 
instruction  pointer.  This  is  convenient 
for  data  breakpoints  because  they  oc¬ 
cur  after  the  offending  instruction.  The 
dump  shows  the  starting  memory  ad¬ 
dress  ( 1  B66:0049)  followed  by  the  bytes 
at  that  address.  An  asterisk  marks  the 
current  CS:IP  location,  followed  by  the 
remaining  8  bytes.  If  IP  is  less  than  8, 
the  code  dump  will  start  at  CS:0  result¬ 
ing  in  fewer  than  8  bytes  before  the 
asterisk. 

The  last  line  of  the  dump  prompts 
you  for  further  action.  You  can: 

1.  View  your  program’s  output  screen. 
When  you  select  this  option,  BREAK386 
replaces  the  current  screen  with  your 
program’s  original  output.  To  restore 
the  debugging  screen,  press  any  key. 


2.  Toggle  the  trace  flag.  This  will  switch 
the  state  of  the  trace  or  single-step  flag, 
and  continue  the  program  in  the  same 
manner  as  the  “C”  command  (see  num¬ 
ber  3).  To  determine  whether  or  not 
tracing  is  on,  examine  the  value  of 
DR6.  If  bit  14  is  set  (4000  hex),  tracing 
is  on. 

3.  Continue  execution  of  the  program. 
Selecting  this  option  will  resume  the 
program  where  it  left  off.  The  program 
will  execute  until  the  next  breakpoint 
(if  the  trace  flag  is  clear)  or  to  the  next 
instruction  (if  the  trace  flag  is  set). 

4.  Abort  the  program.  This  will  cause 
the  program  to  exit.  Be  careful,  how¬ 
ever,  when  using  this  selection.  If  you 
have  interrupt  vectors  intercepted,  ex¬ 
panded  memory  allocated,  or  anything 
else  that  needs  fixing  before  you  quit, 
the  “A”  command  will  not  take  care  of 
these  things  unless  you  rewrite  the  in¬ 
terrupt  handler  or  clear386k ).  (Also,  if 
your  program  spawns  child  processes, 
and  the  breakpoint  occurred  in  the  child, 
the  abort  command  will  terminate  the 
child  and  the  parent  program  will  con¬ 
tinue  without  breakpoints.) 

Listings  Four  and  Five,  page  102,  show 
examples  of  using  BREAK386  in  assembly 
and  C.  The  identifiers  beginning  with 
BP_  are  defined  in  BREAK386.H  and 


Program  breakpoint:OFF1 

AX=0000  FL=7216  BX=0080  CX=0007  DX=06AA 
SU0000  DI  =  OAOO  SP=09FA  BP=0882 
CS=1  B66  IP=0051  DS=1  BAD  ES=1B56  SS=1CB1 
Stack  dump:(  1 CB1  :  09FA  ) 

0051  1 B66  7216  0000  0000  0000  0000  0000  0000  0000  0000  0000  0000  0000  0000  0000 
0000  0000  0000  0000  0000  0000  0000  0000  0000  0000  0000  0000  0000  0000  0000  0000 

CODE=1  B66  :  0049  =6A  04  E8  3F  00  83  C4  08  *  B9  14  00  8A  D1  80  C2  41 

<V>iew  output,  <T>race  toggle,  <C>ontinue  or  <A>bort?  _ 


Figure  1:  Sample  output  from  a  breakpoint  dump 
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(continued  from  page  48) 

BREAK  386. INC. 

A  few  notes  on  these  functions  are 
in  order.  Your  program  must  call 
setup386( )  before  any  other  BREAK386 
calls.  You  should  pass  it  a  segment  and 
an  offset  pointing  to  the  interrupt  han¬ 
dler.  After  calling  setup386( ),  you  may 
use  break386( )  to  set  and  clear  break¬ 
points.  Figure  2  shows  the  parameters 


break386( )  requires. 

You  must  keep  in  mind  a  few  facts 
about  the  80386  when  setting  break¬ 
points  or  tracing.  First,  2-  and  4-byte 
data  breakpoints  must  be  aligned  ac¬ 
cording  to  their  size.  For  example,  it  is 
incorrect  to  set  a  2-byte  breakpoint  at 
location  1000:0015  because  that  loca¬ 
tion  is  on  an  odd  byte.  Similarly,  a 
4-byte  breakpoint  can  monitor  address 


1000:0010  or  1000:0014  but  not  address 
1000:0013.  If  you  must  watch  an  un¬ 
aligned  data  item,  you  will  have  to  set 
multiple  breakpoints.  For  example,  to 
monitor  2  bytes  at  1000:0015,  set  a  1- 
byte  breakpoint  at  1000:0015  and  an¬ 
other  at  1000:0016. 

Also,  keep  in  mind  that  a  data  break¬ 
point  will  occur  even  if  you  only  access 
a  portion  of  its  range.  For  instance,  if 


80386  Debugging  Features 


Most  PC  developers  are  familiar  with 
some  aspect  of  chip  debug  assistance. 
Even  the  8088  has  a  breakpoint  inter¬ 
rupt  and  a  “single-step  flag,”  which 
allows  debuggers  to  trace  code  one 
instruction  at  a  time.  The  386  shares 
these  same  features  with  the  earlier 
processors,  but  adds  eight  debug  reg¬ 
isters  (two  of  which  Intel  reserves). 
These  debug  registers  control  the  hard¬ 
ware  breakpoint  features. 

Hardware  breakpoints  are  much 
more  powerful  than  ordinary  break¬ 
points  (such  as  those  in  DEBUG)  for 
two  reasons.  First,  hardware  break¬ 
points  don’t  actually  modify  your  pro¬ 
gram.  This  means  that  you  can  set 
breakpoints  anywhere,  even  in  ROM. 
Also,  a  program  can’t  overwrite  a  break¬ 
point  when  it  modifies  itself  or  loads 
an  overlay.  Second,  it  is  possible  to 
set  breakpoints  on  data.  A  data  break¬ 
point  triggers  when  your  program  ac¬ 
cesses  a  certain  memory  location. 

Microsoft’s  CodeView  implements 
a  similar  data  breakpoint  capability, 
called  “tracepoints.”  To  maintain  com¬ 
patibility  with  non-386  PCs,  however, 
CodeView  doesn’t  use  386  features. 
As  a  result,  CodeView  checks  trace- 
points  after  the  execution  of  each  in¬ 
struction.  This,  of  course,  is  terribly 
slow.  By  moving  the  tracepoints  to 
386  hardware,  execution  isn’t  slowed 
down  at  all.  Actually,  you  will  usually 
want  to  slow  down  execution  just  a 
bit  (see  the  discussion  of  the  exact 
bit).  Even  then,  the  slowdown  in  exe¬ 
cution  is  imperceptible. 

Because  there  are  four  debug  ad¬ 
dress  registers  in  the  80386,  it  is  possi¬ 
ble  to  have  four  active  breakpoints 
at  once.  Each  address  register  (DR0- 
DR3)  represents  a  linear  address  at 
which  a  different  breakpoint  will  oc¬ 
cur.  In  protected  mode,  the  concept 
of  a  linear  address  is  not  straightfor¬ 
ward.  In  real  mode,  however,  a  linear 
address  can  easily  be  calculated  from 
a  segment/offset  pair.  Simply  multi¬ 
ply  the  segment  value  by  10  hex  (shift 
left  4  bits)  and  add  the  offset.  For 


example,  to  set  a  data  breakpoint  at 
B800:0020  (somewhere  in  the  CGA 
video  buffer),  you  would  need  a  lin¬ 
ear  address  of: 

B800  x  10  +  20  =  B8020 

Once  you  have  loaded  the  address 
registers,  you  must  enable  the  break¬ 
points  you  wish  to  use  and  tell  the 
processor  what  type  of  breakpoints 
they  are.  This  is  done  via  the  debug 
control  register  (DR7).  DR7  contains 
bits  to  enable  each  breakpoint  and 
to  set  their  type  individually  (see  Fig¬ 
ure  4).  You  will  notice  that  DR7  has 
global  and  local  enable  bits  as  well 
as  global  and  local  exact  bits  (ex¬ 
plained  shortly).  The  difference  be¬ 
tween  the  various  global  bits  and  lo¬ 
cal  bits  is  only  important  when  the 
80386  is  multitasking  in  protected 


mode.  For  the  purpose  of  this  article, 
they  are  the  same. 

The  Exact  Bits 

The  exact  bits  are  flags  to  tell  the 
80386  to  slow  down.  At  first  glance, 
this  doesn’t  seem  to  be  helpful,  but  a 
detailed  look  at  the  80386  architec¬ 
ture  reveals  the  purpose  of  this  bit. 

The  80386  gains  some  of  its  speed 
by  overlapping  instruction  fetches  and 
data  fetches.  This  is  an  excellent  idea 
when  executing  code,  but  causes  prob¬ 
lems  in  debugging  data.  Without  the 
exact  bit  set,  a  data  breakpoint  will 
not  occur  at  the  instruction  that  caused 
the  data  access!  Being  somewhat  of 
an  inconvenience,  Intel  included  the 
GE/LE  bits.  With  either  (or  both)  of 
them  set,  data  breakpoints  will  occur 
immediately  after  the  instruction  that 
caused  them,  although  the  processor 
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Legend: 

X 

=  Reserved  bit,  do  not  use 

Len 

=  Breakpoint  length 

R/W 

=  Breakpoint  read/write  status 

GE 

=  Global  exact 

LE 

=  Local  exact 

G0-G3 

=  Global  breakpoint  enable  (breakpoints  0-3) 

L0-L3 

=  Local  breakpoint  enable  (breakpoints  0-3) 

GD 

=  General  Detect 

Figure  4:  Bits  contained  in  DRV  to  enable  and  set  the  type  of  breakpoints 
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Legend: 

X 

=  Reserved  bit,  do  not  use 

BO-3 

=  Breakpoint  occurred 

BD 

=  Illegal  access  to  breakpoint  registers 

BS 

=  Single  step  interrupt  occurred 

BT 

=  Task  switch  occurred 

Figure  5:  Bits  in  DR6  corresponding  to  the  various  breakpoints  conditions 
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you  are  monitoring  a  word  at  2200:00F0 
and  a  program  writes  a  byte  to  2200: 
00F1,  a  breakpoint  will  occur. 

Setting  a  data  breakpoint  with  break- 
386( )  will  also  set  the  global  exact  bit. 
When  all  the  data  breakpoints  are  either 
reassigned  or  deactivated,  break386( ) 
will  clear  the  exact  bit. 

Because  intl_386( )  always  sets  the 
resume  flag,  you  will  find  that  a  code 


will  lose  a  slight  amount  of  speed. 

Other  Bits 

All  debug  breakpoints  generate  an 
interrupt  1.  To  distinguish  the  various 
breakpoints,  you  must  read  the  de¬ 
bug  status  register  (DR6).  DR6  has 
bits  corresponding  to  the  various  break¬ 
point  conditions  (see  Figure  5).  Note 
the  BT  flag  at  bit  15.  As  with  the  local 
bits  in  DR7,  only  multitasking  sys¬ 
tems  use  the  BT  flag.  Therefore,  the 
flag  is  not  considered  in  this  article. 
The  386  never  clears  the  bits  in  DR6, 
so  after  you  determine  what  caused 
the  interrupt,  you  should  clear  DR6. 

The  Only  Other  Bit  We  Haven't 
Discussed  is . , . 

With  the  general  detect  (GD)  bit  set 
in  DR7,  the  80386  prohibits  access  to 
the  debug  registers.  Any  attempt  to 
access  the  debug  registers  will  cause 
an  interrupt  1  with  the  BD  flag  set  in 
DR6.  Intel’s  in-circuit  emulator  uses 
this  feature,  although  you  can  use  it 
if  you  have  any  reason  to  disable  or 
control  access  to  the  debug  registers. 
When  a  GD  interrupt  occurs,  the  in¬ 
terrupt  handler  is  invoked  and  the 
GD  bit  is  cleared.  Otherwise,  the  rou¬ 
tine  would  fault  (with  an  endless  loop) 
when  the  interrupt  routine  attempted 
to  read  DR6. 

You  can  decide  from  the  interrupt 
routine  whether  to  terminate  the  user 
program,  or  to  allow  access  to  the  regis¬ 
ters.  BREAK386  does  not  use  theGD  bit. 

The  Resume  Flag 

The  last  consideration  with  breakpoint 
interrupts  is  how  to  resume  the  inter¬ 
rupted  program.  If  we  simply  return 
(as  in  a  normal  interrupt),  there  is 
nothing  to  stop  a  code  breakpoint 
from  occurring  again  immediately.  The 
resume  flag  (found  in  the  flag’s  regis¬ 
ter)  prevents  this  from  occurring.  This 
flag  inhibits  further  debug  exceptions 
while  set,  and  resets  automatically  as 
soon  as  one  instruction  successfully 
executes.  Control  of  the  resume  flag 
is  automatic  in  protected  mode.  Han¬ 
dling  it  from  real  mode,  however,  is 
somewhat  of  a  trick,  as  seen  in 
BREAK386.  —  A.W. 
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|  breakpoint  that  immediately  follows  a 
data  breakpoint  won’t  work.  I’ll  show 
how  this  can  be  rectified  shortly. 

Because  INT  and  INTO  instructions 
temporarily  clear  the  trace  flag,  BREAK- 
386  will  not  single  step  through  inter¬ 
rupt  handlers.  If  you  wish  to  single 
step  through  an  interrupt  routine,  you 
will  have  to  set  a  breakpoint  on  its  first 
instruction.  A  replacement  for  intl_ 
386( )  might  emulate  INT  and  INTO 
instructions  to  solve  this  problem. 

Because  BREAK386  uses  BIOS  key¬ 
board  and  video  routines,  take  care 
when  placing  breakpoints  in  these  rou¬ 
tines.  In  addition,  single-stepping  BIOS 
keyboard  and  video  routines  should 
be  avoided.  If  you  must  debug  in  these 
areas,  reassemble  BREAK386  so  that  it 
doesn’t  use  BIOS  (see  the  DIRECT 
equate  in  BREAK386.ASM).  Note,  how¬ 
ever,  that  many  of  its  features  will  no 
longer  function.  Finally,  you  should 
avoid  setting  breakpoints  in  BREAK386’s 
code  or  data. 

BREAK386.INC  contains  two  mac¬ 
ros,  traceon  and  traceoff,  that  can  be 
used  to  control  tracing.  You  may  insert 
them  anywhere  in  your  code  to  enable 
or  disable  tracing.  Remember,  how¬ 
ever,  that  you  will  see  the  traceoff  macro 
as  well  as  your  own  code  when  single 
stepping. 

The  function  clear386( )  must  be 
called  prior  to  exiting  the  program.  This 
turns  off  the  breakpoint  handlers.  If 
you  fail  to  call  clear386(  )  for  any  rea¬ 
son  (a  control-break,  or  a  critical  er¬ 
ror),  the  next  program  that  uses  a  loca¬ 
tion  you  have  breakpointed  will  cause 
the  break  to  occur.  This  can  have  un¬ 
fortunate  consequences  because  your 
interrupt  1  handler  is  probably  no  longer 
in  memory.  If  you  find  that  you  have 
exited  a  program  without  turning  off 
debugging  and  you  have  not  encoun¬ 
tered  a  breakpoint,  run  DBGOFF  (List¬ 
ing  Six,  page  104)  to  turn  off  hardware 
debugging. 

With  some  care,  BREAK386  can  be 
used  with  other  debuggers.  In  Code¬ 
View,  for  example,  BREAK386  seems 
to  work  fine,  as  long  as  you  are  not 
single  stepping  (via  CodeView).  When 
you  single  step  data  breakpoints  will 
be  ignored  and  BREAK386  code  break¬ 
points  will  “freeze”  CodeView  at  that 
step.  If  you  are  using  BREAK386  with 
CodeView,  it  is  probably  a  good  idea 
to  leave  the  code  breakpoints  and  sin¬ 
gle  stepping  to  CodeView. 

Detailed  Program  Operation 

BREAK386  (Listing  One)  begins  with 
the  .386P  directive,  which  ensures  that 
MASM  5.0  will  generate  references  to 
the  debug  registers.  Be  careful  to  place 
the  .MODEL  directive  before  the  .386P, 
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(continued  from  page  52) 
otherwise  32-bit  segments  will  be  gen¬ 
erated  (which  doesn’t  work  well  with 
unmodified  DOS!). 

The  parameters  you  may  want  to 
change  are  near  the  top  of  the  source 
file.  The  equate  to  DIRECT  controls  the 
video  mode.  If  DIRECT  is  0,  BREAK386 
uses  BIOS  for  input  and  output.  If, 
however,  you  want  to  poke  around  in 
the  keyboard  or  video  routines,  you 
must  set  DIRECT  to  1.  This  causes 
BREAK386  to  use  direct  video  output 
for  the  debug  dump.  It  will  share  the 
screen  with  your  program  (no  video 
swapping)  and  breakpoints  will  simply 
terminate  the  program  in  a  similar  man¬ 
ner  to  the  “A”  command  mentioned 
earlier. 

You  can  change  the  STKWRD  equate 
to  control  how  many  words  are  dumped 
from  the  stack  when  using  inti _386(  ). 
Setting  STKWRD  to  zero  will  completely 
disable  stack  dumping.  Similarly,  if  you 
set  INTSTACK  to  zero,  the  display  will 
not  show  the  IP/CS/FLAGS  at  the  top 
of  the  stack.  If  you  are  writing  your 
own  interrupt  handler  and  don’t  need 
inti _386(  ).  you  can  assemble  with  /:7V- 
ABLE_INT1  set  to  zero  to  reduce 
BREAK386’s  size. 

The  operations  of  start386(  ),  clear- 
386(  ).  and  break386(  )  are  fairly  straight¬ 
forward.  The  implementation  of  intl_ 
386(  )  deserves  some  comment.  It  is 
important  to  realize  that  inti _386(  ) 
only  debugs  non-386-specific  programs 
because  it  only  saves  the  16-bit  regis¬ 
ters  and  the  8086  segment  registers 
( intl_386( )  does  not  destroy  FS  and 
GS).  Because  intl_386(  )  only  runs  on 
a  386,  it  does  use  the  32-bit  registers. 
You  can  easily  modify  inti _386( )  to 
save  all  the  386  registers,  but  it  requires 


more  space  on  the  interrupted  pro¬ 
gram’s  stack. 

The  most  difficult  aspect  of  the  inter¬ 
rupt  handler  is  managing  the  resume 
flag.  The  code  below  label  cl  converts 
the  three  words  at  the  top  of  the  stack 
into  six  words  so  that  setting  the  re- 

2-  and  4-byte  data 
breakpoints  must  be 
aligned  according  to 
their  size.  For  example, 
it  is  incorrect  to  set  a 
2-byte  breakpoint  at 
location  1000:0015 
because  that  location  is 
on  an  odd  byte 


sume  flag  is  possible.  There  are  three 
things  to  remember  about  the  way  the 
resume  flag  is  managed: 

1.  As  mentioned  earlier,  intl_386(  /al¬ 
ways  sets  the  resume  flag.  As  a  conse¬ 
quence,  a  code  breakpoint  that  occurs 
immediately  after  a  data  breakpoint  will 
not  cause  an  interrupt.  This  is  due  to  the 
resume  flag  being  set  even  though  the 
instruction  that  generated  the  data  break¬ 
point  has  already  executed.  When  the 
program  restarts,  the  next  instruction 


will  execute  with  the  resume  flag  set. 
This  could  be  rectified  by  not  setting 
the  resume  flag  in  the  interrupt  handler 
when  processing  data  breakpoints. 

2.  An  interrupt  handler  written  entirely 
in  C  has  no  way  to  manipulate  the 
resume  flag  properly.  Listing  Seven, 
page  104,  however,  shows  two  assem¬ 
bly  language  functions  that  allow  you 
to  write  your  handler  in  C.  (See  the 
next  section  for  more  details  on  writing 
C  interrupt  handlers.) 

3.  In  real  mode,  hardware  interrupt  han¬ 
dlers  (for  example,  those  in  the  BIOS) 
will  probably  not  preserve  the  resume 
flag.  This  means  that  if  your  code  runs 
with  interrupts  enabled,  there  is  some 
chance  that  one  breakpoint  will  cause 
two  interrupts.  This  chance  increases 
greatly  if  interrupts  remain  disabled  dur¬ 
ing  the  interrupt  1  processing.  Why  is 
this  true?  If  the  80386  receives  a  hard¬ 
ware  interrupt  just  before  executing  an 
instruction  with  the  resume  flag  set,  it 
will  process  that  interrupt.  When  the 
interrupt  returns,  the  resume  flag  is  clear 
and  the  breakpoint  occurs  again.  When 
interrupts  are  disabled  during  break¬ 
point  processing,  it  is  far  more  likely 
that  an  interrupt  is  pending  when  the 
program  restarts.  If  interrupts  were  en¬ 
abled  while  processing  the  debug  in¬ 
terrupt,  however,  there  is  little  chance 
of  this  happening.  If  it  does,  simply 
press  “C”  (when  using  intl_386(  /). 

Advanced  Interrupt  Handlers  in  C 

It  is  possible  to  write  an  interrupt  han¬ 
dler  completely  in  C  to  monitor  data 
breakpoints.  The  handler  must  be  de¬ 
clared  as  a  far  interrupt  function.  For 
example,  the  following  function  could 
be  linked  with  the  example  in  Listing 
Five: 

void  interrupt  far 

newl(Res,Rds,Rdi,Rsi,Rbp,Rsp,Rbx,Rdx, 

Rex, Rax) 

I 

printfl  "\  nBreakpoint  reached.  \  n"); 


By  calling  setup386newl(  )  instead  of 
setup386( inti  386).  newl(  /  will  be  in¬ 
voked  for  every  breakpoint.  Your  func¬ 
tion  can  read  and  write  the  interrupted 
program’s  registers  using  the  supplied 
parameters  ( Rax,  Rbx.  and  so  on).  Keep 
in  mind  that  you  cannot  use  this  tech¬ 
nique  for  code  breakpoints.  C’s  inabil¬ 
ity  to  manipulate  the  resume  flag  will 
cause  an  endless  loop  on  a  code  break¬ 
point. 

Listing  Seven,  provides  the  functions 
to  write  interrupt  handlers  in  C.  The 
procedure  is  much  the  same  as  de¬ 
scribed  earlier,  except  that  you  must 
(continued  on  page  57) 
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retcode  =  break386(n, type, address); 
where: 

n  is  the  breakpoint  number  (from  1  to  4). 

type  is  the  type  of  breakpoint.  This  should  be  one  of  the  manifest  constants  defined  in 
BREAK386.H  (or  BREAK386.INC).  If  you  are  clearing  the  breakpoint,  the  type  is  not 
meaningful. 

address  is  the  address  to  set  the  breakpoint.  This  must  be  a  far  address  (that  is,  one 
with  both  segment  and  offset).  If  you  are  using  small  model  C,  you  should  cast  the 
pointer  to  be  a  far  type  (see  the  example).  To  clear  a  breakpoint,  set  address  to 
0000:0000  (or  a  far  NULL  in  C). 

retcode  is  returned  by  the  function.  A  zero  indicates  success.  A  non-zero  value  means 
that  you  tried  to  set  a  breakpoint  less  than  1  or  greater  than  4.  Note  that  the  type 
parameter  is  not  checked  for  validity. 


The  types  available  are: 
BPCODE 
BPDATAW1 
BPDATARW1 
BPDATAW2 
BPDATARW2 
BPDATAW4 
BP  DATARW4 


-  Code  breakpoint 

-  One  byte  data  write  breakpoint 

-  One  byte  data  read/write  breakpoint 

-  Two  byte  data  write  breakpoint 

-  Two  byte  data  read/write  breakpoint 

-  Four  byte  data  write  breakpoint 

-  Four  byte  data  read/write  breakpoint 


Figure  2:  The  parameters  required  by  break386(  ) 


54 


386  DEBUGGING 


(continued  from  page  54) 
call  csetup386(  )  instead  of  setup386(  ). 
The  argument  to  csetup386(  )  is  always 
a  pointer  to  an  ordinary  far  function 
(even  in  small  model). 

The  actual  interrupt  handler  is  _cintl_ 
386( ).  This  function  will  call  your  C 
code  when  an  interrupt  occurs.  _cintl 
_386( )  passes  your  routine  two  argu¬ 
ments.  The  first  argument,  a  far  void 
pointer,  is  set  to  the  beginning  of  the 
interrupted  stack  frame  (see  Figure  3 
for  the  format  of  the  stack  frame).  The 
second  argument  is  an  unsigned  long 
in/that  contains  the  contents  of  DR6. 

All  registers,  and  local  variables  on 
the  stack  can  be  read  using  the  pointer 
to  the  stack  frame  (if  you  know  where 
to  look).  In  addition,  all  values  (except 
SS)  can  be  modified.  It  is  usually  wise 
not  to  modify  SP,  CS,  or  IP. 

_cintl_386( )  switches  to  a  local 
stack.  The  size  of  the  stack  can  be 
controlled  using  STACKSIZE  (near  the 
top  of  Listing  Seven).  Be  sure  to  adjust 
the  stack  if  you  need  more  space. 

Listing  Eight  (page  105)  shows  an 
example  of  an  interrupt  handler  in  C. 
The  example  interrupt  handler  displays 
a  breakpoint  message  and  allows  you 
to  continue  with  err  without  breakpoints, 
abort  the  program,  or  change  the  value 
of  a  local  variable  in  the  loop(  )  function. 


Future  Directions 

Many  enhancements  and  modifications 
are  possible  with  BREAK386.  By  alter- 


Address 

i 

Contents 
\  \ 

PTR+28 

Code  s  stack 

PTR+26 

Flaas 

PTR+24 

CS 

PTR+22 

IP 

PTR+20 

AX 

PTR+18 

CX 

PTR+16 

DX 

PTR+14 

BX 

Points  to  IP 

PTR+12 

SP 

"*  (above) 

PTR+10 

BP 

PTR+8 

SI 

PTR+6 

D1 

PTR+4 

ES 

PTR+2 

DS 

^Pointer  passed 

PTR+0 

SS 

Example: 

(PTR) 

To  read  AX  use: 

n=*((unsigned  int  far  *)PTR+10); 

Here,  we  add  1 0  to  PTR  rather  than  20 
since  PTR  is  cast  to  an  unsigned  int 
pointer  and  each  unsigned  int  is  two 
bytes  long. 

Figure  3:  Stack  frame  passed  to  the  C 
interrupt  handler 


ing  the  words  on  intl_386(  )’ s  stack,  for 
example,  you  can  modify  registers.  You 
can  redirect  output  to  the  printer  (al¬ 
though  you  can  screen  print  the  display 
now)  by  replacing  the  OUCH  routine. 
Perhaps  the  most  ambitious  enhancement 
would  be  to  use  BREAK386  as  the  core 
of  your  own  debugger.  You  could  write 
a  stand-alone  debugger  or  a  TSR  de¬ 
bugger  that  would  pop  up  over  an¬ 
other  debugger  (DEBUG  or  CodeView). 

Keep  in  mind  that  386  hardware  break¬ 
points  aren’t  just  for  debugging.  The 
data  breakpoint  capability  has  many 
uses.  For  example,  you  might  want  to 
monitor  the  BIOS  keyboard  typeahead 
buffer's  head  and  tail  pointers  to  see 
when  a  keystroke  is  entered  or  removed. 
In  this  manner  you  could  capture  the 
keyboard  interrupt  in  such  a  way  that 
other  programs  couldn't  reprogram  your 
interrupt  vector. 

You  can  also  use  data  breakpoints 
to  detect  interrupt  vector  changes  or 
interrupt  processing.  Some  assembly 
language  programs  could  use  data  break¬ 
points  for  automatic  stack  overflow  de¬ 
tection.  Programs  that  decrement  the 
stack  pointer  without  using  a  push  in¬ 
struction  (Microsoft  C  programs,  for  ex¬ 
ample)  are  not  candidates  for  this  type 
of  stack  protection. 

Debugging  with  386  assistance  is  quite 
practical  and  useful.  The  programs  pre¬ 
sented  here  should  get  you  started  and 
help  you  develop  your  own  programs 
with  this  powerful  hardware  feature. 
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Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobbs  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DD/  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  96.) 
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Part  II 


Managing  Multiple 
Data  Segments  Under 
Microsoft  Windows 


The  segment  table  provides  a  little-known  way  of  managing 
multiple  data  segments 


Tim  Paterson  and  Steve  Flenniken 


In  last  month’s  installment,  we  pre¬ 
sented  a  method  for  managing  mul¬ 
tiple  data  segments  under  MS  Win¬ 
dows  using  a  little-known  Windows 
feature,  the  segment  table,  along 
with  a  library  of  macros  and  functions 
to  assist  in  applying  the  technique.  For 
this  month's  installment,  we’ve  prepared 
a  sample  Windows  program  called  “seg¬ 
ments”  that  demonstrates  the  segtable 
library.  In  its  “random  action”  phase,  it 
randomly  allocates,  reallocates,  and  frees 
global  memory.  A  window  displays  sta¬ 
tistics  about  each  memory  block,  in¬ 
cluding  its  pSeg  (the  address  of  its  Seg- 
mentTable  entry),  the  current  segment 
number,  the  previous  segment  num¬ 
ber,  and  the  number  of  times  it  has 
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moved  since  it  was  allocated.  A  timer 
function  is  used  to  keep  the  window 
continuously  updated,  even  when  an¬ 
other  application  has  the  input  focus. 

The  sample  application  in  Listing  One 
(page  106)  uses  one  segment  as  the 
place  to  keep  track  of  all  the  other 
segments  that  it  fiddles  with  and  dis¬ 
plays  in  the  window.  That  segment 
contains  an  array  of  structures,  one  for 
each  additional  segment.  Because  it  is 
referenced  so  often,  the  macro  FAR- 
DATAP  is  defined  to  return  the  far 
pointer  to  the  first  structure  in  this  seg¬ 
ment.  Listings  Two  through  Five  (be¬ 
ginning  on  page  108)  provide  the  rest 
of  the  files  required  by  the  application. 

The  menu  bar  is  used  to  start  and 
stop  the  random  action  mode.  When 
on,  the  timer  function  picks  one  of  the 
structures.  If  the  structure  does  not  yet 
have  a  pSeg,  it  allocates  one  with  a 
random  amount  of  memory.  If  it  al¬ 
ready  has  a  pSeg,  it  will  do  one  of  three 
things:  Reallocate  the  pSeg  with  a  differ¬ 
ent  memory  size;  free  the  data,  but 
keep  the  pSeg;  or  free  the  pSeg  alto¬ 
gether.  Whenever  a  segment  is  allo¬ 
cated  or  reallocated,  a  text  string  con¬ 
taining  the  last  action  (“A"  for  allocate 
or  “R”  for  reallocate)  and  the  size  of  the 


segment  (for  example,  “1484  bytes”) 
is  copied  into  the  segment  as  its  data. 
Whether  the  random  action  is  on  or 
off,  the  function  checks  to  see  if  any 
of  the  segment  numbers  in  the  seg¬ 
ment  table  have  changed,  and  updates 
the  display  window  if  they  have. 

This  sample  is  a  useful  demonstra¬ 
tion  in  two  ways.  First,  it  has  examples 
on  how  to  code  with  the  segment  ta¬ 
ble.  It  includes  many  references  to  its 
far  array  of  memory  descriptor  struc¬ 
tures,  and  shows  how  IFP  (indirect  far 
pointer)  parameters  are  passed  to  the 
functions  strcpyifpf  )  and  strlenifpl ). 
Second,  it  makes  the  segment  table 
visible  through  a  window  so  that  its 
activity  can  be  observed.  As  other  ap¬ 
plications  are  run  (with  random  action 
stopped),  you  can  see  the  effects  as 
Windows  keeps  rearranging  memory. 
Unless,  of  course,  you  are  using  LIM  4.0 
EMS,  which  lets  Windows  just  swap  the 
data  out  without  physically  moving  it. 

Read-Only  Data 

Some  applications  use  large  amounts 
of  read-only  (constant)  data.  An  exam¬ 
ple  of  this  is  Microsoft  Excel,  which  is 
written  in  C  and  compiled  into  pcode, 
not  native  8086  code.  The  pcode  is 
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(continued  from  page  58) 
data,  not  code,  because  it  is  never  actu¬ 
ally  executed.  Other  applications  could 
simply  have  large  amounts  of  data  in 
the  form  of  tables  or  other  structures. 

Like  code,  read-only  data  should  be 
marked  as  discardable  in  the  linker  defi¬ 
nition  file.  This  allows  Windows  to  throw 
it  away  to  make  room,  but  reload  it  from 
disk  later  when  needed.  Another  good 
practice  is  to  keep  segment  size  to  less 
than  16K,  the  size  of  the  LIM  3.2  ex¬ 
panded  memory  page  frame.  Windows 
can  then  choose  to  use  space  in  EMS 
for  those  segments  that  fit,  entirely  trans¬ 
parent  to  the  application. 

Code  and  read-only  data  don't  sound 
any  different  so  far,  but  there  is  an 
important  distinction.  Windows  keeps 
track  of  how  often  each  code  segment 
is  used,  in  order  to  help  it  make  a  good 
decision  on  discarding  one  when  it 
needs  to  free  some  memory.  It  does 
this  with  the  reload  thunk.  Every  far 
call  to  a  discardable  segment  actually 
calls  a  thunk  specific  to  that  entry  point. 
If  the  segment  being  called  is  present 
in  memory,  the  thunk  will  contain  a 
jump  to  the  entry  point.  If  the  segment 
is  not  loaded,  the  thunk  will  cause  Win¬ 
dows  to  load  it.  Either  way,  the  thunk 
also  notes  the  fact  that  a  call  to  that 
segment  was  made.  Windows  uses  a 
least-recently  used  (LRU)  algorithm  for 
determining  the  best  segment  to  discard 
when  memory  is  needed.  The  thunks 
are  the  source  of  its  information. 

The  easiest  way  to  deal  with  discard¬ 
able  read-only  data  segments  is  to  put 
a  little  code  in  them.  These  lines  of 
assembly  language  belong  in  each  seg¬ 
ment  (but  with  a  unique  entry  point 
name  for  each): 

Load_This_Segment : 
mov  ax,cs 
retf 

To  ensure  that  a  segment  is  loaded, 
and  to  find  out  where,  call  this  entry 
point.  The  return  value  in  ax  is  the 
segment  of  the  data.  The  call  to  this 
entry  point  is,  of  course,  actually  a  call 
to  a  thunk  that  ensures  the  segment  is 
loaded. 

The  segment  number  returned  by 
this  call  can  be  stuffed  into  an  empty 
entry  in  SegmentTable  so  that  it  will 
stay  updated  in  case  of  movement.  But 
recall  that  this  segment  can  also  be 
discarded.  In  that  case,  Windows  will 
update  the  segment  table  with  the  (even- 
numbered)  handle  for  that  segment. 
This  complicates  things  a  bit.  Now  we 
could  make  a  reference  to  the  segment 
table  and  find  an  even  number,  indi¬ 
cating  that  the  segment  we  want  has 
been  discarded.  Calling  the  entry  point 
(the  reload  thunk)  is  the  easiest  way 
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to  bring  the  segment  back. 

Once  the  segment  has  been  loaded, 
we  can  use  it  as  much  as  we  want,  as 
long  as  Windows  doesn’t  discard  it. 
But  if  we  never  call  the  segment’s  entry 
point  again,  Windows  will  think  we’ve 
stopped  using  it  —  after  all,  it’s  the  calls 
through  the  thunk  that  keep  track  of 
usage.  Without  periodic  calls  to  the 
entry  point,  this  segment  will  be  one  of 
the  first  to  be  discarded,  no  matter  how 
much  we’ve  actually  been  using  it. 

Fortunately,  Windows  provides  a 
mechanism  to  remind  us  to  call  the 

Some  applications  use 
large  amounts  of  read¬ 
only  (constant)  data. 
An  example  of  this  is 
Microsoft  Excel 


entry  point  periodically.  On  a  regular 
basis  (typically  every  fourth  timer  tick, 
or  4.5  times  per  second),  Windows  per¬ 
forms  an  “LRU  sweep.”  One  of  the 
things  Windows  will  do  during  the  LRU 
sweep  is  to  fill  part  of  our  segment 
table  with  zeros.  The  number  of  words 
set  to  zero  is  specified  in  SegmentTable!  1) 
the  zero  fill  starts  at  SegmentTabIe/2 '/.  In 
addition,  SegmentTable!  11  itself  is  also 
set  to  zero,  which  means  nothing  will 
be  zero-filled  again  until  it  is  reset  to 
some  value.  This  use  of  SegmentTable!  11 
suggests  using  a  macro  to  give  it  the 
name  cwClear. 

The  idea  is  to  set  aside  the  first  por¬ 
tion  of  the  segment  table  for  read-only 
data.  At  every  LRU  sweep,  Windows 
will  zero  fill  the  segment  numbers  that 
were  stored  in  there.  When  we  try  to 
access  a  segment  number  that  has  been 
zeroed,  we  will  see  an  even  number 
and  conclude  it  was  discarded.  Then 
we  call  the  segment’s  entry  point  to 
reload  it,  and  the  thunk  will  record  the 
activity.  Hopefully,  this  will  prevent  the 
segment  from  being  discarded  while  it 
is  still  needed.  The  overhead  of  zero 
filling  the  table  and  calling  the  entry 
point  is  quite  small  compared  with  the 
time  to  reload  a  segment  from  disk. 

Note  that  the  segtable  library,  as  writ¬ 
ten,  is  not  set  up  for  this  type  of  use. 
The  non  discardable  data  segments, 
such  as  segDgroup,  must  be  moved 
above  the  zero-fill  area  in  SegmentTable. 
Because  there  are  a  fixed  number  of 
read-only  data  segments,  they  would 
probably  each  have  their  own  fixed 
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(continued  from  page  60) 
segment  table  entry.  New  access  mac¬ 
ros  would  be  required  that  could  deal 
with  a  segment  that  was  not  present. 

Debugging  Considerations 

Microsoft  considers  the  ideal  environ¬ 
ment  for  running  Windows  to  be  a 
80386  computer  with  extended  mem¬ 
ory  running  386MAX  by  Qualitas  of 
Bethesda,  Maryland.  386MAX  puts  the 
computer  into  Virtual  8086  Mode  and 
manages  memory  by  using  the  386’s 
paging  mechanism.  It  provides  three 
important  benefits  for  Windows.  First, 
it  fully  emulates  LIM  4.0  expanded  mem¬ 
ory  (EMS).  Second,  it  performs  the  same 
function  as  the  Windows  program  HI- 
MEM.SYS,  making  available  the  first  64K 
of  extended  memory  for  use  by  Win¬ 
dows.  Third,  it  allows  TSR  programs 
such  as  mouse  and  network  drivers  to 
be  loaded  out  of  the  way  of  conven¬ 
tional  memory  —  the  base  640K  mem¬ 
ory  space. 

When  Windows  finds  itself  loaded 
into  a  computer  with  LIM  4.0  EMS,  and 
there’s  a  fair  amount  (like  256K)  of 
conventional  memory  left,  it  will  use 
“large  frame”  EMS.  This  means  that  the 
base  640K  memory  space  becomes  part 
of  the  EMS  page  frame.  Windows  can 
then  swap  different  logical  memory 
pages  into  the  base  640K. 

While  this  is  a  great  way  to  run  Win¬ 
dows,  especially  when  running  several 
large  applications,  it’s  not  so  good  for 
debugging  with  Symdeb.  Symdeb  seems 
to  get  confused  by  the  EMS  swapping, 
and  we’ve  gotten  some  very  strange 
results.  Now  we  always  disable  386MAX 
whenever  we  will  be  debugging  a  Win¬ 
dows  program  with  Symdeb.  On  the 
other  hand,  CodeView  for  Windows  is 
apparently  so  large  that  Windows 
doesn’t  use  large  frame  EMS.  Code¬ 
View  is  so  big  that  it  requires  EMS  to 
run,  and  it  works  fine  with  386MAX. 

While  my  comments  about  EMS  ap¬ 
ply  generally  to  Windows  debugging, 
there  is  a  booby  trap  specific  to  work¬ 
ing  with  a  segment  table.  (Naturally 
we’re  telling  you  this  because  it  hap¬ 
pened  to  us.)  Recall  that,  during  Win¬ 
dows’  LRU  sweep,  civClear  (Segment- 
Table!  1J)  is  used  as  a  count  of  words 
in  the  segment  table  to  zero  fill.  Should 
this  word  get  accidently  set  through 
a  programming  error,  unbelievably 
strange  results  can  occur.  A  random 
value  stored  in  cwClear  will  zero  out  a 
random  amount  of  DGROUP ,  possibly 
including  your  stack.  What  makes  this 
bug  so  nasty  is  that  the  LRU  sweep  is 
driven  by  the  timer  tick  interrupt,  so 
the  data  gets  wiped  out  without  you 
ever  seeing  how.  Even  a  386  hardware 
breakpoint  will  not  necessarily  catch  it. 


(In  our  experience,  the  hardware  break¬ 
point  caught  this  bug  when  debugging 
with  a  serial  terminal,  but  not  when 
using  a  monochrome  monitor.) 

Extensions 

As  written,  the  segtable  library  and  as¬ 
sociated  macros  assume  that  the  seg¬ 
ments  in  the  table  are  always  present 
in  memory.  This  is  guaranteed  by  the 
fact  that  none  of  the  segments  in  the 
table  are  marked  as  discardable.  Ex¬ 
cept  for  DGROUP,  they  are  all  allocated 
by  SegmentAlloc( ),  which  does  not  set 
the  GMEMJ91SCARD ABLE  dug. 

If  the  use  of  the  segment  table  was 
expanded  to  include  read-only  segments 
as  discussed  above,  then  there  would 
be  discardable  segments  in  the  table. 
An  even  value  in  a  table  entry  would 
signify  that  that  segment  had  been  dis¬ 
carded.  More  complicated  access  mac-1 
ros  would  be  needed  to  account  for 
this  possibility  and  to  provide  the  mecha¬ 
nism  to  reload  the  segment.  The  mac¬ 
ros  could  take  one  of  two  approaches. 
The  first  method  would  be  to  always 
call  a  near  function  for  each  segment 
reference,  and  that  function  would  test 
for  an  even  entry  and  perform  the  re¬ 
load  if  needed.  The  alternative  is  to 
make  the  test  for  an  even  entry  in  line, 
and  call  a  function  only  when  reload¬ 
ing  is  necessary.  In  fact,  having  both 
of  these  forms  available  might  be  handy 
so  that  the  speed/size  tradeoff  can  be 
made  on  a  case-by-case  basis.  It  is  likely 
that  read-only  segments  would  be  used 
only  in  special  ways,  so  that  many  seg¬ 
ment  table  references  could  still  assume 
the  segment  was  always  present  and 
use  the  original,  more  efficient  macros. 

We  have  been  describing  the  whole 
idea  of  the  segment  table  as  being  suit¬ 
able  for  large  applications  with  multi¬ 
ple  segments  of  data.  There  is,  how¬ 
ever,  a  limit  on  how  much  data  a  Win¬ 
dows  program  can  have.  Being  non- 
discardable,  the  data  must  be  present 
in  memory  at  all  times.  This  usually 
limits  an  application  to  not  more  than 
300K  under  the  best  conditions.  Large 
frame  EMS  does  not  increase  this  limit, 
but  it  does  allow  each  of  several  appli¬ 
cations  running  simultaneously  to  have 
about  as  much  data  space  as  if  they 
were  running  alone. 

The  problem  is  the  640K  limit  on  con¬ 
ventional  memory,  and  one  possible  an¬ 
swer  is  EMS.  Windows  will  allow  individ¬ 
ual  applications  to  control  the  small  (LIM 
3.2-style)  EMS  frame,  which  provides  four 
16K  portholes  into  the  EMS  space.  It  is 
completely  up  to  the  application  to  man¬ 
age  its  expanded  memory,  using  inter¬ 
rupt  67H  to  access  EMS  functions. 

One  way  to  go  about  this  is  to  inte¬ 
grate  EMS  management  with  the  mem- 
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ory  management  functions  of  the 
segtable  library.  Any  data  segment  of 
less  than  16K  is  a  candidate  for  alloca¬ 
tion  in  EMS  instead  of  using  GlobalAl- 
loc( ).  SegmentAlloc( )  could  be  modi¬ 
fied  to  do  this,  putting  the  EMS  seg¬ 
ment  into  the  segment  table  and  re¬ 
turning  a  pSeg.  In  this  way,  the  use  of 
EMS  becomes  completely  transparent 
to  the  rest  of  the  application. 

There  is,  however,  a  serious  draw¬ 
back.  Because  there  is  space  for  only 
four  EMS  pages  in  the  page  frame,  we 
can’t  allocate  more  than  four  pages 
before  we  run  out  of  places  to  put 
them.  Of  course,  the  whole  point  of 
EMS  is  that  we  can  have  many  mega¬ 
bytes  of  data,  but  we  only  need  to  use 
a  few  pages  at  any  one  time.  Some  of 
the  EMS  pages  we  allocate  for  data  will 
have  to  be  mapped  out  of  the  page 
frame  —  becoming  momentarily  inac¬ 
cessible  —  so  that  others  can  be 
mapped  in  when  we  need  them. 

Fortunately,  the  segment  table  mecha¬ 
nism  provides  a  handy  way  to  do  this. 
pSegs  are  the  handle  by  which  the  ap¬ 
plication  can  refer  to  any  chunk  of 
memory,  whether  conventional,  acces¬ 
sible  EMS,  or  inaccessible  EMS.  If  the 
pSeg  points  to  an  odd-numbered  value 
in  the  segment  table,  then  that  segment 
is  present;  if  it  points  to  an  even-num¬ 
bered  value,  then  it  is  not  present.  This 
is  exactly  the  same  rule  that  is  used  for 
read-only  data  segments. 

To  take  this  approach,  the  applica¬ 
tion’s  EMS  manager  must  ensure  that 
EMS  segments  are  odd.  Whenever  it 
must  change  the  EMS  map,  it  will  have 
to  update  the  segment  table.  When  a 
page  is  mapped  out,  its  segment  num¬ 
ber  in  the  table  must  be  found  and 
replaced  with  an  even-numbered 
marker.  This  marker  must  represent  suf¬ 
ficient  information  to  make  the  page 
accessible  again.  For  example,  1  byte 
of  the  marker  could  represent  an  index 
into  a  table  that  includes  the  EMS  han¬ 
dle,  while  the  other  byte  is  the  logical 
page  number.  Remember  that  only  15 
bits  are  available,  because  the  least  signifi¬ 
cant  bit  must  be  zero. 

The  access  macros  must  understand 
how  to  deal  with  segments  that  aren’t 
present,  using  the  same  general  tech¬ 
niques  as  they  would  for  read-only  seg¬ 
ments.  However,  the  segment  is  “re¬ 
loaded”  by  calling  the  EMS  manager, 
instead  of  by  calling  a  Windows  reload 
thunk.  The  application’s  memory  man¬ 
ager  will  need  to  have  some  reason¬ 
able  way  to  decide  which  logical  page 
to  map  out  when  a  different  one  must 
be  mapped  in.  One  approach  would 
be  to  approximate  the  LRU  algorithm 
by  discarding  the  least-recently  mapped- 
in  page.  Then  when  two  different  seg¬ 


ments,  say  A  and  B,  are  needed  at  the 
same  time,  this  can  be  ensured  by  the 
sequence  access-A,  access-B,  access- 
A.  The  second  access-A  is  required  be¬ 
cause  the  access-B  might  have  caused  A 
to  get  mapped  out.  This  could  happen 
only  if  A  was  already  present  at  the  start, 

Microsoft’s  own 
Windows  applications 
use  all  of  the  techniques 
discussed  here 


so  that  the  first  access-A  did  nothing. 

To  support  cases  when  more  than 
two  segments  were  needed  at  once,  a 
locking  mechanism  could  be  used.  This 
would  be  similar  to  Windows'  Global- 
Lock( )  and  GlobalUnlockC  ),  except  that 
it  would  be  handled  by  the  applica¬ 
tion’s  memory  manager.  A  streamlined 
alternative  to  making  function  calls  for 
locking  would  be  to  set  aside  one  or 
more  special  locations  in  the  segment 
table.  The  presence  of  the  segment  in 
a  special  location  would  tell  the  mem¬ 
ory  manager  not  to  map  it  out. 


If  the  computer  has  no  (or  not 
enough)  EMS,  we  can  still  do  some¬ 
thing  to  handle  large  amounts  of  data. 
By  using  the  segment  table  and  some 
additional  help  from  Windows,  we  can 
set  up  a  virtual  memory  system  —  that 
is,  disk  swapping.  The  key  is  to  allo¬ 
cate  memory  with  the  Windows  func¬ 
tion  GlobalAlloc( )  by  using  the  flags 
GMEM_DISCARDABLE  and  GMEM_ 
NOTIFY.  This  tells  Windows  that  it  can 
discard  the  memory  if  it  needs  to,  but 
to  ask  permission  first.  When  Windows 
notifies  the  application  that  it  would 
like  to  discard  a  segment,  we  can  write 
that  segment  to  disk  first,  then  stick  a 
marker  for  that  segment  in  the  segment 
table.  As  with  EMS,  the  marker  will 
represent  the  information  needed  to 
reload  the  segment  the  next  time  it  is 
accessed. 

The  function  that  Windows  will  call 
to  ask  permission  to  discard  a  segment 
is  set  by  using  GlobalNotify( ).  This  func¬ 
tion  is  documented  in  the  Windows  2.0 
SDK  update  booklet,  with  additional 
information  in  the  Windows  2.1  SDK 
update.  The  function  we  register  with 
Windows  in  this  manner  could  be  de¬ 
clared  as: 

BOOL  FAR  PASCAL 

NotifyProcl  HANDLE  hmem); 


FULL  AT&T  C++:  ANNOUNCING  VERSION  L3  2.0! 

Guidelines  announces  its  port  of  version  2.0  of  AT&T’s  C++  translator.  As  an 
object-oriented  language,  C++  includes:  classes,  multiple  inheritance,  member 
functions,  constructors  and  destructors,  data  hiding,  and  data  abstraction.  Object- 
oriented  means  that  C++  code  is  more  readable,  more  reliable,  and  more  reusable. 
And  that  means  faster  development,  easier  maintenance,  and  the  ability  to  handle 
more  complex  projects.  C++  is  Bell  Labs’  answer  to  Ada  and  Modula  2.  C++  will 
more  than  pay  for  itself  in  saved  development  time  on  your  next  project. 


C++ 

from  GUIDELINES  for  the  IBM  PC:  $395 

Requires  IBM  PC-AT  or  compatible  with  512K  plus  384K  extended  memory. 
Note:  C++  is  a  translator,  and  requires  the  use  of  Microsoft  C  4.0  or  later. 


Here  is  what  you  get: 

•  The  full  AT&T  v2.0  C++  translator  with 
extended  memory  support. 

•  Libraries  for  stream  I/O  and  complex 
math. 

•  C++  Primer,  the  definitive  book  on 
C++  version  2.0  by  Stanley  B.  Lippman. 

•  Sample  programs  written  in  C++. 

•  Printed  installation  guide  and 
documentation. 

•  30-day  money-back  guarantee. 


NOW  AVAILABLE  FOR 
UNIX  V/386  -  $495 

To  Order: 

Send  check  or  purchase  order  to: 

GUIDELINES  SOFTWARE,  INC. 
P.0.  Box  6368,  Dept.  DDJ 
Moraga,  CA  94570 

To  order  with  VISA  or  MC, 
phone  (415)  376-5527.  (California 
residents  add  sales  tax.) 


C++  was  ported  by  GUIDELINES  under  license  from  AT&T. 
Call  or  write  for  a  free  C++  information  package. 
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The  argument  is  supposed  to  be  the 
handle  of  the  segment  being  discarded. 
However,  the  Windows  2.1  SDK  up¬ 
date  says  that  in  Version  2.03,  it  was 
actually  the  segment  number,  not  the 
handle.  This  can  be  straightened  out 
for  both  versions  by  calling  Global- 
HandleC ),  which  can  take  either  the 
handle  or  segment  number  as  its  argu¬ 
ment,  and  will  return  them  both,  as 
mentioned  earlier. 

NotifyProcC )  is  a  function  in  the  ap¬ 
plication,  but  it  must  be  in  a  fixed  code 
segment.  It  will  be  called  for  each  seg¬ 
ment  Windows  would  like  to  discard. 
If  the  application  wants  the  segment 
locked,  the  function  can  return  a  false 
(zero)  value  and  Windows  will  not  dis¬ 
card  it.  The  locking  protocols  could 
be  the  same  as  we  suggested  for  EMS: 
Adding  lock  and  unlock  functions,  and/ 
or  reserving  special  locations  in  the 
segment  table.  If  the  segment  isn’t 
locked,  NotifyProcC )  can  write  it  to  a 
disk  file  that  has  already  been  created 
for  that  purpose.  Then  it  returns  true 
and  Windows  will  reclaim  the  space. 

Any  of  these  extensions  —  read-only 
data,  EMS,  disk  swapping  —  may  be 
combined.  Using  any  one  of  them  re¬ 
quires  handling  the  case  of  segments 
that  are  not  currently  accessible.  Once 
this  jump  has  been  made,  the  others 
can  be  added  with  little  or  no  addi¬ 
tional  change  to  the  main  body  of  the 
application.  Microsoft’s  own  Windows 
applications  use  all  of  the  techniques 
discussed  here  (a  great  deal  of  time 
was  spent  using  Symdeb  on  Excel  in 
preparing  this  article).  While  we  ha¬ 
ven’t  covered  all  of  the  procedures  in 
detail,  these  ideas  can  be  used  to  build 
Windows  applications  with  virtually  un¬ 
limited  data  capacity. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobbs  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  106.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  5. 
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Object-Oriented 
Programming  in 
Assembly  Language 

OOP  applies  equally  well  to  assembly  language  and  high-level 

language  programs 


One  of  the  promises  of  the  ob¬ 
ject-oriented  paradigm  is  that 
it  will  reduce  program  com¬ 
plexity  and  implementation 
effort  for  many  different  types 
of  programs.  Object-oriented  program¬ 
ming,  however,  is  no  panacea.  It  is  a 
technique,  like  recursion,  that  you  can 
apply  in  certain  cases  to  reduce  pro¬ 
gramming  effort.  While  there  are  cer¬ 
tain  types  of  programs  whose  object- 
oriented  implementation  is  better,  ex¬ 
amples  abound  where  object-oriented 
programming  systems  (OOPS)  buy  you 
nothing.  Nonetheless,  object-oriented 
programming  techniques  are  a  valu¬ 
able  tool  to  have  in  one’s  war  chest. 

OOPS  are  nothing  new.  They  have 
been  around  since  the  late  1960s.  Yet 
the  object-oriented  paradigm  was  lan¬ 
guishing  until  Object  Pascal  and  C++ 
began  generating  mainstream  interest. 
The  success  of  these  languages  dem¬ 
onstrates  that  OOP  is  not  the  domain 
of  a  few  esoteric  programming  lan¬ 
guages.  Rather,  object-oriented  program¬ 
ming  is  applicable  to  almost  any  pro¬ 
gramming  language. 

Still,  assembly  language  may  not  seem 


Randy  is  the  designer  of  numerous  hard¬ 
ware  and  software  projects,  including 
assemblers  for  a  variety  of  systems.  In 
addition  to  consulting,  he  is  currently 
a  part-time  instructor  in  computer  sci¬ 
ence  at  California  Polytechnic  Univer¬ 
sity  in  Pomona  and  at  UC  Riverside. 
He  can  be  contacted  at  9570  Calle  La 
Cuesta,  Riverside,  CA  92503- 
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like  the  place  to  apply  the  object-ori¬ 
ented  programming  paradigm.  But  keep 
in  mind  that  people  were  saying  the 
same  thing  about  Pascal  and  C  five 
years  ago. 

What  does  an  object-oriented  assem¬ 
bly  language  program  look  like?  A  bet¬ 
ter  question  to  ask  is,  “What  is  the 
essence  of  an  object-oriented  program, 
and  how  does  one  capture  it  within 
an  assembly  language  program?”  Once 
you  strip  away  the  gloss  and  notation 
convenience  provided  by  languages 
such  as  C++,  you’ll  find  that  the  two 
main  features  of  an  object-oriented  pro¬ 
gram  are  polymorphism  and  inheritance. 

Polymorphism  takes  two  basic  forms 
in  most  programming  languages:  static 
and  dynamic.  The  general  idea,  how¬ 
ever,  is  the  same.  You  call  different 
subroutines  by  the  same  name.  Static 
polymorphism  provides  notational  con¬ 
venience  in  the  form  of  operator/func¬ 
tion  overloading  in  languages  such  as 
C++.  Static  polymorphism  uses  the 
parameter  list,  along  with  the  routine’s 
name  (together  they  form  the  routine’s 
signature),  to  determine  which  routine 
to  call.  For  example,  consider  the  C 
routines: 

CmplxAddCC(Cl,  C2,  C3); 

/*C1=C2+C3;*/ 

CmplxAddCR(Cl,  C2,  Rl); 

/*Cl=C2+ToCmplx(Rl);V 

CmplxAddRC(Cl,  Rl,  C2); 

/*C1  =ToCmplx(Rl  )+C2;  V 

In  C++  you  could  write: 


CmplxAdd(Cl,  C2,  C3); 

CmplxAdd(Cl,  C2,  Rl); 

CmplxAdd(Cl,  Rl,  C2); 

and  the  C++  compiler  would  figure  out 
whether  to  call  CmplxAddCC,  CmpbcAdd- 
CR,  or  CmplxAddRC.  (Actually,  you 
could  overload  C++’s  “+”  operator  and 
use  the  three  forms  C1=C2+C3;,  Cl= 
C2+R1;,  or  C1=R1+C2;,  but  the  exam¬ 
ple  above  would  be  still  valid.) 

Static  overloading,  while  convenient, 
does  not  add  any  power  to  the  lan¬ 
guage.  The  calls  to  CmpbcAdd  call  three 
different  routines.  CmplxAdd f  Cl, C2,C3) 
calls  CmplxAddCC,  CmpbcAdd  (C1,C2,R) 
calls  CmplxAddCR,  and  CmplxAdd- 
(C1,R,C2)  calls  CmplxAddRC.  The  C++ 
compiler  determines  which  routine  this 
code  will  call  at  compile  time.  Static 
polymorphism  is  a  mechanism  that  lets 
the  compiler  choose  one  of  several 
different  routines  to  call  depending 
upon  the  calling  signature. 

Sometimes  you  may  want  to  use  the 
same  signature  to  call  different  rou¬ 
tines.  For  example,  suppose  you  have 
a  class  shape  in  which  there  are  three 
graphical  objects:  circles,  rectangles,  and 
triangles.  If  you  have  an  arbitrary  ob¬ 
ject  of  type  shape,  the  compiler  cannot 
determine  which  DRAW routine  to  call. 
The  program  determines  this  at  run 
time.  This  allows  a  single  call  to  draw 
circles,  rectangles,  triangles  at  run  time 
with  the  same  machine  instructions. 
This  is  dynamic  polymorphism  —  de¬ 
termining  at  run  time  which  routine  to 
call.  C++  uses  virtual  functions  and  Ob- 
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ject  Pascal  uses  override  procedures 

and  functions  to  implement  dynamic 

polymorphism. 

Inheritance  lets  you  build  up  data 
structures  as  supersets  of  existing  data 
structures.  This  provides  a  mechanism 
whereby  you  can  generalize  data  types, 
allowing  you  to  handle  various  objects 
regardless  of  their  actual  type.  This  lets 
you  define  such  diverse  shapes  as  cir¬ 
cles,  rectangles,  and  triangles  and  treat 
them  as  compatible  structures. 

Implementing  Classes  and  Inheritance 

Because  structures  and  classes  are 


closely  related,  it  may  be  instructive  to 
look  at  the  implementation  of  struc¬ 
tures  before  looking  at  classes.  Con¬ 
sider  S,  a  variable  of  the  type  in  Exam¬ 
ple  1 .  Somewhere  in  memory  the  com¬ 
piler  needs  to  generate  storage  for  the 
fields  of  S.  Traditionally,  compilers  al¬ 
locate  these  fields  contiguously  (see 
Figure  1).  Indeed,  Microsoft's  assem¬ 
bler  (MASM)  allows  you  to  declare  struc¬ 
tures  in  a  similar  fashion,  as  shown  in 
Example  2.  If  S  provides  the  base  ad¬ 
dress  of  this  structure,  5+0  is  the  ad¬ 
dress  of  5.1,  5+2  is  the  address  of  S.j, 
and  S+4  is  the  address  of  S.c. 

Now  consider  the  case  of  a  pair  of 


C++  classes  (5c  and  7c)  in  Example  3. 
Pointers  to  objects  ( pS  and  pT)  may 
point  at  an  object  of  the  prescribed 
type  or  to  an  object  that  is  a  descendant 
of  the  pointer’s  base  class.  For  example, 
pS  can  point  at  an  object  of  type  5c  or 
at  an  object  of  type  7c.  Remember,  ac¬ 
cessing  *pS.j  is  equivalent  to  (int)  XpS+2), 
so  if  pS  points  at  an  object  of  type  7c, 
the  j  field  must  also  appear  at  offset 
two  within  the  structure.  For  inheritance 
to  work  properly,  the  common  fields 
must  appear  at  the  same  offset  within 
the  structure  (see  Figure  2). 

Additional  fields  in  the  subclass  often 
appear  after  the  fields  in  the  parent 
class,  so  most  compilers  implement  class 
Tc  as  in  Example  4.  Note  that  the  off¬ 
sets  to  i,  j,  and  c  are  the  same  for  both 
Sc  and  Tc. 

When  I  first  began  exploring  how 
to  implement  inheritance  in  assembly, 

I  got  the  bright  idea  of  using  macros 
inside  structure  definitions  to  handle 
the  problem  of  inheritance.  Briefly,  I 
wanted  to  implement  5c  and  Tc  as  in 
Example  5.  Unfortunately,  MASM 
doesn’t  allow  you  to  expand  macros 
or  strucs  inside  a  structure.  Disap¬ 
pointed,  I  tried  the  brute  force  way  to 
implement  5c  and  Tc.  as  illustrated  in 
Example  6. 

Unfortunately,  I’d  forgotten  that 
MASM  doesn’t  treat  these  symbols  as 
part  of  the  structure.  Names  such  as  i, 
j ,  c,  and  so  on  must  be  unique  in  the 
program.  As  you  can  plainly  see  in 
Example  6, 1  declared  i  twice,  and  the 
assembler  gave  me  a  “redefinition  of 
symbol"  error.  Almost  ready  to  give 
up,  I  tried  the  method  in  Example  7. 

MASM  simply  equates  the  field  names 
to  the  offsets  within  the  structure.  So  it 
equates  i  to  zero,  j  to  two,  and  so  on. 
MASM  does  not  associate  i  with  labels 
of  type  Sc.  You  can  use  the  symbols  Tj 
and  S.j  in  your  program.  Because  the 
operator  behaves  like  the  “+”  op¬ 
erator,  T.j  is  just  like  7+2, 

For  Tc  to  inherit  the  fields  of  5c,  all 
we  have  to  do  is  reserve  enough  space 
at  the  beginning  of  the  Tc  structure  for 


Example  1:  The  variable  S 


int  i; 
int  j; 
char  *c 


}  S; 


Example  4:  The  way  most  compilers 
implement  a  class  like  Tc 


int  i; 
int  j; 
char  *c; 
int  k; 
char  *d 


st  rue 

dw 

dw 

dd 

dw 

dd 

ends 


Example  2:  Declaring 
structures  in  MASM 


SType  struc 
i  dw 

j  dw 

c  dd 

SType  ends 


Example  3:  C++  classes 

class  Sc 
{ 

int  i; 
int  j; 

}? 

char  *c; 

Sc  *pS; 

Tc  *pT; 

Tclass  Tc:Sc 

); 

int  k; 
char  *d; 

Example  5:  One  approach 
to  implementing  Sc  and  Tc 


Scltems  macro 
i  dw 

dw 

c  dd 

endm 


Sc 

Sc 

Tc 

Tc 


macro 

Scltems 

dw 

dd 

endm 


struc 

Scltems 

ends 

struc 

Tcltems 

ends 


High  memory 

&S+4 

: 

c 

&S+2 

- 

j 

&S+0 

- 

i 

Low  memory 

Figure  1:  Storage  allocation  for  S 


pS+4 

pS+2 

pS+0 


High  memory 

d 

k 

c 

c 

i 

i 

i 

i 

Low  memory 

pT+10 

pT+8 

pT+4 

pT+2 

pT+0 


Figure  2:  Storage  allocation  for*  pT  and*  pS 
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each  of  the  fields  of  Sc.  Above,  I  stuck 
in  the  two  DW  and  the  DD  pseudo¬ 
opcodes  to  reserve  space  for  the  i,  j ', 
and  c  fields.  This  technique  might  get 
inconvenient  if  the  number  of  inher¬ 
ited  fields  is  large.  The  code  in  Exam¬ 
ple  8  solves  this  problem. 

The  first  DB  pseudoopcode  in  Tc 
reserves  the  necessary  space  for  the 
fields  Tc  inherits  from  Sc.  Likewise,  Uc 
(which  is  a  subclass  of  7c)  reserves 
space  at  the  beginning  of  the  structure 
for  the  fields  inherited  from  Tc  and  Sc. 
The  code  in  Example  8  works  great  if 
you  don’t  need  to  initialize  any  of  the 
fields  inherited  from  Sc.  if  you  need  to 
initialize  some  fields,  you’ll  have  to  use 
the  brute  force  method  and  redeclare 
space  for  each  field. 

Methods 

The  earlier  paragraphs  discuss  how  to 
implement  objects  whose  fields  are  all 
variables.  What  happens  when  you  in¬ 
troduce  methods?  If  you’re  not  over¬ 
loading  a  method,  you  can  treat  it  in 
the  same  manner  as  any  other  assem¬ 
bly  language  procedure  and  call  it  di¬ 
rectly.  If  you  are  overloading  a  method, 
you  must  call  it  indirectly  via  a  pointer 
within  the  object. 


Consider  the  C++  class  declaration 
in  Example  9.  The  assembly  code  im¬ 
plementing  this  class  is  shown  in  Ex¬ 
ample  10.  To  call  S.geti,  you  would  use 
the  8086  instruction:  CALL  S.geti. 

Because  S.geti  is  a  double  word  mem¬ 
ory  variable,  the  CALL  instruction  will 
call  the  procedure  S.geti,  which  points 
at  Sc_geti.  The  fact  that  we’re  calling  the 
methods  indirectly  will  be  useful  when 
we  look  at  overloading  a  little  later. 

THIS 

Suppose  we  have  three  instances  of 
class  Sc,  say  SI,  S2,  and  S3  declared  in 
assembly  language  as  follows: 

51  Sc 

52  Sc 

53  Sc 

Sl.geti ,  S2.geti,  and  SJ.geti  all  call  the 
same  procedure  (call  it  Sc_geti ).  How 
does  Sc_geti differentiate  between  Sl.i, 
S2.i,  and  S3  J?  In  object-oriented  lan¬ 
guages  such  as  Object  Pascal  and  C++, 
the  compiler  automatically  passes  a  spe¬ 
cial  parameter  named  this  to  the  method. 
this  always  points  at  the  object  through 
which  you’ve  invoked  the  method. 
When  you  execute  Sl.geti,  the  com¬ 
piler  passes  the  address  of  SI  in  this  to 


geti.  Likewise,  the  compiler  passes  the 
address  of  S2  in  this  when  you  call 
S2.geti. 

You  can  pass  this  to  a  method  just 
as  any  other  parameter.  Because  the 
most  efficient  way  of  passing  parame¬ 
ters  is  in  the  8086’s  registers,  I’ve  adopted 
the  convention  of  passing  this  in  the 
ES:BX  registers.  The  Sc_geti  method 
would  look  something  like  Example 
11  (assuming  we’re  returning  i  in  the 
AX  register).  This  example  demonstrates 
a  major  problem  with  object-oriented 
programming  —  it  is  very  inefficient. 
To  load  Sl.i  into  AX,  see  Example  12. 
This  requires  six  instructions  where, 
logically,  you  should  only  need  one 
(mov  ax,  Sl.i).  Welcome  to  the  won¬ 
derful  world  of  object-oriented  program¬ 
ming!  Yet  circumventing  all  this  over¬ 
head  by  loading  Sl.i  directly  into  AX 
will  eliminate  the  benefits  of  object- 
oriented  programming. 

Actually,  this  isn’t  as  bad  as  it  looks. 
A  good  part  of  the  time  ES:BX  will 
already  be  pointing  at  the  object  you 
want  to  access.  Nevertheless,  the  call 
and  return  are  considerable  overhead 
just  to  load  the  AX  register  with  a  word 
value.  Stroustrup  anticipated  this  prob¬ 
lem  when  designing  C++  and  he  solved 
it  by  providing  inline  functions  (a.k.a. 


Example  7:  Yet  another  attempt 
at  implementing  Sc  and  Tc 

Sc  struc 

i  dw  ? 

j  dw  ? 

c  dd  ? 

Sc  ends 

Tc  struc 

dw  ? 

dw  ? 

dd  ? 

k  dw  ? 

d  dd  ? 

Tc  ends 

S  Sc 

T  Tc 


Example  9:  A  C++  class  declaration 


class  Sc 
{ 

int  i,j; 
char  *c; 

public: 

int  geti()  {return  i};  /*  Ignore  the  fact  that  C++  */ 
int  getj()  {return  jj;  /*  would  implement  these  */ 

void  seti(x)  int  x;  {i  =  x;};  /*  methods  in-line.  */ 

void  setj(x)  int  x;  {j  =  x;}; 

}; 


Example  6:  The  brute  force 
method  of  implementing  Sc  and  Tc 


Sc 

struc 

i 

dw 

? 

j 

dw 

7 

c 

dd 

? 

Sc 

ends 

Tc 

struc 

i 

dw 

7 

j 

dw 

? 

c 

dd 

7 

k 

dw 

7 

d 

dd 

? 

Tc 

ends 

Example  8:  The  solution  to 
implementing  Sc  and  Tc 


3 

c 

Sc 


k 

d 

Tc 


struc 

dw 

dw 

dd 

ends 

struc 

db 

dw 

dd 

ends 

struc 

db 

dw 

ends 

Sc 

Tc 


(size  Sc)  dup  (?) 


(size  Tc)  dup  (?) 


Example  10:  Assembly  code  for 
implementing  the  code  in 
Example  9 


Sc 

struc 

i 

dw 

7 

j 

dw 

7 

c 

dd 

7 

geti 

dd 

Sc_geti 

getj 

dd 

Sc_get  j 

seti 

dd 

Sc_seti 

set  j 

dd 

Sc_set j 

Sc 

ends 
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macros).  We  can  use  this  same  tech¬ 
nique  in  assembly  language  to  improve 
efficiency  as  Example  13  illustrates.  This 
code  snippet  demonstrates  another  con¬ 
vention  I  adhere  to:  I  make  macros  for 
all  method  calls,  even  those  that  are 
actual  calls.  This  lets  me  use  a  consis¬ 
tent  calling  format  for  all  methods, 
whether  they  are  actual  subroutines  or 
are  expanded  in-line. 

There  is  one  major  drawback  to  ex¬ 
panding  a  procedure  inline;  you  can¬ 
not  overload  procedures  (C++’s  inline 
functions  suffer  from  this  as  well.  You 
cannot  have  an  inline  virtual  function). 


Therefore,  you  should  only  use  this 
technique  for  those  particular  methods 
that  you  will  never  need  to  overload. 
Fortunately,  the  macro  implementation 
makes  it  easy  to  switch  to  a  call  later  if 
you  need  to  overload  the  procedure. 
Just  substitute  a  call  for  the  inline  code 
inside  the  macro. 

Polymorphism  and  Overloading 

Overloaded  procedures  allow  the 
“same”  method  to  perform  different 
operations,  depending  upon  the  object 
passed  to  the  method.  Consider  the 
class  definitions  in  Example  14.  Red 
and  Circle  ire  types  derived  from  Shape. 


If  ES:BX  points  at  a  generic  shape  (that 
is,  ES:BX  points  at  an  object  of  type 
Shape,  Red,  or  Circle )  then  CALL_ 
THIS. Draw  will  call  Shape_Draw , 
Red_Draw,  or  Circle _Draw.  depend¬ 
ing  upon  where  ES:BX  points.  This  lets 
you  write  generic  code  that  needn’t 
know  the  particular  details  of  the  shape 
it’s  drawing.  The  object  itself  knows 
how  to  draw  itself  via  the  pointer  to  the 
specific  draw  routine. 

Allocation  of  Objects 

High-level  object-oriented  languages 
such  as  Object  Pascal  and  C++  tend  to 
hide  many  of  the  allocation  details  from 
you.  In  assembly  language,  naturally, 
the  programmer  has  to  handle  all  of  the 
allocation  details.  Although  a  complete 
discussion  of  dynamic  allocation  of  ob¬ 
jects  is  beyond  the  scope  of  this  article, 
the  subject  is  so  pervasive  that  it  war¬ 
rants  a  brief  mention. 

Static  allocation  of  an  object  in  as¬ 
sembly  language  is  quite  simple.  If  you 
have  the  shape  class  definitions  (shape, 
red,  and  circle )  mentioned  earlier,  you 
can  easily  declare  variables  of  these 
types  using  declarations  of  the  form: 

MyRect  rect 

MyCircle  circle 

MyShape  shape 

This  automatically  fills  in  the  DRAW 
field  for  these  variables  (the  linker/ 
loader  fills  in  such  addresses  when  it 
loads  the  program  into  memory).  What 
happens  if  you  are  dynamically  allocat¬ 
ing  storage  for  an  object?  Assume  we 
have  a  routine,  alloc,  to  which  we  pass 
a  byte  count  in  CX,  and  it  returns  a 
pointer  to  a  block  of  memory  that  size 
in  ES:BX.  Now  suppose  we  allocate  a 
rectangle  with  the  code  in  Example  15. 
Alloc  will  not  be  smart  enough  to  fill 
in  the  pointer  to  the  red. DRAW  rou¬ 
tine.  This  is  something  we’ll  have  to 
do  ourselves.  This  requires  the  four 
instructions  in  Example  16. 

Eight  instructions  may  not  seem  like 
a  lot  to  create  a  simple  object.  Keep  in 
mind,  however,  that  our  simple  shape 
object  only  has  one  overridden  method. 
If  there  were  a  dozen  methods,  you 
would  need  52  instructions.  Clearly,  a 
CREATE  procedure  begins  to  make  a 
lot  of  sense.  Each  subclass  (shape,  rect, 
and  circle)  will  need  its  own  CREATE 
method.  CREATE  is  not  a  method  you 
normally  overload,  because  during  the 
creation  process  you  know  exactly  the 
type  of  object  you’re  creating.  By  conven¬ 
tion,  the  CREATE  methods  I  write  al¬ 
ways  allocate  the  appropriate  amount 
of  storage,  initialize  any  important  fields, 
and  then  return  a  pointer  to  the  new 
object  in  ES:BX.  The  code  in  Example 
17  provides  an  example,  using  the  rect 


Example  11:  The  Sc_geti  method 


_THIS  equ 

Sc_geti  proc 

mov 
ret 

Sc_geti  endp 


es: [bx] 
far 

ax,  THIS . i 


Example  12:  Loading  SI. i  into  AX 

mov  bx,  seg  SI 

mov  es,  bx 

mov  bx,  offset  SI 

call  Sl.geti  /Assuming  SI  is  in  the  data  seg 


Example  13:  Improving  efficiency 


Inline  expansion  of  geti  to  improve  efficiency: 
Geti 


macro 

mov 

endm 


ax,  THIS . i 


Perform  actual  call  to  routines  which  are  too  big  to 
expand  in-line  in  our  code: 

’rinti  macro 

call  _THIS.Printi 

endm 


;Get  i  into  AX. 


/Call  Printi  routine. 


Example  14:  Typical  class  definitions 

Shape 

struc 

ulx 

dw 

?  /Upper  left  X  coordinate 

uly 

dw 

?  /Upper  left  Y  coordinate 

lrx 

dw 

?  /Lower  right  X  coordinate 

lry 

dw 

?  /Lower  right  Y  coordinate 

Draw 

dd 

Shape  Draw  /Default  (overridden)  DRAW  routine 

Shape 

ends 

Rect 

struc 

dw 

4  dup  (?)  /Reserve  space  for  coordinates 

dd 

Rect  Draw  /Draw  a  rectangle 

Rect 

ends 

Circle 

struc 

dw 

4  dup  (?)  /Reserve  space  for  coordinates 

dd 

Circle  Draw  /Draw  a  circle 

Circle 

ends 

I 


I 
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and  circle  types.  To  manipulate  these 
objects,  we  need  only  load  the  appro¬ 
priate  pointer  into  ES:BX  and  access 
the  appropriate  fields  or  call  the  ap¬ 
propriate  methods  via  this. 

Other  Conventions 

While  writing  object-oriented  programs 
in  assembly  language,  I’ve  found  cer¬ 
tain  guidelines  helpful  in  the  initial  de¬ 
sign  phases  (that  is,  before  having  to 
take  efficiency  into  consideration).  Most 
of  these  guidelines  are  widely  accepted 
object-oriented  practices;  others  per¬ 
tain  mainly  to  assembly  language.  Here 
are  the  major  ones  I’m  using: 

•  Try  to  use  dynamic  allocation  for  ob¬ 
jects  wherever  possible.  In  the  best  ob¬ 
ject-oriented  programs,  instances  of  an 
object  appear  and  disappear  through¬ 
out  the  program.  Rarely  will  a  single 
instance  exist  throughout  the  execu¬ 
tion  of  a  program.  Because  an  object’s 
methods  always  reference  fields  of  an 
object  indirectly,  there  is  little  benefit 
to  statically  allocated  objects.  Convert¬ 
ing  a  statically  allocated  object  to  a 
dynamically  allocated  one  later  on  is 
messy.  Get  it  right  the  first  time! 

•  Avoid  accessing  the  individual  vari¬ 
ables  (fields)  within  an  object.  Write 
methods  that  store  values  into  these 
fields  and  retrieve  values  from  them. 
This  information-hiding  technique  is 
well  proven  in  OOP  and  isn’t  particu¬ 
larly  worthy  of  further  discussion. 

•  Overload  as  many  methods  as  pos¬ 
sible.  CREATE  is  probably  the  only 


Example  15:  Code  to  allocate 
a  rectangle 

mov  cx,  size  rect 

call  alloc 

mov  word  ptr  MyRectPtr,  bx 

mov  word  ptr  MyRectPtr+2,  es 


Example  16:  Filling  in  the 
pointer  to  the  rect. DRAW  routine 

mov  ax,  offset  rectDRAW 

mov  _this.DRAW,  ax 

mov  ax,  seg  rectDRAW 

mov  _this.DRAW+2,  ax 


Example  1 7:  Code  for  example 

using  the  rect  and  circle  types 

mov 

cx,  size  circle 

call 

CreateCircle 

mov 

word  ptr  CircVarPtr,  bx 

mov 

word  ptr  CircVarPtr+2,  es 

i 

mov 

cx,  size  rect 

call 

CreateRect 

mov 

word  ptr  RectVarPtr,  bx 

mov 

word  ptr  RectVarPtr+2,  es 

method  you  shouldn't  overload.  Ac¬ 
cess  methods,  which  provide  access 
to  the  fields  of  the  outermost  class, 
might  be  another  candidate  for  direct 
access.  But  the  loss  of  generality  for  a 
small  increase  in  efficiency  is  rarely 
worth  it. 

•  Always  use  macros  to  call  methods, 
especially  those  you’re  not  calling  indi¬ 
rectly.  This  provides  a  consistent  call¬ 
ing  mechanism  for  methods  and  lets 
you  easily  overload  methods  you 
choose  to  implement  inline  or  without 
overloading.  This  applies  equally  well 
to  accessing  fields  in  an  object. 

•  As  a  bare  minimum,  each  class  should 
have  the  following  methods:  CREATE, 
DISPOSE,  COPY,  and  a  set  of  access 
methods  for  each  of  the  fields.  COPY 
should  copy  the  contents  of  one  in¬ 
stance  variable’s  fields  to  another  vari¬ 
able. 

Naturally,  these  are  just  guidelines, 
not  rules  etched  in  stone.  But  a  certain 
amount  of  discipline  early  in  a  project 
helps  prevent  considerable  kludging 
later  on. 

An  Example 

The  example  in  Listing  One  (page  1 10) 
is  a  program  that  adds,  subtracts,  and 
compares  signed  binary  integers,  un¬ 
signed  binary  integers,  and  BCD  val¬ 
ues.  While  not  a  complete  example  (it’s 
missing  several  important  methods  such 
as  CREATE,  PRINT,  DISPOSE,  and  so 
on)  it  demonstrates  the  flavor  of  object- 
oriented  programming  in  assembly  lan¬ 
guage. 

What  About  Your  Programs? 

Object-oriented  programming  is  a  con¬ 
cept  that  can  reduce  the  time  you  spend 
developing  certain  classes  of  programs. 
The  OOP  concept  applies  equally  well 
to  assembly  language  and  high-level 
language  programs.  The  only  draw¬ 
back  is  that  you  don’t  have  a  large 
library  of  classes  to  build  upon.  Of 
course,  these  same  problems  exist  for 
Object  Pascal  and  C++  users.  Time  will 
solve  this  problem  for  those  languages 
as  users  begin  developing  reusable  mod¬ 
ules  for  both,  which  is  all  that  is  pre¬ 
venting  object-oriented  assembly  lan¬ 
guage  from  taking  off.  Perhaps  some¬ 
day  you  will  be  able  to  buy  off-the- 
shelf  object-oriented  assembly  language 
libraries;  until  then,  you’ll  have  to  write 
your  own.  Even  so,  the  tricks  and  tech¬ 
niques  of  object-oriented  programming 
are  well  worth  considering  for  your 
next  assembly  language  project. 

DDJ 
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EXAMINING  ROOM 


Inside 

Watcom  C  7.0/386 

32-bit  code  can  speed  up  your  programs 
on  an  already  quick  machine 


Andrew  Schulman 


Over  two  years  ago,  the  cover 
of  the  July  1987  issue  of  Dr. 
Dobb 's  carried  the  title  "386 
Development  Tools  Within 
Your  Lifetime”  a  photograph 
of  a  skeleton  that  rotted  away  in  front 
of  its  computer  while  waiting  for  de¬ 
cent  386  tools,  which  summed  up  ev¬ 
eryone's  feelings  about  programming 
for  the  Intel  80386  microprocessor. 

Things  have  improved  a  great  deal 
since  that  issue.  Watcom  C7. 0/386,  for 
instance,  produces  32-bit  code  (such 
as  MOV  VAX.  12345678b,  and  MOV 
FS:[EAX/,  ESI)  while  staying  keyword 
and  library  compatible  with  the  de  facto 
16-bit  industry  standard,  Microsoft  C 
5.1  (MSC51).  Even  weird  low-level  rou¬ 
tines  such  as  intdosxf  ),  _dos_setvect(  ), 
_dos_keep(  ),  and  _cbain_intr(  Ido  the 
right  thing  in  32-bit  protected  mode. 

Of  course,  Watcom  C7.0/386  (WAT- 
386)  has  many  of  the  same  features  as 
Watcom’s  1 6-bit  C  compiler  (see  “Ex¬ 
amining  Room,”  DDJ  September  1989). 
This  includes  Watcom’s  famous  register- 
based  parameter  passing.  Many  of  Wat¬ 
com’s  innovations  involve  the  reduction, 
and  sometimes  elimination,  of  function 
call  overhead.  Any  block  of  code  that 
takes  input  from  registers  and  puts  out¬ 
put  into  registers  is  effectively  a  func¬ 
tional  object,  and  WAT386  takes  advan¬ 
tage  of  this  fact  in  several  places,  includ¬ 
ing  the  nifty  # pragma  aux  feature. 


A  ndrew  is  a  software  engineer  in  Cam¬ 
bridge,  Mass.,  working  on  CD-ROM  net¬ 
work.  applications,  and  is  also  a  con¬ 
tributing  editor  for  DDJ.  He  can  be 
reached  at  32  Andrew  St.,  Cambridge, 
MA  021 39. 


Buying  In 

WAT386  produces  very  different  code 
from  either  Microsoft  C  or  Turbo  C 
(neither  of  which  has  an  option  to  gen¬ 
erate  386  instructions,  much  less  32-bit 
code).  Yet,  this  compiler  will  fit  seam¬ 
lessly  into  your  current  work  habits. 
Unlike  MetaWare’s  High  C  386  com¬ 
piler,  using  WAT386  does  not  produce 
"culture  shock." 

Still,  all  is  not  rosy.  It  will  cost  you 
over  $1000  in  software  to  get  into  386 
development.  WAT386,  like  High  C, 
costs  $895,  and  you  will  also  need  a 
32-bit  DOS  extender,  like  the  industry- 
standard  Phar  Lap  386  toolkit,  which 
costs  $495. 

Further,  the  new  Watcom  C7. 0/386 
compiler  is  just  that  —  new.  While  writ¬ 
ing  this  review,  I  found  a  number  of 
bugs  in  the  compiler  and  its  standard 
libraiy.  Watcom  was  undoubtedly  un¬ 
der  pressure  from  its  major  client,  No¬ 
vell,  to  get  the  386  compiler  out  the 
door.  By  the  time  you  read  this  review, 
though,  a  second,  more  stable,  release 
of  WAT386  should  be  available. 

Primarily  because  of  its  newness, 
WAT386  in  some  ways  is  not  as  good 
a  product  as  MetaWare’s  High  C  386, 
which  has  been  around  for  two  and  a 
half  years.  Still,  there  is  value  in  WAT386. 
For  many  PC  programmers,  this  will 
be  a  much  easier  product  to  use  than 
MetaWare’s  High  C.  WAT386's  Micro¬ 
soft  compatibility  is  very  important.  On 
the  other  hand,  the  next  release  (1.6) 
of  High  C  386,  in  addition  to  many 
other  changes,  is  scheduled  to  have 
what  a  MetaWare  press  release  calls 
“86%  compatibility  with  Microsoft’s  C 
libraries.” 


32  Bits! 

WAT386  generates  code  for  32-bit  pro¬ 
tected  mode.  Thus,  sizeof(int)  and 
sizeofl unsigned)  are  each  4  bytes,  not 
2  bytes.  Likewise,  sizeoff void  *)  is  4 
bytes.  Note  that  sizeofivoid  near  *)  is 
also  4  bytes. 

The  all-important  ANSI  C  identifier 
size_t,  which  is  the  unsigned  type  of 
the  result  of  the  sizeofl  )  operator  and 
the  type  used  by  function  parameters 
that  accept  the  size  of  an  object,  is  also 
4  bytes  ( typedef  unsigned  sizej). 

C  standard  library  functions  such  as 
mallocl ),  fwritel  ),  and  strncpyf  )  all 
take  size_t  parameters,  and  strlenf  )  re¬ 
turns  a  size_t .  These  standard  library 
functions  deal  in  quantities  between  0 
and  UINT_MAX.  In  the  16-bit  code  gen¬ 
erated  by  PC  compilers  like  MSC51, 
UINT_MAX  is  OxEEEE  (65,535),  yield¬ 
ing  the  familiar  64K  limit  on  PC  array 
lengths,  string  lengths,  malloc  blocks, 
and  so  on. 

But  in  32-bit  code,  UINT_MAX  is 
OxFFFFFFFF,  or  4,294,967,295  —  the 
magical  upper  "limit”  of  4  gigabytes! 
In  the  native  mode  of  the  386,  this  is 
the  upper  bound  set  on  array  lengths, 
string  lengths,  and  malloc  blocks.  Effec¬ 
tively,  no  limit  at  all. 

The  Environment 

If  fwritel )  can  write  4  gigabytes  at  a 
time  (which  might  be  handy  if  you’re 
working  with  CD-ROM  or  some  other 
form  of  mass  optical  storage),  how  can 
it  possibly  work  with  MS-DOS?  DOS  is 
a  16-bit  operating  system.  (So  is  OS/2.) 
The  DOS  Write  function  {INT  21,  func¬ 
tion  40H ),  which  fwritel )  must  even¬ 
tually  call,  expects  the  number  of  bytes 


74 


Dr.  Dobbs  Journal,  March  1990 

237 


Programmers 
Wholesaler"1  _ 

Attention! 

Corporate  Accounts 
Resellers 

Programmers 


Cftecl^our  values! 


LIST 

1-2 

3+ 

BASIC 

Turbo  Basic 

100 

67 

64 

QuickBASIC 

99 

67 

64 

Basic  Dev.  Sys.  7.0 

495 

329 

321 

C  LANGUAGE -COMPILERS 

Lattice  C  -  6.0 

250 

156 

143 

Microsoft  C  5.1 

450 

287 

283 

Microsoft  Quick  C 

99 

67 

64 

Turbo  C  by  Borland 

150 

98 

94 

DATABASE  MANAGEMENT 

Clarion 

695 

399 

379 

Paradox  3.0 

DBASE 

725 

489 

479 

Clipper  Summer  '87 

695 

429 

419 

dBASE  IV 

795 

489 

479 

FoxBASE  +  2.1 

DBASE  TOOLS 

395 

209 

199 

Clean  for  dBASE 

200 

149 

139 

dBRIEF  w/BRIEF 

285  Save  Save 

dSalvage 

100 

83 

79 

R&R  Relational  Reportwriter  149 

99 

93 

EDITORS 

BRIEF 

199  Save  Save 

Epsilon 

FORTRAN 

195 

139 

109 

MS  FORTRAN 

OBJECT-ORIENTED 

450 

299 

289 

Smalltalk/V 

100 

59 

54 

Zortech  C++ 

OTHER  PRODUCTS 

199 

Call 

Call 

Carbon  Copy  Plus 

195 

115 

104 

HEADROOM  by  Helix 

130 

85 

79 

Norton  Utilities  Advanced 

150 

89 

87 

PC  Tools  Deluxe 

129 

85 

79 

Remote2 

SPREADSHEETS 

195 

104 

99 

1-2-3 

495 

299 

289 

Excel 

495 

339 

329 

TEXT  SCREENS  ADDONS 

C  Worthy  w/Forms 

295  Save 

Save 

Greenleaf  DataWindows 

395 

249 

239 

Vermont  Views 

WORD  PROCESSING 

395 

319 

299 

Sprint 

200 

134 

129 

WordPerfect 

495 

239 

234 

Prices  subject  to  change  without  notice.  "DD390W" 

Programmers 

Wholesaler™ 

800-228-3736 

CANADA 

800-344-2495 

South  Shore  Park 
P.O.  Box  534 
Accord,  MA  02018 

FAX  617-740-1892 

Hours:  M-F  8:30-5 

CIRCLE  NO.  199  ON  READER  SERVICE  CARD 

76 

238 


E  X  A  M  1  N  I  N  G  ROOM 


( continued  from  page  74) 
to  write  in  the  1 6-bit  CX  register.  The 
maximum  is  64K.  How  can  WAT386,  or 
any  32-bit  C  compiler  for  DOS,  pro¬ 
duce  code  that’s  compatible  with  16- 
bit  DOS? 

The  answer  is  that  386  C  compilers 
(for  DOS)  produce  code  to  be  run  un¬ 
der  a  32-bit  DOS  extender.  Programs 
such  as  Phar  Lap’s  386  I  DOS-Extender 
and  Eclipse  Computer  Solutions’  OS/ 
386  do  not  replace  DOS.  Instead,  they 
(almost  invisibly)  manage  the  interface 
between  16-bit  real-mode  DOS  and  your 
32-bit  protected-mode  program. 

In  the  example  of  fwrite(  ),  the  32-bit 
code  produced  by  WAT386  or  High  C 
(which  MetaWare  actually  calls  “High 
C  for  MS-DOS/386”)  continues  to  call 
/AT  21,  function  40H.  But  now,  the 
number  of  bytes  to  write  goes  into  the 
full  32-bit  ECX  register  rather  than  the 
1 6-bit  CX  register. 

A  DOS  extender  takes  over  /AT  21 
(as  well  as  other  software  interrupts 
like  /AT  10,  1NT  16,  and  so  on),  han¬ 
dles  some  functions  itself,  and  passes 
others  on  to  DOS.  A  program  running 
under  a  32-bit  DOS  extender  is  effec¬ 
tively  running  under  “MS-DOS/386,” 
because,  for  example,  a  call  to  write 
640K  is  really  going  to  write  640K.  The 
DOS  extender  will  invisibly  break  this 
up  into  multiple  calls  to  the  “real”  INT 
21,  function  40H. 

Another  interesting  example  is  mal- 
loc(  ).  If  your  386  computer  came  with 
4  gigabytes  of  memory,  you  could  grab 
it  all  with  a  single  call  to  malloct  ).  As 
in  16-bit  real-mode  C  compilers,  the  C 
memory  manager  eventually  calls  /AT 
21,  function  48  (allocate  memory). 
Here,  however,  the  DOS  extender  pro¬ 
vides  a  complete  replacement,  not  a 
front  end,  for  the  DOS  routine.  There 
is  one  difference  between  Phar  Lap 
and  Eclipse:  386 1  DOS-Extender  expects 
in  EBX  the  number  of  4K  pages  to 
allocate,  where  OS/386  more  closely 
mimics  DOS,  expecting  the  number  of 
16-byte  paragraphs.  The  WAT386  stan¬ 
dard  library  detects  which  DOS  exten¬ 
der  it  is  running  under  and  allocates 
memory  appropriately. 

By  default,  WAT386  produces  code 
to  be  run  under  Phar  Lap  Software’s 
386 1  DOS-Extender.  The  Phar  Lap  toolkit 
(DOS  extender,  linker,  assembler,  and 
debugger)  must  be  purchased  sepa¬ 
rately,  however. 

Oddly,  you  don’t  need  a  386  machine 
or  a  DOS  extender  to  run  the  WAT386 
compiler.  By  the  time  you  read  this 
review,  Watcom  should  be  shipping  a 
32-bit  protected-mode  version  of  the 
compiler.  In  the  version  I  reviewed, 
however,  all  compiler  components  were 
16-bit  real-mode  programs.  To  avoid 


“Not  enough  memory  to  fully  optimize 
procedure”  warnings,  I  had  to  specify 
that  the  compiler  use  a  large-model 
version  of  the  code  generator.  Pretty 
crazy  for  a  386  development  system! 

Presumably,  if  your  customers  had 
386s  but  you  didn’t  (which  is  probably 
the  exact  opposite  of  the  real  situation), 
you  could  use  these  16-bit  tools  to  gen¬ 
erate  386  code  on  your  AT. 

Programs  compiled  with  WAT386  and 
linked  with  Phar  Lap’s  386  I  LINK  will 
only  run  on  386-based  machines.  To 
sell  such  programs,  and  to  acquire  a 
program  that  will  “bind”  the  DOS  ex¬ 
tender  into  the  executable  so  that  your 
customers  don’t  need  to  know  any¬ 
thing  about  the  DOS  extender,  you  must 
acquire  a  redistribution  package  from 
Phar  Lap.  This  costs  an  extra  $1000  for 
unlimited  distribution. 

So  the  entrance  fee  for  386  develop¬ 
ment  is  still  pretty  steep.  What  do  you 
get  in  return?  A  lot:  Code  that  runs 
several  times  faster  than  16-bit  code; 
the  elimination  of  64K  limits  on  array 
sizes  or  function  parameters;  and  the 
elimination  of  the  640K  boundary,  al¬ 
lowing  you  to  use  all  physical  memory 
in  the  machine. 

Note  that  this  “MS-DOS/386”  gives 
you  big  memory,  but  not  virtual  mem¬ 
ory  (VM).  This  is  an  important  differ¬ 
ence  from  OS/2.  However,  a  VM  man¬ 
ager  (386 1  VMM)  is  available  for  $295 
from  Phar  Lap,  and  WAT386  code,  like 
High  C  code,  runs  without  change  un¬ 
der  386 1  VMM. 

WAT386  code  runs  under  one  other 
environment:  Novell’s  new  32-bit  net¬ 
work  operating  system,  NetWare  386 
(see  the  accompanying  box). 

The  Code 

How  can  a  32-bit  C  compiler  such  as 
WAT386  produce  code  that  runs  sev¬ 
eral  times  faster  than  16-bit  code  run 
on  the  same  machine?  Consider  the 
following  two  lines  of  code: 

extern  charfEnv; 

char  *p=Env 

Compiling  under  the  “large  model” 
(which  is  what  most  commercial  PC 
software  uses),  any  16-bit  C  compiler, 
including  Watcom’s  non-386  compiler, 
produce  code  something  like  that  shown 
in  the  first  portion  of  Example  1,  in 
which  the  4-byte  far  pointers  are  trans¬ 
ferred  piecemeal  from  one  location  to 
another. 

Because  mov  mem,  reg  takes  2  clock 
cycles  on  a  386  and  mov  reg,  mem  takes 
4  cycles  regardless  of  whether  the  com¬ 
piler  uses  the  8-bit  (AL),  16-bit  (AX), 
or  32-bit  (EAX)  form  of  the  register,  this 
takes  (2*2)  +  (3*4)  =  16  cycles.  In  con- 
( continued  on  page  79) 
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(continued  from  page  76) 
trast,  the  32-bit  equivalent  takes  2  +  4 
=  6  cycles  (shown  in  the  second  por¬ 
tion  of  Example  1). 

The  32-bit  code  is  similar  to  the  code 
that  would  be  generated  by  a  16-bit  com¬ 
piler  working  with  2-byte  near  pointers: 


mov  ax,  _Env 
mov  word  ptr  _p,  ax 

In  fact,  “flat  model”  32-bit  code  and 
“tiny  model”  16-bit  code  are  very  simi¬ 
lar.  The  only  difference  is  that  the  16- 
bit  code  can  handle  quantities  up  to 


Watcom  and  Novell 


In  addition  to  producing  code  for  Phar 
Lap's  386 1  DOS-Extender  and,  with 
some  difficulty,  for  Eclipse’s  OS/386, 
the  32-bit  Watcom  C  compiler  also 
works  with  Novell’s  new  network  op¬ 
erating  system,  NetWare  386.  In  fact, 
Watcom  C7.0/386  is  being  repackaged 
by  Novell  as  its  C  Network  Compiler/ 
386.  (This  is  the  subject  of  Novell’s 
strange  “See  Dick  and  Jane”  ads.) 

NetWare  386  is  a  32-bit  operating 
system,  and  this  allows  for  several 
performance  leaps  over  the  existing 
286-based  NetWare.  Instead  of  the 
current  limit  of  100  users  per  file  server, 
which  is  dictated  by  the  single  64K 
data  segment  available  in  “medium 
model”  (used  in  286-based  NetWare), 
the  new  NetWare  386  allows  250  si¬ 
multaneous  users  per  file  server.  Like¬ 
wise,  Novell  claims  that  network 
throughput  is  two  to  three  times 
greater  than  its  already  zippy  through¬ 
put  figures. 

In  NetWare  386,  the  lack  of  seg¬ 
mentation  in  “flat  model”  is  taken  to 
its  logical  (but  scary)  extreme  —  no 
memory  protection.  Novell  baldly 
states  that,  “There  is  no  memory  or 
other  application-level  protection:  All 
applications  and  device  drivers  run 
in  kernel  mode”  ( NetWare  Technical 
Journal ,  July  1989). 

When  used  with  NetWare  386,  the 
Watcom  C  compiler  produces  server 
applications  —  programs  that  run  in 
file-server  memory  (the  so-called  “file 
server"  thus  becomes  a  generic  server). 
These  server  applications  are  called 
“NetWare  Loadable  Modules,”  or 
NLMs,  and  are  somewhat  like  value- 
added  processes  (VAPs)  in  pre-386 
NetWare;  except  unlike  VAPs,  NLMs 
can  be  loaded  or  unloaded  at  any 
time,  without  taking  down  the  file 
server.  NLMs,  in  fact,  are  dynamic- 
link  libraries  and,  in  addition  to  pro¬ 
viding  services  to  clients  on  the  net¬ 
work,  can  provide  functions  to  be 
called  by  other  NLMs. 

For  instance,  when  calling  a  C  stan¬ 
dard  library  such  as  open( )  from  an 
NLM,  you  are  actually  calling  a  rou¬ 
tine  in  CLIB.NLM,  which  is  the  C  stan¬ 
dard  library  provided  as  a  dynamic- 


link  library.  The  code  for  open(  )  is 
not  linked  into  your  executable. 

To  produce  such  an  NLM,  use  the 
NLMLINK  provided  by  Novell  rather 
than  the  Phar  Lap  linker.  Similar  to 
the  OS/2  linker,  NLMLINK  requires  a 
.DEF  file  with  import  statements.  The 
module  produced  by  the  Novell  linker 
essentially  contains  unresolved  exter¬ 
nals  that  are  resolved  when  the  NLM 
is  loaded  into  file  server  memory 
(either  by  invoking  the  LOAD  com¬ 
mand  at  the  file  server  console,  or  by 
spawning  one  NLM  from  within  an¬ 
other). 

The  library  included  with  C  Net¬ 
work  Compiler/386 includes  many  func¬ 
tions  not  available  in  the  standard 
Watcom  library.  Naturally,  functions 
are  provided  to  support  network  com¬ 
munications  with  Novell’s  IPX  and 
SPX.  The  Btrieve  data  management 
library  is  provided  as  BTRIEVE. NLM. 
The  Novell  library  includes  functions 
(for  example,  Test  A  ndSetBitf  )  and 
BitScanC  ))  to  interface  to  the  386-bit 
test  instructions. 

Network  servers  are  inherently  mul¬ 
titasking  (multiple  operations  must  be 
in  progress  simultaneously  on  behalf 
of  multiple  clients),  so  the  library  con¬ 
tains  functions  for  “execution  threads,” 
such  as  Beginlbreadf  ),  EnterCritSec(  ), 
IbcitCritSecf  ),  SuspendThreadf  ),  and 
so  on.  There  are  also  functions  to 
manage  semaphores  and  queues. 

While  this  part  of  the  Novell  API 
seems  modeled  on  OS/2,  it  is  impor¬ 
tant  to  note  that  NetWare  386  uses 
non-preemptive  multitasking.  Inside 
a  “big  job,"  it  is  therefore  necessary 
to  call  a  routine  such  as  delayf  )  or 
'lhreadSwitchf  )  so  that  other  threads 
are  not  starved. 

The  library  that  Watcom  provided 
for  Novell  contains  a  few  modifica¬ 
tions  to  support  multiple  threads. 
Global  variables  such  as  errno  are  in 
fact  allocated  on  a  prethread  basis. 
Static  data  such  as  used  by  the  notori¬ 
ous  strtokC  )  function  is  also  handled 
differently  than  in  a  single-threaded 
library.  No  new  keywords  (such  as 
private ,  used  in  Lattice  C  6.0  for  OS/2) 
have  been  added,  however.  —  A.S. 
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64K,  whereas  the  32-bit  code  can  han¬ 
dle  quantities  up  to  4  gigabytes. 

Right  now,  WAT386  supports  flat 
model  and  small  model.  In  the  flat  mem¬ 
ory  model,  the  application’s  code  and 
data  must  total  less  than  4  gigabytes  in 
size.  In  the  small  memory  model,  your 
code  and  data  are  each  "limited”  to  4 
gigabytes.  By  default,  WAT386  uses  the 
flat  model.  When  linking  with  the  Lahey 
linker  (LINK-EM/32)  provided  with  OS/ 
386,  you  must  compile  with  the  small 
model. 

Because  an  offset  into  a  segment  is 
4  bytes  while  the  segment  registers  are 
still  2  bytes,  sizeof(void  far  *)  is  6  bytes 
(an  FWORD,  not  a  DWORD).  But  be¬ 
cause  a  near  pointer  is  a  4-byte  quan¬ 
tity,  you  almost  never  have  to  deal  with 
far  pointers.  When  a  segment  takes  a 
4-byte  offset,  even  the  most  sloppily 
written,  bloated  program  in  the  world 
should  do  fine  with  the  flat  model. 
Once  loaded,  DS  and  CS  stay  constant. 
Effectively,  this  is  a  linear  address  space. 

Real-World  Benchmarks 

Interpreters  are  better  for  benchmark¬ 
ing  compilers  than  the  tiny  programs 
that  are  usually  used.  Such  benchmarks 
usually  involve  a  fair  amount  of  source 
code.  The  C  source  code  for  several 
interpreters  is  readily  available,  and  to 
execute  one  line  in  the  interpreted  lan¬ 
guage,  the  interpreter  needs  to  crunch 
through  a  lot  of  C  code. 

In  the  remainder  of  this  review,  I’ll 
describe  using  WAT386  (and  Meta  Ware 
High  C)  to  port  a  larger  program  to  the 
386:  ISETL  (Interactive  Set  Language), 
written  in  C  by  Gary  Levin  (Dept,  of 
Mathematics  and  Computer  Science, 
Clarkson  University,  Potsdam,  N.Y.). 
ISETL  is  an  interpreter  for  working  with 
sets,  tuples,  propositions,  several  dif¬ 
ferent  types  of  functional  objects,  ma¬ 
trices,  and  other  constructs  useful  for 
studying  the  mathematical  foundations 
of  computer  science.  It  is  described  in 
the  book  Learning  Discrete  Mathemat¬ 
ics  with  ISETL  by  Nancy  Baxter,  Ed  Du- 
binsky,  and  Gary  Levin  (New  York:  Sprin- 
ger-Verlag,  1989).  ISETL  deserves  a  full 


16-bit  code: 

mov  es, 

seg  Env 

mov  ax, 

word  ptr  es:  Env 

mov  dx, 

word  ptr  es:  Env+2 

mov  word  ptr  p,  ax 
mov  word  ptr  p+2,  dx 

32-bit  code: 

mov  eax, 

Env 

mov  _p, 

eax 

Example  1:  32-  and  16-bit  code  gen¬ 
erated  under  the  large  memory  model 


discussion,  but  for  now  I’ll  just  describe 
the  process  of  producing  ISETL/386. 

Due  to  space  considerations,  the 
ISETL/386  listings  are  not  included  in 
this  issue.  They  are  available  through 
DDJ  (see  the  end  of  this  article  for 
information).  The  ISETL  implementa¬ 
tion  consists  of  29  C  files  and  14  .H  files, 
and  totals  about  13,000  lines  of  code. 
Some  of  the  code  is  YACC  output. 


To  sell  such  programs, 
and  to  acquire  a 
program  that  will 
“hind”  the  DOS 
extender  into  the 
executable  so  that  your 
customers  don ’t  need  to 
know  anything  about 
the  DOS  extender,  you 
must  acquire  a 
redistribution  package 
from  Phar  Lap 


When  I  tried  to  produce  a  386  ver¬ 
sion  of  this  real  program,  my  opinion 
about  WAT386  vs.  High  C  nearly  re¬ 
versed.  As  long  as  I  was  working  on 
small  one-  or  two-module  programs, 
WAT386’s  similarity  to  Microsoft  C  and 
Turbo  C  made  it  preferable  to  Meta- 
Ware  High  C.  But  once  I  started  work¬ 
ing  on  ISETL/386,  with  more  source 
code,  written  by  someone  else,  my  al¬ 
legiance  shifted  to  High  C. 

High  C  provides  better  warning  mes¬ 
sages  than  WAT386;  the  High  C  com¬ 
piler  is  faster  than  WAT386  (remember, 
the  WAT386  compiler  I  used  was  a 
16-bit  real-mode  program);  surprisingly, 
High  C  seems  to  produce  better  overall 
code  than  WAT386;  and,  most  impor¬ 
tant,  High  C  and  its  standard  library 
isn't  buggy  like  WAT386. 

I  should  mention  that  Watcom  has 
terrific  technical  support.  If  you  call 
up  with  a  problem,  you  get  to  talk  to 
the  person  responsible  for  the  library 
or  the  compiler.  Watcom  is  quick  to 
find  and  fix  bugs  and,  with  the  WPATCH 


utility  that  comes  with  WAT386,  they 
have  made  the  patch  a  fine  art.  Wat¬ 
com  runs  a  well-organized  BBS.  On 
the  other  hand,  I  don’t  even  know  how 
good  Meta  Ware’s  technical  support  is, 
because  I  never  needed  to  use  it. 

At  one  time  or  another,  we’ve  all 
thought  we’ve  found  a  compiler  bug 
only  to  discover  that  in  fact  we  have  a 
bug  in  our  own  code.  But  after  work¬ 
ing  with  WAT386  for  about  a  month,  I 
found  that  nearly  every  time  it  was  a 
compiler  or  library  bug. 

First  of  all,  one  of  the  key  switch 
statements  in  ISETL  was  behaving  bi- 
zarrely.  The  value  of  the  variable  being 
switched  on  was  correct,  we  would 
jump  to  the  correct  case  label,  but  a 
function  call  to  Emit(42)  wasn’t  work¬ 
ing.  The  problem  is  that  any  constant 
(for  example,  42),  used  (anywhere)  in¬ 
side  a  switch  statement  is  scrambled  if 
that  constant  happens  to  match  the 
number  of  case  labels  in  the  switch 
statement!  This  bug  should  be  fixed 
by  the  time  you  read  this.  If  you  have 
this  same  release  of  the  compiler,  you 
can  download  a  patch  from  the  Wat¬ 
com  BBS. 

Another  problem  occurs  because  the 
ISETL  initialization  file  opens  the  DOS 
device  CON  (to  implement  a  pause (  ) 
routine  for  use  in  ISETL  programs)  and 
tries  to  read  from  this  device.  The  prob¬ 
lem  is,  when  reading  from  any  of  the 
DOS  device  files  (CON,  AUX,  and  so 
on),  the  WAT386  library  gets  confused 
between  binary  and  text  mode;  a  call 
to  wait  for  one  character  actually  waits 
for  512  characters,  that  makes  it  seem 
like  the  machine  is  hung. 

In  another  project,  I  found  that  int- 
dosx(  ...  /  was  not  working,  even 
though  int386x( 0x21, .  .  .  /worked  fine. 
If  this  has  not  been  corrected  by  the 
time  you  read  this,  a  patch  is  available 
from  the  Watcom  BBS. 

In  that  same  project,  I  found  an  ob¬ 
scure  bug  in  Watcom’s  use  of  the  “in¬ 
terrupt”  keyword  that  had  to  do  with 
calling  an  interrupt  function  rather  than 
generating  an  interrupt.  Basically,  func¬ 
tions  defined  with  void  interrupt  (far  f)(  ) 
work.  But  functions  defined  with  void 
( interrupt  far  f)(  )  (note  the  placement 
of  parentheses)  don't  do  a  PUSHFD 
when  you  call  them. 

There  is  one  problem  that’s  not  Wat- 
com’s  fault:  Debugging  with  the  386 
flat  memory  model  is  hardly  better  than 
debugging  in  real  mode.  With  one  sin¬ 
gle  segment  working  as  a  linear  ad¬ 
dress  space,  it  is  nowhere  as  easy  to 
catch  bugs  as  when  you  have  lots  of 
little  segments  (for  example,  a  286- 
based  protected-mode  DOS  extender 
such  as  DOS/16M).  In  fact,  to  debug 
ISETL/386,  I  found  it  necessary  to  cre- 
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(continued  from  page  80) 
ate  a  DOS/16M  version  (ISETL/286). 
This  shows  that  segmentation  is  not 
such  a  bad  idea,  after  all,  it’s  crucial  for 
genuine  memory  protection.  The  ideal 
situation  is  to  use  lots  of  segments  for 
development,  and  then  switch  over  to 
the  flat  model  for  production. 

The  only  assistance  you  get  in  catch¬ 
ing  memory  protection  violations  from 
the  WAT386  flat  memory  is  the  Phar 
Lap  linker’s  OFFSET  switch,  which  al¬ 
lows  you  to  load  code  or  data  starting 
at  some  offset  other  than  zero.  This 
way,  you  get  page  faults  when  derefer¬ 


encing  bad  pointers,  though  you  often 
won’t  know  where  they  come  from. 

Benchmarking  with  ISETL/386 

Once  ISETL/386  was  up  and  running 
with  WAT386, 1  was  able  to  write  some 
ISETL  programs  and  use  them  for  bench¬ 
marking  the  compilers.  In  addition  to 
contrasting  WAT386  and  High  C,  I  was 
able  once  again  to  compare  32-bit  code 
with  16-bit  code,  using  the  Turbo  Co¬ 
produced  executable  from  the  ISETL 
distribution. 

Figure  1  shows  the  results  for  two 
different  ISETL  programs  to  generate 


WAT386 

HIGH  C  386 

TURBO C 

PRIME. SET  2000 

18.0 

16.3 

24.8 

PRIME. SET  4000 

42.6 

40.0 

N/A 

PRIME. TUP  2000 

1 :03.7 

52.7 

1:11.3 

PRIME. TUP  4000 

4:14.9 

3:27.6 

N/A 

FIB. SET  1000 

15.0 

14.1 

20.4 

FIB. SET  1200 

18.0 

17.0 

N/A 

overall  test 

1 .05.3 

59.4 

1:30 

total 

477.5 

407.1 

N/A 

ISETL  filesize 

133K 

148K 

209K 

ISETL  full  compile 

12:52  min. 

11 :45  min. 

3:30  min. 

Figure  1:  ISETL  test  execution  times  in  seconds  (Watcom  and  High  C  run 
times  using  Phar  Lap  386 1  DOS-Extender) 


prime  numbers,  for  an  ISETL  program 
to  generate  the  first  1000  Fibonacci  num¬ 
bers,  and  for  an  overall  test  of  ISETL 
operations. 

Rather  than  use  explicit  loops,  the 
ISETL  prime  number  program  in  List¬ 
ing  One  (page  115)  uses  set  notation. 
This  program  creates  the  se’t  of  all  odd 
numbers  less  than  n,  takes  the  union 
of  this  set  with  the  singleton  set  |2|, 
then  takes  the  difference  between  the 
resulting  set  and  the  set  of  all  odd  com¬ 
posite  numbers  less  than  n.  The  result¬ 
ing  set  is  the  set  of  all  primes  <=  n. 
This  can  be  expressed  in  a  few  lines 
of  ISETL  code. 

Listing  Two  (page  115)  performs  the 
same  operation,  but  uses  ordered  tu¬ 
ples  (sets  are,  of  course,  unordered).  I 
had  to  choose  a  small  number  n  be¬ 
cause,  even  with  garbage  collection, 
ISETL  gobbles  up  a  lot  of  memory. 

Listing  Three  (page  115)  is  a  pro¬ 
gram  to  generate  the  first  1000  Fibon¬ 
acci  numbers.  This  relies  on  ISETL’s 
support  for  assignment  to  the  return 
value  of  a  function  (which  allows  one 
to  write  functions  that  “remember”  past 
values-dynamic  programming)  and 
ISETL’s  arbitrary-precision  arithmetic. 
Fibonacci(lOOO)  is  a  209-digit  number. 
ISETL/386  takes  15  seconds  to  com¬ 
pute  the  first  1000  Fibonacci  numbers 
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in  the  WAT386  version  and  14  seconds 
in  the  High  C  version.  The  16-bit  Turbo 
C  ISETL  takes  20.4  seconds. 

The  High  C  386  version  of  ISETL  was 
faster  than  the  WAT386  version  in  ev¬ 
ery  case  tested.  Overall,  the  High  C 
version  was  about  15  percent  faster 
than  the  WAT386  version.  This  is  some- 

Programs  such  as 
Phar  Lap ’s  386 1 DOS- 
Extender  and 
Eclipse  Computer 
Solutions’s  OS/386  do 
not  replace  DOS.  They 
manage  the  interface 
between  16-bit  real¬ 
mode  DOS  and  your 
32-bit  protected-mode 
program 


what  surprising  since,  as  is  well  known, 
MetaWare  produces  High  C  by  using 
an  automatic  compiler-compiler  (which 
MetaWare  markets  separately  as  the 
Translator  Writing  System). 

Profiling  with  the  DOS/16M  protected- 
mode  debugger  from  Rational  Systems 
(DOS/16M  currently  has  the  only  de¬ 
cent  protected  mode  C  source-level  de¬ 
bugging  tools  available),  I  found  that 
ISETL  generally  spends  50  percent  of 
its  time  in  only  four  routines.  Perhaps 
this  test  is  somewhat  lopsided.  Any 
real  program,  on  the  other  hand,  will 
have  similar  “hot  spots.” 

The  Future 

Over  the  next  few  months,  both  Wat- 
com  and  MetaWare  are  planning  major 
upgrades  that  may  be  out  by  the  time 
you  read  this.  One  obvious  change  in 
High  C  is  that  while  the  1.5  libraries  are 
missing  functions  such  as  open( ), 
fdopen( ),  dup(  )Jileno(  ),  and  signal!  ), 
High  C  1.6  is  scheduled  to  include  both 
a  Microsoft-compatible  standard  library 
(including  _dos_keep(  ),  inl86x(  )),  a  32- 
bit  version  of  the  GFX  graphics  library, 
and  a  32-bit  version  of  the  Sterling  Cas¬ 
tle  C  library. 
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WAT386’s  new  release  should  include 
a  32-bit  protected  mode  source-level 
debugger,  a  32-bit  version  of  Watcom’s 
graphics  library  (which  is  identical  to 
the  MSC51  graphics  library),  a  32-bit 
version  of  the  WAT386  compiler,  and 
a  32-bit  version  of  Watcom’s  Express 
in-memory  quick  compiler.  The  source- 
level  debugger  is  urgently  needed,  and 
should  put  Watcom  ahead  in  the  386 
development  tool  race. 

A  386  compiler  war  may  indeed  be 
starting.  While  WAT386  itself  is  not  fully 
mature,  its  arrival  is  a  sign  of  the  grow¬ 
ing  strength  of  the  market  for  386  de¬ 
velopment  tools.  And  about  time  too, 
now  that  the  first  486s  are  rolling  off 
the  assembly  line.  But  remember,  even 
an  80586  will  not  save  you  from  bad 
code. 


Product  Information 

Watcom  C7.0/386 
Watcom 

415  Phillip  Street 

Waterloo,  Ontario,  Canada  N2L  3X2 

800-265-4555 

Price:  $895 

Requirements:  386-based  PC-  or  PS/2 
compatible,  MS-DOS  3-1  or  higher, 
386  DOS  extender  toolkit:  386 1 DOS- 
Extender  (Phar  Lap)  or  OS/386 
(Eclipse  Computer  Solutions) 

C  Network  Compiler/386 
Novell  Development  Products 
P.O.  Box  9802 
Austin,  Texas  78766 
512-346-8380 
Price:  $995 


Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobbs  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  115.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  7. 
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Mixed-Language 
Programming  with 

Getting  the  job  done  often  requires 
blending  models  and  languages 


ASM 


Karl  Wright  and  Rick  Schell 


As  applications  get  larger,  fewer 
and  fewer  are  written  in  a  sin¬ 
gle  language.  Large  software 
projects  tend  to  come  together 
in  a  piecemeal  fashion  —  some 
parts  are  borrowed  from  previous  pro¬ 
jects,  other  parts  may  be  purchased 
from  various  vendor  sources,  and,  let’s 
face  it,  every  programmer  has  a  favor¬ 
ite  language.  Assembly  languages  have 
made  great  strides  recently  in  the  area 
of  mixed  language  programming.  Now 
more  than  ever  before,  it  makes  sense 
to  write  applications  with  more  than 
one  language  and  to  include  assembly 
language  in  the  mix. 

Furthermore,  every  programming  lan¬ 
guage  ever  created  has  inherent 
strengths  and  weaknesses.  One  area 
in  which  different  languages  have  dis¬ 
tinct  strengths  is  in  how  procedures  are 
called.  This  is  an  extremely  important 
issue,  because  in  many  applications 
more  time  and  effort  is  spent  getting 
in  and  out  of  procedures  than  doing 
anything  else!  Conversely,  a  good  choice 
of  procedure  calling  conventions  can 
actually  make  the  difference  between 
an  application  that  can  be  written 
quickly  and  one  which  cannot  be  writ¬ 
ten  at  all. 

Usually,  higher-level  languages  such 


Karl  is  the  principal  developer  of  Turbo 
Assembler  and  he  can  be  reached 
at  P.O.  Box  39,  Bedford,  MA  01730. 
Rick  is  director  of  language  develop¬ 
ment  for  Borland  International  and 
can  be  reached  at  1800  Green  Hills 
Road,  Scotts  Valley,  CA  95065. 


as  C  and  Pascal  use  an  argument  pass¬ 
ing  technique  known  as  the  “stack  frame 
method,”  where  arguments  are  pushed 
onto  a  stack  and  addressed  as  an  offset 
from  some  “frame  "  pointer.  It  is  a  good 
general  technique  in  that  it  allows  for 
an  unlimited  number  of  arguments  with 
built-in  recursion. 

C  and  Pascal  each  make  use  of  a 
slightly  different  flavor  of  the  stack  frame 
method.  The  C-style  stack  frame  per¬ 
mits  a  variable  number  of  arguments 
to  be  passed  to  a  procedure.  This  re¬ 
quires  that  the  caller  remove  the  argu¬ 
ments  from  the  stack  after  the  proce¬ 
dure  call,  because  it  is  the  caller  who 
knows  best  how  many  arguments  were 
passed.  In  Pascal,  on  the  other  hand, 
the  number  of  arguments  is  fixed,  so 
the  procedure  itself  is  responsible  for 
removing  its  arguments  from  the  stack. 
Typically,  this  is  done  efficiently  with 
the  single  machine  instruction  RET xx. 

Until  recently,  assembly  language  was 
generally  limited  to  what  is  known  as 
the  “register  passing  method”  of  pass¬ 
ing  arguments.  With  register  passing, 
arguments  are  passed  to  procedures 
in  machine  registers  or  at  fixed  mem¬ 
ory  locations.  (Stack  frames  could  be 
constructed  in  assembly  language,  but 
with  considerable  effort  on  the  part  of 
the  programmer.)  Register  passing  is 
not  a  general  argument  passing  method. 
There  are  a  limited  number  of  registers 
in  any  machine,  and  explicit  PUSH  and 
POP  instructions  must  be  used  to  re¬ 
tain  the  availability  of  arguments  dur¬ 
ing  recursion.  Nevertheless,  register  pass¬ 
ing  is  a  much  more  efficient  method 


of  passing  arguments  than  the  stack 
frame  when  the  number  of  arguments 
to  a  procedure  is  small  and  the  particu¬ 
lar  argument  registers  are  chosen  care¬ 
fully  in  light  of  the  instructions,  which 
are  to  be  done  inside  the  procedure. 

A  Text  "Spectrum  Analyzer"  Example 

The  example  used  to  illustrate  this  point 
is  a  program  that  reads  one  or  more  text 
files,  breaks  them  into  words,  and  counts 
the  individual  words.  It  then  sorts  the 
resulting  array  by  word  count,  and  dis¬ 
plays  the  word  and  the  associated  count 
together  in  a  neat,  tabular  form. 

This  example  emphasizes  speed  of 
execution,  with  the  additional  criteria 
that  modularity  is  preserved  and  nasty 
tricks  like  self-modifying  code  are  not 
used.  This  will  permit  the  program  to 
be  relatively  easy  to  change  or  to  up¬ 
grade,  and  still  be  considerably  faster 
than  anything  written  wholly  in  a  sin¬ 
gle  language. 

The  major  points  that  need  to  be 
covered  are  the  interfaces  between  mod¬ 
ules  and  what  each  module  is  respon¬ 
sible  for,  as  well  as  the  overall  organi¬ 
zation  of  the  application. 

The  command  line  that  this  program 
will  accept  has  the  following  format: 
SPECTRUM  <J'ile_spec>  <file_spec>  .  .  . 
where  each  <ftle_speO  can  include  wild 
cards.  If  a  file  name  is  given  more  than 
once,  its  spectrum  will  be  taken  more 
than  once.  The  output  of  the  applica¬ 
tion  will  be  a  table  that  is  written  to 
Standard  Out  and  is  sorted  in  order  of 
reference  count,  the  most  referenced 
words  being  listed  first. 
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(continued  from  page  84) 

The  basic  steps  are:  1.  Initialize  all 
data  structures.  2.  Parse  the  command 
line.  For  each  file  spec,  read  the  file(s) 
and  break  it  (them)  into  words.  Keep  a 
reference  count  for  each  unique  word. 
3.  Build  a  list  of  unique  words  and  sort 
it  by  reference  count.  4.  Scan  the  sorted 
list  and  print  out  the  reference  count  and 
associated  word  for  each  list  element. 

For  the  sake  of  performance,  the  work 
of  reading  a  file,  breaking  it  into  words, 
and  hashing  them  into  a  symbol  table 
is  best  handled  in  assembly  language, 
as  is  the  other  time  bottleneck  that 
occurs  when  the  sort  is  done.  Less  time- 
critical  areas,  such  as  command-line 
parsing  and  table  formatting,  are  writ¬ 
ten  in  C  to  provide  greater  flexibility 
in  the  user  interface.  Finally,  the  gener¬ 
ality  of  assembly  language,  another  in¬ 
herent  strength,  makes  it  best  for  deal¬ 
ing  with  the  heap  and  error  handling 
modules. 

The  major  modules  we  need  and 
their  respective  languages  are:  ER¬ 
ROR.  ASM,  the  assembly  language  error 
handler  (see  Listing  One,  page  116); 
HEAP.ASM,  the  assembly  language  mem¬ 


ory  allocator  (Listing  Two,  page  116); 
WORD. ASM.  the  assembly  language 
lexer/word,  table/file  input  (Listing 
Three,  page  116);  SORT.ASM,  the  as¬ 
sembly  language  general-sort  proce¬ 
dure  (Listing  Four,  page  119);  and  SPEC- 
TRUM.C,  the  command-line  parsing,  text 
formatting,  and  output  written  in  C  (List¬ 
ing  Five,  page  120).  The  make  file  is 
shown  in  Listing  Six,  page  121. 

Throughout  the  program,  we’ve  made 
every  effort  to  use  an  appropriate  call¬ 
ing  convention  for  the  situation.  On 
procedures  with  stack  frames,  Pascal- 
style  calling  conventions  are  most  fre¬ 
quently  used  because  of  their  inher¬ 
ently  faster  execution  and  smaller  code 
requirements.  Only  on  procedures  that 
require  a  variable  number  of  arguments 
do  we  use  a  C-style  stack  frame. 

The  extensive  modularity  we  use  in 
this  application  is  not  absolutely  neces¬ 
sary  given  its  small  size.  We  have  tried, 
however,  to  put  forth  as  general  a  treat¬ 
ment  as  possible,  demonstrating  tech¬ 
niques  that  are  appropriate  even  for 
very  large  applications.  The  use  of 
strong  data  abstraction  is  one  of  these 
techniques.  In  strong  data  abstraction, 


the  details  of  an  actual  data  structure 
are  known  only  to  a  small  set  of  proce¬ 
dures  that  manage  that  data  structure. 
The  data  structure  and  the  procedures 
that  manage  it  are  taken  together  to 
form  a  module.  Any  other  code  in  the 
program  that  deals  with  the  data  struc¬ 
ture  must  do  so  through  the  appropriate 
procedures  —  any  other  access  is  con¬ 
sidered  to  be  a  breach  of  modularity. 
In  this  application,  the  HEAP  and 
WORD  modules  are  good  examples  of 
strong  data  abstractions. 

The  program  uses  SMALL  model  with 
a  NEAR  stack.  All  of  the  code  is  in 
segment  _TEXT  (except  for  any  code 
in  the  C  libraries),  so  CS  is  always  set 
to  _TEXT.  Data,  uninitialized  data,  and 
stacks  are  all  in  DGROUP,  so  SS  must 
always  be  set  to  DGROUP.  DS  is  also 
set  to  DGROUP  in  the  C  sections  of  the 
program,  but  is  used  as  a  general  seg¬ 
ment  register  in  the  assembly  language 
code. 

The  interfaces  to  the  procedures  in 
the  various  modules  pretty  well  spell 
out  the  function  of  each  module: 

Error  Handling  Module  Because 
errors  need  only  to  be  caught  and  dis- 


Assembler  Specific  Features 


The  assembly  language  section  of  the 
application  was  written  in  Borland’s 
Turbo  Assembler  2.0  and  uses  several 
features  unique  to  that  assembler.  If 
you  are  using  another  assembler,  you 
may  need  to  modify  portions  of  the 
example  so  that  your  assembler  will 
accept  it.  The  following  are  the  fea¬ 
tures  I  used  and  how  you  can  work 
around  them  in  your  assembler. 
Extended  CALL  automatically  builds 
a  calling  stack  frame  by  generating  a 
series  of  PUSHes  in  the  order  appropri¬ 
ate  to  the  specified  language.  For  ex¬ 
ample,  CALL  foo  pascal ,  ax,  bx,  ivordptr 
would  PUSH  the  three  arguments  AX, 
BX,  and  WORDPTR  onto  the  stack  in 
the  order  appropriate  for  Pascal  stack 
frames,  and  is  equivalent  to 

PUSH  ax 
PUSH  bx 
PUSH  wordptr 
CALL  foo 

Multiple  PUSHes/POPs  permit  more 
than  one  item  at  a  time  to  be  PUSHed 
or  POPed  with  a  single  instruction. 
For  example, 

PUSH  AX  BX 
POP  BX  AX 


is  equivalent  to 

PUSH  AX 
PUSH  BX 
POP  BX 
POP  AX 

Local  Symbols  are  enabled  with  the 
LOCALS  directive.  All  local  symbols 
begin  with  the  two  characters  @@. 
They  are  scoped  to  be  local  to  the 
enclosing  procedure.  For  example 

fool  proc 
jmp  @@exit 
@@exit:  ret 
endp 

foo2  proc 
jmp  @@exit 

@@exit:  ret  ;This  @@EXIT  can  co¬ 
exist  amicably  with  the  former  one. 
endp 

If  you  are  using  an  assembler  that 
does  not  support  this  feature,  one 
way  to  work  around  it  is  to  change 
the  .MODEL  statement  at  the  start  of 
each  module  to  .MODEL  SMALL,  PAS¬ 
CAL.  This  will  cause  all  symbols  within 
a  procedure  to  become  local. 

ARG  and  USES  Statements  the  as¬ 


sembler  used  for  the  example  has  a 
way  of  setting  up  procedure  stack 
frames  that  is  somewhat  easier  to  read 
than  the  standard  method.  For  example: 

foo  proc  pascal 
arg  al,a2 
uses  ds,si 


is  equivalent  to  the  statement: 
foo  proc  pascal  uses  ds  si,al,a2 


Some  assemblers  require  a  language 
to  be  specified  in  the  .MODEL  state¬ 
ment  before  the  language  keyword 
PASCAL  is  recognized.  If  this  is  true 
for  your  assembler,  you  will  need  to 
change  the  .MODEL  statement  at  the 
start  of  each  module  to  MODEL 
SMALL, PASCAL. 

The  CODEPTR  type  is  used  occasion¬ 
ally  in  the  example.  It  means  either 
WORD  or  DWORD  depending  on 
whether  the  selected  model  has  NEAR 
or  FAR  code,  respectively.  Because  the 
example  is  SMALL  model,  you  may  re¬ 
place  CODEPTR  with  WORD  wherever 
it  is  found. 

—  R.S. 
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0 continued  from  page  86) 
played  without  the  ability  to  resume 
execution  of  the  application,  the  error 
handling  scheme  this  program  uses  is 
a  mechanism  whereby  the  stack  pointer 
is  saved  at  some  point  in  the  execution 
of  the  program,  and  if  an  error  is  en¬ 
countered,  the  program  is  resumed  at 
that  point.  The  required  procedures  are 
listed  in  Table  1 . 

Heap  Module  Because  data  struc¬ 
tures  are  allocated  but  never  freed,  a 
simple  stack  heap  is  the  best  choice  for 
both  performance  and  simplicity.  The 
application  uses  a  paragraph-based 
heap  where  memory  is  allocated  with 
16-byte  granularity.  This  turns  out  to 
Table  1:  Required  procedures  for  error  handling  be  useful  because  it  permits  any  data 

item  allocated  from  the  heap  to  be 
described  with  a  single  16-bit  segment 
address.  See  Table  2. 

Symbol  Table  Module  The  symbol 
table  module  is  responsible  for  much 
of  the  actual  work  of  reading  in  a  file, 
converting  it  to  words,  and  recording 
the  word  usage  information.  After  it  is 
read  in,  each  symbol  is  represented  by 
an  area  of  memory  allocated  from  the 
Table  2:  Required  procedures  for  stack  heap  heap  containing  the  reference  count 

for  the  symbol  and  the  actual  text  of 
the  symbol.  Because  it  is  allocated  from 
the  heap,  each  symbol  can  be  addressed 
by  using  a  16-bit  word  descriptor.  Re¬ 
fer  to  Table  3- 

Sorting  Module  The  sort  routine  is 
written  in  assembly  language  because 
a  recursive  algorithm  was  chosen  and 
recursion  tends  to  be  faster  if  register 
passing  can  be  used  appropriately.  In 
this  case,  there  are  a  small  number  of 
registers  that  are  used  directly;  more 
importantly,  during  the  innermost  step 
of  the  recursion  (which  is  done  most 
often)  no  registers  whatsoever  need  to 
be  saved  on  the  stack.  Recursion  with 
a  stack  frame  can't  make  a  decision  this 
intelligent,  because  access  to  the  argu¬ 
ments  is  needed  first. 

The  sort  procedure  operates  on  an 
array  of  words,  calling  a  generic  com¬ 
parison  routine  whose  address  is  passed 
as  an  argument.  This  comparison  routine 
uses  a  hybrid  calling  convention,  where 
a  stack  frame  is  present  but  registers  are 
not  necessarily  consistent  with  C.  The 
level  of  generality  this  arrangement 
achieves  is  high,  but  it  does  require  that 
the  comparison  routine  be  written  in  as¬ 
sembly  language.  See  Table  4. 

If  raw  speed  were  the  only  concern, 
the  SORT_DO  procedure  might  best 
be  integrated  entirely  into  the  symbol 
table  module,  which  would  permit  the 
comparison  to  be  performed  directly 
and  would  remove  the  need  to  call  the 
comparison  routine.  But  we  felt  that  a 
more  general  treatment  was  superior 
in  terms  of  modifiability  —  it  is  rela- 


void  pascal  WORDJNIT  (unsigned  maximum_word_count) 

Initializes  symbol  table.  The  maximum  number  of 
different  words  allowed  is  passed  so  that  a  hash  table 
can  be  initialized. 

void  pascal  WORD  READ  (unsigned  file  handle) 

Reads  all  the  text  there  is  from  the  specified  file 
handle  and  analyzes  it. 

void  pascal  WORD_SCAN  (void  pascal  fwordj>rocedure)() ) 

Calls  the  specified  procedure  once  for  each  individual 
symbol.  The  word  descriptor  for  the  symbol  is  passed  to 
WORD  PROCEDURE  as  an  argument.  WORD_PROCEDURE  might 
be  declared  in  C  as  follows: 

void  pascal  word_procedure(unsigned  word_descriptor). 

char  far  *  pascal  WORD_NAME  (unsigned  word_descriptor) 

Returns  the  FAR  address  of  the  name  of  the  described  symbol. 

unsigned  pascal  WORD_REFCOUNT  (unsigned  word_descriptor) 

Returns  the  total  reference  count  of  the  described  symbol. 

unsigned  pascal  WORDCOUNT  (void) 

Returns  the  total  number  of  distinct  words  processed  so  far. 

int  pascal  WORD__COMPREF  (unsigned  word_descriptor1 ,  unsigned 
word_descriptor2) 

Compares  the  reference  counts  of  two  word  descriptors. 

Returns  flags  for  refcount(word_descriptor2)  - 
refcount(word_descriptor1).  NOTE:  This  procedure,  while 
it  obeys  Pascal  calling  conventions,  is  not  callable 
directly  from  C  because  it  returns  its  result  in  the  flag 
register.  It  also  has  the  requirement  that  the  registers 
CX  and  DX  are  preserved. 

This  procedure  might  be  described  as  using  a  sort  of 
“hybrid"  calling  convention,  where  a  stack  frame  is 
used  but  high-level  language  register  conventions  are  not 
obeyed. 


Table  J:  Procedures  for  symbol  table 


void  pascal  HEAPJNIT  (unsigned  starting_segment,  unsigned  segment_count) 
Initializes  the  heap  to  start  at  a  certain  segment  and  be 
a  certain  size. 

void  far  *  pascal  HEAP  ALLOC  (unsigned  paragraph_count) 

Allocates  the  requested  number  of  paragraphs  from  the 
heap  and  returns  the  far  address  of  the  memory  in  DX:AX. 

NOTE:  The  offset  part  of  the  address  is  always  0. 


void  pascal  ERRORJNIT  (void) 

Initializes  error  module. 

unsigned  pascal  ERROR_TRAP  (void  pascal  (*execution_procedure)() ) 
Returns  0  if  no  error  occurred  in  the  execution  of 
EXECUTION_PROCEDURE  or  any  procedures  it  calls.  (Otherwise, 
an  error  code  is  returned.)  EXECUTION_PROCEDURE  is  a 
generic  procedure  which  can  generate  errors  in  its  execution 
(via  ERROR_LOG)  and  might  be  declared  in  C  as  follows: 
void  pascal  execution_procedure(void) 

void  pascal  ERROR^LOG  (unsigned  error_code) 

Causes  control  to  pass  to  the  nearest  enclosing  ERROR_TRAP. 
Execution  resumes  with  that  instance  of  function  ERROR_TRAP 
returning  error  code. 
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tively  straightforward  to  add  a  switch 
to  control  the  particular  sorting  method, 
for  example. 

The  Command-line  Parsing  and 
Text  Formatting  Module  We  are  now 

ready  to  lay  out  the  full-scale  sequenc¬ 
ing  of  the  program.  Given  the  assem¬ 
bly  language  interface  listed  earlier,  the 
following  steps  should  be  taken  by  the 
C  portion  of  the  program: 


Assembly  language’s 
flexibility  can  assist  in 
everything  from 
optimization  to  the 
creation  of  programs 
using  more  than  one 
interfacing  convention 


void  pascal  SORT_DO  (unsigned  far  *sort_array,  unsigned  sort_count, 
int  pascal  (*compare_procedure)()) 

Uses  the  specified  compare  procedure  to  order  the  array. 
COMPARE_PROCEDURE  is  called  with  two  array  values,  and 
returns  flags  appropriate  to  a  comparison  of  those 
values.  Note  that  compare_procedure  cannot  be  written  in 
C  because  the  value  is  returned  in  the  machine  flags.  In 
addition,  the  segment  registers  are  not  guaranteed  to  be 
set  up  in  a  manner  consistent  with  C  when 
compare_procedure  is  called.  Compare_procedure  itself  is 
expected  to  preserve  CX  and  DX.  The  definition  for 
compare_procedure  might  be  stated: 

int  pascal  compare_procedure(unsigned  valuel,  unsigned  value2) 


Table  4:  Procedures  for  sorting 


1.  Allocate  memory  from  DOS,  call  ER- 
ROR_INIT,  and  set  up  an  error  trap 
using  ERROR_TRAP. 

2.  Call  HEAPJNIT  and  WORDJNIT 
appropriately. 

3.  Parse  the  command  line.  For  each 
file  spec,  call  WORD_READ  for  all  files 
matching  the  file  spec  (the  C  code  is 
responsible  for  resolving  all  wild  cards 
and  for  opening  and  closing  each  file). 

4.  Request  the  total  number  of  unique 
words  using  WORD_COUNT,  and  allo¬ 
cate  an  array  of  16-bit  word  descriptors 
using  HEAP_ALLOC  that  is  large  enough 
to  hold  them.  Call  WORD_SCAN  appro¬ 
priately  to  fill  up  the  array  with  word 
descriptors. 

5.  Sort  the  array  using  SORT_DO  with 
the  comparison  routine  WORD_COMP 
REF,  which  compares  the  count  of 
references  for  two  word  descriptors. 

6.  Write  the  table  title. 

7.  Scan  the  array  to  write  out  the  table 
entries.  Use  WORD_REFCOUNT  to  get 
the  reference  count  for  each  word  de¬ 
scriptor,  and  WORD_NAME  to  get  the 
name  string  for  each  word  descriptor. 

Theory  of  Operation 

The  SPECTRUM  program  uses  a  hash 
function  and  hash  table  to  achieve  its 
level  of  performance.  Inside  the  WORD 
module,  the  procedure  WORD_READ 
reads  text  into  a  buffer.  This  text  is 
copied  to  a  storage  area  one  word  at  a 
time.  During  the  copy  operation,  which 
uses  the  LODSB  and  STOSB  instruc- 
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tions,  the  text  is  converted  to  upper¬ 
case  and  the  hash  value  for  the  word 
is  calculated,  all  on-the-fly. 

The  hash  table  is  an  array  of  word 
descriptors.  An  element  in  the  hash 
table  is  0  if  there  is  not  yet  an  associ¬ 
ated  symbol.  The  hash  function  is  cal¬ 
culated  by  looking  at  each  character 
in  the  word,  rotating  the  previous  hash 
value  circularly  left  by  five,  and  XORing 
in  the  character  value.  The  final  hash 
value  is  masked  off  to  become  an  in- 

Now  more  than  ever 
before,  it  makes  sense 
to  write  applications 
with  more  than  one 
language  and  to 
include  assembly 
language  in  the  mix 


dex  into  the  hash  table. 

After  the  hash  index  is  calculated, 
the  corresponding  hash  table  entry  is 
checked.  If  it  is  0,  a  new  symbol  is 
created,  and  its  reference  count  is  in¬ 
itialized  to  1.  Otherwise,  the  text  of  the 
word  is  compared  against  the  text  stored 
in  the  symbol  whose  word  descriptor 
is  found  in  the  hash  table.  If  it  agrees, 
the  correct  symbol  has  been  located, 
and  its  reference  count  is  incremented. 
If  not,  a  collision  has  occurred,  and  the 
next  hash  value  is  calculated  by  adding 
11*2  to  the  current  hash  index  (this 
number  must  be  relatively  prime  to  the 
size  of  the  hash  table).  The  process 
then  repeats  until  the  correct  hash  ta¬ 
ble  entry  or  a  0  is  found. 

An  unusual  technique  is  used  to 
speed  the  recognition  of  the  various 
different  character  types  during  the  lex- 
ing  process.  BX  is  initialized  to  point 
to  a  translation  table,  which  contains  a 
bit  for  each  pertinent  character  type. 
An  XLAT  instruction  followed  by  a  TEST 
AL, xxx  is  then  all  that  is  needed  to  iden¬ 
tify  a  character  as  a  numeral,  delimiter, 
lowercase  alphabetic,  and  so  on. 

Another  unusual  technique  is  used 
to  describe  objects  in  the  assembly  lan¬ 
guage  section  of  the  program.  Rather 
than  use  a  full  32  bits  to  describe  the 
address  of  a  data  object,  which  is  some¬ 
what  cumbersome,  a  paragraph  address 


is  used  instead.  This  paragraph  address 
becomes  the  “descriptor”  for  the  ob¬ 
ject.  Data  within  the  object  is  addressed 
by  loading  an  appropriate  segment  reg¬ 
ister  with  the  object  descriptor  and  ac¬ 
cessing  the  data  with  a  constant  offset 
using  that  segment  register. 

After  all  files  have  been  read  in  and 
parsed,  an  array  of  word  descriptors  is 
built  using  the  routine  WORD_SCAN. 
This  array  is  then  sorted  using  SORT_DO 
with  the  comparison  routine  WORD_ 
COMPREF.  SORT_DO  is  a  recursive  sort 
that  requires  N*LOG(N)  comparisons. 
It  operates  by  dividing  the  array  into 
two  roughly  equal  parts,  recursively 
sorting  each  part,  and  then  merging  the 
two  parts  in  place. 

Finally,  to  output  the  table,  the  array 
is  scanned  sequentially.  For  each  word 
descriptor  in  the  array,  WORD_NAME 
is  used  to  obtain  the  actual  text  of  the 
word,  and  WORD_REFCOUNT  is  used 
to  obtain  the  reference  count.  These 
values  are  displayed  using  PRINTF. 

Conclusion 

It  is  not  only  practical  but  advisable  to 
mix  languages  and  models  in  order  to 
achieve  the  best  results.  Modern  as¬ 
sembly  language  is  a  vital  part  of  this 
mix,  and  will  continue  to  be  important 
in  the  future,  because  space  and  per¬ 
formance  are  always  important  for  com¬ 
petitive  software,  no  matter  how  pow¬ 
erful  the  hardware  becomes.  Assembly 
language’s  flexibility  can  assist  in  ev¬ 
erything  from  optimization  to  the  crea¬ 
tion  of  programs  using  more  than  one 
interfacing  convention. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  11 6.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  8. 
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ASM  LIVES 


Listing  One  (Text  begins  on  page  16.) 

/*  Sample  program  to  copy  one  far  string  to  another  far  string, 

*  converting  lowercase  letters  to  uppercase  letters  in  the  process.  */ 

♦include  <ctype.h> 

char  Source []  =  "AbCdEfGhI jKlMnOpQrStUvWxYz0123456789 ! 
char  Dest [100]; 

/*  Copies  one  far  string  to  another  far  string,  converting  all  lower 

*  case  letters  to  upper  case  before  storing  them.  */ 

void  CopyUppercase (char  far  *DestPtr,  char  far  ‘SourcePtr)  ( 
char  UpperSourceTemp; 
do  ( 

/*  Using  UpperSourceTemp  avoids  a  second  load  of  the  far  pointer 
SourcePtr  as  the  toupper  macro  is  expanded  */ 

UpperSourceTemp  =  *SourcePtr++; 

*DestPtr++  =  toupper (UpperSourceTemp) ; 

)  while  (UpperSourceTemp) ; 

) 

main()  ( 

CopyUppercase ( (char  far  *) Dest, (char  far  *)Source); 

End  Listing  One 


Listing  Two 


C  near-callable  subroutine,  callable  as: 

void  CopyUppercase (char  far  ‘DestPtr,  char  far  *SourcePtr) ; 
Copies  one  far  string  to  another,  converting  all  lowercase  letters 
to  upper  case  before  storing  them.  Strings  must  be  zero-terminated. 


parms  struc 


dw 

?  ; pushed  BP 

dw 

?  /return  address 

DestPtr  dd 

?  /destination  string 

SourcePtr  dd 
parms  ends 

?  /source  string 

.model 

.code 

small 

public 

_CopyUppercase 

_Copy Upper case 

proc  near 

push 

bp 

mov 

bp,  sp 

;set  up  stack  frame 

push 

si 

/preserve  C's  register  vars 

push 

di 

push 

ds 

;we'll  point  DS  to  source 
/segment  for  the  duration  of  the 

les 

di, [bp+DestPtr] 

/point  ES:DI  to  destination 

Ids 

si, (bp+SourcePtr) 

/point  DS:SI  to  source 

CopyAndConvertLoop: 

lodsb 

/get  next  source  byte 

cmp 

al, ' a' 

/is  it  lowercase? 

jb 

SaveUpper 

/no 

cmp 

al, ' z' 

/is  it  lowercase? 

ja 

SaveUpper 

/no 

and 

SaveUpper : 

al.not  20h 

/convert  to  uppercase 

stosb 

/store  the  byte  to  the  dest 

and 

al,al 

/is  this  the  terminating  0? 

jnz 

CopyAndCon ve  r t  Loop 

/if  not,  repeat  loop 

pop 

ds 

/restore  caller's  DS 

pop 

di 

/restore  C's  register  vars 

pop 

si 

pop 

ret 

bp 

/restore  caller's  stack  frame 

_CopyUppercase 

endp 

end 

End  Listing 

Listing  Three 

/*  Sample  program  to  copy  one  near  string  to  another  near  string, 

*  converting  lower  case  letters  to  upper  case  letters  in  the  process.  */ 

♦include  <ctype.h> 

char  Sourced  =  "AbCdEfGhI jKlMnOpQrStUvWxYz012345678 9 ! 
char  Dest (100) ; 

/*  Copies  one  near  string  to  another  near  string,  converting  all  lower 

*  case  letters  to  upper  case  before  storing  them.  */ 
void  CopyUppercase (char  ‘DestPtr,  char  ‘SourcePtr)  ( 

char  UpperSourceTemp; 
do  { 

/*  Using  UpperSourceTemp  allows  slightly  better  optimization 
than  using  ‘SourcePtr  directly  */ 

UpperSourceTemp  =  *SourcePtr++; 

*DestPtr++  =  toupper (UpperSourceTemp) ; 

}  while  (UpperSourceTemp) ; 

} 

main()  { 

CopyUppercase (Dest, Source) ; 

End  Listing  Three 


Listing  Four 


C  near-callable  subroutine,  callable  as: 

void  CopyUppercase (char  ‘DestPtr,  char  ‘SourcePtr); 

Copies  one  near  string  to  another,  converting  all  lowercase  letters  to 
uppercase  before  storing  them.  Strings  must  be  zero-terminated. 


parms  struc 
dw 
dw 

DestPtr  dw 
SourcePtr  dw 
parms  ends 


; pushed  BP 
; return  address 
.•destination  string 
.•source  string 


.code 

public 

CopyUppercase 

CopyUppercase 

proc  near 

push 

bp 

mov 

bp,  sp 

push 

si 

push 

di 

mov 

di, [bp+DestPtr] 

mov 

si, [bp+SourcePtr] 

mov 

cx, ('a'  shl  8)  +  ' : 

mov 

bl,not  20h 

CopyAndConvertLoop : 

lodsw 

cmp 

al,  ch 

jb 

SaveUpper 

cmp 

al,  cl 

ja 

SaveUpper 

and 

al,  bl 

SaveUpper: 

and 

al,al 

jz 

SaveLastAndDone 

cmp 

ah,ch 

jb 

SaveUpper2 

cmp 

ah,  cl 

ja 

SaveUpper2 

and 

ah.bl 

SaveUpper2: 

stosw 

and 

ah,  ah 

jnz 

CopyAndCon ve  rt  Loop 

jmp 

short  Done 

SaveLastAndDone 

stosb 

Done: 

pop 

di 

pop 

si 

pop 

bp 

ret 

_CopyUppercase 

endp 

end 

;set  up  stack  frame 
.•preserve  C's  register  vars 

,-point  DI  to  destination 
; point  SI  to  source 
.•preload  CH  with  lower  end  of 
;  lowercase  range  and  CL  with 
;  upperend  of  that  range 
.•preload  BL  with  value  used  to 
;  convert  to  uppercase 

;get  next  two  source  bytes 
;is  the  1st  byte  lowercase? 

;no 

;is  the  1st  byte  lowercase? 

;no 

.•convert  1st  byte  to  uppercase 

;is  the  1st  byte  the  terminating  0? 

;yes,  save  it  &  done 

;is  the  2nd  byte  lowercase? 

;no 

;is  the  2nd  byte  lowercase? 

?no 

.•convert  2nd  byte  to  uppercase 

; store  both  bytes  to  the  dest 
;is  the  2nd  byte  the  terminating  0? 
;if  not,  repeat  loop 
;if  so,  we're  done 

.•store  the  final  0  to  the  dest 

.•restore  C's  register  vars 

.•restore  caller's  stack  frame 


End  Listing  Four 


Listing  Five 


C  near-callable  subroutine,  callable  as: 

void  CopyUppercase (char  ‘DestPtr,  char  ‘SourcePtr); 

Copies  one  near  string  to  another,  converting  all  lowercase  letters  to 
upper  case  before  storing  them.  Strings  must  be  zero-terminated.  Uses 
extensive  optimization  for  enhanced  performance. 


parms  struc 
dw 
dw 

DestPtr  dw 
SourcePtr  dw 
parms  ends 


.•pushed  BP 
; return  address 
.•destination  string 
.•source  string 


.model  small 
.data 

;  Table  of  mappings  to  uppercase  for  all  256  ASCII  characters. 
UppercaseConversionTable  label  byte 

ASCI I_VALUE=0 

rept  256 

if  (ASCII_VALUE  It  'a')  or  (ASCII_VALUE  gt  'z') 

db  ASCII_VALUE  ; non-lowercase  characters  map  to  themselves 


else 

db  ASCII_VALUE  and  not  20h 

endif 

ASCI I_VALUE=ASCI I_VALUE+1 
endm 
.code 

public  _CopyUppercase 
_CopyUppercase  proc  near 
push  bp 

mov  bp, sp 

push 
push 
mov 
mov 
mov 


di 

di, [bp+DestPtr] 
si, [bp+SourcePtr] 


.•lowercase  chars  map  to  upper  equivalents 


;set  up  stack  frame 
.•preserve  C's  register  vars 


; point  DI  to  destination 
;point  SI  to  source 
bx, offset  UppercaseConversionTable 

;point  BX  to  lowercase  to 
;  uppercase  mapping  table 

;  This  loop  processes  up  to  16  bytes  from  the  source  string  at  a  time, 
;  branching  only  every  16  bytes  or  after  the  terminating  0  is  copied. 
CopyAndConvertLoop: 


rept 

15 

/for  up  to  15  bytes  in  a  row. 

lodsb 

/get  the  next  source  byte 

xlat 

/make  sure  it's  upper  case 

stosb 

/save  it  to  the  destination 

and 

al,  al 

/is  this  the  terminating  0? 

jz 

endm 

Done 

/if  so,  then  we're  done 

lodsb 

/get  the  next  source  byte 

xlat 

/make  sure  it's  upper  case 

stosb 

/save  it  to  the  destination 

and 

al,  al 

/is  this  the  terminating  0? 

jnz 

CopyAndConvertLoop 

/if  not,  repeat  loop 

pop 

di 

/restore  C's  register  vars 

pop 

si 

pop 

bp 

/restore  caller's  stack  frame 

ret 

_CopyUppercase 

end 


endp 


End  Listings 


.model  small 
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Listing  One  (Text  begins  on  page  46.) 


*  File:  BREAK386.ASM 

*  BREAK386  "main  programs 

*  intl_386. 

*  Williams  -  June,  1989 

*  Compile  with:  MASM  /Ml  BREAK386; 

MODEL  small 
386P 


Contains  setup386,  clear386,  break386  and 


public  _break386,_clear386,_setup386,_intl_386 

Set  up  stack  offsets  for  word  size  arguments  based  on  the  code  size 
Be  careful,  regardless  of  what  Microsoft's  documentation  says, 
you  must  use  @CodeSize  (not  @codesize,  etc.)  when  compiling  with  /Ml 


IF  @CodeSize 


;  True  for  models  with  far  code 


argl 
arg2 
arg3 
arg4 
ELSE 
argl 
arg2 
arg3 
arg4 
END  IF 


EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 


< [BP+6] > 

< [BP+8] > 

< [BP+10] > 
< [BP+12] > 

<(BP+4]> 

< [BP+6] > 

< [BP+8 ] > 

< [BP+10] > 


.DATA 

Things  you  may  want  to  change: 


DIRECT  EQU  0 

STKWRD  EQU  32 

INTSTACK  EQU  1 

USE  INTI  EQU  1 


oldoffset 

oldsegment 

IF  USE_INT1 

video 

csip 

done 

notdone 

stkmess 


dw  0 
dw  0 


IF  0  use  BIOS;  IF  1  use  direct  video  access 
#  of  words  to  dump  off  the  stack 
When  0  don't  display  interrupt  stack  words 
Set  to  0  to  disable  intl_386() 

old  interrupt  1  vector  offset 
old  interrupt  1  vector  segment 


segment  of  video  adapter  (changed  by  vinit) 

,0 


vpage 
vcols 

IFE  DIRECT 

prompt 

savcursor 

ALIGN  4 

vbuff 

ELSE 

cursor 

color 

END  IF 

END  IF 


dw  ObOOOH 
db  ' CODE=' , 0 
db  'Program  terminated  normally, 
db  'Program  breakpoint:',© 
db  ' Stack  dump: ' ,  0 

db  0 
db  80 


db  '<V>iew  output,  <T>race  toggle,  <C>ontinue  or  <A>bort? 
dw  0  ;  inactive  video  cursor 


dd  1000  dup  (07200720H) 


dw  0 
db  7 


.CODE 

;  This  is  the  start  up  code.  The  old  interrupt  one  vector  is  saved  in 
;  oldsegment,  oldoffset.  intl_386  does  not  chain  to  the  old  vector,  it 
;  simply  replaces  it. 

_setup386  proc 
push  bp 
mov  bp, sp 
push  es 
mov  ax,3501H 
int  21h 
mov  ax,es 
mov  oldsegment, ax 
mov  oldoffset, bx 
pop  es 
mov  ax,arg2 
push  ds 
mov  dx,argl 

;  If  intl_386  is  being  assembled,  setup386  will  check  to  see  if  you  are 
;  installing  intl386.  If  so,  it  will  call  vinit  to  set  up  video  parameters 
;  that  intl_386  requires. 

IF  USE_INT1 

cmp  ax,seg  _intl_386 
jnz  notus 

cmp  dx, offset  _intl_386 
jnz  notus 
push  dx 
push  ax 
call  vinit 
pop  ds 
pop  dx 


get  old  inti  vector 


get  new  interrupt  handler  address 


Int'l  video  if  it  is  our  handler 


END  IF 
notus : 


Store  interrupt  address  in  vector  table 


Clear  DR7/DR6  (just  in  case) 


mov  ax,2501H 
int  21H 
pop  ds 
xor  eax,eax 
mov  dr7,eax 
mov  dr6,eax 
pop  bp 
ret 

setup386  endp 


This  routine  sets/clears  breakpoints 
Inputs: 

breakpoint  #  (1-4) 

breakpoint  type  (see  BREAK386 . INC) 

segment/offset  of  break  address  (or  null  to  clear  breakpoint) 


Outputs: 

AX=0  If  successful 
AX=-1  If  not  successful 

_break386  proc 
push  bp 
mov  bp,sp 
mov  bx,argl 
cmp  bx, 1 
jb  outrange 
cmp  bx, 4 
jna  nothigh 
outrange: 

mov  ax,0ffffH 

pop  bp 

ret 

nothigh: 

movzx  eax,word  ptr  arg4 
shl  eax,4 

movzx  edx,word  ptr  arg3 
add  eax,edx 
jz  resetbp 
dec  bx 
jz  bpO 
dec  bx 
jz  bpl 
dec  bx 
jz  bp2 
mov  dr3,eax 
jmp  short  brcont 
bpO:  mov  dr0,eax 

jmp  short  brcont 
bpl:  mov  drl,eax 

jmp  short  brcont 
mov  dr2,eax 


;  breakpoint  #  (1-4) 


error:  breakpoint  #  out  of  range 


get  breakpoint  address 

calculate  linear  address 
if  address  =  0  then 
turn  breakpoint  off! 
set  correct  address  register 


bp2: 
brcont : 


movzx  eax,word  ptr  arg2 
mov  cx,argl 


get  type 

calculate  proper  position 


rotate  type 
calculate  type  mask 

calculate  position  of  enable  bit 


enable  bp 
get  old  DR7 
mask  out  old  type 
set  new  type/enable  bits 
off  if  no  data  bp's) 


reset  GE  bit 
test  for  data  bp's 


push  cx 
dec  cx 
shl  cx,2 
add  cx, 16 
shl  eax,cl 
mov  edx, Ofh 
shl  edx, cl 
not  edx 
pop  cx 
shl  cx,l 
dec  cx 
mov  ebx, 1 
shl  ebx, cl 
or  eax,ebx 
mov  ebx, dr 7 
and  ebx, edx 
or  ebx,eax 

;  Adjust  enable  bit  (set  on  for  data  bp's, 
adjge: 

mov  eax, 200H 
and  ebx, OfffffdffH 
test  ebx, 033330000H 
jz  nodatabp 
or  ebx, 512 
nodatabp: 

mov  dr 7, ebx 
pop  bp 
xor  ax, ax 
ret 

;  Here  we  reset  a  breakpoint  by  turning  off  its  enable  bit  &  setting  type  to  0 
;  Clearing  the  type  is  required  so  that  disabling  all  data  breakpoints  will 
;  clear  the  GE  bit  also, 
resetbp: 

mov  cx,bx 
mov  edx, Ofh 
dec  cx 
shl  cx,2 
add  cx, 16 
shl  edx, cl 
not  edx 
mov  cx,bx 
shl  cx,l 
dec  cx 
mov  eax, 1 
shl  eax, cl 
not  ax 
mov  ebx,dr7 
and  ebx, eax 
and  ebx, edx 
jmp  adjge 
_break386  endp 

;  Reset  the  debug  register,  disabling  all  breakpoint.  Also  restore  the  old 
;  interrupt  1  vector 
_clear386  proc 
pushf 
pop  ax 

and  ax, 0FEFFH 
push  ax 
popf 

xor  eax, eax 
mov  dr7,eax 
mov  dr0,eax 
mov  dr 1, eax 
mov  dr2,eax 
mov  dr 3, eax 
mov  dr 6, eax 
mov  ax,2501H 
push  ds 

mov  bx,  oldsegment 
mov  dx, oldoffset 
mov  ds,bx 
int  21H 
pop  ds 


calculate  type/len  bit  positions 


calculate  enable  bit  position 


flip  bits 


clear  enable 
clear  type 


turn  off  trace  flag 


turn  off  all  other  breakpoints 


restore  old  int  1  vector 


(continued  on  page  98) 
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386  DEBUGGING 


Listing  One  (Listing  continued,  text  begins  on  page  46.) 

ret 

_clear386  endp 
IF  USE_INT1 

;  This  is  all  code  relating  to  the  optional  INT  1  handler 

;  This  macro  is  used  to  get  a  register  value  off  the  stack  and  display  it 
;  R  is  the  register  name  and  n  is  the  position  of  the  register  on  the  stack 
;  i.e.:  outreg  'AX', 10 

outreg  macro  r,n 
mov  ax,&r 

mov  dx, [ebp+&n  SHL  1] 

call  regout 

endm 


;  This  is  the  interrupt  1  handler 
_intl_386  proc  far 
sti 
pusha 
push  ds 
push  es 
push  ss 
push  @data 
pop  ds 
mov  bp, sp 
IFE  DIRECT 

call  savevideo 

END  IF 

mov  ax, video 
mov  es,ax 

assume  cs:@code,ds:@data 
mov  bx, offset  notdone 
call  outstr 
mov  edx,dr6 
call  hexout 
xor  edx,edx 
mov  dr6,edx 
call  crlf 
; do  register  dump 

outreg  ' AX' , 10 
outreg  ' FL' , 13 
outreg  'BX',7 
outreg  'CX',9 
outreg  'DX',8 
call  crlf 
outreg  'SI ',4 
outreg  'DI',3 
outreg  'SP',6 
outreg  'BP' ,5 
call  crlf 
outreg  'CS',12 
outreg  ' IP' , 11 
outreg  'DS',2 
outreg  ' ES' , 1 
outreg  'SS',0 
call  crlf 
;  do  stack  dump 
IF  STKWRD 

mov  bx, offset  stkmess 

call  outstr 

push  fs 

mov  dx, [ebp] 

mov  fs,dx 

mov  al, '  (' 

call  ouch 

mov  al, '  ' 

call  ouch 

call  hexout 

mov  al, ' : ' 

call  ouch 

mov  al, '  ' 

call  ouch 

mov  bx, [ebp+12] 

IFE  INTSTACK 

add  bx, 6 

END  IF 

mov  dx,bx 
push  bx 
call  hexout 
mov  al, ' ) ' 
call  ouch 
call  crlf 
pop  bx 

mov  cx, STKWRD 

sloop: 


;  Enable  interrupts  (see  text) 
;  Save  all  Registers 

;  Reload  DS 

;  point  ebp  to  top  of  stack 

;  get  video  addressabilty 
;  Display  breakpoint  message 


;  Print  stack  dump  title 
;  get  program' s  ss 


;  get  stack  pointer  (before  pusha) 
;  skip  interrupt  info  if  desired 


mov  dx, fs: [bx]  ;  get  word  at  stack 

push  bx 
push  cx 

call  hexout  ;  display  it 

pop  cx 

pop  bx 

inc  bx 

inc  bx 

loop  sloop 

pop  fs 

END  IF 
nostack: 

;  Here  we  will  dump  16  bytes  starting  8  bytes  prior  to  the  instruction 
;  that  caused  the  break 
push  fs 
call  crlf 
mov  bx,  offset  csip 
call  outstr 
mov  cx, 8 

mov  ax, [ebp+24]  ;  get  cs 

mov  fs,ax 

mov  bx, [ebp+22]  ;  get  ip 


cmp  bx, 8 
jnb  ipbegin 
mov  cx,bx 

ipbegin:  sub  bx,cx 
push  bx 
push  cx 
mov  dx,ax 
call  hexout 
mov  al, ' : ' 
call  ouch 
mov  al, '  ' 
call  ouch 
mov  dx,bx 
call  hexout 
mov  al, ' =' 
call  ouch 
pop  cx 
pop  bx 
or  bx,bx 
jz  ipskip 

iploop: 

mov  dl, fs: (bx) 
push  bx 
push  cx 
call  hexlout 
pop  cx 
pop  bx 
inc  bx 
loop  iploop 

ipskip: 

push  bx 
mov  al, ' 
call  ouch 
mov  al, '  ' 
call  ouch 
pop  bx 

;  This  is  basically  a  repeat  of  the  above  loop  except  it  dumps  the  8  bytes 

;  starting  at  IP 
mov  cx, 8 

xiploop: 

mov  dl, fs: [bx] 
push  bx 
push  cx 
call  hexlout 
pop  cx 
pop  bx 
inc  bx 

loop  xiploop 
call  crlf 
call  crlf 
pop  fs 

IFE  DIRECT 

;  Here  we  will  ask  if  we  should  continue  or  abort 
mov  bx, offset  prompt 
call  outstr 

key loop: 

xor  ah, ah  ;  Get  keyboard  input 

int  16H 

and  al,0dfh  ;  make  upper  case 

cmp  al, 'T' 
jz  ttoggle 
cmp  al, ' A' 
jz  ql 

cmp  al, 'C' 
jz  cl 

cmp  al, ' V' 
jnz  keyloop 

;  Display  program's  screen  until  any  key  is  pressed 
call  savevideo 
xor  ah, ah 
int  16H 

call  savevideo 
jmp  keyloop 


;  make  sure  we  have  8  bytes  before 
;  the  begining  of  the  segment 
;  If  not,  only  dump  from  the  start 
;  of  the  segment 


;  display  address 


;  if  starting  at  0,  don't  display  any 
;  before  IP 

;  get  byte 


;  output  it 


;  put  '*'  before  IP  location 


;  Execution  comes  here  to  toggle  trace  flag  and  continue 
ttoggle: 

xor  word  ptr  [bp+26],256  ;  toggle  trace  flag  on  stack 

;  Execution  comes  here  to  continue  running  the  target  program 
cl: 

call  crlf 
IFE  DIRECT 

call  savevideo 

ELSE 

xor  ax, ax 
mov  cursor, ax 

END  IF 

pop  ss 
pop  es 
pop  ds 
popa 

;  This  seems  complicated  at  first. 

;  You  MUST  insure  that  RF  is  set  before  continuing.  If  RF  is  not  set 
;  you  will  just  cause  a  breakpoint  immediately! 

;  In  protected  mode,  this  is  handled  automatically.  In  real  mode  it 
;  isn't  since  RF  is  in  the  high  16  bits  of  the  flags  register. 

;  Essentially  we  have  to  convert  the  stack  from: 

;  16  bit  Flags  32  bit  flags  (top  word  =  1  to  set  RF) 

;  16  bit  CS  to  - >  32  bit  CS  (garbage  in  top  16  bits) 

;  16  bit  IP  32  bit  IP  (top  word  =  0) 

;  All  this  so  we  can  execute  an  IRETD  which  will  change  RF. 

sub  esp, 6 
xchg  ax, [esp+6] 
mov  [esp], ax 
xor  ax, ax 
mov  [esp+2],ax 
mov  ax, [esp+6] 
xchg  ax, [esp+8] 


make  a  double  stack  frame 
get  ip  in  ax 
store  it 

eip  =  0000: ip 
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Listing  One  Listing  continued,  text  begins  on  page  46.) 


mov  [esp+4],ax 
xor  ax, ax 
mov  [esp+6],ax 
mov  ax, [esp+8] 
xchg  ax, [esp+10] 
mov  [esp+8], ax 
mov  ax, 1 
xchg  ax, [esp+10] 
iretd 


;  zero  that  stack  word  &  restore  ax 
;  get  flags 


;  set  RF 

;  DOUBLE  IRET  (32  bits!) 


END  IF 


;  Execution  resumes  here  to  abort  the  target  program 
ql: 

IFE  DIRECT 

call  savevideo 

END  IF 

call  quit 
_intl_386  endp 

IFE  DIRECT 

;  save  video  screen  &  restore  ours  (only  with  BIOS  please!) 

;  (assumes  25  lines/page) 
savevideo  proc  near 
pusha 
push  es 
mov  ah,0fh 

int  lOh  ;  reread  video  page/size  in  case 

mov  vpage,bh  ;  program  changed  it 

mov  vcols,ah 


get  old  cursor 


set  new  cursor 

compute  #  bytes/page 
vcols  *  25  *  2 


start  at  beginning  of  page 
#  of  double  words  to  transfer 


store  inactive  screen  in  vbuff 
swap  screens 


push  savcursor 
mov  ah, 3 
mov  bh,vpage 
int  10H 

mov  savcursor, dx 
pop  dx 
mov  ah, 2 
int  10H 

movzx  ax,vpage 
mov  cl, vcols 
xor  ch,ch 
mov  dx,cx 
shl  cx,3 
shl  dx, 1 
add  cx,dx 
mov  dx,cx 
shl  cx,2 
add  cx,dx 
push  cx 
mul  cx 
mov  di,ax 
pop  cx 
shr  cx,2 
mov  ax, video 
mov  es,ax 

mov  si, offset  vbuff 

xloop:  mov  eax,es: [di] 
xchg  eax, [si] 
mov  es: [di] ,eax 
add  si, 4 
add  di, 4 
loop  xloop 
pop  es 
popa 
ret 

savevideo  endp 

END  IF 


;  This  routine  prints  a  register  value  complete  with  label 
;  The  register  name  is  in  AX  and  the  value  is  in  dx  (see  the  outreg  macro) 
regout  proc  near 
push  dx 
push  ax 
mov  al,ah 
call  ouch 
pop  ax 
call  ouch 
mov  al, '=' 
call  ouch 
pop  dx 
call  hexout 
ret 

regout  endp 

;  Plain  vanilla  hexadecimal  digit  output  routine 
hexdout  proc  near 
and  dl, Ofh 
add  dl, ' 0' 
cmp  dl, 3ah 
jb  ddigit 
add  dl, ' A' -3ah 

ddigit : 

mov  al,dl 
call  ouch 
ret 

hexdout  endp 

;  Plain  vanilla  hexadecimal  word  output  routine 
hexout  proc  near 
push  dx 
shr  dx, 12 
call  hexdout 
pop  dx 
push  dx 
shr  dx,8 
call  hexdout 
pop  dx 


;  Call  with  this  entry  point  to  output  just  a  byte 
hexlout : 

push  dx 
shr  dx, 4 
call  hexdout 
pop  dx 
call  hexdout 
mov  al, '  ' 
call  ouch 
ret 

hexout  endp 


;  These  routines  are  for  direct  video  output.  Using  them  allows  you  to 
;  debug  video  bios  calls,  but  prevents  you  from  single  stepping  IF  DIRECT 
/output  a  character  in  al  assumes  ds=dat  es=video  destroys  bx,ah 
ouch  proc  near 

mov  bx, cursor 
mov  ah, color 
mov  es: [bx] ,ax 
inc  bx 
inc  bx 

mov  cursor, bx 
ret 

ouch  endp 


;  <CR>  <LF>  output 
df 

crlf 


assumes  ds=dat  es=video  destroys  ax,cx,dx,di  clears 


proc  near 
mov  ax, cursor 
mov  cx, 160 
xor  dx,dx 
div  cx 
inc  ax 
mul  cx 

mov  cursor, ax 
mov  cx,80 
mov  ah, color 
mov  al, '  ' 
mov  di, cursor 
cld 

rep  stosw 
ret 

crlf  endp 
ELSE 

;  These  are  the  BIOS  output  routines 
;  Output  a  character 
ouch  proc  near 
mov  ah, Oeh 
mov  bh,vpage 
int  lOh 
ret 

ouch  endp 

;  <CR>  <LF>  output, 
crlf  proc  near 

mov  al,0dh 
call  ouch 
mov  al, Oah 
call  ouch 
ret 

crlf  endp 


Intialize  the  video  routines 
init  proc  near 
mov  ah, Ofh 
int  lOh 
mov  vcols, ah 
mov  vpage,bh 
cmp  al, 7 
mov  ax,0b000H 
jz  vexit 
mov  ax,0b800H 
exit:  mov  video, ax 

ret 

init  endp 


;  monochrome 


;  outputs  string  pointed  to  by  ds:bx  (ds  must  be  dat)  es=  video  when  DIRECT=1 

outstr  proc  near 

outagn: 

mov  al, [bx] 
or  al,al 
jz  outout 
push  bx 
call  ouch 
pop  bx 
inc  bx 
jmp  outagn 
outout :  ret 
outstr  endp 


;  This  routine  is  called  to  return  to  DOS 
quit  proc  near 

call  clear386 


mov  ax,4c00h 
int  21h 
endp 


;  Return  to  DOS 


End  Listing  One 
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listing  Two  (Text  begins  on  page  46.) 


File:  BREAK386 . INC 

Header  file  to  include  with  assembly  language  programs  using  BREAK386 
Williams  -  June,  1989 


IF  @CodeSize  ;  If  large  style  models 

extrn  _break386: far,_clear386: far,_setup386: far,_intl_386: far 

ELSE 

extrn  _break386 : near , _clear386 : near , _setup386 : near, _intl_386 : far 

END  IF 


Breakpoint  equates 


BP_CODE 
BP_DATAW1 
BP_DATARW1 
BP_DATAW2 
BP_DATARW2 
BP_DATAW4 
BP  DATARW4 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU  13 
EQU  15 


CODE  BREAKPOINT 

ONE  BYTE  DATA  WRITE  BREAKPOINT 
ONE  BYTE  DATA  R/W  BREAKPOINT 
TWO  BYTE  DATA  WRITE  BREAKPOINT 
TWO  BYTE  DATA  R/W  BREAKPOINT 
FOUR  BYTE  DATA  WRITE  BREAKPOINT 
FOUR  BYTE  DATA  R/W  BREAKPOINT 


Macros  to  turn  tracing  on  and  off 
Note:  When  tracing,  you  will  actually 
tracing  off 

traceon  macro 

push  bp 
pushf 
mov  bp, sp 
xchg  ax, [bp] 
or  ax, 100H 
xchg  ax, [bp] 
popf 
pop  bp 
endm 

traceoff  macro 

push  bp 
pushf 
mov  bp, sp 
xchg  ax, [bp] 
and  ax, OFEFFH 
xchg  ax, [bp] 
popf 
pop  bp 
endm 


see"  traceoff  before  it  turns 


End  Listing  Two 


Listing  Three 


File:  BREAK386 . H 


Header  for  C  programs  using  BREAK386  or  CBRK386 
Williams  -  June,  1989 


#ifndef  NO_EXT_KEYS 
♦define  _CDECL  cdecl 
♦else 

♦define  _CDECL 
♦endif 

♦ifndef  BR386_HEADER 
♦define  BR386_HEADER 

/*  declare  functions  */ 

void  _CDECL  setup386 (void  (_CDECL  interrupt  far 
void  _CDECL  csetup386 (void  (_CDECL  far  *)()); 
void  _CDECL  clear386 (void) ; 
int  _CDECL  break386 (int, int,  void  far  *); 
void  _CDECL  far  interrupt  intl_386(); 


')  0); 


7 

0 

1 

3 

5 

7 

13 

15 


/*  CODE  BREAKPOINT*/ 

/*  ONE  BYTE  DATA  WRITE  BREAKPOINT*/ 
/*  ONE  BYTE  DATA  R/W  BREAKPOINT*/ 

/*  TWO  BYTE  DATA  WRITE  BREAKPOINT 
/*  TWO  BYTE  DATA  R/W  BREAKPOINT*/ 

/*  FOUR  BYTE  DATA  WRITE  BREAKPOINT*/ 
/*  FOUR  BYTE  DATA  R/W  BREAKPOINT*/ 


/*  breakpoint  types 
♦define  BP_CODE 
♦define  BP_DATAW1 
♦define  BP_DATARW1 
♦define  BP_DATAW2 
♦define  BP_DATARW2 
♦define  BP_DATAW4 
♦define  BP  DATARW4 


Listing  Four 


File:  DEBUG386 . ASM 

Example  assembly  language  program  for  use  with  BREAK386 

Williams  -  June,  1989 

Compile  with:  MASM  /Ml  DEBUG386 . ASM; 

.model  large 
.386 

INCLUDE  break386.inc 
.stack  OaOOH 


End  Listing  Three 


.data 
align  2 
memcell  dw  0 


make  sure  this  is  word  aligned 
cell  to  write  to 


.code 

main  proc 
; setup  data  segment 
mov  ax, @data 
mov  ds,ax 

assume  cs:@code,ds:@data 

;  start  debugging 

push  seg  _intl_386 
push  offset  _intl_386 
call  _setup386 
add  sp, 4 

;  set  up  a  starting  breakpoint 
push  seg  bpl 
push  offset  bpl 
push  BP_CODE 
push  1 

call  _break386 
add  sp, 8 

push  seg  bp2 
push  offset  bp2 
push  BP_CODE 
push  2 

call  _break386 
add  sp,  8 

push  seg  bp3 
push  offset  bp3 
push  BP_CODE 
pus’  ■* 

call  _break386 
add  sp, 8 

push  @data 
push  offset  memcell 
push  BP_DATAW2 
push  4 

call  _break386 
add  sp, 8 


segment  of  interrupt  handler 
offset  of  interrupt  handler 

balance  stack  (like  a  call  to  C) 

segment  of  breakpoint 
offset  of  breakpoint 
breakpoint  type 
breakpoint  ♦  (1-4) 

balance  the  stack 

set  up  breakpoint  ^2 


set  up  breakpoint  ^3 


set  up  breakpoint  #4  (data) 


bpl : 
loopl : 


bp2 : 
bp3: 


mov  cx,20 

mov  dl,cl 
add  dl, '0' 
mov  ah, 2 

int  21h 

loop  loopl 

mov  bx, offset  memcell 

mov  ax, [bx] 

mov  [bx],ah 

call  _clear386 

mov  ah, 4ch 

int  21h 

endp 

end  main 


loop  20  times 
print  some  letters 


repeat 

point  bx  at  memory  cell 
read  cell  (no  breakpoint) 
this  should  cause  breakpoint 
shut  off  debugging 

back  to  DOS 


End  Listing  Four 


Listing  Five 


*  File:  DBG386.C 

*  Example  C  program  using  BREAK386  with  the  built  in  interrupt  handler 

*  A1  Williams  —  15  July  1989 

*  Compile  with:  CL  DBG386.C  BREAK386 

♦include  <stdio.h> 

♦include  <dos.h> 

♦include  "break386.h" 

int  here [10]; 
void  far  *bp; 
int  i; 

main  () 

{ 

int  j; 

setup386 (intl_386) ; 
bp=(void  far  *)&here[2]; 
break386 (1, BP_DATAW2, bp) ; 
for  ( j=0; j<2; j++)  { 
for  (i*0;i<10;i++) 

( 

char  x; 

putchar (i+' 0' ) ; 
here[i]=i; 

) 

break386 (1,0, NULL) ; 

) 

clear386 () ; 


/*  set  up  debugging  */ 

/*  make  long  pointer  to  data  word  */ 
/*  set  breakpoint  */ 

/*  loop  twice  */ 

/*  for  each  element  in  here[]  */ 

/*  print  index  digit  */ 

/*  assign  ♦  to  array  element  */ 

/*  turn  off  breakpoint  on  2nd  pass  */ 


:  turn  off  debugging 


End  Listing  Five 

(continued  on  page  104) 
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Listing  Six  (Text  begins  on  page  46.) 


*  File:  DBGOFF . ASM 

*  Try  this  program  if  you  leave  a  program  abnormally  (say,  with  a  stack 

*  overflow).  It  will  reset  the  debug  register. 

*  Williams  -  June,  1989 

*  Compile  with:  MASM  DBGOFF; 


.model  small 
.  386P 
.stack  32 
.code 

main  proc 

xor  eax,eax  ;  clear  dr7 

mov  dr7,eax 

mov  ah,  4ch  ;  exit  to  DOS 

int  21H 
main  endp 

end  main 


End  Listing  Six 


pop  es 

mov  ax,arg2 

push  ds 

mov  dx,argl 

mov  c_seg, ax 

mov  c_off,dx 

mov  ax,seg  _cintl_386 

mov  ds,ax 

mov  dx, offset  _cintl_386 

mov  ax,2501H 

int  21H 

pop  ds 

xor  eax,eax 

mov  dr6,eax 

pop  bp 

ret 

csetup386  endp 


*  Here  is  the  interrupt  handler!!! 

*  Two  arguments  are  passed  to  C,  a  far  pointer  to  the  base  of  the  stack 

*  frame  and  the  complete  contents  of  dr6  as  a  long  unsigned  int. 


*  The  stack  frame  is  as  follows: 


Listing  Seven 


File:  CBRK386 . ASM 

Functions  to  allow  breakpoint  handlers  to  be  written  in  C. 

Williams  -  June,  1989 

Compile  with:  MASM  /Ml  CBRK386 . ASM; 


MODEL  small 
386P 


public  _csetup386 

;  Set  up  stack  offsets  for  word  size  arguments  based  on  the  code  size 
;  Be  careful,  regardless  of  what  Microsoft's  documentation  says, 

;  you  must  use  @CodeSize  (not  @codesize,  etc.) 

IF  @CodeSize  ;  True  for  models  with  far  code 


argl 

EQU 

< [BP+6] > 

arg2 

EQU 

< [BP+8] > 

arg3 

EQU 

< [BP+10] > 

arg4 

ELSE 

EQU 

< [BP+12] > 

argl 

EQU 

< [BP+4 ] > 

arg2 

EQU 

< [BP+6] > 

arg3 

EQU 

< [BP+8] > 

arg4 

END  IF 

EQU 

< [BP+10] > 

.DATA 

;  You  may 

need  to  change  the  next 

line  to  expand  the  stack  your  breakpoint 

;  handler 

runs  with 

STACKSIZE 

EQU  2048 

oldof fset 

dw  0 

;  old  interrupt  1  vector  offset 

oldsegment 

dw  0 

;  old  interrupt  1  vector  segment 

oldstack 

equ  this  dword 

sp_save 

dw  0 

ss_save 

dw  0 

ds_save 

dw  0 

es_save 

dw  0 

ccall 

equ  this  dword 

;  C  routine's  adress  is  saved  here 

c_off 

dw  0 

c_seg 

dw  0 

oldstkhqq 

dw  0 

;  Old  start  of  stack 

newsp 

equ  this  dword 
dw  offset  stacktop 
dw  seg  newstack 

;  New  stack  address  for  C  routine 

;  Here  is  the  new  stack.  DO  NOT  MOVE  IT  OUT  OF  DGROUP 
;  That  is,  leave  it  in  the  DATA  or  DATA?  segment, 
newstack  db  STACKSIZE  DUP  (0) 

stacktop  EQU  $ 

extrn  STKHQQ:word  ;  Microsoft  heap/stack  bound 


(Interrupted  code's  stack) 

FLAGS 

CS 


CX 

DX 


SP  ■ 

BP 

SI 

DI 

ES 


(Stack  pointer  points  to  IP  above) 


-  pointer  passed  to  your  routine  points  here 


*  The  pointer  is  two  way.  That  is,  you  can  read  the  values  or  set  any  of 

*  them  except  SS.  You  should,  however,  refrain  from  changing  CS,IP,or  SP. 


cintl_386  proc 
pusha 
push  es 
push  ds 
push  ss 
mov  ax,@data 
mov  ds,ax 
mov  ax,ss 
mov  ss_save,ax 
mov  sp_save,sp 
cld 

lss  sp,newsp 

mov  ax, STKHQQ 

mov  oldstkhqq,ax 

mov  ax, offset  newstack 

mov  STKHQQ, ax 

sti 

mov  eax,dr6 
push  eax 
push  ss_save 
push  sp_save 
mov  ax,es_save 
mov  es,ax 
mov  ax,ds_save 
mov  ds,ax 
call  ccall 
xor  eax, eax 
mov  dr6,eax 
mov  ax,@data 
mov  ds,ax 
lss  sp,oldstack 
add  sp,  2 

mov  ax,oldstkhqq 
mov  STKHQQ, ax 
pop  ds 
pop  es 
popa 


;  save  registers 


;  point  at  our  data  segment 


;  remember  old  stack  location 


;  switch  stacks 
;  save  old  end  of  stack 

;  load  new  end  of  stack 


;  put  DR6  on  stack  for  C 

;  put  far  pointer  to  stack  frame 
;  on  new  stack  for  C 
;  restore  es/ds  from  csetup386() 


;  call  the  C  program 
;  clear  DR6 


;  regain  access  to  data 
;  restore  old  stack 
;  don't  pop  off  SS 
;  (in  case  user  changed  it) 
;  restore  end  of  stack 


CODE 

This  routine  is  called  in  place  of  setup386().  You  pass  it  the  address  of 
a  void  far  function  that  you  want  invoked  on  a  breakpoint. 

It's  operation  is  identical  to  setup386()  except  for: 

1)  The  interrupt  1  vector  is  set  to  cintl_386()  (see  below) 

2)  The  address  passed  is  stored  in  location  CCALL 

3)  DS  and  ES  are  stored  in  ds_save  and  es_save 

_csetup386  proc 
push  bp 
mov  bp, sp 
push  es 
mov  ax,es 
mov  es_save,ax 
mov  ax,ds 
mov  ds_save,ax 
mov  ax, 3501H 
int  21h 
mov  ax,es 
mov  oldsegment, ax 
mov  oldoffset,bx 


This  seems  complicated  at  first. 

You  MUST  insure  that  RF  is  set  before  continuing.  If  RF  is  not  set 
you  will  just  cause  a  breakpoint  immediately! 

In  protected  mode,  this  is  handled  automatically.  In  real  mode  it 
isn't  since  RF  is  in  the  high  16  bits  of  the  flags  register. 
Essentially  we  have  to  convert  the  stack  from: 


16  bit  Flags  32  bit  flags  (top  word  =  1  to  set  RF) 

16  bit  CS  to  - >  32  bit  CS  (garbage  in  top  16  bits) 

16  bit  IP  32  bit  IP  (top  word  =  0) 

All  this  so  we  can  execute  an  IRETD  which  will  change  RF. 

sub  esp,6  ;  make  a  double  stack  frame 

xchg  ax, [esp+6]  ;  get  ip  in  ax 

mov  [esp],ax  ;  store  it 

xor  ax, ax 

mov  [esp+2],ax  ;  eip  =  0000: ip 

mov  ax, [esp+6] 

xchg  ax, [esp+8]  ;  get  cs 

mov  [esp+4],ax 
xor  ax, ax 
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mov  [esp+6],ax 
mov  ax, [esp+8] 
xchg  ax, [esp+10] 
mov  [esp+8], ax 
mov  ax, 1 
xchg  ax, [esp+10] 
iretd 

cintl_386  endp 
end 


;  zero  that  stack  word  &  restore  ax 
;  get  flags 

;  set  RF 

;  DOUBLE  IRET  (32  bits!) 


End  Listing  Seven 


Listing  Eight 

/a*********************************************************, **************** 

*  File:  CBRKDEMO . C 

*  Example  C  interrupt  handler  for  use  with  CBRK386 

*  Williams  -  June,  1989 

*  Compile  with:  CL  CBRKDEMO. C  BREAK386  CBRK386 
*********************************»*****************************************, 


♦include  <stdio.h> 
♦include  <conio.h> 
♦include  <ctype.h> 
♦include  <dos.h> 
♦include  "break386.h" 


♦define  IOFFSET  15  /*  use  16  for  large,  medium  or  huge  models  */ 

n=* ( (unsigned  int  far  *) p+IOFFSET) ; 

printf ("XnBreakpoint  reached!  (DR6=%1X  i=%d) \n",dr6,n) ; 

/*  Ask  user  what  to  do.  */ 
do  { 

printf ("<C>ontinue,  <M>odify  i,  <A>bort,  or  <N>o  breakpoint?  "); 
c=getche() ; 
putch(' \r' ) ; 

putch('\n');  /*  start  a  new  line  */ 

if  (!c)  /*  function  key  pressed  */ 

( 

getch() ; 
continue; 

I 

c=toupper (c) ; 

/*  Modify  loop's  copy  of  i  (doesn't  change  main's  i)  */ 
if  (c=='M') 

{ 

int  newi; 

printf ("Enter  new  value  for  i:  "); 
scanf ("%d", &newi) ; 

‘((unsigned  int  far  *) p+IOFFSET) =newi ; 
continue; 

) 

if  (c=='A')  /*  Exiting  */ 

I 

clear386();  /*  ALWAYS  turn  off  debugging!!!  */ 

exit (0) ; 

} 

if  (c=='N') 

breaking=0;  /*  We  could  have  turned  off  breakpoints  instead  */ 

)  while  (c !  =  '  A' &&c !=' N' 4&c !  =' C' ) ; 


/*  functions  we  will  reference  */ 

int  loop ( ) ; 

void  far  broke  (); 


main  () 

{ 

int  i; 

/*  declare  function  broke  as  our  interrupt  handler  */ 
csetup386 (broke)  ; 

break386 (1, BP_CODE, (void  far  *)loop);  /*  set  break  at  function  loop  */ 

for  (i=0;i<10;i++)  loop(i); 
printf ("Returned  to  main.Nn"); 

clear386();  /*  turn  off  debugging  */ 


End  Listings 


/*  This  function  has  a  breakpoint  on  its  entry  */ 
loop (int  j) 

{ 

printf ("Now  in  loop  (%d)\n",j); 

} 

/******************«***************************,**,************************„ 

*  Here  is  the  interrupt  handler!!! 

*  Note  it  must  be  a  far  function  (normal  int  the  LARGE,  HUGE  &  MEDIUM 

*  models) .  Two  arguments  are  passed:  a  far  pointer  to  the  base  of  the  stack 

*  frame  and  the  complete  contents  of  dr6  as  a  long  unsigned  int. 

*  The  stack  frame  is  as  follows: 


(Interrupted  code's  stack) 

FLAGS 

CS 


BX 

SP  ■ 

BP 

SI 

DI 

ES 


(Stack  pointer  points  to  IP  above) 


pointer  passed  to  your  routine  points  here 


The  pointer  is  two  way.  That  is,  you  can  read  the  values  or  set  any  of 
them  except  SS.  You  should,  however,  refrain  from  changing  CS,IP,or  SP. 


void  far  broke (void  far  *p,long  dr6) 

{ 

static  int  breaking=l;  /*  don't  do  anything  if  breaking=0  */ 
int  c; 

if  (breaking) 

{ 

int  n; 

int  far  *ip; 

*  Here  we  will  read  the  local  variable  off  the  interrupted  program's  stack! 

*  Assuming  small  model,  the  stack  above  our  stack  frame  looks  like  this: 

*  i  variable  sent  to  loop 

*  add  -  address  to  return  to  main  with 

*  <our  stack  frame  starts  hero 

*  This  makes  i  the  15th  word  on  the  stack  (16th  on  models  with  far  code) 
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WINDOWS  MANAGEMENT 


Listing  One  (Text  begins  on  page  58.) 

TextOut(hDC,  9*xchar,  ychar,  "pseg  seg  oldseg  moved",  23); 
for  (i  =0;  i  <  MAX  VARIABLE  PSEGS;  i++) 

/*  segments. c  */ 

( 

len  =  sprintf (buffer,  "data[%d]  %.4X  %.4X",  i,  FARDATAP [i] .pseg, 

# include  <stdio.h> 

♦include  <stdlib.h> 

‘FARDATAP [i] .pseg) ; 

♦include  <windows.h> 

TextOut(hDC,  xchar,  (i+2) ‘ychar,  buffer,  len); 

♦include  "segments. h" 

if  (FARDATAP [i] .pseg) 

♦include  "segtable.h" 

{ 

if  ( ‘FARDATAP [i] .pseg  ==  0) 

int  szAppNameLength  =  8; 

Text Out (hDC,  31*xchar,  (i+2) ‘ychar,  "Data  Free",  9); 

char  *szAppName  =  "Segments"; 

else 

char.  ‘szClocks  =  "Too  many  clocks  or  timers!"; 

( 

char  ‘szOutOfMemory  =  "Not  enough  memory."; 

len  =  sprintf (buffer,  "%.4X  %.2X",  FARDATAP [i] .oldseg, 

FARDATAP [i] .changed) ; 

♦define  MAX  VARIABLE  PSEGS  (MAXPSEGS  -  MINPSEGS  -  1) 

TextOut(hDC,  21*xchar,  (i+2) ‘ychar,  buffer,  len); 

strcpyifp  (MAKE IFP  (buffer,  fi'segDgroup) , 

typedef  struct  data  { 

MAKEIFP (0,  FARDATAP [i] .pseg) ) ; 

PSEG  pseg; 

len  =  strlenifp (MAKEIFP (buffer,  fisegDgroup) ) ; 

SEG  lastseg; 

TextOut(hDC,  31*xchar,  (i+2) ‘ychar,  buffer,  len); 

SEG  oldseg; 

) 

short  changed; 

) 

}  DATA,  FAR  *  DATAP; 

else 

TextOut (hDC,  31*xchar,  (i+2) ‘ychar,  "Free",  4); 

PSEG  psegdata; 

> 

♦define  FARDATAP  {  (DATAP) F ARP TR(0,  *psegdata)  ) 

short  xchar; 

short  ychar; 

IFP  strcpyifp (IFP  stringl,  IFP  string2) 

BOOL  random  action  =  TRUE; 

I 

int  action  count  =  0; 

char  FAR  *strl; 

HWND  hWindow; 

char  FAR  *str2; 

PSEG  allocate (LONG  size,  char  *string); 

strl  =  IFP2PTR (stringl) ; 

BOOL  reallocate (PSEG  pseg,  LONG  size,  char  *string) ; 

str2  =  IFP2PTR(string2); 

LONG  FAR  PASCAL  SegmentsWndProc (HWND,  unsigned,  WORD,  LONG); 

int  FAR  PASCAL  timer  routine (HWND  hwnd,  unsigned  message,  short  id,  LONG  time); 

while  (1) 

IFP  strcpyifp(IFP  stringl,  IFP  string2); 

{ 

int  strlenifp(IFP  string); 

*strl++  =  *str2; 

if  (*str2  ==  0) 

int  FAR  PASCAL  timer  routine (HWND  hwnd,  unsigned  message,  short  id,  LONG  time) 

break; 

I 

str2++; 

/*  Randomly  allocate/ free  a  segment  in  the  Segment  Table  or 

) 

monitor  the  Segment  Table  for  movement.  Update  the  line  in  the  window 

return (stringl) ; 

) 

that  changes. 

int  i; 

int  strlenifp (IFP  string) 

LONG  size; 

{ 

char  buffer (40]; 

char  FAR  *str; 

RECT  rect; 

int  len; 

int  random  switch; 

message; 

str  =  IFP2PTR (string) ; 

time; 

for  (len  =  0;  strflen]  !-  0;  len++) 

if  (random_action) 

return (len) ; 

if  (++action  count  <  10) 

return (0) ; 

BOOL  Segmentslnit (HANDLE  hlnstance) 

action_count  =  0; 

WNDCLASS  SegmentsClass; 

i  =  rand()  %  MAX  VARIABLE  PSEGS; 

SegmentsClass.hCursor  =  LoadCursor  (NULL,  ID'C  ARROW); 

SegmentsClass. hlcon  =  Loadlcon (hlnstance, 

size  =  (LONG) rand() ;  /*  0  <=  size  <=  32767  */ 

sprintf (buffer,  "  %d  bytes",  (short) size) ; 

MAKE I NTRE SOURCE (SEGTABLEICON) ) ; 

random_switch  =  rand(); 

SegmentsClass. IpszMenuName  =  "segmentsmenu"; 

if  (FARDATAP [i] .pseg) 

SegmentsClass. IpszClassName  =  szAppName; 

SegmentsClass . hbrBackground  -  (HBRUSH) GetStockObject (WHITE  BRUSH); 

{ 

if  (random  switch  >  2*32767/4) 

SegmentsClass .hlnstance  =  hlnstance; 

SegmentsClass. style  =  CS  HREDRAW  1  CS  VREDRAW; 

{ 

if  (FARDATAP [i] .lastseg  ==  0)  /*  if  data  is  free  */ 

SegmentsClass. lpfnWndProc  =  SegmentsWndProc; 

FARDATAP [ij .changed  =  -1;  /*  reset  the  count  */ 

if  ( ! RegisterClass ( (LPWNDCLASS) & SegmentsClass) ) 

buffer (0]  =  'R'; 

return  FALSE; 

reallocate (FARDATAP [i] .pseg,  size,  buffer); 

} 

return  TRUE; 

else  if  (random_switch  >  1*32767/4) 

1 

SegmentFree (FARDATAP [i] .pseg); 

PSEG  allocate (LONG  size,  char  ‘string) 

FARDATAP [i] .pseg  =  0; 

{ 

else  if  (*FARDATAP[i] .pseg) 

Allocate  'size'  bytes  from  the  global  heap.  Copy  a  null  terminated 

DataFree (FARDATAP [i] .pseg) ; 

'string'  into  the  allocated  memory. 

else 

*/ 

PSEG  pseg; 

buffer [0]  =  'A'; 

char  FAR  ‘farptr; 

FARDATAP ( i ] .pseg  =  allocate (size,  buffer); 

' 

FARDATAP [ij .changed  =  -1; 

if  ( ! (pseg  =  SegmentAlloc (size) ) ) 

return  NULL; 

SetRect (&rect,  9*xchar,  (i+2)*ychar,  46*xchar,  (i+3) *ychar) ; 

farptr  =  FARPTR(0,  *pseg) ; 

InvalidateRect (hwnd,  Srect,  TRUE); 

farptr [i]  =  string[i]; 

farptr [i]  =  0; 

for  (i  =  0;  i  <  MAX_VARI ABLE_P SEGS ;  i++) 

return  pseg; 

) 

if  (FARDATAP [i] .lastseg  !=  ‘FARDATAP [i] .pseg) 

BOOL  reallocate (PSEG  pseg,  LONG  size,  char  ‘string) 

FARDATAP [i] .oldseg  =  FARDATAP [i] .lastseg; 

/* 

FARDATAP [ij .lastseg  =  ‘FARDATAP [i] .pseg; 

Allocate  'size'  bytes  from  the  global  heap.  Copy  a  null  terminated  string 

FARDATAP [ij .changed++; 

'string'  into  the  allocated  memory. 

SetRect (&rect,  9*xchar,  (i+2)*ychar,  46*xchar,  (i+3) *ychar) ; 

*/ 

InvalidateRect (hwnd,  Srect,  TRUE); 

char  FAR  ‘farptr; 

) 

int  i; 

return (0) ; 

if  ( ! (SegmentRealloc (pseg,  size))) 

return  FALSE; 

void  SegmentsPaint (HDC  hDC) 

farptr  =  FARPTR (0,  *pseg) ; 

for  (i  =  0;  string[ij  &&  i  <  (int) size-1;  i++) 

char  buffer[100]; 

short  len; 

int  i; 

farptr  [i]  =  string[i]; 
farptr [i]  =  0; 

(  return  TRUE;  (continued  OH  pUgC  108) 
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Listing  One  (Listing  continued,  text  begins  on  page  58.) 

int  PASCAL  WinMain (HANDLE  hlnstance,  HANDLE  hPrevInstance,  LPSTR  IpszCmdLine, 
int  cmdShow) 

{ 

MSG  msg; 

HWND  hWnd; 
int  i; 

TEXTMETRIC  tm; 

HDC  hdc; 

FARPROC  IpprocTimer; 

DATAP  datap; 

IpszCmdLine; 

if  (! hPrevInstance) 

if  (! Segmentslnit (hlnstance) ) 
return  FALSE; 

Segment Init ( ) ; 
if  ( !  (psegdata  = 

Segment Alloc ( (DWORD) sizeof (DATA) *MAX_VARIABLE_PSEGS ) ) ) 

{ 

MessageBox (hWnd,  szOutOfMemory,  szAppName,  MB_OK) ; 
return  FALSE; 

} 

datap  =  FARPTR(0,  *psegdata) ; 

for  (i  =  0;  i  <  MAX_VARI ABLE_PSEGS ;  i++) 

( 

datap [i] . lastseg  =  0; 
datap [i] .pseg  =  0; 

} 

hdc  =  CreateIC( "DISPLAY",  NULL,  NULL,  NULL); 

GetTextMetrics (hdc,  &tm) ; 
xchar  =  tm. tmAveCharWidth; 
ychar  =  tm.tmHeight; 

DeleteDC(hdc) ; 

hWindow  =  hWnd  =  CreateWindow (szAppName,  szAppName,  WS_TILEDWINDOW,  0,0, 
46*xchar,  14*ychar,  NULL,  NULL,  hlnstance,  NULL); 

IpprocTimer  =  MakeProcInstance (timer_routine,  hlnstance); 
while  ( ISetTimer (hWnd,  1,  100,  IpprocTimer)) 

{ 

if  (IDCANCEL  ==  MessageBox (hWnd,  szClocks,  szAppName, 

MB_ I CONEXC LAMAT I ON  \  MB_RETRYCANCEL) ) 

return  FALSE; 

} 

ShowWindow (hWnd,  cmdShow); 

UpdateWindow(hWnd) ; 

while  (GetMessage (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage (&msg) ; 

DispatchMessage (&msg) ; 


return  (int) msg. wParam; 

} 

LONG  FAR  PASCAL  SegmentsWndProc (HWND  hWnd,  unsigned  message,  WORD  wParam, 


PAINTSTRUCT  ps; 

switch  (message) 

{ 

case  WM_COMMAND: 

switch  (wParam) 

{ 

case  MENU_START : 

random_action  =  TRUE; 
break;  • 
case  MENU_STOP : 

random_action  =  FALSE; 
break; 

default: 

break; 

) 

break; 

case  WM_DESTROY : 

KillTimer (hWnd,  1)  ; 

PostQuitMessage (0) ; 
break; 

case  WM_PAINT : 

BeginPaint (hWnd,  &ps); 

SegmentsPaint (ps . hdc) ; 

EndPaint (hWnd,  &ps); 
break; 

default: 

return  DefWindowProc (hWnd,  message,  wParam,  lParam) ; 
break; 

I 

return (0L) ; 

End  Listing  One 


Listing  Two 

/*  segments. h  */ 

# define  SEGTABLEICON  1 
#def ine  MENU_START  50 

•define  menu_stop  51  End  Listing  Two 


Listing  Three 

#  segment s.mak 

cp=cl  -d  -DDEBUG  -c  -W2  -DLINT_ARGS  -AM  -Gswc  -Os  -Zdpi 

.C.obj : 

S(cp)  $*.c  >$*.err 
type  $*.err 

segtable.obj:  segtable.c  segtable.h 

segments. obj:  segments. c  segments.h  segtable.h 

segments . res :  segments. rc  segments.ico  segments.h 
rc  -r  segments. rc 

segments.exe:  segments. obj  segments. res  segments. def  segtable.obj 

link4  /linenumbers/co  segments  segtable, /align:16, /map, mlibw/noe, segments. def 
mapsym  segments 
rc  segments. res 


End  Listing  Three 


Listing  Four 

/*  segment s.rc  */ 

tinclude  "segments.h" 

SEGTABLEICON  ICON  segments.ico 

segment smenu  MENU 
BEGIN 

MENUITEM  "Start!",  MENU_START 
MENU ITEM  "Stop!",  MENU_STOP 

end  End  listing  Four 


Listing  Five 

;  segments. def 

NAME  Segments 

DESCRIPTION  'Segments' 

STUB  'WINSTUB.EXE' 

CODE  MOVEABLE 

DATA  MOVEABLE  MULTIPLE 

HEAPSIZE  10000 
STACKSIZE  4096 

EXPORTS 

SegmentsWndProc  @1 

timer_routine  @2  End  Listings 
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OOP  IN  ASM 


Listing  One  (Text  begins  on  page  66.) 

page  62,  132 


;  OBJECTS. ASM  —  This  program  demonstrates  object-oriented  programming 
/  techniques  in  8086  assembly  language. 


dseg 


assembly  language, 
segment  byte  public  'data' 


/  Unsigned  Data 

Type: 

Unsigned 

struc 

Value 

dw 

0 

Get 

dd 

? 

AX  =  This 

_Put_ 

dd 

? 

This  =  AX 

Add 

dd 

7 

AX  =  AX  +  This 

Sub 

dd 

7 

AX  =  AX  -  This 

_Eq_ 

dd 

? 

Zero  flag  =  AX  ==  This 

_Lt_ 

dd 

7 

Zero  flag  =  AX  <  This 

Unsigned 

ends 

/  UVar  lets  you 

(easily)  declare 

an  unsigned  variable. 

UVar 

macro 

var 

var 

Unsigned  <, uGet, uPut, uAdd, uSub, uEq, uLt> 

endm 

;  Signed  Data  Type: 

Signed 

struc 

dw 

0 

dd 

?  ;Get  method 

dd 

7 

Put  method 

dd 

7 

Add  method 

dd 

7 

Sub  method 

dd 

? 

Eq  method 

dd 

? 

Lt  method 

Signed 

ends 

;  SVar  lets  you 

easily 

declare  a 

signed  variable. 

SVar 

macro 

var 

var 

Signed 

<,sGet,  sPut,  sAdd,  sSub,  sEq,  sLt> 

endm 

;  BCD  Data  Type 

BCD 

struc 

dw 

0  /Value 

dd 

7 

Get  method 

dd 

7 

Put  method 

dd 

7 

Add  method 

dd 

7 

Subtract  method 

dd 

? 

Eq  method 

dd 

?  ;Lt  method 

BCD 

ends 

;  BCDVar  lets  you  (easily)  declare  a  BCD  variable. 

BCDVar 

macro 

var 

var 

BCD 

<, bGet,  bPut,  bAdd,  bSub,  bEq,  bLt> 

endm 

Declare  variables  of  the  appropriate  types  (For  the  sample  pgm  below) : 
Also  declare  a  set  of  DWORD  values  which  point  at  each  of  the  variables. 
This  provides  a  simple  mechanism  for  obtaining  the  address  of  an  object. 


UVar 

ul 

UlAdr 

dd 

U1 

/Provide  convenient  address  for  Ul 

UVar 

u2 

U2Adr 

dd 

U2 

/Ditto  for  other  variables. 

SVar 

si 

SlAdr 

dd 

si 

SVar 

s2 

S2Adr 

dd 

s2 

BCDVar 

bl 

BlAdr 

dd 

bl 

BCDVar 

b2 

B2Adr 

dd 

b2 

;  Generic 

Pointer  Variables: 

Genericl 

dd 

7 

Generic2 

dd 

7 

dseg 

ends 

cseg 

segment 

byte  public 

'CODE' 

assume 

cs:cseg,  ds  :< 

dseg,  es:dseg,  ss:sseg 

_This 

equ 

es: [bx] 

/Provide  a  mnemonic  name  for  THIS. 

;  Macros  to  simplify  calling  the  various  methods 

_Get 

macro 

call 

_This._Get_ 

endm 

_Put 

macro 

call 

_This._Put_ 

endm 

_Add 

macro 

call 

_This._Add_ 

endm 

_Sub 

macro 

call 

_This._Sub_ 

endm 

_Eq 

macro 

call 

This.  Eq 

endm 

_Lt 

macro 

call 

_This ._Lt_ 

endm 

************** 

************** 

*************************************** 

;  Methods 

for  the  unsigned  data  type 

uGet 

proc 

far 

mov 

ax,  _This 

ret 

uGet 

endp 

uPut 

proc 

far 

mov 

This, ax 

ret 

uPut 

endp 

uAdd 

proc 

far 

add 

ax,  _This 

ret 

uAdd 

endp 

uSub 

proc 

far 

sub 

ax,  _This 

ret 

uSub 

endp 

uEq 

proc 

far 

cmp 

ax,  _This 

ret 

uEq 

endp 

uLt 

proc 

far 

cmp 

ax,  _This 

jb 

uIsLt 

cmp 

ax,  0 

/Force  Z  flag  to  zero. 

jne 

uLtRtn 

cmp 

ax,  1 

uLtRtn: 

ret 

uIsLt: 

cmp 

ax,  ax 

/Force  Z  flag  to  one. 

ret 

uLt 

endp 

********** 

:************* 

************* 

*************************************** 

/  Methods 

for  the  unsigned  data  type 

sPut 

equ 

uPut 

/Same  code,  why  duplicate  it? 

sGet 

equ 

uGet 

sAdd 

equ 

uAdd 

sSub 

equ 

uSub 

sEq 

equ 

uEq 

sLt 

proc 

far 

cmp 

ax,  _This 

jl 

sIsLt 

cmp 

ax,  0 

/Force  Z  flag  to  zero. 

jne 

sLtRtn 

cmp 

ax,  1 

sLtRtn: 

ret 

sIsLt : 

cmp 

ax,  ax 

/Force  Z  flag  to  one. 

ret 

sLt 

endp 

;  ********* 

*************1 

************** 

*************************************** 

;  Methods 

for  the  BCD -data  type 

bGet 

equ 

uGet 

/Same  code,  don't  duplicate  it. 

bPut 

equ 

uPut 

bEq 

equ 

uEq 

bLt 

equ 

uLt 

bAdd 

proc 

far 

add 

ax,  _This 

da  a 

ret 

bAdd 

endp 

bSub 

proc 

far 

sub 

ax,  This 

das 

ret 

bSub 

endp 

************** 

:************************************** 

no 
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;  Test  code 

for  this 

program: 

TestSample 

proc 

near 

push 

ax 

push 

bx 

push 

es 

Compute  "Genericl  = 

=  Genericl  +  Generic2;" 

les 

bx,  Genericl 

_Get 

les 

bx,  Generic2 

_Add 

les 

bx,  Genericl 

_Put 

pop 

es 

pop 

bx 

pop 

ax 

ret 

TestSample 

endp 

;  Main  driver  program 

MainPgm 

proc 

far 

mov 

ax,  dseg 

mov 

ds,  ax 

;  Initialize 

the  objects: 

;  ul  =  39876 

.  Also  initialize  Genericl  to  point  at  ul  for 

les 

bx,  UlAdr 

mov 

ax,  39876 

_Put 

mov 

word  ptr  Genericl,  bx 

mov 

word  ptr  Genericl+2,  es 

;  u2  =  45677 

.  Also  point  Generic2  at  u2  for  later  use. 

les 

bx,  U2Adr 

mov 

ax,  45677 

_Put 

mov 

word  ptr  Generic2,  bx 

mov 

word  ptr  Generic2+2,  es 

;  si  =  -5. 

les 

bx,  SlAdr 

mov 

ax,  -5 

_Put 

;  s2  =  12345 

les 

bx,  S2Adr 

mov 

ax,  12345 

_Put 

?  bl  =  2899. 

les 

bx,  BlAdr 

mov 

ax,  2899h 

_Put 

;  b2  =  195. 

les 

bx,  B2Adr 

mov 

ax,  195h 

Put 

;  Call  TestSample  to 

add  ul  &  u2. 

call 

TestSample 

;  Call  TestSample  to 

add  si  &  s2. 

les 

bx,  SlAdr 

mov 

word  ptr  Genericl,  bx 

mov 

word  ptr  Genericl+2,  es 

les 

bx,  S2Adr 

mov 

word  ptr  Generic2,  bx 

mov 

word  ptr  Generic2+2,  es 

call 

TestSample 

;  Call  TestSample  to 

add  bl  &  b2 . 

les 

bx,  BlAdr 

mov 

word  ptr  Genericl,  bx 

mov 

word  ptr  Genericl+2,  es 

les 

bx,  B2Adr 

mov 

word  ptr  Generic2,  bx 

mov 

word  ptr  Generic2+2,  es 

call 

TestSample 

mov 

ah,  4ch  /Terminate 

int 

21h 

MainPgm 

endp 

cseg 

ends 

sseg 

segment  byte  stack  'stack' 

stk 

dw 

OfOh  dup  (?) 

endstk 

dw 

? 

sseg 

ends 

end 

MainPgm 

End  Listing 
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E  X  A  M  I  N  1  N  G  ROOM 


Listing  One  (Text  begins  on  page  74.) 

Listing  Three 

$  PRIMES. SET 

$  ISETL  program  to  find  number  of  primes  <=  n,  using  set  notation 

$  FIB. TUP 

$  ISETL  program  to  find  Fibonacci  numbers,  using  dynamic  programming 

size  :=  1000  ; 

sqrt_size  :=  fix (sqrt (size) )  ; 

composites  :=  (i*j  !  i  in  {3, 5.. sqrt  size),  j  in  |i..size  div  i})  ; 
primes  :=  {2}  +  {3, 5.. size)  -  composites  ; 
print  size  ; 
print  fprimes  ; 

$  uses  log():  only  accurate  up  to  308  digits 
digits  :=  func(x); 

if  (x  =  0)  then  return  1  ; 

else  return  1  +  floor (log (abs (x) ) )  ; 

end; 

end; 

$  use  "dynamic  programming"  to  assign  to  fib ( ) 
fib  :=  func (x) ; 

fib(x)  :=  fib(x-l)  +  fib(x-2)  ; 
return  fib(x)  ; 

end; 

End  Listing  One 

fib (0)  :=  1  ; 
fib  (1)  :=  1  ; 

fibonacci  :=  [fib(x)  :  x  in  [1  ..  1000  ]  ]  ; 

print  fibonacci (1000)  ; 

print  digits (fibonacci (1000) )  ; 

Listing  Two 

$  PRIMES. TUP 

$  ISETL  program  to  find  number  of  primes  <=  n,  using  ordered  tuples 

$  tuple  difference  operator 
dif f  :=  func (tl,  t2) ; 

return  [i  :  i  in  tl  !  i  notin  t2  )  ; 

end; 

size  :=  1000  ; 

sqrt  size  :=  fix (sqrt (size) )  ; 

composites  :=  [i*j  :  i  in  (3, 5. .sqrt_size] ,  j  in  [i..size  div  i ] ]  ; 
primes  :=  [2]  +  (3, 5.. size]  .diff  composites  ; 
print  size  ; 
print  #primes  ; 

End  Listings 

End  Listing  Two 

Dr.  Dobb’s  Journal,  March  1990 


115 

259 


P  R  0  G  R  AMMER'S  WORKBENCH 


Listing  One  (Text  begins  on  page  84.) 

/*  Module  description  *  This  module  takes  care  of  error  trapping.  The  scheme 
;used  records  the  trapping  routine  stack  pointer  so  that  an  error  can  cause 
;the  stack  to  return  to  a  consistent  state.  This  module  was  written  using 
/Borland's  Turbo  Assembler  2.0. 

;**  Environment  ** 

.model  small  ;Set  up  for  SMALL  model, 
locals  ; Enable  local  symbols. 

;**  Macros  ** 

;«Generate  correct  return  based  on  model» 
procret  macro 
if  @codesize 
retf 

else 

retn 

endif 

endm 

/**  Public  operations  ** 

public  pascal  ERROR_INIT  ; Initialize  error  handler, 

public  pascal  ERROR_TRAP  ;Set  up  error  trap, 

public  pascal  ERROR_LOG  ;Log  error. 

;**  Uninitialized  data  ** 

.data? 

errstk  dw  ?  ;SP  at  last  error  log  (-1  if  none). 

;**  Code  ** 

.code 

;Set  up  DS  to  nothing  since  that  is  the  typical  arrangement, 
assume  ds: nothing 

;  [Initialize  error  manager] 

error_init  proc  pascal  /Declare  proc  with  PASCAL  calling  conventions, 

mov  errstk, -1 
ret 

endp 

; [Set  up  error  trap] 

/This  procedure  preserves  the  previous  ERRSTK,  sets  up  a  new  ERRSTK,  and 
/calls  the  passed  procedure.  On  exit,  the  previous  ERRSTK  is  restored. 
error_trap  proc  pascal  /Pascal  calling  conventions, 

arg  @@proc:codeptr  /Only  argument  is  procedure  to  call, 

uses  ds,si,es,di  /Force  a  save  of  all  registers  C  cares  for. 

push  errstk 

/Call  internal  routine  to  record  return  address  on  stack, 
call  @@rtn 
pop  errstk 
ret 

@@rtn  label  proc 

mov  errstk, sp  /Save  SP  so  we  can  restore  it  later, 

call  @@proc  pascal  /Call  procedure. 

xor  ax, ax  /Return  code  =  0  for  normal  return, 

procret 

endp 

/ [Log  error] 

/Control  is  passed  to  the  last  ERROR_TRAP,  if  any. 

/Error  code  is  passed  and  returned  in  AX. 
error_log  proc  pascal 
arg  @@error_code: word 

cmp  errstk, -1  /Lock  up  if  no  error  address. 

@@1:  jz  @ @ 1 

mov  ax, @@error_code 
mov  sp, errstk 
procret 

endp 

end 

End  Listing  One 


Listing  Two 

/*  Module  description  *  This  module  manages  a  simple  stack-based  heap. 
/Deallocation  is  not  supported.  NOTE:  This  module  must  be  assembled  with  /MX 
/to  publish  symbols  in  the  correct  case.  This  module  is  written  using 
/Borland's  Turbo  Assembler  2.0. 

/**  Environment  ** 

.model  small  /Set  up  for  SMALL  model, 
locals  /Enable  local  symbols. 

/**  Equates  ** 

err_memory  =  1  /Out  of  memory  error  number. 

;**  public  operations  ** 

public  pascal  HEAP_INIT  /Initialize  heap. 

public  pascal  HEAP_ALLOC  /Allocate  memory  from  heap. 

/**  External  operations  ** 

/<<Error  handler» 

extrn  pascal  ERROR_LOG : proc  /Long  jump  library  procedure  for  errors. 

/**  Uninitialized  data  ** 

.data? 

memptr  dw  ?  /Pointer  to  first  free  segment, 
memsiz  dw  ?  /Remaining  paragraphs  in  heap. 

/**  Code  ** 

.code 

/Set  up  DS  to  nothing  since  that  is  the  typical  arrangement, 
assume  ds: nothing 

/ [Initialize  the  heap] 

heap_init  proc  pascal  /Declare  proc  with  PASCAL  calling  conventions, 
arg  @@start_seg: word, @@para_size : word 


/Arguments  are  starting  segment  and  para  count, 
mov  ax, @@start_seg 
mov  memptr, ax 
mov  ax, @@para_size 
mov  memsiz, ax 
ret 

heap_init  endp 

/ [Allocate  memory  from  the  heap] 

heap_alloc  proc  pascal  /Declare  proc  with  PASCAL  calling  conventions. 

arg  @@para_count :word  /Only  argument’  is  count  of  paragraphs. 

/See  if  there  is  enough  remaining. 

mov  ax, @@para_count 

cmp  memsiz, ax 

jc  @@err 

sub  memsiz, ax 

add  ax, memptr 

xchg  ax, memptr 

mov  dx, ax 

xor  ax, ax 

ret 

@@err:  /Out -of -memory  error, 
mov  ax, err_memory 
call  error_log  pascal, ax 
/Never  returns. 

heap_alloc  endp 

end  End  Listing  Two 


Listing  Three 

/*  Module  description  *  This  module  reads  source  files  and  converts  them  into 
/words,  then  files  the  words  away  in  a  symbol  table  with  the  help  of  a  hash 
/function.  This  module  was  written  using  Borland's  Turbo  Assembler  2.0. 

/**  Environment  ** 

.model  small  /Set  up  for  SMALL  model, 

locals  /Enable  local  symbols. 

/**  Equates  ** 

/«Error  numbers» 

err_hash  =  2  /Out  of  hash  space  error  number. 
err_read  =  3  /Read  error. 

/«Hash  function» 

hash_rotate  =  5  /Amount  to  rotate  for  hash  function. 

hash_skip  =  11/Number  of  entries  to  skip  on  hash  collision. 

/«Read  buffer» 

rbf_size  =  800h  /Size  of  read  buffer  in  paragraphs. 

/**  Public  operations  ** 

public  pascal  WORD_INIT  /Initialize  hash  table. 

public  pascal  WORD_READ  /Read  file,  convert  to  words,  and  hash  them. 

public  pascal  WORD_COUNT  /Get  total  word  count. 

public  pascal  WORD_NAME  /Get  name  of  word. 

public  pascal  WORD_REFCOUNT  /Get  reference  count  of  word. 

public  pascal  WORD_SCAN  /Scan  all  words. 

public  pascal  WORD_COMPREF  /Compare  word  reference  counts. 

/**  External  operations  ** 

/«Heap» 

extrn  pascal  HEAP_ALLOC:proc  /Heap  allocation. 

/«Error  handling» 

extrn  pascal  ERROR_LOG:proc  /Trap  an  error. 

/**  Data  structure  ** 

/«Symbol  table  entry» 
symtbl  st rue 

symref  dw  ?  /Reference  count, 
symsiz  dw  ?  /Length  of  word, 
ends 

symnam  =  size  symtbl  /Offset  of  start  of  name  text. 

/**  Initialized  data  ** 

.data 

/«Translation  character  type  table» 
typdlm  =  1  /Delimiter  bit. 
typnum  =  2  /Numerical  digit. 

typeas  =  20h  /Lower  case  bit:  Set  if  lower  case  letter, 
xlttbl  label  byte 

db  '0'  dup  (typdlm) 
db  10  dup  (typnum) 
db  ( ' A' — 1 ) — ' 9'  dup  (typdlm) 
db  'Z'-('A'-l)  dup  (0) 
db  ('a'-l)-'Z'  dup  (typdlm) 
db  'z'-('a'-l)  dup  (typeas) 
db  255-' z'  dup  (typdlm) 

/**  Uninitialized  data  ** 

.data? 

/«Hash  table  values» 

hshptr  dw  ?  /Segment  address  of  hash  table. 

hshsiz  dw  ?  /Totai  number  of  hash  entries.  Must  be  a  power  of  2! 

hshent  dw  ?  /Total  free  entries  remaining  in  hash  table, 

hshmsk  dw  ?  /Mask  for  converting  hash  value  to  address. 

/«Read  buffer  values» 

rbfptr  dw  ?  /Segment  address  of  read  buffer. 

/«Word  buffer» 
wrdbuf  db  256  dup  (?) 

/**  Code  ** 

.  code 

/Set  up  DS  to  nothing  since  that  is  the  typical  arrangement, 
assume  ds: nothing 

/[Initialize  hash  table]  (LiStiYIQ  COTltiflUGCi  Otl  pd^6  118) 
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PROGRAMMER'S  WORKBENCH 


Listing  Three  (Listing  continued,  text  begins  on  page  84.) 


word_init  proc  pascal 

arg  @@max_word_count:word  /Argument:  Maximum  number  of  words, 

uses  es,di 

/First,  allocate  read  buffer, 
mov  ax,  rbf_size 
call  heap_alloc  pascal) ax 
mov  rbfptr,dx 

/Now  convert  maximum  word  count  to  power  of  2. 
mov  ax, @@max_word_count 
mov  cl, 16+1 
@011:  dec  cl 

shl  ax, 1 
jnc  @011 
mov  ax, 1 
shl  ax, cl 

/Initialize  some  hash  parameters. 

mov  hshsiz,ax 

mov  hshcnt,ax 

dec  ax 

shl  ax, 1 

mov  hshmsk,ax 

/Now,  allocate  hash  table  from  heap. 

mov  ax,hshsiz  /Size  of  hash  table  in  words. 

add  ax, 7 

mov  cl, 3 

shr  ax, cl  /Convert  to  paragraphs, 

call  heap_alloc  pascal, ax 
mov  hshptr,dx 

/Clear  out  hash  table:  0  means  'no  value', 
mov  es,dx 
xor  di,di 
cld 

mov  cx,hshsiz 
xor  ax, ax 
rep  stosw 
ret 

word_init  endp 

/ (Read  file  and  assimilate  all  words] 
word_read  proc  pascal 

arg  @@handle:word  /Argument  is  file  handle, 

uses  ds,si,es,di 

/Load  XLAT  buffer  address.  The  XLAT  table  is  used  for  case  conversion 
/and  for  character  type  identification, 
mov  bx, offset  xlttbl 

@@read:  /Read  next  buffer  while  delimiter  processing, 
call  @@brd 
jcxz  @@done 

@@skip:  /Skip  all  delimeters,  etc. 
lodsb 

xlat  xlttbl 
test  al,typdlm 
loopnz  @@skip 
jnz  @@read 

/Adjust  pointer  &  count, 
dec  si 
inc  cx 

/If  it  is  a  number,  skip  to  end. 
test  al,typnum 
jnz  0@num 

/It  is  a  word.  We'll  transfer  a  word  at  a  time  to  the  word  buffer, 
/hashing  it  as  we  go.  DX  will  be  the  current  hash  value.  CX  is  the 
/amount  remaining  in  the  buffer, 
xor  dx,dx 

/Initialize  output  address, 
push  ss 
pop  es 

mov  di, offset  wrdbuf 

0@clp:  /Transfer.  This  is  THE  most  time-critical  loop  in  the  program, 
lodsb  /Read  character, 

mov  ah,al 

xlat  xlttbl  /Get  its  type, 

test  al,typdim  /Abort  if  delimiter, 

jnz  @@wend 

and  al,typcas  /Use  case  bit  to  convert  to  upper  case, 

neg  al 
add  al,ah 

stosb  /Save  it  in  word  buffer. 

/Calculate  hash  value, 
mov  ah, cl 

mov  cl, hash_rotate 
rol  dx,cl 
mov  cl, ah 
xor  dl,al 

loop  0@clp  /Keep  going  until  end  of  buffer. 

/End  of  buffer  while  word  processing.  Read  more, 
call  @@brd 
jcxz  @0wnd2 
jmp  @@clp 

@@nrd:  /Read  next  buffer  while  number  processing, 
call  0@brd 
jcxz  @@done 

@@num:  /Numbers  are  not  considered  'words'  and  should  be  skipped. 

/Skip  up  to  first  delimiter, 
lodsb 

xlat  xlttbl 
test  al,typdlm 
loopz  @@num 
jz  @@nrd 

/Adjust  pointer  and  count, 
dec  si 
inc  cx 
jmp  @@skip 
@@done:  ret 

@@wend:  /End  of  word.  Adjust  buffer  pointer, 
dec  si 

0@wnd2:  /End  of  word.  Hash  value  is  in  DX,  upper-case  word  is  in  WRDBUF, 

/DI  points  to  end  of  word  +  1. 

push  ds  si  cx  bx  /Save  the  registers  we  will  use  for  this  step. 


xor  al,al  /Null-terminate  the  word, 

stosb 

mov  cx,di  /Calculate  the  word's  length, 

sub  cx, offset  wrdbuf 

mov  bx,dx  /Put  the  hash  value  in  a  useable  register, 

shl  bx,l  /Lower  bit  will  be  discarded,  so  shift, 

push  ss  /Initialize  DS. 

pop  ds 

assume  ds:dgroup 

/Now  it  is  time  to  locate  the  word  in  the  hash  table  if  it  is  there, 

/or  create  an  entry  if  it  is  not. 

mov  es,hshptr 

and  bx,hshmsk 

mov  ax, es : [bx] 

and  ax, ax 

jz  @@make 

/Verify  that  the  hash  entry  is  the  correct  one. 
mov  es,ax 
mov  ax,cx 

cmp  es: [symsiz] ,ax  /Compare  length  of  word, 

jnz  @0coll 

mov  si, offset  wrdbuf  /Compare  actual  text  if  that  agrees. 

mov  di,symnam 

repz  cmpsb 

mov  cx, ax 

jz  @@fd 

:  /Collision!  Advance  to  the  next  candidate  hash  entry, 
add  bx, hash_skip*2 
jmp  @@hlp 
ret 

;We  have  encountered  this  word  for  the  first  time. 

; We  must  create  a  new  symbol  entry  of  the  appropriate  size. 

/First  decrement  remaining  free  hash  count. 

dec  hshcnt 

jz  @0herr 

push  cx 

push  bx 

mov  ax,cx  /Calculate  length  of  symbol  descriptor, 

add  ax,symnam+15 
mov  cl, 4 
shr  ax, cl 

call  heap_alloc  pascal, ax 


/Compare  length  of  word. 

/Compare  actual  text  if  that  agrees. 


/Move  text  of  word  into  symbol  table. 


/Clear  reference  count. 
Increment  reference  count. 


/Read  character. 


/Get  its  type. 

/Abort  if  delimiter. 


/Use  case  bit  to  convert  to  upper  case. 


/Save  it  in  word  buffer. 


pop  bx  /Record  symbol  descriptor  in  hash  table, 

moy  es: [bx] ,dx 

pop  cx  /Record  length, 

mov  es,dx 
mov  es: [symsiz] , cx 

mov  di,symnam  /Move  text  of  word  into  symbol  tab] 

mov  si, offset  wrdbuf 
shr  cx,  1 
rep  movsw 
rcl  cx,l 
rep  movsb 

mov  es : [symref ] , 0  /Clear  reference  count. 

@@fd:  /Matching  entry  found!  Increment  reference  count, 

inc  es: (symref] 

@@nwd:  /Go  on  to  the  next  word  in  the  buffer,  if  any. 
pop  bx  cx  si  ds 
assume  ds: nothing 
jcxz  @0dne2 
jmp  @@skip 

@@herr:  /Out  of  hash  space  error, 
mov  ax,err_hash 
call  error_log  pascal, ax 
/No  return  from  ERROR_LOG. 

/  (Read  buffer) 

/Reads  the  next  hunk  of  buffer.  Returns  actual  amount  read  in  CX, 

/DS:SI  as  start  of  data  to  read. 

@@brd:  push  dx  bx 

mov  cx, rbf_size*16 
mov  bx,@@handle 
mov  ah, 3fh 
mov  ds,rbfptr 
xor  dx,dx 
int  21h 
jc  @@err 
mov  cx,ax 
xor  si, si 
pop  bx  dx 
cld 

retn  /Use  RETN  so  stack  frame  return  won't  be  ge 

@@err:  /Read  error. 

mov  ax,err_read 
call  error_log  pascal, ax 

/No  return  is  needed  because  ERROR_LOG  never  returns. 
word_read  endp 

/[Get  total  word  count] 
word_count  proc  pascal 

mov  ax,hshsiz  /Load  total  word  capacity, 

sub  ax, hshcnt  /Subtract  actual  remaining  free  wor 

ret 

word_count  endp 

/ [Get  address  of  name  of  word] 
word_name  proc  pascal 

arg  @@word_desc:word  /Argument  is  word  descriptor, 

mov  dx, @@word_desc 
mov  ax,symnam 
ret 

word_name  endp 

/ [Get  refcount  for  word] 
word_refcount  proc  pascal 

arg  @@word_desc:word  /Argument  is  word  descriptor, 

uses  ds 

mov  ds, @@word_desc 
mov  ax, ds: [symref ] 
ret 

word_refcount  endp 


/Use  RETN  so  stack  frame  return  won't  be  generated. 


/Load  total  word  capacity. 

/Subtract  actual  remaining  free  words. 


/Argument  is  word  descriptor. 


/Argument  is  word  descriptor. 
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/Argument  is  procedure  to  call  for  each  word. 


; [Scan  all  words] 
word_scan  proc  pascal 
arg  @@scan_proc:codeptr 
uses  ds,si 

mov  ds,hshptr 
xor  si, si 
mov  cx,hshsiz 
cld 

@011:  lodsw 

and  ax, ax 
jnz  @@take 
@@next:  loop  @011 
ret 

@@take:  push  cx  ds 
push  ss 
pop  ds 

call  @@scan_proc  pascal, ax 

pop  ds  cx 

cld 

jmp  @@next 
word_scan  endp 

; [Compare  reference  counts  for  two  word  descriptors] 

word_compref  proc  pascal 

arg  @@word_descl :word, @@word_desc2 :word 

uses  ds 

mov  ds, 0@word_desc2 
mov  ax, ds: [symref] 
mov  ds, @@word_descl 
sub  ax, ds: [symref] 
ret 

word_compref  endp 
end 


End  Listing  Three 


Listing  Four 

;*  Module  description  *  This  module  contains  the  sort  routine  for  SPECTRUM. 

;This  module  was  written  using  Borland's  Turbo  Assembler  2.0. 

/**  Environment  ** 

.model  small  ;Set  up  for  SMALL  model, 

locals  /Enable  local  symbols. 

;**  Public  operations  ** 

public  pascal  SORT_DO  /Perform  sort. 

/**  Code  ** 

.code 

/Set  up  DS  to  nothing  since  that  is  the  typical  arrangement, 
assume  ds: nothing 

/  [Sort  procedure] 
sort_do  proc  pascal 

arg  @@array :dword, @@count :word, @@compare_proc:codeptr 
uses  ds,si,di 

/First  load  up  registers  for  internal  recursion.  DS:SI  will  be 
/the  current  sort  array  address,  CX  the  count  of  elements  to  sort. 

Ids  si,@@array 
mov  cx,@@count 
call  @@sort 
ret 

/Internally  recursive  sort  routine.  This  routine  accepts  DS:SI  as  the  sort 
/array  address,  and  CX  as  the  count  of  elements  to  sort. 

@@sort:  cmp  cx,2 
jnc  @@go 
retn 

@@go:  /Save  all  registers  we  will  change. 

/Internally,  DI  and  DX  will  be  start  and  count  of  second  merge  area, 
push  si  cx  di  dx 

/Divide  into  two  parts  and  sort  each  one. 

mov  dx,cx 

shr  cx, 1 

sub  dx,cx 

call  @@sort 

mov  di, si 

add  di , cx 

add  di,cx 

xchg  si,di 

xchg  cx,dx 

call  @@sort 

xchg  cx,dx 

xchg  si,di 

/Now,  merge  the  two  areas  in  place. 

/Each  area  must  be  at  least  size  1. 

@@mrgl:  /Compare  -  DS:DI  -  DS:SI. 

call  @@compare_proc  pascal, ds : [di] ,ds: [si] 

//The  following  commented-out  sequence  is  the  code  that  would  be  required 
//if  strict  Pascal  calling  conventions  were  adhered  to  for  calling 
// COMP ARE_P ROC .  You  can  see  how  much  extra  work  this  is!! 

/  /  push  cx  dx 

/  /  push  ds 

/  /  mov  ax ,  ds :  [  di  ] 

/ /  mov  bx,ds: [si] 

/  /  push  ss 

ZZ  pop  ds 

//  call  @@compare_proc  pascal, ax, bx 

/  /  pop  ds 

/  /  pop  dx  cx 

//  and  ax, ax 

jns  @@ok 

/Slide  up  first  merge  area  using  starting  value  from  DI. 
mov  ax,ds: [di] 

(Listing  continued  on  page  120) 
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Listing  Four  (Listing  continued,  text  begins  on  page  84.) 

push  si  cx 

@@sllp:  xchg  ax,ds:[si] 
add  si, 2 
loop  @@sllp 
xchg  ax,ds: [si] 
pop  cx  si 
add  si, 2 
add  di,2 
dec  dx 
jnz  @@mrgl 
jmp  short  @@exi 

@@ok:  /Correct  so  far.  Advance  SI. 

add  si, 2 
loop  @@mrgl 

@@exi:  /Restore  registers, 
pop  dx  di  cx  si 
retn 

sort_do  endp 

end 

End  Listing  Four 


Listing  Five 

/****•  File:  SPECTRUM. C  ***•*/ 

/*  This  C  module  is  written  using  Borland's  Turbo  C  2.0  and  can  be 

compiled  using  the  default  switches.  It  should  be  linked  with  the  file 
WILDARGS . OBJ  from  the  Turbo  C  examples  directory  to  enable  the  wild  card 
file  name  expansion  facility.  Without  WILDARGS,  SPECTRUM  will  still  work 
but  will  not  be  capable  of  expanding  file  names  with  wild  cards. 

The  following  is  an  example  make  file,  where  TA  is  the  assembler  name,  TCC 
is  the  C  compiler  name,  TLINK  is  the  linker  name,  \TC\LIB  contains  the  C 
libraries,  and  \TC\EXA  contains  the  Turbo  C  examples: 

spectrum.exe:  spectrum. obj  heap.obj  word.obj  error. obj  sort.obj 

tlink  \tc\lib\cOs+\tc\exa\wildargs+spectrum+heap+word+error+sort, spectrum, , 

\tc\lib\cs.lib; 
heap.obj:  heap. asm 
ta  heap  /mx/ 
word.obj:  word. asm 
ta  word  /mx/ 
error. obj:  error. asm 
ta  error  /mx/ 
sort.obj:  sort. asm 
ta  sort  /mx; 

spectrum. obj :  spectrum. c 
tcc  -c  spectrum 

*/ 

/***  Header  Files  ***/ 

♦include  <dos.h> 

♦include  <stdio.h> 

♦include  <fcntl.h> 

/***  Function  Protypes  ***/ 

/*  Used  Locally  */ 

int  allocmem(  unsigned,  unsigned  *  )/ 
int  freemem  (  unsigned  )/ 
int  _open(  const  char  *,  int  oflags  )/ 
int  _close (  int  ) ; 

/*  Error  trapper  */ 

extern  void  pascal  error_init  (void) / 

extern  unsigned  pascal  error_trap  (void  pascal  (*execution_procedure) ()  )/ 
extern  void  pascal  error_log  (unsigned  error_code)/ 

/*  Heap  */ 

extern  void  pascal  heap_init  (unsigned  starting_segment, 

unsigned  segment_count) / 

extern  void  far  *  pascal  heap_alloc  (unsigned  paragraph_count) / 

/*  Symbol  table  */ 

extern  void  pascal  word_init  (unsigned  maximum_word_count) / 
extern  void  pascal  word_read  (unsigned  file_handle) / 
extern  void  pascal  word_scan  (void  pascal  (*word_procedure) ()  )/ 
extern  char  far  *  pascal  word_name  (unsigned  word_descriptor) / 
extern  unsigned  pascal  word_refcount  (unsigned  word_descriptor) / 
extern  unsigned  pascal  word_count  (void) / 

extern  int  pascal  word_compref  (unsigned  word_descl,  unsigned  word_desc2)z 
/*  Sorting  procedure  */ 

extern  void  pascal  sort_do  (unsigned  far  *sort_array,  unsigned  sort_count, 
int  pascal  (*compare_procedure) ()  )/ 

/***  Global  Variables  ***/ 

/*  Error  table  */ 

char  *  error_table  []  =  { 

"Insufficient  Memory\n", 

"Out  of  Hash  Space\n", 

"File  Read  ErrorXn", 

"Usage:  SPECTRUM  filespec  [filespec]  ...  [filespec] \n (filespec  may  have  ?,*)\n" 
}  ; 

/*  Arguments  */ 
int  global_argc/ 
char  **global_argv/ 

/*  Memory  */ 

unsigned  segment_count; 

unsigned  starting_segmentz 

/*  Sort  array  */ 
unsigned  sort_index; 
unsigned  far  *sort_array; 

/****  Procedures  ****/ 

/*  Fill  sort  array  with  descriptors  */ 
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void  pascal  array_f ill (unsigned  word_desc) 

{ 

sort_array [sort_index++]  =  word  desc; 

} 

/*  Main  execution  procedure  */ 
void  pascal  main2  (void) 

{ 

int  i; 
unsigned  j; 
int  words  =  0; 
int  file_handle; 
if {  global_argc  <  2  )  ( 
error_log(4) ; 

} 

heap_init  (starting_segment,  segment_count) ; 

word_init  (32767); 

for(  i=l  ;  i<global_argc  ;  i++  )  { 

file_handle  =  _open  (global_argv[iJ ,  0_RD0NLY) ; 
if  (file_handle  !=  -1  )  { 
word_read(  file_handle) ; 

_close (  f ile_handle  ) ; 

)  else  ( 
error_log (3) ; 


/*  Obtain  array  address  */ 

sort_array  =  (unsigned  far  *) heap_alloc ( (word_count () +7) / 8 ) ; 
/*  Fill  array  */ 
sort_index  =  0; 
word_scan (array  fill); 

/*  Sort  array  *7 
printf  ("Sorting. .. \n") ; 

sort_do  (sort_array,  sort_index,  word_compref ) ; 

/*  Display  output  */ 
printf  ("\nCount\tWord\n") ; 

printf  (" - \t - \n")  ; 

for  (i=0  ;  i<sort_index-l  ;  i++)  ( 
j  =  word_ref count (sort_array [i] ) ; 
words  =  words  +  j; 
pirintf  ("%d",j); 
printf  ("Xt"); 

printf  ("%Fs",word_name(sort_array[i] ) ) ; 
printf  ("\n"); 

} 

printf  ("\nTotal  unique  words : \t%d\n", sort_index) ; 
printf  ("Total  words:\t\t%d\n", words); 


/*  Main  procedure  */ 

int  main(  int  argc,  char  *argv[]  ) 

( 

int  i; 

/*  Copy  arguments  */ 
global_argc  =  argc; 
global_argv  =  argv; 
error_init () ; 

segment_count  =  allocmem( 65535, &starting_segment) ; 
allocmem(  segment_count,  &starting_segment  ); 
i  =  error_trap  (  main2  ); 
if  (i  ! =  0)  { 

/*  Print  error  message  */ 
printf  (error_table(i-l] ) ; 

} 

freemem  (starting_segment) ; 
return  (i) ; 

1  End  Listing  Five 


Listing  Six 

spectrum.exe:  spectrum. obj  heap.obj  word.obj  error. obj  sort.obj 

tlink  /v  \tc\lib\cOs+\tc\exa\wildargs+spectrum+heap+word+error+sort, 

spectrum, , \tc\lib\cs . lib; 
heap.obj:  heap. asm 

ta  heap  /mx  / zi 
word.obj:  word. asm 

ta  word  /mx  /zi 
error. obj:  error. asm 

ta  error  /mx  /zi 
sort.obj:  sort. asm 

ta  sort  /mx  /zi 
spectrum. ob j :  spectrum. c 

tcc  -c  -v  spectrum 


End  Listings 
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Getting  CLOS 


What  makes  Lisp  relevant  today 
is  that  it  is  converging,  in  terms 
of  features  and  performance, 
with  other  development  envi¬ 
ronments  for  large  software  projects. 
When  Guy  Steele  published  Common 
Lisp:  The  Language  (Digital  Press,  1984), 
he  codified  what  quickly  became  the 
de  facto  standard  for  Lisp;  now  the 
ANSI  subcommittee  X3J13  has  nearly 
completed  a  draft  standard  for  Com¬ 
mon  Lisp  that  includes  the  Common 
Lisp  Object  System  (CLOS),  an  object- 
oriented  extension  to  the  language.  I 
had  this  column  half  written  when  the 
second  edition  of  Steele’s  book  arrived, 
containing  much  new  material,  includ¬ 
ing  an  entirely  new  chapter  on  CLOS. 
It  forced  me  to  go  back  and  rewrite 
several  things;  this  column  also  cor¬ 
rects  some  things  I  said  last  month  that 
are  now  out  of  date.  Steele’s  treatment 
of  CLOS  is  essentially  the  ANSI  com¬ 
mittee’s  treatment,  and  should  be  very 
close  to  the  final  draft  standard,  due 
out  this  year. 

This  convergence,  though,  is  turning 
Lisp  into  something  new.  At  last  year’s 
OOPSLA  meeting,  Bjarne  Stroustrup 
summed  up  CLOS  by  calling  it  a  multi¬ 
paradigm  language.  The  circumstances 
(the  developer  of  C++  being  asked  to 
deliver  a  lecture  on  the  virtues  of  CLOS) 
left  it  unclear  whether  he  meant  it  as  a 
term  of  opprobrium  or  as  a  compliment. 


Michael  Swaine 


This  column’s  beat  is  paradigms,  and 
it  seemed  worthwhile  to  take  a  look  at 
how  one  paradigm  (functional  program¬ 
ming)  is  extended  to  another  (object- 
oriented  programming).  In  January  we 
looked  at  “pure”  Lisp;  in  February  we 
saw  how  this  pure  functional  paradigm 
has  evolved  with  the  widespread  ac¬ 
ceptance  of  Common  Lisp,  and  this 
month  we’ll  take  a  look  at  the  objectifi¬ 


cation  of  Lisp  in  the  form  of  the  Com¬ 
mon  Lisp  Object  System.  Well  exam¬ 
ine  two  themes:  How  the  Common 
Lisp  data-type  system  underlies  the 
CLOS  class  system,  and  how  the  basic 
concept  of  a  function,  a  key  aspect  of 
Common  Lisp  as  well  as  of  “pure”  Lisp, 
has  been  extended  to  the  object  world. 

Typing  Tutor 

Some  of  the  things  I  said  last  month 
have  been  superseded  by  the  new  edi¬ 
tion  of  Steele’s  book,  and  this  edition 
makes  some  things  more  official  than 
they  were  previously.  Because  of  these 
things  and  also  because  CLOS  classes 
map  into  the  Common  Lisp  hierarchy, 
I’ll  spell  out  the  Common  Lisp  data 
type  relationships  in  some  detail. 

To  begin  with,  it’s  not  really  a  hierar¬ 
chy,  but  an  overlapping  structure  that 
Rosemary  Simpson,  in  her  Common 
Lisp:  The  Index  (Coral  Software  and 
Franz,  Inc.,  1987)  calls  a  “heterarchy.” 
Two  types  stand  at  the  very  top  and 
bottom  of  the  Common  Lisp  data  type 
heterarchy,  t  is  a  supertype  of  every 
other  type,  and  nil  is  a  subtype  of  every 
other  type.  No  object  is  of  type  nil. 
Every  object  is  of  type  t. 

The  following  subtypes  of  type  t  are 
of  interest  because  X3J13  has  defined 
them  to  be  pairwise  disjoint:  character, 
number,  symbol,  cons,  array,  random- 
state,  hash-table,  read-table,  package, 
pathname,  and  stream.  A  Common  Lisp 
object  cannot  belong  to  more  than  one 
of  these  types,  although  it  need  not 
belong  to  any  of  them. 

In  addition  to  these  types,  any  data 
type  created  by  the  def  struct  or  def class 
macros  (a  user-defined  structure  or  a 
CLOS  class,  respectively)  is  also  dis¬ 
joint  from  any  of  the  above  types.  Any 
two  user-defined  structures  are  disjoint 
from  one  another  unless  defined  oth¬ 
erwise,  and  the  same  goes  for  classes. 
Classes,  though,  are  always  defined  in 
terms  of  other  classes.  I  won’t  say  much 


about  structures  here,  and  I’ll  discuss 
classes  later. 

Functions  are  data  objects,  too,  and 
the  data  type  function  is  disjoint  from 
some  of  the  above  types,  specifically 
from  character,  number,  symbol,  cons, 
and  array.  The  types  character,  num¬ 
ber,  symbol,  cons,  array,  and  function 
are  worthy  of  some  elaboration. 

Lisp  Has  Character 

First,  I’ll  discuss  characters  and  num¬ 
bers,  correcting  some  outdated  info  from 
last  month. 

X3J13  redefined  the  character  subtypes 
that  were  given  in  the  first  edition  of 
Steele’s  book.  Now  the  base-character 
and  extended-character  subtypes  form 
an  exhaustive  partition  of  the  type  char¬ 
acter.  All  characters  are  one  or  the  other 
of  these  types.  Base-character  is  im¬ 
plementation-defined,  but  must  be  a 
supertype  of  standard  char,  which  is  a 
set  of  96  characters  that  any  Lisp  im¬ 
plementation  must  support;  the  extended- 
charactertype  seems  to  be  X3J13’s  way 
of  dodging  the  confusion  of  bit  and 
font  attributes  prevalent  in  Lisp. 

Formerly,  the  data  type  number  con¬ 
tained  three  disjoint  subtypes,  rational, 
float,  and  complex.  Now  a  new  type, 
real,  has  been  introduced.  The  hierar¬ 
chy  runs  like  this:  Types  real  and  com¬ 
plexes  disjoint  subtypes  of  type  num¬ 
ber,  other  subtypes  of  type  number 
can  be  defined.  Each  of  these  two 
subtypes  also  has  two  disjoint  subtypes. 
Type  real  has  the  disjoint  subtypes  ra¬ 
tional  and  float-,  it’s  possible  to  define 
other  real  subtypes.  Type  rational  has 
the  disjoint  subtypes  integer  and  ratio-, 
other  rational  types  can  be  defined. 

However,  type  integer  has  exactly 
two  subtypes,  and  Common  Lisp  does 
not  allow  other  subtypes  of  integer  to 
be  defined.  The  two  integer  subtypes 
are  fixnum  and  bignum.  The  fixnum 
data  type  is  a  conventional  fixed-word- 
length  integer,  the  word  length  being 
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implementation-dependent,  bignums  are 
“true”  integers,  their  size  dependent 
only  on  storage  limits,  not  on  word 
length,  fixnums  are  more  efficient  than 
bignums ,  and  are  used  where  efficiency 
is  more  important  than  being  able  to 
represent  precisely  the  number  of  grains 
of  sand  required  to  fill  the  universe. 
For  example,  fixnum  is  the  required 
data  type  for  array  indices. 

An  object  of  type  ratio  represents 
the  ratio  of  two  integers.  The  Lisp  sys¬ 
tem  is  required  to  reduce  all  ratios  to 
the  lowest  terms,  representing  a  ratio 
as  an  integer  if  that  is  possible. 

Common  Lisp  defines  four  subtypes 
of  type  float,  but  an  implementation 
need  not  have  all  four  as  distinct  types. 
Types  short-float,  singlefloat,  double¬ 
float,  and  long-float,  in  nondecreasing 
order  of  word  length,  all  must  be  sup¬ 
plied,  but  any  adjacent  pair  or  triplet 
of  these  may  be  identical.  Any  float 
subtypes  that  are  not  identical  must  be 
disjoint. 

An  object  of  type  complex  represents 
a  complex  number  in  Cartesian  form, 
as  a  pair  of  numbers.  The  two  numbers 
must  be  of  type  real,  and  both  must 
be  rational  or  both  must  be  of  the  same 
floating-point  type. 

Everything  in  Lisp  is  a  List 

Characters  and  numbers  are  straight¬ 
forward  data  types,  but  symbols  and 
lists  are  trickier.  Symbols  are  named 
data  objects.  Type  symbol  includes 
among  its  subtypes  one  peculiar 
subtype:  type  null,  null  is  the  type  of 
exactly  one  Lisp  data  object:  the  object 
nil.  The  status  of  type  null  is  one  rea¬ 
son  that  the  type  relationships  of  Com¬ 
mon  Lisp  form  a  heterarchy  rather  than 
a  hierarchy,  null  is  a  subtype  of  two 
types,  neither  of  which  is  a  subtype  of 
the  other:  symbol  and  list,  nil  is  the 
only  object  that  is  both  a  list  and  a 
symbol. 

Actually,  at  another  level,  all  sym¬ 
bols  have  a  list-like  structure.  Each  sym¬ 
bol  has  an  associated  data  structure 
called  a  “property  list,”  a  list  of  pairs, 
the  first  elements  being  (typically)  sym¬ 
bols,  and  the  second  elements  being 
any  Lisp  data  objects.  The  purpose  of 
the  property  list  of  a  symbol  has  evolved 
over  time;  in  Common  Lisp  it  is  less 
important  than  in  earlier  Lisps,  being 
used  now  for  data  not  needed  fre¬ 
quently,  such  as  debugging,  documen¬ 
tation,  or  compiler  information.  Nei¬ 
ther  a  property  list  nor  a  symbol  is  of 
type  list,  but  somehow  everything  in 
Lisp  is  a  list  of  some  sort.  (Viewed 
another  way,  almost  everything  in  Lisp 
is  a  function,  as  well  see  shortly.) 

The  data  type  list,  though,  is  not 
regarded  as  being  as  basic  as  type  cons. 
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These  are  alternate  ways  of  viewing 
the  same  thing.  A  list  is  recursively 
defined  to  be  either  the  object  nil  or  a 
cons  whose  second  component  is  a 
list.  A  cons  is  a  data  structure  with  two 
components,  which  can  be  pretty  much 
anything;  usually,  though,  the  second 
component  of  a  cons  is  a  list  (or  nil ,  the 
empty  list).  The  first  components  of  the 
conses  making  up  a  list  are  the  ele¬ 
ments  of  the  list. 

The  data  type  cons ,  then,  is  the  type 
of  the  basic  data  structure  used  to  build 
lists.  Any  object  that  is  a  cons  is  also  a 
list,  so  list  is  a  supertype  of  cons.  The 
data  type  list  has  exactly  two  subtypes, 
and  they  are  disjoint:  cons  and  null.  In 
this  sense,  null  is  the  (type  of  the) 
empty  list,  list  itself  is  a  subtype  of  the 
data  type  sequence,  which  has  one  other 
subtype:  vector,  vector  and  list  are  dis¬ 
joint. 

Vectors,  and  arrays  generally,  can 
be  rather  complex.  Arrays  can  be  com¬ 
plex,  with  the  ability  to  share  data  with 
other  arrays,  be  dynamically  sized,  and 
have  fill  pointers.  An  array  that  has 
none  of  these  features  is  called  a  “sim¬ 
ple  array.”  Vectors  are  one-dimensional 
arrays;  they  differ  from  lists  in  perfor¬ 
mance  characteristics.  Accessing  an  ele¬ 
ment  of  a  list  is,  on  average,  a  linear 
function  of  list  length,  while  the  time 
to  access  an  element  of  a  vector  is 
constant.  When  it  comes  to  adding  an 
element  to  the  beginning  of  a  list  or 
vector,  though,  the  relationship  is  re¬ 
versed:  constant  for  the  list,  and  a  lin¬ 
ear  function  of  vector  length  for  the 
vector. 

One  of  vector’s  more  interesting 
subtypes  is  type  string.  Type  string  is 
the  union  of  one  or  more  vector  types 
with  the  characteristic  that  the  types  of 


the  vector’s  elements  are  subtypes  of 
type  character. 

According  to  X3J13,  the  data  type 
function  is  strictly  disjoint  from  data 
types  cons  and  symbol.  But  lists  and 
symbols  are  the  only  tools  available  for 
referring  to  functions,  or  for  invoking 
them.  This  is  probably  a  use-mention 
distinction,  but  in  any  case,  when  a  list 
or  symbol  is  used  in  this  way  it  is  auto¬ 
matically  coerced  to  type  function.  As 
well  see  shortly,  there’s  some  truth  to 
the  exaggeration  that  everything  in  Lisp 
is  a  function. 

Lisp  Has  Class 

CLOS  is  an  object-oriented  extension 
to  CL,  adding  four  kinds  of  objects  to 
CL:  classes,  instances,  generic  functions, 
and  methods.  The  key  aspects  are  ge¬ 
neric  functions,  multiple  inheritance, 
declarative  method  combination,  and 
a  metaobject  protocol.  Classes  and  in¬ 
stances  are  tied  to  data  types,  generic 
functions  to  functions.  I’ll  say  only  a 
little  bit  here  about  the  metaobject  pro¬ 
tocol,  which  is  not  yet  officially  a  part 
of  CLOS. 

The  Common  Lisp  Object  System 
maps  classes  into  the  data  types  just 
described.  Many  Common  Lisp  types 
have  corresponding  classes  with  the 
same  names,  but  not  all.  Normally,  a 
class  has  a  corresponding  type  with  the 
same  name. 

Because  the  types  do  not  form  a 
simple  tree,  and  a  type  can  be  a  subtype 
of  two  types  neither  of  which  is  a 
subtype  of  the  other,  you  might  expect 
CLOS  to  support  multiple  inheritance, 
in  which  a  class  can  inherit  from  more 
than  one  superclass.  In  fact,  this  is  the 
case.  The  heterarchical  structure  of  types 
is  mirrored  in  the  inheritance  structure 
of  classes,  but  CLOS  requires  that  more 
structure  be  added  to  establish  a  clear 
precedence  order  for  inheritance.  For 
example,  the  class  vector  has  super¬ 
classes  sequence  and  array,  just  as  the 
type  vector  has  supertypes  sequence 
and  array,  but  from  which  superclass 
does  vector  inherit  what? 

CLOS  resolves  questions  such  as  this 
by  requiring  that  you  specify  an  order¬ 
ing  of  direct  superclasses  when  you 
define  a  class  (and  by  supplying  this 
ordering  for  predefined  classes).  The 
business  of  deriving  a  full  precedence 
order  is  fairly  complex,  but  the  CLOS 
class  precedence  order  for  predefined 
classes  resolves  such  issues.  In  particu¬ 
lar,  the  precedence  order  for  the  class 
null  is  null,  symbol,  list,  sequence,  t-, 
and  the  precedence  order  for  the  class 
string  is  string,  vector,  array,  sequence, 
t.  By  implication,  the  precedence  order 
for  the  class  vector  is  vector,  array,  se¬ 
quence,  t;  so  array  methods  have  prece¬ 


dence  over  sequence  methods  when 
class  vector  is  inheriting  methods. 

Everything  in  Lisp  is  a  Function 

The  simplifying  generalization  is  that 
everything  in  Lisp  is  a  function.  It’s 
nearly  true;  any  data  object  can  be 
treated  as  a  function,  or  rather,  as  a 
form.  A  form  is  simply  a  data  object 
treated  as  a  function.  You  treat  a  data 
object  as  a  function  when  you  hand  it 
to  the  evaluator,  which  is  the  mecha¬ 
nism  that  executes  Lisp  programs.  The 
evaluator  accepts  a  form  and  does  what¬ 
ever  computation  the  form  specifies. 

The  evaluator  can  be  implemented 
in  various  ways,  such  as  by  an  inter¬ 
preter  that  traverses  the  form  recursively, 
performing  the  required  calculations 
along  the  way;  or  as  a  pure  compiler; 
or  by  some  mixed  form.  Common  Lisp 
requires  that  correct  programs  produce 
the  same  results,  regardless  of  the 
method  of  implementation.  The  evalu¬ 
ator  is  available  to  the  user  via  the 
function  eval,  and  also  the  special  form 
eval-when,  which  allows  specifying  that 
a  form  should  be  evaluated,  say,  only 
at  compile  time. 

Not  every  data  object  specifies  a  mean¬ 
ingful  function,  but  most  do.  To  the 
evaluator,  there  are  three  kinds  of  forms, 
corresponding  to  three  nearly  disjoint 
data  types.  There  are  symbols,  lists, 
and  self-evaluating  forms  (per  X3J13, 
all  standard  Common  Lisp  objects,  ex¬ 
cept  symbols  and  lists,  are  self-evaluat¬ 
ing  forms). 

Self-evaluating  forms  are  taken  liter¬ 
ally  by  the  evaluator;  they  return  them¬ 
selves  on  evaluation. 

Symbols  name  variables,  constants, 
keywords  and  functions.  They  evalu¬ 
ate  to  whatever  they  name;  for  exam¬ 
ple,  what  they  are  bound  to  or  what 
they  are  set  to. 

Lists,  from  the  viewpoint  of  the  evalu¬ 
ator,  come  in  three  varieties:  special 
forms,  macro  calls,  and  function  calls. 
Note  that  while  a  function  is  not  a  list, 
a  function  call  is. 

Special  forms  are  structural  elements 
of  the  language  that  don’t  fit  the  func¬ 
tional  paradigm  well,  such  as  the  if-then- 
else  structure.  These  deviations  from 
the  purity  of  the  paradigm  have  been 
a  part  of  Lisp  since  the  beginning,  and 
new  special  forms  have  been  added 
over  the  years,  but  in  Common  Lisp  the 
set  of  special  forms  is  fixed  and  cannot 
be  extended  by  the  programmer.  A 
macro  is  a  function  from  forms  to  forms, 
much  as  in  other  languages.  A  macro 
call,  when  evaluated,  is  said  to  be  ex¬ 
panded.  Programmers  can  extend  the 
set  of  macros.  Despite  the  fact  that  they 
are  not  true  functions,  special  forms 
look  like  functions  syntactically,  as  do 


124 


Dr.  Dobb’s Journal,  March  1990 

267 


macros.  The  consequence  of  this  is 
that  when  you  are  sitting  at  the  key¬ 
board  typing  in  Lisp  code,  it  feels  like 
you  are  dealing  with  one  kind  of  con¬ 
struct:  A  parenthesized  list  that  repre¬ 
sents  a  function  and  its  arguments. 

A  form  that  is  a  function  call  consists 
of  a  list  whose  first  element  is  a  func¬ 
tion  name.  The  other  elements  of  the 
list,  if  any,  are  treated  by  the  evaluator 
as  forms  to  be  evaluated  to  provide  the 
function  with  arguments.  There  are  two 
levels  of  evaluation  that  take  place  when¬ 
ever  the  evaluator  deals  with  a  func¬ 
tion  call:  The  arguments  get  evaluated, 
then  the  function  is  evaluated  with  these 
arguments.  Typically,  the  evaluation  of 
the  function  produces  a  value,  which 
becomes  the  value  of  the  original  form. 

There  are  two  ways  in  which  the  first 
element  of  a  form  can  name  a  function, 
one  involving  a  symbol  and  the  other 
involving  a  list.  Because  symbols  are 
used  to  name  functions,  this  is  the  most 
direct  and  obvious  way.  The  other  way 
involves  the  use  of  a  lambda  expres¬ 
sion.  A  lambda  expression  is  techni¬ 
cally  not  a  form,  and  cannot  be  evalu¬ 
ated.  It  is  a  list,  the  first  element  being 
the  word  lambda.  The  second  element 
is  a  list  of  parameters,  and  this  is  fol¬ 
lowed  by  some  number  of  forms  to  be 
evaluated,  which  can  use  the  parame¬ 
ters.  When  the  function  that  the  lambda 
expression  names  is  applied  to  argu¬ 
ments,  the  parameters  are  bound  to  the 
arguments  and  the  forms  are  executed 
with  these  bindings. 

Using  a  lambda  expression  as  a  func¬ 
tion  name  is  like  slipping  physical  ac¬ 
tions  into  your  speech,  as  you  would 
be  doing  if  you  referred  to  what  comes 
at  the  end  of  a  joke  by  making  a  punch¬ 
ing  motion,  then  saying  the  word  "line." 
Lambda  expressions  see  their  main  use 
in  defining  functions,  roughly  like  this: 

defun  <fn-name>  <lambda-list> 

<forms> 

CLOS  adds  generic  functions  to  Lisp. 
Because  the  evaluation  of  functions  is 
central  to  Lisp,  the  extension  of  func¬ 
tions  to  generic  functions  has  a  lot  to 
say  about  how  it  feels  to  program  in 
CLOS. 

A  generic  function  is  a  true  Lisp  func¬ 
tion,  is  called  with  the  same  syntax, 
and  can  be  used  in  the  same  contexts 
in  which  a  Lisp  function  can  be  used. 

Defining  a  generic  function  object  is 
similar  to  defining  a  function.  You  use 
the  defgeneric macro,  basically  like  this: 

defgeneric  <fn-name>  <lambda-list> 

<methods> 

The  difference  is  that,  rather  than  a 


fixed  set  of  forms  to  be  evaluated,  the 
generic  function  has  a  collection  of 
method  descriptions,  each  of  which 
may  consist  of  a  number  of  forms.  The 
method  descriptions  have  their  own 
lambda  lists  that  must  be  congruent 
with  the  main  lambda  list.  Texas  Instru¬ 
ments  has  implemented  generic  func¬ 
tions  in  its  TICLOS  as  normal  compiled 
functions  with  pointers  to  data  struc¬ 
tures  containing  their  slots.  When  the 
function  is  called,  it  is  up  to  the  object 
system  to  select  the  appropriate  method 
from  its  methods.  Actually,  not  select; 
the  technique  is  more  general  than  this, 
and  is  called  “method  combination.” 
The  code  eventually  executed  is  called 
the  “effective  method.” 

The  selection/ combination  has  three 
stages:  select  applicable  methods,  or¬ 
der  them  by  precedence,  and  apply 
method  combination.  The  method  com¬ 
bination,  defined  in  the  definition  of 
the  generic  function,  can  be  as  simple 
as  using  the  most  specific  method,  or 
it  can  be  some  function  of  some  of  the 
applicable  methods.  Some  built-in 
method  combination  types  are  +,  and , 
or,  append ,  max ,  and  min ,  which  per¬ 
form  the  corresponding  functions  on 
the  applicable  methods  to  produce  the 
effective  method. 

Some  of  the  most  interesting  CLOS 
functions  are  those  that  allow  customi¬ 
zation  of  the  object  system  itself,  by 
manipulating  metaobjects  and  metaclas¬ 
ses.  Unfortunately,  these  have  not  yet 
been  approved  by  X3J13  for  inclusion 
in  the  standard.  They  do,  however,  sup¬ 
port  the  original  spirit  of  Lisp  as  an 
introspective  language,  with  all  the 
strangeness  that  Douglas  Hofstadter  sug¬ 
gested  when  I  quoted  him  last  month, 
a  quote  that  I  here  double-quote: 

“A  .  .  .  double-entendre  can  happen 
with  LISP  programs  that  are  designed 
to  reach  in  and  change  their  own  struc¬ 
ture.  If  you  look  at  them  on  the  LISP 
level,  you  will  say  that  they  change 
themselves;  but  if  you  shift  levels,  and 
think  of  LISP  programs  as  data  to  the 
LISP  interpreter .  .  .  then  in  fact  the  sole 
program  that  is  running  is  the  inter¬ 
preter,  and  the  changes  being  made  are 
merely  changes  in  pieces  of  data.  ” 

Editor’s  Note:  For  a  general  discus¬ 
sion  of  functional  programming,  see 
“Functional  Programming  and  FPCA 
’89’’  by  Ronald  Fischer,  DDJ,  December 
1989-  Also,  see  “A  Neural  Networks 
Instantiation  Environment"  by  Andrew 
J.  Czuchry,  Jr.  in  next  month ’s  DDJ  for 
more  information  on  programming  in 
Lisp. 
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A  Thousand  CURSES 
on  TEXTSRCH 


Last  month  we  completed  the  re¬ 
trieval  processes  of  the  TEXTSRCH 
project,  a  “C  Programming”  column 
project  that  we  started  in  December 
of  last  year.  It  builds  and  maintains  a 
text  indexing  and  retrieval  data-base  sys¬ 
tem  that  allows  a  user  to  find  text  files 
by  composing  key  word  query  expres¬ 
sions.  The  program  has  two  passes:  an 
index  builder  and  a  query  retrieval  pro¬ 
gram.  The  query  retrieval  program 
searches  the  text  file  indexes  for  files 
that  match  the  criteria  of  a  Boolean  key 
word  search.  It  delivers  a  list  of  the  file 
names  that  match  the  search.  With  the 
software,  developed  through  last 
month’s  installment,  a  user  can  deter¬ 
mine  which  files  in  the  text  data  base 
match  the  criteria  of  the  query,  and 
from  there  he  or  she  can  move  the  files 
into  another  application,  for  example, 
a  word  processor. 

This  month  we  will  add  a  new  fea¬ 
ture  to  TEXTSRCH  to  allow  the  user  to 
select  and  view  one  of  the  files  from 
within  the  TEXTSRCH  retrieval  program 
itself.  Instead  of  merely  displaying  a 
list  of  file  names  that  rpatch  the  query, 
TEXTSRCH  will  display  them  in  a  menu 
window  from  which  the  user  can  se¬ 
lect.  Then  it  will  display  the  contents 
of  the  selected  file  with  the  query  ex¬ 
pression’s  key  words  highlighted. 

We  use  this  new  feature  to  explore 


Al  Stevens 


the  screen  driver  software  called 
“CURSES.”  CURSES  is  a  library  of  func¬ 
tions  that  were  originally  implemented 
in  Unix  V.  Its  purpose  is  to  allow  you 
to  write  portable,  terminal  device-inde¬ 
pendent  C  programs.  The  Unix  system 
and  the  C  language  are  still  inexorably 
oriented  to  the  simple  teletype-like  con¬ 
sole  device.  The  standard  input  and 
output  devices  are  such  that  they  can 


be  anything  from  a  clunky  old  ASR-33 
teletype  to  a  high-resolution,  many 
MIPS,  full-color,  belch-fire,  neck-snap¬ 
per  graphics  workstation.  To  support 
them  all,  stdin  and  stdout  must  speak 
to  the  lowest-common  denominator. 

There  are  still  many  installations  that 
use  simple  terminal  devices,  and  these 
devices  are  grist  for  the  stdin,  stdout 
mill.  Terminals  are  the  same  yet  they 
are  different.  A  system’s  local  devices 
may  be  many  and  varied,  and  the  re¬ 
mote  dial-up  users  are  likely  to  be  call¬ 
ing  in  from  any  one  of  a  number  of 
different  terminal  types.  These  differ¬ 
ent  video  display  terminal  devices  can 
work  as  one  because  they  share  the 
common  ability  to  send  and  receive 
ASCII  text  with  carriage  returns  and 
line  feeds.  If  that  is  the  only  way  a 
program  needs  to  communicate  with  a 
user,  then  these  devices  share  all  the 
commonality  they  will  ever  need. 

There  are,  however,  features  in  the 
typical  video  display  terminal  that  a 
program  can  use  to  enhance  its  user 
interface.  Most  such  terminals  have  com¬ 
mand  sequences  to  clear  the  screen, 
position  the  cursor,  and  so  forth.  As 
you  might  expect,  there  is  no  one  way 
to  do  all  this.  ANSI  published  a  stan¬ 
dard,  and  some  terminal  devices  com¬ 
ply.  The  ANSI. SYS  device  driver  that 
comes  with  MS-DOS  allows  a  PC  to  use 
the  ANSI  protocols. 

Many  terminals  have  their  own,  non- 
ANSI  ways  to  clear  the  screen,  position 
the  cursor,  scroll,  and  achieve  other 
video  effects.  A  program  written  spe¬ 
cifically  to  use  the  features  of  one  of 
these  terminals  must  be  modified  if  an 
incompatible  terminal  is  connected  to 
the  program.  As  a  programmer  in  such 
an  environment  you  have  three  choices: 
You  can  write  to  the  common  base, 
which  means  simple,  unadorned,  glass- 
teletype  ASCII  text;  you  can  use  the 
unique  features  of  the  terminal  du  jour 


and  modify  your  program  every  time  a 
new  terminal  comes  into  the  picture; 
or  you  can  write  to  a  higher-level  video 
protocol  and  have  a  system-level  inter¬ 
preter  library  translate  your  video  com¬ 
mands  into  the  commands  of  whatever 
terminal  a  user  signs  on  with.  The  first 
choice  is  the  appropriate  one  for  text 
filter  programs  and  console  command 
programs.  The  second  one  is  appropri¬ 
ate  when  the  operating  environment 
is  well-defined  and  contained,  and  per¬ 
haps  when  user  language  performance 
is  an  issue.  The  third  choice  is  the  best 
one  to  make  when  you  are  striving  for 
portability  and  device  independence. 

CURSES 

To  provide  for  an  environment  where 
users  with  different  terminals  can  use 
the  same  software,  and  where  the  soft¬ 
ware  can  use  the  video  temninal  features 
that  go  beyond  simple  text  display,  the 
Unix  system  contains  the  “CURSES”  li¬ 
brary  and  the  “termcaps”  data  base. 
The  data  base  describes  the  video  pro¬ 
tocols  of  each  of  the  terminals,  and  the 
library  provides  functions  that  translate 
a  higher-level  common  protocol  into 
that  of  the  user’s  terminal  device. 

CURSES  functions  facilitate  a  primi¬ 
tive  window-oriented  display  architec¬ 
ture.  You  can  define  windows  and  use 
them  as  virtual  terminals.  There  are 
character  and  string  display  operations, 
cursor  positioning  operations,  video  at¬ 
tributes  (such  as  highlighting  and  nor¬ 
mal  displays),  keyboard  character  and 
string  input,  scrolling,  and  simple  text 
editing  operations  such  as  inserting  and 
deleting  characters  and  lines. 

CURSES  works  in  memory  buffers. 
You  address  your  operations  to  a  de¬ 
fined  window,  and  CURSES  makes  the 
changes  in  memory.  These  changes  do 
not  appear  on  the  screen  until  you  tell 
CURSES  to  refresh  the  window.  This 
method  might  seem  peculiar  to  a  PC 


Dr.  Dobb’s Journal,  March  1990 


127 

269 


C  PROGRAMMING 


programmer  who  is  accustomed  to  in¬ 
stantaneous  video  memory  updates.  But 
it  reflects  its  roots  in  the  RS-232  ASCII 
terminal.  It  takes  more  time  to  update 
a  terminal’s  screen  than  it  does  to  write 
characters  into  a  PC’s  video  memory. 
For  example,  a  24  x  80  terminal  operat¬ 
ing  at  19,200  baud  will  use  about  a 
second  to  refresh  its  screen.  A  well- 
behaved  video  library  can  keep  a  copy 
of  the  current  screen  image  and  be 
building  another  copy  to  contain  what¬ 
ever  changes  you  are  making.  When 
you  tell  it  to  refresh,  the  library  can,  if 
the  terminals  features  allow,  refresh  only 
that  part  of  the  screen  that  changes. 

Lattice  C  6.0 

Lattice  C  is  an  old  PC  workhorse  that 
has  been  around  since  Gates  was  in 
short  pants  and  Kahn  was  a  dynasty.  It 
was  one  of  the  original  full  K&R  C 
compilers  for  the  PC.  The  first  Microsoft 
C  was  in  fact  Lattice  in  a  Microsoft  binder 
giving  Microsoft  an  entrance  into  the 
C  compiler  marketplace  while  they  took 
their  time  building  one  of  their  own. 
Because  Microsoft’s  own  C  compiler 
targeted  upward  compatibility  for  pro¬ 
grams  written  with  their  earlier  Lattice 
version  and  because  the  rest  of  the  C 
compiler  business  strives  for  compati¬ 
bility  with  Microsoft  C,  it  can  be  said  that 
Lattice  had  a  strong  influence  on  what 
C  compilers  for  the  PC  would  become. 

There  are  Lattice  versions  now  for 
other  platforms,  including  the  amazing 
and  wonderful  Commodore  Amiga.  The 
most  recent  version  for  the  PC,  Version 
6.0,  supports  DOS  and  OS/2,  conforms 
with  the  ANSI  proposed  draft,  and 
comes  with  a  source-level  debugger, 
an  editor,  an  assembler,  a  librarian,  a 
linker,  lots  of  utility  programs,  a  com¬ 
munications  function  library,  a  data¬ 
base  library  that  supports  dBase  III  for¬ 
mats,  a  graphics  library,  a  library  of 
DOS-OS/2  Family  Mode  functions,  and 
a  CURSES  library.  If  you  do  not  require 
an  Integrated  Development  Environ¬ 
ment  after  the  fashion  of  Turbo  C, 
QuickC,  and  others  (and  many  of  us 
do  not),  this  is  as  complete  a  C  lan¬ 
guage  development  environment  as 
you’d  want. 

The  Lattice  CURSES  Library 

The  Lattice  CURSES  library  is  available 
in  source  code  for  $125  so  you  can 
port  it  to  the  compiler  of  your  choice. 
This  CURSES  library  provides  a  means 
for  developing  screen  programs  that 
can  be  ported  between  DOS,  OS/2, 
and  Unix  with  minimum  changes.  I 
used  the  Lattice  compiler  and  this  li¬ 
brary  to  build  the  document  viewing 
feature  that  we  are  adding  to  TEXTSRCH 
this  month. 


Porting  Crotchety  TEXTSRCH  to  Lattice  C 

I  wrote  the  first  three  installments  of 
TEXTSRCH  in  Turbo  C  2.0.  My  inten¬ 
tion  was  to  make  the  code  as  close  to 
ANSI  C  and  as  far  from  the  PC  architec¬ 
ture  as  possible  to  avoid  restricting  the 
program  to  a  particular  platform.  To 
use  the  Lattice  CURSES  library,  I  de¬ 
cided  to  port  the  code  to  Lattice  C 
rather  than  to  port  the  CURSES  code 
to  Turbo  C.  Somehow  I  figured  I’d  have 
an  easier  time  of  it  by  porting  my  own 
stuff.  Maybe,  maybe  not. 

CURSES  is  a  library  of 
functions  that  were 
originally  implemented 
in  Unix  V  to  allow  you 
to  write  portable , 
terminal 

device-independent 
C  programs 


The  port  was  reasonably  easy  with 
just  a  few  hitches.  Here  is  what  I  ran 
up  against,  and  what  follows  is  a  new 
crotchet  that  I  hereby  induct  into  the 
“C  Programming”  column  Crotchet  Hall 
of  Fame. 

It  is  said  that  a  compiler  that  com¬ 
piles  programs  that  comply  with  the 
ANSI  standard  is  considered  to  be  an 
ANSI-conforming  compiler.  But  what 
about  those  compilers  that  extend  the 
standard?  For  example,  Watcom  C  sup¬ 
ports  the  C++  convention  for  double¬ 
slash  comments.  The  Turbo  C  f open 
function  allows  the  use  of  a  non-stan¬ 
dard  mode  parameter.  To  be  sure,  both 
compilers  will  compile  programs  that 
do  not  use  these  extensions.  But,  be¬ 
cause  you  can  write  programs  that  use 
them,  you  can  unintentionally  write 
code  that  is  not  ANSI-conforming.  Turbo 
C  has,  of  course,  many  other  exten¬ 
sions,  such  as  pseudo-register  variables 
and  interrupt  functions.  Many  compilers 
now  include  the  interrupt  function  type, 
which  I  first  saw  in  Wizard  C,  the  an¬ 
cestor  of  Turbo  C.  Usually  you  can  tell 
the  compilers  to  disallow  such  exten¬ 
sions,  that  you  are  interested  in  writing 
portable  code,  and  the  compilers  will 
comply.  But  when  an  extension  takes 
the  form  of  the  values  accepted  as  a 
function’s  parameters,  the  compiler  does 


not  preempt  the  extension.  So,  in  all 
my  innocence  and  with  good  inten¬ 
tions  aforethought,  I  used  the  Turbo  C 
“rt”  and  “wt”  formats  for  the  fopen 
mode  parameter.  The  Lattice  fopen  func¬ 
tion,  in  true  ANSI  compliance,  simply 
refused  to  open  those  files  because  it 
did  not  recognize  the  modes.  Turbo  C 
also  supports  mode  formats  such  as 
“r+b”  where  ANSI  and  the  Lattice  docu¬ 
mentation  specify  “rb+.”  Naturally,  I 
used  the  non-standard  formats  in  my 
fopen  calls.  You  should  go  through  all 
the  code  in  <index.c>  from  last  month 
and  change  every  “r+b”  to  “rb+”  and 
“w+b”  to  “wb+.”  Change  all  fopen 
modes  that  include  the  “t”  to  remove 
the  “t.”  I  believe  that  the  definition  of 
compliance  should  exclude  such  ex¬ 
tensions. 

The  next  portability  issue  came  with 
header  files.  Turbo  C  puts  some  func¬ 
tion  prototypes  into  more  than  one 
header  file.  In  this  case,  I  included  the 
non-standard  <process.h>  to  get  the 
prototype  for  the  exit  function.  Accord¬ 
ing  to  ANSI,  this  prototype  is  in 
<stdlib.h>,  and  that  is  where  Lattice 
keeps  it. 

The  moral  of  the  story  has  to  be:  Get 
a  good  ANSI  function  library  reference 
book  and  ignore  the  library  documen¬ 
tation  that  comes  with  your  compiler. 

Other  storms  in  my  port  were  the 
result  of  issues  unrelated  to  ANSI  C. 
The  TEXTSRCH  <cmdline.c>  source  file 
uses  the  Turbo  C  findfirst  and  findnext 
functions  to  search  a  file  directory.  ANSI 
C  has  no  equivalent  functions  because, 
I  suppose,  there  are  some  C  platforms 
that  have  no  analogue  to  the  DOS  di¬ 
rectory  search.  When  I  wrote  about 
those  functions  last  month,  I  said  you 
would  need  to  make  substitutions  if 
you  are  using  a  different  compiler.  Now 
I  find  myself  in  that  same  boat.  Be¬ 
cause  Lattice  has  equivalent  functions 
in  its  dfind  and  dnext  functions  and 
because  it  does  not  have  the  <dir.h> 
file  that  cmdline.c  includes,  I  coded  a 
<dir.h>  that  substitutes  with  macros  the 
Lattice  functions  for  the  Turbo  C  func¬ 
tions.  You  will  find  <dir.h>  as  Listing 
One  on  page  144. 

I  had  the  global  variable  OK  defined 
as  0,  and  the  Lattice  <curses.h>  defines 
it  as  1 .  If  you  use  the  Lattice  definition, 
all  the  TEXTSRCH  code  works  fine. 

The  next  set  of  problems  occurs  be¬ 
cause  of  errors  in  the  Lattice  header 
files.  It’s  difficult  to  imagine  how  these 
errors  have  gone  undetected  until  now. 
The  <curses.h>  file  includes  definitions 
of  keystroke  values  for  the  keypad  keys. 
One  of  these  is  KEY_PGDN,  which  de¬ 
fines  the  value  returned  when  you  press 
the  PgDn  key.  The  definition,  0x0181, 
is  wrong.  It  should  be  0x0151.  The 
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(continued  from  page  128) 
macros  for  the  CURSES  wstandout  and 
wstandend  functions  are  incorrect.  They 
do  not  include  the  win  parameter  in 
the  macro  expansion.  Not  only  do  you 
get  compiler  warnings,  but  the  func¬ 
tions  do  not  work.  Finally,  the  Lattice 
<stdlib.h>  header  file  specifies  in  the 
free  function  prototype  that  free  returns 
void,  which  is  wrong.  It  returns  int.  I 
had  to  repair  the  Lattice  header  files  to 
proceed. 

My  final  problem  was  with  the 
CURSES  screen  driver  software.  For 
some  reason  it  reprograms  the  video 
mode  of  my  Vega  Video  7  in  a  way 
that  makes  the  display  go  off  into  the 
weeds  at  unexpected  times,  usually  af¬ 
ter  I  exit  my  program.  To  solve  this 
problem  I  would  need  to  look  at  the 
source  code  for  CURSES,  and  time  and 
deadlines  do  not  permit.  A  workaround 
solution  is  to  run  the  TEXTSRCH  pro¬ 
gram  from  a  batch  file  that  executes  the 
DOS  command  MODE  CO80  after  the 
TEXTSRCH  program  exits  to  DOS. 

TEXTSRCH 

To  install  the  new  file-viewing  func¬ 
tions  of  TEXTSRCH,  you  must  replace 
the  source  file  named  <search.c>  from 
last  month  with  the  one  in  Listing  Two, 
page  144.  You  must  also  compile  and 


link  <display.c>,  Listing  Three,  page 
144,  and  <error.c>,  Listing  Four,  page 
149,  into  the  <textsrch.exe>  program. 

The  BLDINDEX  program  works  the 
same  way  that  it  did  before.  The  new 
feature  is  in  the  TEXTSRCH  program. 
When  you  enter  a  query  expression  the 
results  are  now  displayed  in  a  screen 
window  with  an  ASCII  ->  cursor  to  the 
left  of  each  file  name.  With  the  up  and 
down  arrow  keys,  you  move  that  cur¬ 
sor  and  scroll  the  display.  When  the 
cursor  points  to  a  file  you  might  want 
to  view,  press  the  Enter  key.  The  first 
page  of  the  selected  document  text  dis¬ 
plays  in  a  new  full-screen  window.  The 
up  and  down  arrow  keys  will  scroll  the 
display.  The  up  and  down  page  keys 
will  page  the  display.  The  Home  key 
goes  to  the  first  page  and  the  End  key 
to  the  last.  During  the  display  all  occur¬ 
rences  of  the  key  words  from  the  query 
expression  display  in  a  highlighted 
mode.  You  can  move  to  the  next  page 
where  a  key  word  appears  by  pressing 
the  right  arrow  key.  The  left  arrow  key 
moves  you  to  the  previous  page  where 
a  key  word  appears. 

Here  is  how  to  use  CURSES  to  achieve 
these  results.  The  process_result  func¬ 
tion  in  <search.c>  is  changed.  Instead 
of  displaying  the  matching  file  names  it 
builds  an  array  of  those  names.  Then  it 


calls  the  CURSES  initscr  function  to  in¬ 
itialize  the  screen  manager,  calls  select  Jext 
so  the  user  can  select  a  file  to  look  at, 
and  calls  the  CURSES  endwin  function 
to  shut  down  the  screen  manager. 

The  select_text  function  is  where  the 
user  picks  a  file  to  view.  We  use  the 
CURSES  newwin  function  to  build  a 
menu  window.  The  keypad  function 
allows  the  CURSES  keyboard  routines 
to  recognize  the  keypad  characters,  and 
the  wsetscrreg function  defines  the  scroll¬ 
ing  boundaries  of  the  window.  Use  of 
this  function  prevents  the  window  bor¬ 
ders  from  scrolling  along  with  the  rest 
of  it. 

The  display_page  function  displays 
a  specified  page  of  the  file  menu  in  the 
window.  Initially  we  call  it  to  display 
the  first  page.  Then  we  draw  a  box 
around  the  window,  write  the  ASCII 
->  selector  cursor,  and  read  the  key¬ 
board.  The  various  cases  under  the  key¬ 
stroke  switch,  take  care  of  moving  the 
selector  cursor  up  and  down,  and  pag¬ 
ing  and  scrolling  the  file  selector  menu. 
When  the  user  presses  the  Enter  key, 
that  case  calls  the  display_text  func¬ 
tion,  passing  the  name  of  the  selected 
file  as  shown  in  the  menu  window. 

At  this  point  we  must  consider  the 
values  assigned  to  the  different  keys 
we  are  interpreting.  They  are  taken 
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(cotitinued  from  page  130) 
from  the  Lattice  <curses.h>  header  file 
and  they  correspond  to  what  the  Lat¬ 
tice  version  of  the  CURSES  ivgetch  func¬ 
tion  returns  for  the  cursor  keys  when 
the  CURSES  keypad  mode  is  on.  These 
values  might  not  apply  to  different  en¬ 
vironments.  Also  see  the  use  of  the 
VERT_DOUBLE  and  HORlZ_DOUBLE 
global  variables  in  the  call  to  the  CURSES 
box  function.  These  too  appear  in 
<curses.h>  and  they  correspond  to  the 
PCs  graphics  characters  for  border  char¬ 
acters.  You  might  need  to  change  these 
values  to  something  that  matches  your 
system.  CURSES  does  not  provide  for 
border  corner  characters,  but  the  Lat¬ 
tice  implementation  recognizes  the  IBM 
set  and  uses  the  matching  corner  graph¬ 
ics  characters. 

Look  now  at  Listing  Three  to  see  the 
code  that  displays  a  text  file.  The  func¬ 
tion  named  display_text  opens  the  file 
and  calls  its  do_display  function  if  the 
file  opens  OK.  If  not,  it  calls  the  er¬ 
ror, _handler  function  that  you  will  find 
in  Listing  Four.  This  general-purpose 
function  displays  an  error  message  in 
a  window,  waits  for  a  key  press,  and 
clears  the  message. 

The  do_display  function  reads  all  the 
lines  of  text  from  the  chosen  file  and 
stores  them  in  a  linked  list  in  the  heap. 
The  list  connects  each  line  to  its  fol¬ 
lowing  line  and  records  the  positions 
of  any  key  words  in  each  line. 

The  findkeys  function  takes  care  of 
finding  and  storing  key  word  occur¬ 
rences.  It  scans  the  line  of  text  compar¬ 
ing  each  word  to  the  ones  in  the  query 
expression.  If  a  word  matches  one  of 
the  keys,  its  character  offset  relative  to 
the  start  of  the  line  goes  into  the  header 
block  of  the  line’s  linked  list  entry.  The 
header  block  can  contain  up  to  five 
key  words  for  each  line,  which  should 
be  enough  to  call  your  attention  to  the 
line. 

After  all  the  lines  of  text  are  tucked 
away  in  the  linked  list,  the  program 
builds  a  full-screen  window  to  display 
the  text.  The  display_textpage  function 
displays  a  page  of  text  beginning  with 
a  specified  line.  It  displays  the  lines  a 
character  at  a  time.  If  the  current  char¬ 
acter  position  is  marked  in  the  line’s 
header  block  as  the  position  of  a  key 
word,  the  program  calls  the  CURSES 
wpstandout  function  to  cause  the  word 
to  be  highlighted.  When  the  program 
finds  the  next  white  space  character,  it 
calls  the  CURSES  upstandend  function 
to  return  the  display  to  the  normal, 
non-highlighted  mode. 

Once  a  page  is  displayed,  the  pro¬ 
gram  reads  the  keyboard.  As  with  the 
file  selector  menu,  the  keystroke  val¬ 
ues  control  the  screen  display.  You  can 
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page  and  scroll  up  and  down,  and  you 
can  move  the  next  or  previous  page 
where  a  marked  key  word  appears. 
The  pagemarked  function  makes  this 
test,  finding  the  first  line  of  the  speci¬ 
fied  page  and  looking  at  each  entry  in 
the  list  to  see  if  any  line  has  a  marked 
key  word. 

When  you  press  the  ESC  key,  the 
function  calls  wclear  to  clear  the  text 
display  window  and  wrefresh  to  re¬ 
fresh  that  clearing  to  the  screen.  Then 
it  deletes  the  window  and  frees  the 
heap  of  the  linked  list  entries. 

Back  in  the  selectjtext  function  the 
file  selector  window  gets  redisplayed 
and  the  user  can  pick  out  another  file 
to  look  at. 

TEXTSRCH  Performance 

How  effective  is  the  CURSES  approach 
to  the  development  of  portable  code? 
The  proof  would  be  in  the  successful 
porting  of  a  program  such  as  this  one 
to  another  platform.  I  am  sure  that  this 
program  would  port  to  a  Unix  system 
with  no  more  fuss  than  I  had  moving 
it  to  Lattice  C.  There  is,  however,  one 
big  area  of  concern  in  such  a  move. 
We  do  not  know  how  efficiently  the 
program  would  operate.  CURSES  is  a 
technique  for  the  portability  of  screen 
driver  code  to  a  multitude  of  display 


devices.  Its  implementation  in  the  Lat¬ 
tice  library  makes  for  an  effective  and 
efficient  program  because  they  used  all 
the  PC  tricks  for  fast  screen  updates. 
What’s  more,  I  developed  this  program 
on  and  for  a  20-MHz  386  computer. 
The  only  way  to  know  how  well  or 
poorly  this  particular  use  of  CURSES 
would  work  on  a  slower  machine  or 
with  a  different  terminal  is  to  move  the 
program.  So,  with  that  in  mind,  I  moved 
TEXTSRCH  to  the  slowest  compatible 
computer  at  my  house,  an  8-MHz  COM¬ 
PAQ  II.  I  am  happy  to  report  that  it 
works  fine.  This  does  not,  however, 
qualify  it  for  an  environment  where  the 
terminal  device  is  a  serial  VDT.  I  would 
suspect  that  some  of  the  ways  I  used 
CURSES  are  not  the  best  choices  for 
such  a  setup.  A  seasoned  CURSES  pro¬ 
grammer  probably  knows  intuitively 
what  to  do  and  what  to  avoid  to  sup¬ 
port  the  most  effective  user  interface. 

The  collective  abilities  and  shortcom¬ 
ings  of  CURSES  across  a  wide  selection 
of  terminals  would,  no  doubt,  influ¬ 
ence  the  way  you  would  design  a  user 
interface.  Given  that  one  could  learn 
these  boundaries  and  with  all  this  in 
mind,  I  can  conclude  that  CURSES  is 
an  effective  technique  for  wide  plat¬ 
form  independence  of  text-based  screen 
management.  That,  of  course,  is  no 


news  to  Unix  programmers,  who  have 
had  CURSES  for  several  years.  It  is  news 
to  those  others  of  us  who  might  be 
looking  for  tidy  ways  to  develop  pro¬ 
grams  on  the  PC  that  can  be  moved  to 
other  operating  environments. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  144.) 

Vote  for  your  favorite  feature/artiole. 

Circle  Reader  Service  No.  11. 
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Sifting  for  Sharks’ 
Teeth 


Prowling  the  23  miles  of  aisles  at 
Comdex  Fall,  looking  for  program¬ 
mer  tools,  is  like  sifting  the  sand 
hills  over  in  Lockhart  Gulch  west 
of  Scotts  Valley,  looking  for  sharks’ 
teeth.  You  know  that  they’re  down 
there,  and  if  you  dig  long  enough  you’ll 
find  a  few.  However,  the  smart  guys 
run  down  to  New  Age  Annie’s  Kosmic 
Krystal  Koop  in  Santa  Cruz  and  buy 
one  of  the  nice  clean  sharks’  teeth  An¬ 
nie  keeps  in  a  “Save  the  Whales”  bowl 
next  to  the  two-for-a-dollar  tiger  eyes. 
Saves  a  heap  o’  diggin’  —  which  is  what 
you’re  doing  by  buying  this  magazine. 

Into  the  Outback 

What  wild  and  wonderful  programmer 
stuff  there  is  is  not  on  the  main  floor, 
by  and  large.  (Exceptions  might  in¬ 
clude  the  Microsoft  booth,  which  was 
the  size  of  a  small  county  in  Arkansas.) 
Finding  the  good  stuff  means  traipsing 
around  the  outlying  hotels  such  as  the 
Tropicana  and  Bally’s. 

The  #1  Neat  Comdex  Idea  for  pro¬ 
grammers  comes  from  two  different 
vendors,  who  solved  the  same  knotty 
problem  using  two  different  technolo¬ 
gies.  The  problem  is  a  common  one: 
Running  out  of  DOS  memory  while 
doing  a  build  on  a  large  application 
using  command-line  compilers  and  link¬ 
ers.  QuickPascal  has  this  problem  in 
spades;  for  all  its  many  virtues,  QP  uses 
memory  like  cheap  cologne  and  al¬ 
ways  runs  out  before  Turbo  Pascal. 
Even  a  memory  miser  such  as  Turbo 
will  run  out  eventually  if  you  hand  it  a 
big  enough  application. 


Jeff  Duntemann,  KI6RA 


Qualitas’  superb  386-to-the-MAX  nib¬ 
bles  on  the  problem  by  using  the  386’s 
hardware  memory  manager  to  remap 
some  of  386  extended  memory  down 
beneath  the  video  refresh  buffer.  You 
can  get  a  contiguous  DOS  memory  area 
as  large  as  704K  if  you’re  using  a  mono¬ 
chrome  display  adapter.  A  small  San 
Jose,  California  company  named  V 
Communications  takes  the  idea  much 


further,  by  moving  the  video  refresh 
buffer  entirely  to  some  other  location 
in  386  memory  and  making  BIOS  aware 
of  the  move.  Their  Memory  Commander 
product  can  give  you  as  much  as  924K 
of  contiguous  DOS  memory,  depend¬ 
ing  on  what  TSRs,  device  drivers,  and 
BIOS  software  needs  space  in  the  first 
megabyte. 

924K  is  an  extreme  case.  The  com¬ 
pany  says  a  typical  system  should  be 
able  to  have  about  860K  available  for 
compiles,  if  no  attempt  is  made  to  ad¬ 
dress  screen  memory  directly.  Because 
command-line  compilers  and  linkers 
typically  write  to  standard  output  rather 
than  the  refresh  buffer,  this  is  not  a 
problem.  And  860K  could  allow  you 
to  build  a  much  larger  app.  Think  of 
all  that  symbol  table  space  .  .  . 

Invisible  Software  of  Foster  City,  Calif, 
has  a  product  that  does  much  the  same 
thing,  only  they  use  a  little-known  and 
less-understood  feature  called  “shadow 
RAM,”  supported  by  several  of  the  Chips 
and  Technologies  VLSI  chip  sets  for 
286  and  386  motherboards.  Shadow 
RAM  is  present  only  in  those  machines 
using  those  chip  sets.  If  the  mother¬ 
board  is  equipped  with  a  minimum  1 
Mbyte  of  RAM,  (rather  than  the  canoni¬ 
cal  640K)  the  chip  set  can  map  portions 
of  that  RAM  where  it  needs  to.  The 
feature  was  developed  to  allow  the 
copying  of  code  from  slower  BIOS 
ROMs  into  faster  RAM  to  improve  per¬ 
formance,  but  it  can  also  map  RAM  into 
the  segment  space  between  $AOOO  and 
$B800  (assuming  you  don’t  have  a  mono¬ 
chrome  display  board)  giving  you  a 
contiguous  DOS  space  of  as  much  as 
736K.  So  while  the  Invisible  RAM  prod¬ 
uct  does  not  give  you  quite  as  much 
potential  space  as  Memory  Commander, 
it  has  the  advantage  of  working  in  the 
great  many  inexpensive  Asian  286  moth¬ 
erboards  that  use  the  Chips  chip  sets. 
(Memory  Commander,  remember,  is  a 
386-only  product.)  You  can  download 
a  test  program  from  Invisible  Software’s 
BBS  to  detect  and  report  on  whether 
you  have  the  necessary  chip  set  in  your 
system.  Call  them  for  details  if  you’re 
interested;  it’s  a  very  slick  product. 


Documentation  on  Demand 

The  #2  Neat  Comdex  Idea  for  pro¬ 
grammers  solves  an  ugly  logistical  prob¬ 
lem  facing  shareware  authors:  How  to 
provide  attractive  printed  documenta¬ 
tion  without  going  broke.  As  one  of  the 
inducements  to  registering  a  shareware 
package,  many  authors  offer  typeset 
printed  documentation.  The  catch  is 
that  manuals  cannot  be  printed  eco¬ 
nomically  in  batches  of  fewer  than  500 
or  so,  and  costs  don’t  really  go  down 
until  the  numbers  head  up  into  the  tens 
of  thousands. 

However,  when  you  punt  your  share¬ 
ware  creation  out  into  the  brave,  cold 
world,  you  have  no  idea  how  many 
registrations  you’re  likely  to  get.  Worse, 
products  generally  evolve  far  more 
quickly  than  500  manuals  are  likely  to 
be  needed,  leaving  authors  stuck  with 
piles  of  obsolete  manuals  that  are  fully 
paid  for  —  and  worthless. 

Workhorse  laser  printers  (especially 
HP’s  that  prints  on  both  sides  of  a  sheet 
at  once)  and  desktop  publishing  pack¬ 
ages  such  as  Ventura  Publisher  allow 
high-quality,  short-run  printed  output. 
What’s  needed  is  a  mechanism  to  bind 
loose  sheets  together  in  a  professional¬ 
looking  way,  and  at  Comdex  I  found 
one:  The  Unibind  binding  system. 

In  a  nutshell,  Unibind  works  like 
this:  The  sheets  to  be  bound  are  placed 
inside  a  plastic  or  card-stock  folder  with 
a  thermoplastic  adhesive  bar  running 
down  the  middle.  This  assemblage  is 
then  placed  in  a  toaster-gadget  that 
positions  the  sheets  and  cover  accu¬ 
rately,  and  heats  them  until  the  adhe¬ 
sive  melts  and  glues  the  sheets  together 
at  the  spine  and  the  spine  to  the  cover. 
The  system  can  bind  stacks  from  2 
sheets  to  650  sheets  in  size,  and  each 
volume  takes  about  45  seconds  to  bind. 

Systems  similar  to  this  have  been 
available  for  some  time,  but  the  ones 
I’ve  seen  and  used  (typically  from 
Cheshire)  are  extremely  messy  and 
mechanically  fragile.  Unibind  is  nei¬ 
ther;  the  bound  volumes  are  tidy  and 
show  no  loose  traces  of  adhesive,  and 
the  binder  device  has  far  fewer  moving 
parts  than  Cheshire  and  similar  systems. 
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Once  bound,  the  sheets  are  in  there  for 
the  long  haul;  I  was  unable  to  pull  any 
of  the  sheets  from  the  bound  volume 
without  tearing  them.  On  the  down¬ 
side,  the  system  has  significant  upfront 
costs,  and  the  per-piece  cost  of  the 
bound  volumes  is  higher  than  volumes 
printed  and  bound  at  a  printing  plant. 
However,  there  is  no  waste  and  no 
obsolescence,  because  the  system  truly 
allows  “documentation  on  demand.” 
You  print  what  you  need  as  you  need 
it,  folding  in  updates  as  they  happen, 
no  sooner,  no  later.  You  can  support 
several  low-volume  shareware  prod¬ 
ucts  without  going  broke  printing  500 
manuals  for  each  while  expecting  to 
sell  maybe  20  or  30  manuals  per  year. 

It’s  getting  tougher  and  tougher  all 
the  time  to  put  low-cost  specialty  soft¬ 
ware  products  on  the  market  and  make 
them  pay.  Shareware  is  our  last  best 
hope  in  this  regard,  and  Unibind  can 
help  solve  that  ugly  documentation  is¬ 
sue.  If  you’re  a  shareware  author  you 
ought  to  look  into  it. 

Stereo-On-A-Card 

The  #3  Neat  Comdex  Idea  for  pro¬ 
grammers  may  seem  a  little  loopy,  but 
it  solved  an  infuriating  problem  for  me 
and  may  solve  that  same  problem  for 
you  if  you’re  one  of  the  many  program¬ 
mers  who  listens  to  music  while  pro¬ 
gramming.  The  Desktop  Stereo  prod¬ 
uct  from  Optronics  of  Ashland,  Ore.  is 
a  half-sized  board  for  the  PC  bus  con¬ 
taining  a  world-class  FM  stereo  receiver 
and  4  watts  per  channel  amplifier.  There 
are  no  tuning  knobs  on  the  board 
bracket;  all  controls  are  done  electroni¬ 
cally,  through  pop-up  dialog  boxes  con¬ 
taining,  among  other  things  (dare  I  say 
it?)  radio  buttons.  You  can  view  the 
FM  band  as  a  graph  of  vertical  bars 
displaying  signal  intensity  at  various 
frequencies  (neat  touch!)  and  preset 
up  to  ten  frequencies  with  mnemonic 
names  such  as  “KRAP”  or  “Hillbilly 
Rock”  and  punch  them  up  like  buttons 
on  your  car  radio. 

The  problem  that  this  board  solves 
is  that  the  expensive  Japanese  CD- 
equipped  boom  boxes  that  many  of 
us  place  beside  our  RAM  charged  386 
boxes  leak  like  sieves.  Unless  your  fa¬ 
vorite  FM  station’s  towers  are  on  the 
next  block,  what  you’ll  hear  on  your 
FM  receiver  is  likely  to  be  your  ma¬ 
chine’s  switching  transients  playing  solo, 
and  that  is  dull  (if  powerful)  music.  I’d 
long  since  abandoned  FM  and  simply 
play  my  CDs.  The  FM  module  on  the 
Desktop  Stereo  card  is  extremely  well 
shielded  (it  had  better  be!)  and  abso¬ 
lutely  quiet  in  the  absence  of  signal 
modulation. 

Now  I  can  listen  to  PBS  again.  20 


plus  stations  accessible  from  fringey 
Scotts  Valley.  No  racket.  Jeff-Bob  says 
check  it  out. 

All  Set  with  Modulo 

Let’s  continue  our  discussion  of  the 
vice  president  of  Structured  Languages, 
Modula-2.  Will  Modula  ever  overtake 
Pascal  for  small  machines?  Probably 
not.  Unless  .  .  .  the  president  decides 
not  to  run  in  OS/2  land,  in  which  case 
the  race  gets  interesting.  Modula-2  is 
already  very  big  over  on  the  OS/2  side 
of  things,  second  (so  far  as  I  can  tell) 
only  to  You  Know  What.  If  this  contin¬ 
ues  for  a  few  more  years,  the  OS/2 
products  could  achieve  a  formidable 


critical  mass,  especially  since  Modula 
contains  standard  syntactic  support  for 
multitasking.  (More  on  that  very  thorny 
issue  when  I  get  OS/2  running  reliably 
on  this  sorry  excuse  for  a  386  machine.) 
If  you’re  contemplating  a  project  for 
OS/2,  ignore  those  C-sirens  claiming 
that  C  is  the  only  way  to  go.  You  can 
do  very  well  with  Modula-2,  according 
to  sources  that  I  trust.  Someday  I’ll  know 
from  firsthand  experience,  sigh. 

No,  in  this  issue  we’re  going  to  talk 
about  sets.  Sets  are  what  drove  me  out 
of  Modula-2  several  years  ago.  When 
the  language  spec  was  first  released  I 
jumped  on  it,  with  full  intent  to  port 
over  my  disks  full  of  code,  written  in 
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the  faltering  corpse  of  Pascal/MT+  for 
CP/M-80.  I  dug  in  and  discovered  sev¬ 
eral  days  into  the  project  that  I  couldn’t 
do  it.  My  code  was  absolutely  pep¬ 
pered  with  the  killer  type  definition: 

TYPE 

CharSet  =  SET  OF  Char; 

Uh-uh,  said  the  compiler.  Sets  in  Modula-2 
may  have  no  more  than  16  elements. 

This  is  a  serious  semantic  bite  in  the 
buns.  Sets  work  well  for  me  and  I  use 
them  a  lot,  especially  for  building  sys¬ 
tems  to  handle  characters  moving  from 
one  place  to  another,  as  from  the  key¬ 
board  to  the  screen  or  from  a  serial 
port  to  the  screen  or  to  a  disk  file.  Like 
Maxwell’s  Demon,  a  set  is  a  filter  that 
can  pass  odd  characters  among  the 
ASCII  throng  while  denying  passage 
to  others  in  a  group  just  as  odd.  Con¬ 
sider  the  elegance  of  this  classic  con¬ 
struct: 

IF  AnswerChar  IN  [‘Y’,‘y’] 

THEN  Dolt  ELSE  DontDoIt; 

The  alternative  is  this: 

IF  (AnswerChar  =  ‘Y’)  OR 
(Answer-Char  =  ‘y’) 

THEN  .  .  . 

You  might  argue  that  the  second  form 
resolves  to  fewer  machine  instructions, 
and  I’d  argue  back  that  you’re  rarely 
going  to  have  to  execute  17,000  such 
tests  in  a  tight  loop.  Furthermore,  what 
about  this: 

IF  IncomingChar  IN  WhiteSpaceSet 
THEN . .  . 

There’s  simply  nothing  like  sets  for  char¬ 
acter  filters  such  as  this.  It  was  just 
possibly  possible  in  some  cases  to  pull 
tricks  with  subranges  of  fewer  than  16 
characters,  but  the  whole  notion  of¬ 
fended  me:  Niklaus  Wirth  threw  char¬ 
acter  sets  out  the  window  to  make  it 
easier  to  implement  Modula-2.  There 
are  maybe  two  or  three  hundred  po¬ 
tential  Modula-2  compiler  implemen¬ 
tors  in  this  world.  There  are  hundreds 
of  thousands  of  potential  Modula-2  pro¬ 
grammers.  One  suspects  he  skipped 
Marketing  101  as  an  undergrad. 

About  then  Turbo  Pascal  happened, 
and  Modula-2  slipped  into  eclipse  for 
some  years.  Logitech  held  the  torch 
alight  all  that  time,  but  their  product, 
while  solid,  was  complex  and  slow 
and  admittedly  intended  for  internal 
use.  It  wasn’t  until  JPI  introduced 
TopSpeed  Modula-2  that  the  language 
showed  any  serious  life.  Soon  after¬ 
ward,  the  Stony  Brook  compiler  made 
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its  debut,  and  I’ve  begun  to  do  some 
serious  work  in  Modula  again. 

The  reason  is  pretty  simple:  TopSpeed 
and  Stony  Brook  have  done  the  Awful 
Thing:  Extended  Modula-2  by  allowing 
sets  to  have  as  many  as  65,536  ele¬ 
ments.  Horrors.  You  might  not  be  able 
to  port  your  dog  kennel  management 
package  to  the  Lilith  operating  system. 
It  is  to  cry  real  tears. 


Niklaus  Wirth  threw 
character  sets 
out  the  window 


Duntemann's  One  Law  of  Portability 

Remember  this,  chilluns:  For  any  plat¬ 
form  with  I/O  more  complex  than  a 
batch  system,  semantic  differences  be¬ 
tween  platforms  makes  portability  im¬ 
possible.  In  other  words,  even  if  you 
wrote  your  character-based  PC  kennel 
manager  in  absolutely  standard  Modu¬ 
la-2,  could  you  port  it  to  the  Macintosh? 
If  you  had  written  it  for  multiple  termi¬ 
nals  under  Unix,  could  you  port  it  to 
DOS?  Get  real  —  the  effort  spent  re¬ 
solving  semantic  conflicts  would  far 
outweigh  trifles  like  the  shape  of  an  IF 
statement. 

So  let’s  quit  arguing  about  some¬ 
thing  that’s  never  been  worth  a  plugged 
nickel  outside  of  academe  anyway. 

Watch  the  Corral,  Not  the  Cows! 

A  set  is  an  abstraction  of  a  group  of 
values,  indicating  whether  one  or  more 
of  those  values  are  present  or  not  pre¬ 
sent.  It’s  like  a  corral  on  a  farm  with 
seven  cows;  at  any  given  time  a  cow  is 
either  in  the  corral  or  not.  The  cows  are 
in  no  particular  order  within  the  corral. 
They’re  either  there  or  else  out  making 
things  for  the  unwary  to  step  in. 

It’s  important  to  remember  that  the 
set  is  not  the  cows;  the  set  is  the  corral. 
It’s  still  a  set  even  when  it  is  empty. 

In  Modula-2,  a  set  is  defined  in  terms 
of  some  ordinal  type  or  subrange  of 
an  ordinal  type,  including  enumera¬ 
tions  such  as  the  insufferable  list  of 
colors  that  every  writer  on  the  subject 
(myself  included)  has  used  in  books 
explaining  the  concept: 

TYPE 

Colors  =  (Red,  Orange, 

Yellow,  Green,  Blue,  Indigo, 

Violet); 

WarmColors  =  [Red  .  .  Yellow]; 

ColorSet  =  SET  OF  Colors; 


WarmSet  =  SET  OF  WarmColors; 
CardSet  =  [0..655351 

CharSet  =  SET  OF  CHAR;  (*  Yay!  *) 

Beneath  it  all,  in  physical  memory,  a 
set  is  a  bitmap.  There  is  one  bit  in  the 
set  for  each  value  that  may  legally  be 
present  in  the  set.  Each  bit  carries  one 
Boolean  fact:  Whether  the  value  that 
the  bit  stands  for  is  present  or  not  pre¬ 
sent  in  the  set.  Adding  a  value  to  the 
set  is  done  by  raising  that  value’s  bit  to 
binary  1.  Removing  a  value  from  the 
set  is  done  by  changing  that  value’s  bit 
back  to  a  binary  0. 

A  “full”  set  (that  is,  one  having  all 
values  present)  is  not  one  bit  larger 
than  an  empty  set.  Again,  the  set  is  the 
corral,  not  the  cows! 

Set  Operators 

There  are  a  number  of  operators  and 
standard  procedures  that  work  on  sets 
in  Modula-2.  The  two  most  obvious  are 
INCL,  which  places  a  value  in  a  set,  and 
EXCL ,  which  removes  a  value  from  a 
set.  These  are  not  present  in  Pascal.  IN 
is  still  there,  doing  exactly  what  it  does 
in  Pascal:  Return  a  Boolean  value  indi¬ 
cating  whether  the  value  on  the  left  is 
present  in  the  set  on  the  right.  Ditto 
>=  (set  inclusion,  right  in  left),  and  <= 
(set  exclusion,  left  in  right)  which  do 
much  the  same  but  for  whole  sets:  >= 
returns  TRUE  if  all  values  of  the  set  on 
its  right  are  present  in  the  set  on  its  left; 
and  <=  returns  TRUE  if  all  values  in  the 
set  on  its  left  are  present  in  the  set  on 
its  right. 

There  are  actually  only  four  opera¬ 
tors  that  are  true  set  operators  in  that 
they  act  on  sets  and  return  sets:  +  (set 
union)  -  (set  difference)  *  (set  intersec¬ 
tion)  and  /  (set  symmetric  difference). 
Of  these,  only  the  first  three  are  present 
in  Pascal. 

Set  union  of  two  sets  returns  the  set 
that  contains  all  the  elements  present 
in  both  of  the  sets  taken  as  one.  Set 
intersection  of  two  sets  returns  the  set 
of  values  that  are  present  in  both  sets, 
but  none  of  those  values  that  may  be 
present  in  one  or  the  other  but  not 
both. 

Set  difference  is  a  little  trickier;  my 
Pascal  prof  explained  it  badly  (getting 
it  mixed  up  with  symmetric  difference, 
see  below)  and  I  misunderstood  it 
through  ten  years  and  two  editions  of 
my  book.  Set  difference  of  two  sets 
returns  the  set  that  consists  of  the  ele¬ 
ments  in  the  set  on  the  left  once  those 
in  the  set  on  the  right  have  been  re¬ 
moved  from  it. 

Basically,  set  difference  is  a  way  of 
pulling  several  elements  out  of  a  set 
without  using  EXCL  to  do  it  one  ele¬ 
ment  at  a  time: 
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(continued  from  page  136) 

This  set  expression  returns  the  set 
l‘A’..‘L’l.  (Keep  in  mind  that  Modula-2 
uses  curly  brackets  for  set  constructors 
rather  than  straight  brackets.) 

Finally,  set  symmetric  difference 
(which  is  not  in  any  Pascal  implemen- 

Remember  that  the  set 
is  not  the  cows;  the  set 
is  the  corral 


tation  I’m  aware  of)  is  rather  like  set 
union  turned  inside  out.  The  symmet¬ 
ric  difference  of  two  sets  is  the  set  of 
all  elements  that  are  present  in  one  or 
the  other  set,  but  not  in  both  sets.  In  a 
sense,  the  symmetric  difference  of  two 
sets  is  what  the  two  sets  don’t  have  in 
common;  for  example,  what  remains 
once  their  intersection  (overlap)  has 
been  removed. 

Among  them,  these  operators  allow 
you  to  do  just  about  anything  with  a 
set  that  you’d  ever  want  to  do.  And 
now  that  sets  can  have  up  to  65,535 
elements  in  Modula-2,  that’s  a  lot. 

The  Naked  Set 

Wirth’s  original  language  definition  did 
not  hard-code  16  as  the  number  of 
elements  in  a  set.  The  number  of  ele¬ 
ments  in  a  Modula-2  set  was  originally 
defined  as  the  number  of  elements  in 
the  machine  word  used  by  the  system 
for  which  the  compiler  was  imple¬ 
mented.  In  other  words,  in  a  system 
with  a  32-bit  word  there  would  be  32 
possible  elements  in  a  Modula-2  set. 

This  makes  those  limited  set  opera¬ 
tions  very  easy  to  implement,  and  very 
fast,  because  they  can  be  done  using 
the  native  bit-manipulation  instructions 
present  in  all  modern-day  CPUs.  Re¬ 
member  that  sets  are  bitmaps.  Further¬ 
more,  the  four  true  set  operators  bear 
a  certain  uncanny  functional  resem¬ 
blance  to  certain  logical  operators  such 
as  AND,  OR,  and  XOR. 

OR  the  bits  of  two  sets  together  and 
whammo,  suddenly  you  have  the  un¬ 
ion  of  the  two  sets.  AND  the  bits  of  two 
sets  together,  and  what  remains  is  the 
intersection  of  the  two  sets.  AND  the 
bits  of  one  set  with  the  complement 
(reversed)  bits  of  another  set,  and  you 
remove  the  bits  of  the  complemented 
set  from  the  other  set,  that  is,  set  differ- 
I  ence.  Finally,  XOR  the  bits  in  two  sets 


together  and  what’s  left  are  the  bits 
that  are  present  in  one  set  or  the  other 
but  not  in  both  sets,  since  XOR  drives 
identical  bit  pairs  to  0.  Voila:  Symmetric 
set  difference. 

This  is,  of  course,  exactly  what  Wirth 
intended,  and  he  intended  for  it  all  to 
happen  within  the  accumulator  of  the 
host  CPU,  ensuring  speed  and  minimal 
fussing.  Happily,  in  this  brave  new 
world  of  fast  global  optimizing  compil¬ 
ers  (Stony  Brook’s  is  fabulous)  we  can 
have  it  both  ways:  When  we’re  fiddling 
small  sets  we  can  do  it  fast  at  one  shot 
inside  the  accumulator;  when  we’re  fid¬ 
dling  big  sets  we  can  do  it  a  word  at  a 
time  and  take  the  performance  hit. 

Now,  Wirth  defined  a  specific  kind 
of  set  that  has  no  true  analog  in  Pascal: 
BITSET,  a  standard  type  supported  in 
all  Modula-2  compilers.  A  BITSET  is  a 
machine  word  used  as  a  bitmap.  All  of 
the  set  operators  operate  on  BITSET 
values.  A  BITSETs  nominal  values  are 
0  .  .  15,  but  these  are  bit  numbers  more 
than  values.  A  BITSET  is  thus  a  sort  of 
naked  set,  in  which  the  bitmap  nature 
of  the  set  is  laid  bare  and  can  be  ma¬ 
nipulated  directly.  A  bit  in  a  BITSET 
does  not  abstract  a  color,  or  a  charac¬ 
ter,  or  a  cardinal  number,  or  a  cow;  a 
bit  in  a  BITSET  represents  a  bit,  period. 

Twiddling  Bits  in  Other  Types 

With  very  little  futzing,  this  fills  an  ap¬ 
parent  gap  in  Modula-2:  The  lack  of 
explicit  bit-manipulation  facilities.  Turbo 
Pascal  has  explicit  bitwise  AND,  OR, 
NOT,  and  XOR  operators  for  numeric 
ordinal  types,  and  it  can  also  shift  bits 
in  numeric  ordinal  values  with  its  SHR 
and  SHL  operators.  Modula-2  has  none 
of  these  ...  or  does  it? 

It  does  .  .  .  but  they  only  operate  on 
values  of  type  BITSET. 

No  problem  —  just  ask  Pizza  Terra. 
(For  those  unfamiliar  with  the  refer¬ 
ence,  see  my  May  1989  column.) 
Modula-2  has  explicit  type  casting 
(which  Wirth  calls  type  coercion),  so 
if  you  want  to  fiddle  bits  in  type  CHAR, 
cast  type  CHAR  onto  type  BITSET,  and 
fiddle  away!  Any  type  can  be  cast  onto 
any  other  type  of  identical  size,  and 
there  are  transfer  functions  such  as  Ord 
to  cast  8-bit  types  like  CHAR  and 
BOOLEAN  onto  16-bit  types  like  CAR¬ 
DINAL 

For  example,  to  AND  a  CARDINAL 
variable  MyCard  with  the  value  128, 
you  could  do  this: 

NewCard  := 

CARDINAL(BITSET 

(MyCard)  *  BITSET(128)); 

Here,  MyCard  and  the  value  128  are 
(continued  on  page  141) 
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(continued  from  page  138) 
both  cast  onto  BITSETs ,  which  are  then 
ANDe d  together  by  using  the  set  inter¬ 
section  operator,  which  is  equivalent 
(on  a  bit  level)  to  AND.  Finally,  the 
result  of  the  set  intersection  operation 
is  cast  back  onto  a  CARDINAL  for  as¬ 
signment  to  the  CARDINAL  variable 
NewCard. 

This  works  .  .  .  but  it  sure  as  hell  isn’t 
obvious.  Unfortunately,  in  Modula  this 
is  how  the  game  is  played.  Better  to 
disguise  all  this  arm-twisting  of  types 
(coercion  is  such  a  lovely  word!)  be¬ 
hind  some  procedures  with  more  mne¬ 
monic  names.  This  is  what  I’ve  done 
in  the  listings  for  this  column,  which 
present  a  Modula-2  module  called  Bit¬ 
wise.  Listing  One,  page  150,  is  the  defi¬ 
nition  module  for  Bitwise ,  and  Listing 
Two,  page  150,  is  the  implementation 
module. 

Bitwise  provides  function  procedures 
to  perform  bitwise  AND,  OR,  XOR,  and 
NOT  operations.  (See  Table  1.)  Note 
that  the  capitalization  is  different  from 
that  used  here  in  the  descriptive  text, 
in  order  to  differentiate  my  procedure 
And  from  the  existing  (and  incompat¬ 
ible)  Boolean  logical  operator  AND. 
(Case  is  significant  in  Modula-2,  and 
this  is  the  first  time  in  my  career  I’ve 
caught  myself  being  glad.  Crazy  world, 
ain’t  it?)  Additionally,  Bitwise  contains 
procedures  to  set,  clear,  and  test  indi¬ 
vidual  bits,  and  also  to  shift  values  right 
or  left  by  up  to  16  bits.  This  suite  of 
routines  provides  roughly  the  same  bit¬ 
banging  power  you  get  stock  in  Turbo 
Pascal.  This  seems  to  be  the  lot  of 
Modula-2  programmers:  To  perpetu¬ 
ally  build  what  those  Turbo  guys  have 
come  to  take  for  granted! 

The  formal  parameters  for  all  of  the 
routines  in  Bitwise  are  type  CARDINAL, 
because  CARDINAL  is  the  unsigned  16- 
bit  numeric  type  in  Modula-2,  equiva- 
alent  to  Word  in  Turbo  Pascal.  It’s  a 
good  basic  foundation  upon  which  to 
cast  all  other  ordinal  types  in  Modula-2. 
(And  it’s  used  quite  a  bit  by  itself.)  If 
you  want  to  set  bit  number  3  in  a  char¬ 
acter,  for  example,  you  could  do  this: 

NewChar  := 

CHAR(SetBit(ORD(‘A’),3)); 

The  ORD  transfer  function  casts  the 
character  value  onto  a  CARDINAL  value 
for  passing  to  the  SetBit  function  pro¬ 
cedure,  and  finally  the  CARDINAL  value 
returned  by  SetBit  is  cast  back  onto  a 
character  for  assignment  to  NewChar. 

Read  over  the  code  implementing 
Bitwise  and  it  all  makes  sense  to  you. 
Again,  understand  type  casting/coer¬ 
cion  and  you’ve  got  it  in  your  hip 
pocket. 


When  Words  Runneth  Over 

There  is  something  a  little  bit  hazard¬ 
ous  about  Bitwise.  The  SHR  and  SHL 
routines  can  cause  overflow  errors  if 
you  shift  bits  to  the  extent  that  1-bits 
roll  out  of  either  side  of  the  1 6-bit  word 
in  which  they  exist.  Stony  Brook  Modu¬ 
la-2  code  checks  for  overflow  errors 
and  will  crash  your  program  when  you 
shift  bits  out  of  the  word  they  live  in. 

Now,  shifting  bits  off  the  edge  of 
their  word  is  not  necessarily  a  bad  thing. 
Sometimes  you  do  it  deliberately  to  get 
rid  of  the  bits  in  question.  There’s  noth¬ 
ing  inherently  damaging  about  it,  be¬ 
cause  on  a  machine  level  the  bits  get 
shunted  first  into  the  carry  flag  and 
then  off  into  nothingness.  (What  we 
affectionately  call  “the  bit  bucket.”)  Ad¬ 
jacent  data  is  never  overwritten,  no 
matter  if  we  try  to  shift  a  bit  by  (a 
meaningless)  245  positions. 

The  way  out  is  to  turn  off  overflow 
error  checking.  Enter  here  one  of  my 


Table  1:  Relating  bitwise  operators  to 


major  arguments  with  Modula-2:  For 
portability’s  sake  (gakkh!)  there  are  no 
compiler  toggles.  Turbo  Pascal  has  a 
whole  raft  of  them,  things  like  !$R~) 
and  so  on.  The  situation  would  seem 
to  call  for  bracketing  the  SHR  and  SHL 
routines  between  compiler  toggles  that 
switch  overflow  checking  off  only  for 
the  duration  of  the  routine,  then  on 
again  once  the  routine  terminates. 

Sorry,  Charlie.  As  every  good  tuna 
fish  knows,  compiler  toggles  are  im¬ 
plementation  dependent  and  destroy 
the  prospects  for  portability.  Lord 
knows,  we  can’t  have  that,  now,  can 
we?  The  best  that  can  be  done  with  the 
Stony  Brook  compiler  is  to  turn  off 
overflow  checking  entirely  within  the 
Bitwise  module  by  changing  the  com¬ 
pile  options  on  a  by-module  basis.  Be 
sure  to  do  this  when  you  compile  and 
use  Bitwise*.  If  you’re  using  a  Modula 
compiler  in  which  overflow  checking 
cannot  be  turned  off,  you’d  better  add 


operations 


Bitwise  operators 

Set  operation 

AND 

* 

Intersection 

OR 

+ 

Union 

XOR 

/ 

Symmetric  difference 

NOT 

{0..15}  -  BITSET 

“Full”  set  -  target  set 
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safety  belts  to  any  code  that  uses  SHL 
and  SHR. 

The  Boss  DOS  Book 

There  is  a  certain  type  of  book  I  call  a 
“category  killer;”  it’s  the  book  on  a 
certain  subject  and  tends  to  keep  other 
books  of  its  type  from  being  published. 
One  of  these  is  Ray  Duncan’s  Advanced 
MS-DOS  (Microsoft  Press),  a  book  that 
has  never  been  very  far  from  my  left 
hand  while  sitting  in  this  particular  chair. 
I’m  pleased  to  report  that  Ray  has  com¬ 
pany,  in  the  form  of  Que  Corporation’s 
DOS  Programmer's  Reference,  by  Terry 
Dettmann.  On  892  pages  Terry  has  man¬ 
aged  to  summarize  every  BIOS  func¬ 
tion  through  PS/2,  every  DOS  call 
through  V4.0,  all  mouse  function  calls, 
all  EMS  function  calls,  and  a  blizzard 
of  other  information  including  low- 
level  disk  structure,  device  driver  and 
interrupt  programming,  serial  port  pro¬ 
gramming,  and  lots  more. 

The  very  best  part  about  this  book, 
however,  may  well  be  its  index.  Hav¬ 
ing  892  pages  of  information  is  small 
comfort  if  you  can’t  find  anything  when 


Products  Mentioned 

Memory  Commander 
V  Communications 
3031  Tisch  Way,  Ste.  802 
San  Jose,  CA  95128 
408-296-4224 
$129.95 

Invisible  RAM 
Invisible  Software 
1165  Chess  Drive,  Ste.  D 
Foster  City,  CA  94404 
415-570-5967 
$39.95 

Unibind 

Unibind  Systems 
7900  Capwell  Drive 
Oakland,  CA  94621 
415-638-1060 

Various  configurations  and  prices 
Contact  the  vendor  for  specifics 

Desktop  Stereo 
Optronics  Technology 
P.O.  Box  3239 
Ashland,  OR  97520 
503-488-5040 
$199 

DOS  Programmer's  Reference, 

2nd  edition 

Terry  Dettmann,  revised  by  Jim  Kyle 
Que  Corporation,  1989 
ISBN  0-88022-458 -4 
Softcover,  892  pages,  $27.95 
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you  need  it  in  a  hurry.  The  index  occu¬ 
pies  33  pages,  with  about  100  citations 
per  page,  set  small  in  two  columns. 
Everything  I  tried  to  look  up  was  either 
indexed  or  not  covered  in  the  book. 
(And  things  that  weren’t  covered  really 
shouldn’t  have  been  anyway,  like  VGA 
hardware  architecture  details.) 

Altogether,  the  best  hacker’s  book 
to  cross  my  desk  in  a  good  long  while. 
Get  it. 

Dredging  the  Channel 

There  are  millions  —  nay,  tens  of  mil¬ 
lions  —  of  DOS  machines  out  there, 
and  various  research  reports  I’ve  seen 
indicate  that  the  greatest  growth  poten¬ 
tial  lies  in  machines  of  modest  cost  and 
capabilities:  The  “bare  bone”  88  and 
286  clones  that  fill  Computer  Shopper 
to  a  depth  of  800+  pages  every  month. 
There  are  already  30  million  of  them 
(conservative  estimate)  and  in  another 
few  years  there  could  be  as  many  as 
100  million  of  them  out  there,  plugging 
away.  This  is  an  utterly  unbelievable 
market  for  software  products,  and  yet 
the  distribution  channel  has  closed  up 
to  the  point  that  a  small-time  operator 
(like  most  of  us)  has  no  chance  to  make 
those  millions  of  people  even  aware 
of  the  existence  of  their  products. 

There  has  got  to  be  a  way.  Any  ideas? 
Pass  them  by  me.  I’ll  be  talking  about 
this  subject  in  future  months,  and  I’ll 
share  some  guerrilla  marketing  con¬ 
cepts  I’ve  devised,  and  will  discuss  how 
the  little  guys  can  shove  some  very  big 
rear  ends  out  of  their  monopoly  posi¬ 
tion  in  the  retail  channel. 

Write  to  Jeff  Duntemann  on  MCI  Mail 
as  JDuntemann,  or  on  CompuServe  to 
ID  76117,1426. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  150.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  12. 
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Listing  One  (Text  begins  on  page  127.) 


dir.h - */ 


/*  Substitute  Lattice  directory  functions  for 
*  Turbo  C  directory  functions 


♦include  <dos.h> 


♦define  ffblk  FILEINFO 
♦define  ff  name  name 


♦define  findfirst (path, ff , attr)  dfind(ff,path,attr) 
♦define  findnext(ff)  dnext(ff) 


End  Listing  One 


Listing  Two 


- search,  c - */ 

the  TEXTSRCH  retrieval  process 


*/ 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  <curses.h> 

♦include  "textsrch.h" 

static  char  fnames [MAXFILES]  [65]; 
static  int  fctr; 


file_selector,  int  pg) ; 


static  void  select_text (void) ; 
static  void  display_page (WINDOW 
void  display_text (char  *fname) ; 

/*  -  process  the  result  of  a  query  expression  search  -  */ 

void  process_result (struct  bitmap  mapl) 

( 

int  i; 

extern  int  file_count; 
for  (i  =  0;  i  <  file_count;  i++) 
if  (getbit (&mapl,  i)) 

strncpy (fnames [fctr++] ,  text_f ilename (i) ,  64); 
initscrO;  /*  initialize  curses  */ 

select_text () ;  /*  select  a  file  to  view  */ 

endwinO;  /*  turn  off  curses  */ 

fctr  =  0; 


/*  -  search  the  data  base  for  a  word  match  ■ 

struct  bitmap  search (char  *word) 


struct  bitmap  mapl; 

memset (&mapl,  Oxff,  sizeof  (struct  bitmap)); 
if  (srchtree (word)  !=  0) 

mapl  =  search_index (word) ; 
return  mapl; 


♦define  HEIGHT  8 
♦define  WIDTH  70 
♦define  HOMEY  3 
♦define  HOMEX  3 

♦define  ESC  27 

/*  —  select  text  file  from  those  satisfying  the  query  -  */ 

static  void  select_text (void) 

{ 

WINDOW  *file_selector; 

int  selector  =  0;  /*selector  cursor  relative  to  the  table  */ 

int  cursor  =  0;  /‘selector  cursor  relative  to  the  screen*/ 

int  keystroke  =  0; 

/*  —  use  a  window  with  a  border  to  display  the  files  —  */ 
file_selector  =  newwin (HEIGHT+2,  WIDTH+2,  HOMEY,  HOMEX); 

keypad (file_selector,  1);  /*  turn  on  keypad  mode  */ 

noecho ();  /*  turn  off  echo  mode  */ 

wsetscrreg (file_selector,  1,  HEIGHT);/*  set  scroll  limits  */ 

/* - display  the  first  page  of  the  table - */ 

display_page (file_selector,  0) ; 

while  (keystroke  !=  ESC)  { 

/* - draw  the  window  frame - */ 

box (file_selector,  VERT_DOUBLE,  HORIZJXXJBLE)  ; 

/* - fill  the  selector  window - */ 

mvwaddstr (file_selector,  cursor+1,  1,  "->"); 
wref resh (file_selector) ; 

/* - - make  a  selection - */ 

keystroke  =  wgetch (file_selector) ; /*  read  a  keystroke  */ 
mvwaddstr (file_selector,  cursor+1,  1,  "  ") ; 

switch  (keystroke)  { 
case  KEYJIOME: 

/* - Home  key  (to  top  of  list)  - */ 

selector  =  cursor  =  0; 


display_page (file_selector,  0) ; 
break; 

case  KEY_END : 

/* - End  key  (to  bottom  of  list) 

selector  =  fctr  -  HEIGHT; 
if  (selector  <  0)  { 

selector  =  0; 
cursor  =  fctr-1; 

} 

else 

cursor  =  HEIGHT-1; 

display_page (file_selector,  selector) ; 
break; 


case  KEY_D0WN : 

/*  -  down  arrow  (move  the  selector  cursor)  — 

/* - test  at  bottom  of  list - 

if  (selector  <  fctr-1)  { 
selector++; 

/* - test  at  bottom  of  window - 

if  (cursor  <  HEIGHT-1) 
cursor++; 
else  ( 

/*  -  scroll  the  window  up  one  - 

scroll (file_selector) ; 

/*  —  paint  the  new  bottom  line  - 

mvwprintw(file_selector,  cursor+1,  3, 
fnames [selector] ) ; 


) 

break; 

case  KEY_UP : 

/*  —  up  arrow  (move  the  selector  cursor)  — 

/* - test  at  top  of  list - 

if  (selector)  ( 

— selector; 

/* - test  at  top  of  window - 

if  (cursor) 

— cursor; 
else  ( 

/*  -  scroll  the  window  down  one  — 

winsertln(file_selector) ; 

/*  -  paint  the  new  top  line  - 

mvwprintw (file_selector,  1,  3, 
fnames [selector] ) ; 

} 

} 

break; 
case  ' \n' : 

/*  —  user  selected  a  file,  go  display  it  — 

display_text (fnames [selector] ) ; 

break; 


case  ESC: 
/* 

break; 


exit  from  the  display 


default : 

/*  -  invalid  keystroke 

beep  ( ) ; 
break; 


delwin (file_selector) ; 
clear () ; 
refresh))  ; 


/*  delete  the  selector  window  */ 
/*  clear  the  standard  window  */ 


/*  -  display  a  page  of  the  file  selector  window  - 

static  void  display_page (WINDOW  ‘file  selector,  int  line) 

{ 

int  y  =  0; 

werase (file_selector) ; 

while  (line  <  fctr  &&  y  <  HEIGHT) 

mvwprintw (file_selector,  ++y,  3,  fnames [line++] ) ; 


End  Listing  Two 


Listing  Three 


display. c 


*/ 


Display  a  text  file  on  the  screen. 

User  may  scroll  and  page  the  file. 

Highlight  key  words  from  the  search. 

User  may  jump  to  the  next  and  previous  key  word. 


♦include  <stdio.h> 
♦include  <stdlib.h> 
♦include  <curses.h> 
♦include  <ctype.h> 
♦include  <string.h> 
♦include  "textsrch.h" 
♦define  ESC  27 


/* 


header  block  for  a  line  of  text 


struct  textline  { 


(continued  on  page  146) 
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Listing  Three  (Listing  continued,  text  begins  on  page  127.) 

char  keys [5];  /*  offsets  to  key  words  */ 

struct  textline  *nextline;  /*  pointer  to  next  line  */ 
char  text;  /*  first  character  of  text  */ 

}; 

/*  - listhead  for  text  line  linked  list - */ 

struct  textline  *firstline; 
struct  textline  *lastline; 

int  pagemarked (int  topline); 

static  void  do_display (FILE  *fp) ; 

static  void  findkeys (struct  textline  *thisline) ; 

static  void  display_textpage (WINDOW  *text_window,  int  line); 

/* - display  the  text  in  a  selected  file - */ 

void  display_text (char  *filepath) 

{ 

FILE  *fp; 

fp  =  fopen(filepath,  "r"); 
if  (fp  ! =  NULL)  { 
do_display (fp) ; 
f close (fp) ; 

} 

else  { 

/* - the  selected  file  does  not  exist - */ 

char  ermsg [80]; 

sprintf (ermsg,  "%s:  No  such  file",  filepath) ; 
error_handler (ermsg) ; 

) 

) 

static  void  do_display (FILE  *fp) 

( 

char  line [120]; 

WINDOW  *text_window; 

int  keystroke  =  0; 

int  topline  =  0; 

int  linect  =  0; 

struct  textline  *thisline; 

firstline  =  lastline  =  NULL; 

/* - read  the  text  file  into  the  heap - */ 

while  (fgets(line,  sizeof  line,  fp)  !=  NULL)  ( 
line [78]  =  '\0'; 
thisline  = 

malloc (sizeof (struct  textline) +strlen (line) +1) ; 
if  (thisline  ==  NULL) 

break;  /*  no  more  room  */ 

/* - clear  the  text  line  record  space - */ 

memset (thisline,  '\0',  sizeof (struct  textline)  + 
strlen (line) +1)  ; 

/*  -  build  the  text  line  linked  list  entry  -  */ 

if  (lastline  !=  NULL) 

lastline->nextline  =  thisline; 
lastline  =  thisline; 
if  (firstline  ==  NULL) 

firstline  =  thisline; 
thisline->nextline  =  NULL; 
strcpy (&thisline->text,  line);- 

/* - mark  the  key  words - */ 

findkeys (thisline) ; 
linect++; 

) 

/* - build  a  window  to  display  the  text - */ 

text_window  =  newwin (LINES,  COLS,  0,  0) ; 

keypad (text_window,  1);  /*  turn  on  keypad  mode  */ 

while  (keystroke  !=  ESC)  ( 

/*  —  display  the  text  and  draw  the  window  frame  —  *7 
display  textpage (text_window,  topline); 
box (text_window,  VERT_S INGLE,  HORIZ_SINGLE) ; 
wrefresh (text_window) ; 

/* - read  a  keystroke - */ 

keystroke  =  wgetch(text_window) ; 
switch  (keystroke)  { 
case  KEY  HOME: 


/* - Home  key  (to  top  of  file)  - */ 

topline  =  0; 
break; 


case  KEY_DOWN : 

/*  -  down  arrow  (scroll  up)  -  */ 

if  (topline  <  linect- (LINES-2) ) 
topline++; 
break; 

case  KEY_UP : 

/* - up  arrow  (scroll  down)  - */ 

if  (topline) 

— topline; 
break; 

case  KEY_PGUP : 

/* - PgUp  key  (previous  page)  - */ 

topline  -=  LINES-2; 
if  (topline  <  0) 
topline  =  0; 
break; 

case  KEY_PGDN : 

/* - PgDn  key  (next  page)  - */ 

topline  +=  LINES-2; 
if  (topline  <=  linect- (LINES-2) ) 
break; 

case  key  end:  (continued  on  page  148) 
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Listing  Three  ( Listing  continued,  text  begins  on  page  127.) 

/* - End  key  (to  bottom  of  file)  - */ 

topline  =  linect- (LINES-2) ; 
if  (topline  <  0) 
topline  =  0; 
break; 

case  KEY_RIGHT: 

/*  -  Right  arrow.  Go  to  next  marked  key  word  */ 
do  ( 

/*  —  repeat  PGDN  until  we  find  a  mark  —  */ 
topline  +=  LINES-2; 
if  (topline  >  linect- (LINES-2) )  { 
topline  =  linect- (LINES-2) ; 
if  (topline  <  0) 
topline  =  0; 

) 

if  (pagemarked (topline) ) 
break; 

)  while  (topline  && 

topline  <  linect- (LINES-2) ) ; 

break; 

case  KEYLEFT: 

/*  Left  arrow.  Go  to  previous  marked  key  word  */ 
do  { 

/*  --  repeat  PGUP  until  we  find  a  mark  —  */ 
topline  -=  LINES-2; 
if  (topline  <  0) 
topline  =  0; 

if  (pagemarked (topline) ) 
break; 

}  while  (topline  >  0); 
break; 
case  ESC: 

break; 
default: 
beep ( ) ; 
break; 

) 

} 

/* - clean  up  and  exit - */ 

wclear (text_window) ; 
wref resh (text_window) ; 
delwin (text_window) ; 
thisline  =  firstline; 
while  (thisline  !=  NULL)  { 
free (thisline) ; 

thisline  =  thisline->  nextline; 

} 


/*  -  test  a  page  to  see  if  a  marked  keyword  is  on  it  -  */ 

int  pagemarked (int  topline) 

{ 

struct  textline  *tl  =  firstline; 
int  line; 

while  (topline--  &&  tl  !=  NULL) 
tl  =  tl->nextline; 

for  (line  =  0;  tl  !=  NULL  &&  line  <  LINES-2;  line++)  { 
if  (*tl->keys) 
break; 

tl  =  tl->nextline; 

} 

return  *tl->keys; 


fdefine  iswhite(c)  ((c) =='  ' I ! (c) ==' \t' ! ! (c) ==' \n' ) 

/*  -  Find  the  key  words  in  a  line  of  text.  Mark  their 

character  positions  in  the  text  structure  -  */ 

static  void  findkeys (struct  textline  *thisline) 

{ 

char  *cp  =  &thisline->text; 
int  ofptr  =  0; 

while  (*cp  &&  ofptr  <  5)  { 

struct  postfix  *pf  =  pftokens;/*  the  query  expression  */ 
while  (iswhite (*cp) )  /*  skip  the  white  space  */ 

cp++; 

if  (*cp)  { 

/*  -  test  this  word  against  each  argument  in  the 


query  expression - */ 

while  (pf->pfix  !=  TERM)  { 


if  (pf->pf ix  ==  OPERAND  && 

strnicmp(cp,  pf->pfixop, 

strlen  (pf->pfixop) )  ==  0) 

break; 

pf++; 

I 

if  (pf->pfix  !=  TERM) 

/*  -  the  word  matches  a  query  argument. 

Put  its  offset  into  the  line's  header  —  */ 
thisline->keys [ofptr++]  = 

(cp  -  &thisline->text)  &  255; 

/*  -  skip  to  the  next  word  in  the  line  -  */ 

while  (*cp  &&  ! iswhite (*cp) ) 
cp++; 

} 

) 

} 

/*  -  display  page  of  text  starting  with  specified  line  -  */ 

static  void  display_textpage (WINDOW  *text_window,  int  line) 

{ 

struct  textline  *thisline  =  firstline; 
int  y  =  1; 

wclear (text_window) ; 
wmove (text_window,  0,  0); 
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/*  -  point  to  the  first  line  of  the  page  -  */ 

while  (line —  &&  thisline  !=  NULL) 
thisline  =  thisline->nextline; 

/* - display  all  the  lines  on  the  page - */ 

while  (thisline  !=  NULL  &&  y  <  LINES-1)  { 

char  *cp  =  &thisline->text; 
char  *kp  =  thisline->keys; 
char  off  =  0; 

wmove (text_window,  y++,  1); 

/* - a  character  at  a  time - */ 

while  (*cp)  ( 

/*  -  is  this  character  position  a  key  word?  -  */ 

if  (*kp  &&  off  ==  *kp)  ( 

wstandout (text_window) ;  /*  highlight  key  words*/ 
kp++; 

} 

/*  -  is  this  character  white  space?  -  */ 

if  (iswhite(*cp) ) 

wstandend (text_window) ;  /*  turn  off  hightlight*/ 

/* - write  the  character  to  the  window - */ 

waddch (text_window,  *cp) ; 

off++; 

cp++; 

) 

/* - a  line  at  a  time - */ 

thisline  =  thisline->nextline; 

} 

} 


End  Listing  Three 


Listing  Four 

/* - error. c - */ 

/*  General-purpose  error  handler  */ 

♦include  <curses.h> 

♦include  <string.h> 

void  error_handler (char  *ermsg) 

{ 

int  x,  y; 

WINDOW  *error_window; 

x  =  (COLS  -  (strlen  (ermsg)  +2) )  /  2; 
y  =  LINES/2-1; 

error_window  =  newwin(3,  2+strlen (ermsg) ,  y,  x) ; 
box (error_window,  VERT_SINGLE,  HORIZ_SINGLE) ; 
mvwprintw(error_window,  1,  1,  ermsg); 
wrefresh (error_window) ; 
beep ( ) ; 
getch  ()  ; 

wclear (error_window) ; 
wrefresh (error_window) ; 
delwin (error_window) ; 


End  Listings 
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Listing  One  (Text  begins  on  page  134.) 


- - - - 

(*  BITWISE. MOD  *) 
(*  Definition  Module  *) 
{*  *) 
(*  Bit-manipulation  routines  for  Modula-2  *) 
(*  *) 
(*  by  Jeff  Duntemann  *) 
(*  For  DDJ  :  March  1990  *) 
(*  Last  modified  11/25/89  *) 
<* - *) 


IMPLEMENTATION  MODULE  Bitwise; 
VAR 

I  :  CARDINAL; 

TempSet  :  BITSET; 


PROCEDURE  And (A, B  :  CARDINAL)  :  CARDINAL; 
BEGIN 

RETURN  CARDINAL (BITSET (A)  *  BITSET (B) ) ; 
END  And; 


DEFINITION  MODULE  Bitwise; 

PROCEDURE  And (A, B  :  CARDINAL)  :  CARDINAL; 

PROCEDURE  Or (A, B  :  CARDINAL)  :  CARDINAL; 

PROCEDURE  Xor(A,B  :  CARDINAL)  :  CARDINAL; 

PROCEDURE  Not (Target  :  CARDINAL)  :  CARDINAL; 

PROCEDURE  SetBit (Target  :  CARDINAL;  BitNum  :  CARDINAL)  :  CARDINAL; 
PROCEDURE  ClearBit (Target  :  CARDINAL;  BitNum  :  CARDINAL)  :  CARDINAL; 
PROCEDURE  TestBit (Target  :  CARDINAL;  BitNum  :  CARDINAL)  :  BOOLEAN; 
PROCEDURE  SHR (Target  :  CARDINAL;  By  :  CARDINAL)  :  CARDINAL; 

PROCEDURE  SHL (Target  :  CARDINAL;  By  :  CARDINAL)  :  CARDINAL; 


END  Bitwise. 

Listing  Two 


(* . — - - *) 

(*  BITWISE. MOD  *) 
(*  Implementation  Module  *) 
(*  *) 
(*  Bit-manipulation  routines  for  Modula-2  *) 
(*  *) 
(*  by  Jeff  Duntemann  *) 
(*  For  DDJ  :  March  1990  *) 
(*  Last  modified  11/25/89  *) 
(*  *) 
(*  NOTES  ON  THE  CODE:  *) 
(*  *) 
{*  In  all  cases  below,  BitNum  MOD  16  is  used  as  a  *) 


(*  means  of  ensuring  that  BitNum  will  be  in  the  *) 
(*  range  of  0..15.  MOD  16  divides  by  16  but  returns  *) 
(*  the  remainder,  which  cannot  be  over  15  when  you  *) 


(*  divide  by  16.  *) 

(‘ - - - - *) 


End  Listing  One 


PROCEDURE  Or (A, B  :  CARDINAL)  :  CARDINAL; 
BEGIN 

RETURN  CARDINAL (BITSET (A)  +  BITSET (B) ) ; 
END  Or; 


PROCEDURE  Xor (A, B  :  CARDINAL)  :  CARDINAL; 
BEGIN 

RETURN  CARDINAL (BITSET (A)  /  BITSET (B) ) ; 
END  Xor; 


PROCEDURE  Not (Target  :  CARDINAL)  :  CARDINAL; 
BEGIN 

RETURN  CARDINAL ((0. .15)  -  BITSET (Target) ) ; 
END  Not; 


PROCEDURE  SetBit (Target  :  CARDINAL;  BitNum  :  CARDINAL)  :  CARDINAL; 

BEGIN 

TempSet  :=  BITSET (Target ) ;  (*  INCL  does  not  operate  on  expressions!  *) 

INCL (TempSet, BitNum  MOD  16); 

RETURN  CARDINAL (TempSet);  (*  Cast  the  target  back  to  type  CARDINAL  *) 
END  SetBit; 


PROCEDURE  ClearBit (Target  :  CARDINAL;  BitNum  :  CARDINAL)  :  CARDINAL; 
BEGIN 

TempSet  :=  BITSET (Target) ;  (*  EXCL  does  not  operate  on  expressions!  *) 

EXCL (TempSet, BitNum  MOD  16); 

RETURN  CARDINAL (TempSet);  (*  Cast  the  target  back  to  type  CARDINAL  *) 
END  ClearBit; 


PROCEDURE  TestBit (Target  :  CARDINAL;  BitNum  :  CARDINAL)  :  BOOLEAN; 
BEGIN 

IF  (BitNum  MOD  16)  IN  BITSET (Target)  THEN 
RETURN  TRUE; 

ELSE 

RETURN  FALSE; 

END; 

END  TestBit; 


PROCEDURE  SHR (Target  :  CARDINAL;  By  :  CARDINAL)  :  CARDINAL; 
BEGIN 

FOR  I  :=  1  TO  By  DO 

Target  :=  Target  DIV  2; 

END; 

RETURN  Target; 

END  SHR; 


PROCEDURE  SHL (Target  :  CARDINAL;  By  :  CARDINAL)  :  CARDINAL; 
BEGIN 

FOR  I  :=  1  TO  By  DO 
Target  :=  Target  *  2; 

END; 

RETURN  Target; 

END  SHL; 


END  Bitwise. 


End  listings 
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Codecheck,  a  rule-based  expert  system 
that  checks  C  and  C++  source  code  for 
maintainability,  portability,  and  com¬ 
pliance  with  in-house  style,  has  been 
announced  by  Conley  Computing. 
Codecheck  has  the  ability  to  identify 
the  number  of  operators  per  expres¬ 
sion  and  lines  per  statement,  and  it 
provides  a  statistical  analysis  of  code 
complexity  and  style,  allowing  program¬ 
mers  to  check  for  both  industry  stan¬ 
dards  and  those  established  by  their 
company. 

Codecheck  also  reviews  code  for  its 
portability  to  ANSI  C  and  K&R  C,  among 
others.  Company  president  Patrick  Con¬ 
ley  told  DDJ  that  Codecheck  can  be 
beneficial  to  both  corporations  and  in¬ 
dividuals,  but  especially  to  corpora¬ 
tions  that  use  many  programmers  for 
single  projects.  “The  problem  is  getting 
programmers  to  adhere  to  standards; 
since  everyone  has  their  own  Tower  of 
Babel  concerning  standards,  Code¬ 
check  can  be  programmed  to  check 
in-house  style.” 

Codecheck  supports  all  C  compilers 
from  major  vendors,  and  is  available 
for  PC-DOS  and  Macintosh  at  $495,  for 
OS/2  at  $695,  and  for  AIX,  PC/IX,  and 
QNX  at  $995.  Multiple  copy  and  educa¬ 
tional  discounts  are  also  available. 
Reader  service  no  21. 

Conley  Computing 
7033  SW  Macadam  Ave. 

Portland,  OR  97219 
503-244-5253 

The  Paradox  Engine,  a  C  library  for  the 
relational  database  Paradox,  has  been 
announced  by  Borland  International. 
The  company  claims  that  this  product 
will  enable  C  programmers  to  build 
applications  that  create  or  access  Para¬ 
dox  data  because  programs  that  use 
the  Paradox  Engine  are  standard  .EXE 
files.  The  benefit  is  interoperability 
among  Borland’s  major  business  appli¬ 
cations  and  languages,  which  theoreti¬ 
cally  allows  the  building  of  customized 
computing  environments. 

A  program  written  with  the  Paradox 
Engine  is  compiled  in  C  and  linked 
with  the  Paradox  Engine  library  to  build 
an  executable  application  that  can  dy¬ 
namically  access  Paradox  data.  The  PAL 
language  can  also  access  Paradox  ta¬ 
bles. 


The  engine  provides  an  API  of  more 
than  70  funcitons,  which  allows  the 
manipulation  of  Paradox  tables  in  sin¬ 
gle  and  multiuser  environments.  The 
C  version  should  be  shipping  this  quar¬ 
ter,  and  will  cost  $495.  A  Pascal  version 
is  scheduled  for  release  sometime  in 
the  middle  of  the  year,  and  OS/2  and 
Windows  versions  are  also  under  de¬ 
velopment.  During  the  first  90  days  of 
availability,  registered  Borland  users  can 
purchase  the  product  for  $195.  Reader 
service  no.  22. 

Borland  International 
P.O.  Box  660001 
Scotts  Valley,  CA  95066-0001 
408-439-1622 

VRTX-PC,  a  real-time  environment  for 
the  PC/XT/AT  compatibles  that  allows 
these  machines  to  be  used  as  both  de¬ 
velopment  platforms  and  embedded 
computers,  has  been  introduced  by 
Ready  Systems.  Time-critical  applica¬ 
tions  in  which  deterministic  operating 
system  performance  is  necessary  can 
now  be  controlled  by  PCs.  The  com¬ 
pany  is  excited  that  the  VRTX-PC  al¬ 
lows  simultaneous  development  and 
execution  of  real-time  multitasking  ap¬ 
plications,  eliminating  the  need  for  low- 
level  hardware  control  on  the  PC.  They 
believe  that  this  technology  will  reduce 
development  costs  and  get  products 
on  the  shelf  faster. 

The  VRTX-PC  real-time  operating  sys¬ 
tem  supports  MS-DOS  functions,  in¬ 
cluding  all  MS-DOS  file  and  device 
I/O,  and  can  be  executed  as  a  DOS 
resident  program. 

VRTX-PC  includes  a  real-time  ker¬ 
nel,  a  real-time  debugger,  an  input/ 
output  file  executive,  a  run-time  library, 
a  PC  support  executive,  and  a  window 
manager  that  provides  a  user  interface. 
For  application  development,  VRTX- 
PC  supports  Microsoft  C  and  Borland 
Turbo  C.  The  price  for  a  single  user  is 
$7600.  Reader  service  no.  23. 

Ready  Systems 
P.O.  Box  60217 
Sunnyvale,  CA  94086 
408-736-2600 

The  Sierra  C  toolset  for  the  M68000  is 
available  from  Sierra  Systems.  The 
toolset  includes  an  optimizing  C  com¬ 
piler  and  complete  C  run-time  library, 
two  assemblers,  linker,  librarian,  code 
management  and  debugging  utilities, 
a  serial  downloaded  a  high-speed  par¬ 
allel  downloaded  and  a  source-level 
debugger.  The  company  claims  that 
the  code  produced  is  position  inde¬ 
pendent,  ROMable,  and  re-entrant. 

The  Sierra  C  compiler  that  is  included 
in  the  toolset  is  ANSI  compatible  and 
supports  the  keywords  and  functional¬ 


ity  required  for  embedded  systems  pro¬ 
gramming. 

Compiler  flags  control  individual  sup¬ 
pression  of  optimization  techniques, 
generation  of  floating  point  code  (in¬ 
line  or  for  the  68881),  formatting  and 
contents  of  the  listing  and  assembler 
output  files,  generation  of  source  level 
debugger  information,  IEEE  floating 
point  operation  modes,  and  register 
usage,  among  others.  Reader  service 
no.  24. 

Sierra  Systems 
6728  Evergreen  Ave. 

Oakland,  CA  94611 
415-339-8200 

PC  Techniques ,  a  new  magazine  for 
programmers,  has  been  announced  by 
The  Coriolis  Group.  The  first  bi¬ 
monthly  issue  will  be  published  with 
a  March/ April  1990  cover  date.  The 
magazine  will  become  a  monthly  pub¬ 
lication  in  January  of  1991  ■ 

PC  Techniques  will  cover  the  DOS, 
Windows,  OS/2,  and  Presentation  Man¬ 
ager  platforms.  C,  Pascal,  Basic,  and 
assembly  language  will  be  covered  in 
every  issue.  Specialty  languages  like 
C++,  Object  Pascal,  Smalltalk,  and  Ac¬ 
tor  will  also  find  coverage. 

The  Coriolis  Group  was  founded  by 
DDJ  columnist  Jeff  Duntemann  and  by 
Keith  Weiskamp,  occcasional  DDJ 
author.  PC  Techniques  is  available  for 
$21.95  for  one  year  and  $37.95  for  two. 
Reader  service  no.  25. 

Coriolis  Group 

3202  E.  Greenway,  Ste.  1307-302 
Phoenix,  AZ  85032 
602-493-3070 

Two  new  journals,  Inside  Turbo  C  and 
Inside  Turbo  Pascal,  which  offer  pro¬ 
grammers  ongoing  support  of  these  two 
Borland  languages,  have  been  an¬ 
nounced  by  The  Cobb  Group.  The 
purpose  of  the  two  journals  is  to  ex¬ 
plore  new  algorithms,  system  tricks, 
and  product  updates,  including  com¬ 
plete  source  code.  They  will  also  con¬ 
tain  tips,  programming  techniques,  prod¬ 
uct  news  and  reviews,  as  well  as  ad¬ 
vice.  And  Inside  Turbo  Pascal  covers 
OOP  with  Turbo  Pascal. 

Each  journal  costs  $59  for  12  issues; 
sample  issues  are  available.  Source  code 
in  both  issues  can  be  downloaded  from 
Cobb’s  BBS,  for  a  yearly  fee  of  $30. 
Reader  service  no.  26. 

The  Cobb  Group 
P.O.  Box  24480 
Louisville,  KY  4022 4 
800-223-8720 

The  original  developer  of  Turbo  Prolog, 

the  Prolog  Development  Center 

(continued  on  page  157) 
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(continued  from  page  152) 

(PDC),  has  been  granted  the  rights  to 
the  product  by  Borland  International. 
The  PDC  will  publish  and  market  new 
versions  under  the  name  PDC  Prolog. 
According  to  Michael  Alexander  at  PDC, 
“The  new  version  is  a  superset  of  the 
current  Turbo  Prolog.  With  the  excep¬ 
tion  of  the  turtle  graphics  predicates,  it 
is  source-compatible  with  Turbo  Prolog, 
so  existing  Turbo  Prolog  programs  can 
be  compiled  ‘as  is’  with  PDC  Prolog.” 
And  PDC  Prolog  supports  the  Borland 
BGI  graphics  interface. 

A  new  DOS  version  should  be  avail¬ 
able  by  now,  and  registered  users  of 
the  DOS  version  of  Turbo  Prolog  will 
be  able  to  upgrade  for  $79.  The  OS/2 
version  should  also  be  available,  and 
will  cost  $599.  Network  support  and  a 
SCO  386  Unix  version  is  scheduled  for 
release  in  the  second  quarter  of  this 
year.  Reader  service  no.  27. 

Prolog  Development  Center 
568  14th  Street  N.W. 

Atlanta,  GA  30318 
404-873-1366 

Intek  C++  2.0  is  now  available  from 
Intek  Integration  Technologies.  The 

company  claims  the  product  has  as 
much  power  as  AT&T’s  C++  2.0  in  an 
80386  MS-DOS  or  Unix  environment. 
Intek  C++  2.0  translates  C++  code  into 
C  code.  It  supports  most  DOS  C  com¬ 
pilers,  including  Microsoft  C,  Turbo  C, 
Meta  Ware  High  C  and  High  C  386,  Wat- 
com  C  and  Watcom  C  386,  and  Novell 
Network  C  and  Network  C  386. 

This  support  also  includes  the  C  ex¬ 
tended  keywords  near ;  far ;  huge,  cdel, 
pascal,  and  fortran,  which  makes  it 
useful  with  Microsoft  Windows  and 
OS/2. 

The  Intek  C++  translator  uses  386 
protected  memory  mode,  and  can  com¬ 
pile  large  programs  —  up  to  4  giga¬ 
bytes.  It  supports  multiple  inheritance, 
type-safe  linkage,  new  and  delete  op¬ 
erators  as  class  members,  overloading 
of  the  ->,  ->*,  and,  operators,  const  and 
static  member  functions,  and  static  in¬ 
itialization.  It  requires  1  Mbyte  of  mem¬ 
ory,  MS-DOS  3-1  or  later  or  Unix  Sys¬ 
tem  V/386,  and  costs  $495-  Reader  ser¬ 
vice  no.  28. 

Intek 

1400  112th  Ave.  SE,  Ste.  202 
Bellevue,  WA  98004 
206-455-9935 

A  C++  compiler  for  80386/486  Unix- 
based  systems  has  been  released  by 
Peritus  International.  In  addition  to 
AT&T  C++  2.0,  the  highly-optimized 
C++  compiler  also  provides  support 
for  K&R  C  and  ANSI  C;  programmers 
select  the  appropriate  C  dialect  by  set¬ 


ting  a  compiler  switch. 

The  compiler  supports  an  extensive 
set  of  data  types,  including  8-,  16-,  32-, 
and  64-bit  integers,  IEEE-compatible  32-, 
64-,  and  80-bit  floating  point,  user- 
defined  aggregate  types,  and  C++  class 
data  types.  The  optimizations  include 
global  register  allocation,  constant  propa¬ 
gation  and  folding,  backward  code  mo¬ 
tion  with  loop  invariant  removal,  in¬ 
duction  variable  elimination,  redundant 
store  and  dead  code  removal,  and  con¬ 
stant  elevation. 

Company  president  Ron  Price  told 
DDJ  that  Peritus  intends  on  providing 
class  libraries  and  development  tools 
within  the  near  future,  including  a  pack¬ 
age  to  provide  a  graphical  interface  to 
the  X  Windows  system.  He  also  said 
that  the  C++  is  compliant  to  the  AT&T 
2.0  spec,  except  for  multiple  inheri¬ 
tance,  which  will  also  be  supported  in 
the  near  future. 

The  Peritus  C++  compiler,  which  runs 
on  386/486  systems  under  SVR3  Unix 
and  SunOS  4.0  Unix,  sells  for  $1000. 
Reader  service  no.  29. 

Peritus  International 
10201  Torre  Ave.,  Ste.  295 
Cupertino,  CA  95014 
408-725-0882 

A  few  new  assembly  tools  are  now 
available.  An  assembly  language  library 
written  entirely  in  assembly  language 
has  been  released  by  Quantasm  Cor¬ 
poration.  Quantasm  Power  Lib  (QPL) 
contains  over  256  routines,  provides 
high-level  functionality,  and  has  the 
ability  to  be  customized. 

QPL  can  be  used  by  both  novice  and 
expert  programmers.  The  documenta¬ 
tion  is  coordinated  with  example  pro¬ 
grams  on  disk.  The  company  claims 
that  the  compactness  of  QPL  makes  it 
convenient  for  programming  memory 
resident  programs  or  TSRs. 

The  product  includes  a  menu  and 
windowing  system,  over  75  string  han¬ 
dling  functions,  extended  precision 
math  functions,  a  set  of  date/time  func¬ 
tions,  encryption/decryption  algorithms, 
file  name  parsing,  and  sound  control. 
The  company  intends  to  have  high- 
level  language  interface  routines  avail¬ 
able  in  the  first  quarter  of  this  year. 
QPL  requires  MS-  or  PC-DOS  2.1  or 
above;  256K  RAM;  IBM  PC/XT/AT, 
PS/2  or  compatible;  Microsoft  MASM, 
Borland  TASM,  or  SLR  OPTASM.  This 
product  is  not  copy  protected,  nor  has 
run-time  royalties.  The  price  is  $99.95 
without  source  code,  $299. 95  with. 
Reader  service  no.  30. 

Quantasm  Corporation 
19855  Stevens  Creek  Blvd. 

Cupertino,  CA  95014 
408-244-6826 
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From  Base  Two  Development  comes 
Spontaneous  Assembly,  an  assembly- 
language  library  that  contains  over  600 
functions  and  macros,  including  string 
and  memory  manipulation,  near/far/ 
relative  heap  management,  doubleword/ 
quadword  integer  math,  date  and  time 
manipulation,  and  more.  The  company 
claims  that  every  routine  is  hand-coded 
and  optimized,  and  are  easy  to  use 
because  of  the  register-oriented  parame¬ 
ter-passing  convention.  Company 
spokesman  Alan  Collins  told  DDJ  that 
“this  product  does  for  8088-family  as¬ 
sembly  language  programming  what 
Borland  did  for  high-level  language  pro¬ 
gramming.” 

Spontaneous  Assembly  supports  all 
Microsoft/Borland  standard  memory 
models,  as  well  as  custom  models  and 
mixed-model  programming.  The  tool 
sports  a  full-overlapping  windowing 
system  with  custom  shadowing  that  al¬ 
lows  direct  memory  via  screen  access 
or  BIOS.  DOS  2.0  or  higher  is  required, 
and  MASM  5.1  or  TASM  1.0  are  recom¬ 
mended.  It  costs  $199,  includes  all 
source  code,  and  comes  with  a  money 
back,  60-day  guarantee.  Reader  service 
no.  3. 

Base  Two  Development 
1 1  East  200  North 
Orem,  UT  84057 
800-277-3625 

Another  is  DASM,  a  disassembler  for 
the  8086,  8088,  and  80286,  available 
from  JBSoftware.  DASM  is  able  to  dis¬ 
assemble  and  modify  programs  for 
which  the  source  code  is  unavailable. 
It  takes  binary  run  files  for  DOS  and 
compatible  operating  systems  as  input, 


and  creates  an  assembly  language  file 
suitable  for  modification  and  reassem¬ 
bly  as  output.  It  acts  as  a  virtual  ma¬ 
chine  and  maps  the  program  being  dis¬ 
assembled.  It  tracks  register  usage  and 
determines  the  code,  data,  and  labels, 
allowing  the  user  to  then  edit  the  out¬ 
put  and  change  the  program. 

DASM  works  by  viewing  commands 
and  procedures  in  their  real-time  pro¬ 
cessing  order,  rather  than  in  the  se¬ 
quence  they  appear  in  the  program, 
which  JBSoftware  claims  makes  the  pro¬ 
grams  easier  to  interpret  and  edit.  Some 
of  DASM’s  other  features  include  the 
ability  to  generate  appropriate  ASSUMES 
and  segment  maps,  to  handle  multiple 
entry  points,  transfer  vectors,  and  .EXE, 
.COM,  and  .BIN  files  up  to  200K.  It 
costs  $250.  Reader  service  no.  2. 
JBSoftware 

701  Cathedral  St.,  Ste.  81 
Baltimore,  MD  21201 
301-752-1348 

Two  new  software  products  for  Mo¬ 
torola’s  88000  RISC  microprocessor  are 
available  from  Diab  Data.  The  D-CC/ 
88K,  an  optimizing  C  compiler,  com¬ 
plies  with  the  88000  object  code  com¬ 
patibility  standard  (OCS)  and  the  Bi¬ 
nary  compatibility  standard  (BCS),  and 
conforms  to  the  proposed  ANSI  C  stan¬ 
dard.  Optimizations  include  global  com¬ 
mon  subexpression  elimination,  life¬ 
time  analysis  (color),  reaching  analy¬ 
sis,  automatic  register  allocation,  loop 
invariant  code  motion,  constant  propa¬ 
gation  and  folding,  dead  code  elimina¬ 
tion,  switch  optimizations,  and  the  abil¬ 
ity  to  pass  parameters  into  registers. 

Diab’s  MC88000  toolkit  is  made  up 


of  the  D-AS/88K  Assembler,  the  D-LD/ 
88K  Linker,  and  the  D-AR/88K  Archiver. 
This  package  includes  the  D-CC/88K 
optimizing  C  compiler.  The  assembler 
is  also  OCS  and  BCS  compliant,  pro¬ 
duces  COFF  object  modules,  supports 
standard  MC88000  mnemonics,  pro¬ 
duces  standard  Unix  directives  for  or¬ 
ganizing  code,  among  other  things.  The 
linker  performs  literal  synthesis,  gener¬ 
ates  warnings  for  unidentified  external 
references,  and  is  able  to  perform  in¬ 
cremental  links.  The  archiver  maintains 
multiple  files  in  a  single  archive  file, 
and  supports  Unix  System  V  command¬ 
line  options.  The  compiler  and  toolkit 
are  available  for  the  Sun3/SunOS,  Mac 
II/MPW,  DECstation/Ultrix,  and  DEC 
VAX/VMS,  among  others.  Reader  ser¬ 
vice  no.  33. 

Diab  Data  Inc. 

323  Vintage  Park  Dr. 

Foster  City,  CA  94404 
415-573-7562 

Books  of  Interest 

A  comprehensive  treatment  of  concur¬ 
rent  programming  techniques  in  the 
Strand  programming  language  has  been 
published  by  Prentice  Hall.  Strand: 
New  Concepts  in  Parallel  Programming, 
by  Stephen  Taylor  and  Ian  Foster,  cov¬ 
ers  an  introduction  to  Strand,  basic  and 
advanced  programming  techniques,  and 
how  to  apply  Strand,  with  examples 
from  both  the  academic  and  real  worlds. 
The  price  is  $30.  ISBN  013-850587-X. 
Reader  service  no.  38. 

Prentice  Hall 

Englewood  Cliffs,  NJ  07632 
201-767-5937 
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S  W  A  I  N  E'  $  FLAMES 


Pub  Crawler 


I  read  a  lot  of  magazines.  I  read  during  meals,  while  talking  to  Jon  on  the  phone,  and  while  visiting 
the  little  programmer’s  room.  I  also  follow  magazine’s  fortunes,  and  I  thought  I’d  pass  along  the 
latest  rumors  regarding  some  in  which  you  may  be  interested. 

CD-ROM  End  User.  If  you  are  interested  in  CD-ROM  and  haven’t  seen  this,  give  it  a  look.  Once 
you  get  past  the  uninspired  name,  the  amateur  editing,  and  the  boring  design,  you’ll  find  a 
bimonthly  packed  with  information  of  solid  value  for  both  CD-ROM  users  and  developers,  written 
and  compiled  by  knowledgeable  people. 

Embedded  Systems  Programming.  Those  whose  realm  is  the  other  kind  of  ROM  should  know 
that  ESP  has  gone  to  controlled  circulation.  What  this  means  if  you’re  a  subscriber  or  potential  ditto 
is  that  you  may  get  it  for  free.  What  it  means  if  you’re  an  advertiser  or  potential  ditto  is  that  you  can 
look  for  increased  rates.  It’s  a  zero-sum  game. 

Micro  Cornucopia.  Dave  Thompson  is  considering  taking  his  50-issue-old  hacker’s  magazine 
monthly.  He’s  looking  for  a  “partner”  —  one  with  money  to  invest,  I  gather. 

Microsoft  Systems  Journal.  MSJ  has  been  redesigned,  and  it’s  an  improvement,  though  the 
publication  still  works  too  hard  at  being  taken  seriously.  It’s  probably  too  much  to  expect  that  MSJs 
editors  could  learn  from  someone  such  as  Dave  Thompson  how  wit  and  playfulness  can  coexist 
with  solid  technical  content. 

Other  captive  magazines.  Sun’s  user  magazine  is  about  to  be  sold  —  “given”  is  a  better  word, 
from  what  I  hear  of  the  deal  —  to  IDG,  publisher  of  Computer  World ,  InfoWorld,  PC  World , 
Macworld ,  etc.;  while  Aldus  has  launched  a  magazine  with  a  surprisingly  drab  look.  The  content 
is  too  self-serving,  but  the  first  issue  contains  a  few  good  things,  including  what  may  be  the  most 
quick-and-dirty  DTP  how-to  ever  written,  and  an  interview  with  Steve  Ballmer  on  OS/2. 

Ziff-Davis.  The  company  that  publishes  PC  Magazine ,  MacUser,  PC  Computing,  Digital  Review, 
and  others  (and  that  killed  off  Creative  Computing,  Popular  Electronics,  PC  Tech  Journal,  and 
others)  has  been  rumored  for  the  past  six  months  to  be  on  the  block.  The  rumors,  which  are  making 
ulcers  for  Z-D  employees,  have  been  vehemently  denied  by  Bill  Ziff.  The  rumors  are  remarkably 
detailed:  Pat  McGovern,  chairman  of  IDG,  has  perused  the  perspectus;  Cahners,  publisher  of 
Mini-Micro  Systems,  has  tendered  an  offer;  the  asking  price  is  in  the  $800  million  range;  Goldman 
Sachs  &  Co.  is  handling  the  deal.  If  you  believe  Ziffs  denials,  you  are  led  to  believe  that  the  rumors 
were  started  by  one  of  Z-D’s  competitors.  Whatever  the  truth,  somebody  is  an  awfully  big  liar. 

Buzzwords 

“Done  deal”  is  one  of  those  buzzwords  that  should  buzz  off,  and  I  apologize  for  using  it.  Another 
buzzword  that  I  hope  won’t  catch  on  in  the  90s  is  “experience,”  as  in  “user  experience.”  Apparently 
the  multimedia  types  within  Apple  are  pushing  to  use  it  in  the  place  of  “user  interface.”  I  get  the 
point,  but  I  hope  they  keep  this  one  in  house. 

My  pick  for  the  buzzword  of  the  90s  is  “facilitate.”  At  least  it  has  the  right  polysyllabic,  academic 
aura.  But  I  actually  think  it  could  be  a  GOOD  buzzword.  No,  really.  Here’s  why. 

I  believe  fervently  in  the  value  of  education,  but  I  don’t  buy  into  the  myth  of  teaching.  The 
existence  of  this  verb  “teach"  conveys  the  erroneous  impression  that  it  is  possible  to  force-feed 
knowledge.  The  best  teachers  seem  to  understand  that  there  is  no  such  thing:  Richard  Feynman, 
on  being  given  a  teaching  excellence  award  by  the  American  Association  of  Physics  Teachers,  said, 
“I  don’t  know  how  to  teach.  I  have  nothing  to  say  about  teaching,”  then  went  on  to  deliver  a  brilliant 
and  entertaining  lecture. 

If  you  can’t  teach  anyone  anything,  then  all  you  can  do  is  get  out  of  the  way,  move  any  obvious 
obstacles  aside,  and  let  them  learn.  Facilitating  learning,  you  might  call  it.  The  problem,  I  guess,  is 
that  it’s  hard  to  do.  Clearing  the  student’s  path  is  one  of  those  subtle  acts  that  succeeds  only  by 
making  itself  invisible. 

Like  good  writing,  and  like  good  user  interface  design.  Good  writer  Esther  Dyson  discussed  the 
desktop  metaphor  in  the  January  issue  of  PC  Computing,  saying  that  it  “is  not  meant  to  suggest 
that  the  computer  is  a  desktop,  but  to  provide  a  sense  of  recognition  and  reasonable  expectations. 
This  metaphor,  so  popular  now,  suggests  tasks  the  computer  can  reasonably  be  expected  to  do.” 
Suggest  things.  Create  an  environment  the  user  can  explore,  letting  the  user  discover  things  by 
recognizing  the  familiar  and  following  reasonable  expectations  into  the  unfamiliar.  Get  out  of  the 
user’s  way.  Facilitate.  Yeah.  I  like  the  word.  The  trouble  is  that  if  it  catches  on,  people  will  start 
ringing  the  changes  on  it:  facilitator,  facilitation,  facile.  And  sooner  or  later  some  user  is  going  to 
walk  into  a  computer  store  and  ask  to  be  shown  the  facilities.  And  be  taken  to  the  little 
programmer’s  room.  Might  be  all  right  if  there  are  some  good  magazines  in  there. 


Michael  Swaine 
editor-at-large 
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It  Takes  More 
Than  Nerve 


L 


The  biggest  fear  of  those  who  champion  neural  networks  is  guilt-by-comparison  with  the 
artificial  intelligence  camp.  They’re  not  alone  in  this.  Object-oriented  advocates,  as  well  as 
most  other  popular  technologies  that  make  the  front  pages  of  pseudo-technology  news 
tabloids,  don't  want  to  be  snake-bit  by  the  same  type  of  hype  that  poisoned  AI  development.  The 
frontal  assaults  of  AI  and  expert  systems,  fueled  by  big  money  and  bigger  promises,  have  been 
nonexistent  for  neural  nets  and,  although  those  neural  net  developers  trying  to  eke  out  a  living 
might  disagree,  the  lack  of  venture  capital  has  probably  been  a  blessing.  Less  hype  buys  more  time, 
at  least  as  long  as  enough  money  comes  in  to  keep  the  lights  turned  on. 

Nevertheless,  there  continues  to  be  a  lot  of  interest  and  development  in  neural  nets.  A  survey 
recently  published  by  Future  Technology  Surveys  of  Madison,  Georgia  listed  over  200  companies 
and  organizations  currently  producing  neural-related  products  or  undertaking  serious  neural  net 
research.  And  it  just  isn’t  the  little  guys  doing  all  this  research,  either. 

Among  the  big  outfits  testing  the  neural  net  waters  is  Intel.  Early  last  summer,  a  ten-member  Intel 
engineering  team,  under  the  direction  of  Mark  Holler,  rolled  out  an  Electronic  Trainable  Artificial 
Neural  Network  (ETANN)  chip  that  is  capable  of  up  to  2  billion  multiplies  and  accumulates  per 
second.  To  put  the  chip  to  work,  Holler  and  his  crew  have  built  a  prototype  ETANN-based  board 
that  plugs  into  the  PC  AT  bus;  Mark  Lawrence  and  the  folks  at  California  Scientific  (developers  of 
BrainMaker,  a  neural  net  simulation  package  for  PCs)  are  developing  the  software  tools  that  let  you 
use  the  system.  There’s  also  a  rumored  Intel  research  project  that  will  put  a  version  of  the  ETANN 
board  into  an  i860-based  system  that  can  achieve  33  billion  connections  per  second. 

Intel  isn’t  the  only  big  IC  manufacturer  poking  around  in  neural  nets.  A  few  months  ago,  Sharp 
introduced  a  neural-network  image-processor  chipset  that  simulates  human  vision  and,  the 
company  claims,  supports  PC  applications  at  speeds  up  to  700  MIPS. 

These  examples  illustrate  another  trend  in  the  neural  net  world  —  a  transition  from  software  to 
hardware.  Within  ten  years,  or  so  say  the  experts,  more  neural  nets  will  be  implemented  in  hardware 
than  software.  Until  then,  engineers  will  begin  to  overcome  many  challenges,  including  the 
implementation  of  back  propagation  in  hardware  and  the  parallelization  of  the  entire  scheme. 

So  where  does  this  leave  software  developers?  For  one  thing,  a  whole  new  class  of  development 
tools  is  in  the  offing,  designed  for  specific  neural  net  hardware  implementations.  Another  type  of 
tool  will  be  like  that  described  by  Andy  Czuchry  in  this  issue,  whereby  designers  can  match  the 
right  neural  model  with  the  task  at  hand.  Nor  will  the  simulators  go  away;  they  may  be  used  to 
simulate  the  right  net  with  appropriate  learning,  then  generate  source  code  to  be  frozen  in  silicon. 


In  her  keynote  address  at  Miller-Freeman’s  SD’90,  Smalltalk  pioneer  and  ParcPlace  System’s 
president  Adele  Goldberg  expressed  a  concern  similar  to  that  I  wrote  about  in  this  space 
last  month  —  the  spread  of  litigation  and  its  effect  on  the  software  industry. 

Although  her  talk  concerned  a  wide  variety  of  legal  issues  —  from  intellectual  property  to  the 
emerging  problem  of  who  owns  the  design  and  implementation  of  objects,  as  in  object-oriented 
programming  —  she  spent  a  fair  amount  of  time  on  copyrights  and  patents.  “Lawyers  will  always 
tell  you  two  things,”  she  said,  “try  to  patent  or  copyright  whatever  you  do.”  She  went  on  to  describe 
a  speech  she  gave  to  a  group  of  lawyers,  where  she  was  asked  how  to  convince  software  developers 
to  protect  their  works.  “My  answer  was  simple,”  she  said.  “Tell  them  to  protect  their  work  so  that 
they  have  the  choice  later  on  to  give  it  away."  Not  doing  so,  she  explained,  opens  the  door  for 
someone  to  come  along  and  take  it  away.  But  Goldberg  wasn’t  engaged  in  lawyer-bashing,  no 
matter  how  easy  that  is.  What  she  was  presenting  was  a  persuasive  argument  for  open  standards 
and  open  licensing.  She  pointed  out  that  among  the  problems  litigation  forces  upon  us  are  the 
waste  of  time  and  money,  the  fear  of  alliances,  the  inability  of  entrepreneurs  who  lack  clear  patent 
or  copyright  protection  to  attract  investors,  and  the  expense  of  starting  up  new  businesses. 

One  of  the  main  points  of  her  talk  was  simply  to  “reassert  an  often  unstated  goal  of  our 
industry  —  to  share  ideas  and  to  challenge  one  another  with  our  innovative  expressions  of  those 
ideas.”  Nicely  put. 


And  no,  the  favored  horse  running  in  the  first  race  at  Bay  Meadows  racetrack  the  other  night 
wasn’t  our  official  mascot,  even  though  the  nag’s  name  was  “Dr.  Dobbs.”  Although,  he  lost  by  a 
nose  in  a  photo  finish,  the  good  Doctor  is  surely  chomping  at  the  bit  to  get  into  the  next  race.  We’ll 
keep  you  posted  on  his  progress  this  season. 


Jonathan  Erickson 
editor-in-chief 
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LETTERS 


Faster  Animation 

Dear  DDJ, 

I  enjoyed  Rahner  James’s  article  on  “Real 
Time  Animation”  in  the  January  1990 
issue  of  DDJ.  Ever  since  the  price  of 
EGA  devices  dropped,  magazines  have 
been  filled  with  how-to  articles,  but 
few  have  covered  icons  or  sprites.  In 
1986  I  ported  a  collection  of  graphics 
routines  from  my  Zenith  100  system  to 
the  EGA.  These  routines  are  now  part 
of  an  icon  development  environment 
called  “ProGraphx  Toolbox,”  available 
from  Stanwood  Associates. 

Speed  is  definitely  the  key  to  success 
in  graphics,  and  Mr.  James’s  routines 
definitely  are  fast.  In  my  routines  I  have 
come  up  with  another  approach,  which, 
I  believe,  is  slightly  faster  in  displaying 
icons.  Since  the  EGA  is  latched,  you 
must  determine  which  planes  will  be 
accessed  during  a  write,  a  clock  cycle 
consuming  process.  Mr.  James’s  rou¬ 
tines  store  one  byte  per  pixel,  enabling 
128  colors  and  an  intensity  bit.  If  the 
format  of  the  sprite  were  laid  out  plane 
by  plane  rather  than  pixel  by  pixel,  the 
function  could  set  the  registers  for  a 
plane  and  then  write  all  the  data  for 
that  plane.  The  function  would  con¬ 
tinue  plane  by  plane,  only  setting  up 
the  register  once  per  plane  per  icon. 
Additionally,  the  EGA  does  not  allow 
bit  access.  So  why  not  place  a  byte’s 
worth  of  data  on  the  screen  during 
each  write  rather  than  only  one  new 
bit?  I  enjoy  seeing  quality  articles  every 
time  I  open  a  new  issue  of  DDJ.  Keep 
it  up! 

Pederjungck,  Stanwood  Assoc. 

Chicago,  Illinois 

On  Location 

Dear  DDJ, 

The  excellent  article  “Location  is  Ev¬ 
erything,”  by  Mark  Nelson,  (January, 
1990)  was  most  timely.  Once  again  DDJ 
came  up  with  just  what  I  wanted  just 
when  I  needed  it.  I  think,  however, 
there  is  a  small  problem  with  the  code. 

Mark  uses  the  exe  header  field  “Dis¬ 
placement  of  stack  in  Paras”  (Oe)  to 
locate  the  start  of  the  initialized  data 


area.  This  works  only  when  the  amount 
of  initialized  data  is  less  than  one  para¬ 
graph  long  since  the  stack  displace¬ 
ment  corresponds  to  the  end  of  the 
initialized  data  area.  In  the  general  case, 
the  program  needs  the  starting  para¬ 
graph.  I  was  able  to  easily  find  this 
value  by  parsing  it  out  of  the  .MAP  file. 
Using  this  value  in  the  relocation  func¬ 
tion  causes  the  program  to  perform  as 
advertised. 

/*  input_base_data_segment  is  a  global 
unsigned  int  V 

/*  data_seg  is  declared  as  char 

data_seg[81]  */ 

/*  map_file  is  a  FILE  *  to  the  .MAP  file 
created  by  */ 

/*  Scan  the  .map  file  for  the  word  “BSS” 

7 

while(strcmp(data_seg,  "BSS")  !  =  0) 
fscanf(map_file,  "%s",  data_seg); 
/*  The  next  field  in  the  file  is  the  loca¬ 
tion  of  the  V 

/*  data.  V 

fscanf(map_file,  "%s",  data_seg); 
data_seg[strlen(data_seg)-l]  =  ’\0’; 

/‘kill  the  ’H’  V 
input_base_data_segment  = 

htoi(data_seg) »  4; 

In  the  function  process_relocation_ta- 
ble( ),  replace  all  references  to  the  vari¬ 
able  first_data_segment_  in_exe_  file 
with  input_ base_data_segment. 
Stephen  J.  Beaver 
Winchester,  Virginia 

Mark  responds:  As  Stephen  Beaver  notes, 
there  is  a  field  in  the  header  portion  of 
an  EXE file  that  tells  me  where  the  start 
of  the  program  stack  segment  is  lo¬ 
cated.  I  use  this  field  to  determine  where 
RAM  data  starts  in  the  EXE  file.  Mr. 
Beaver  must  have  taken  note  of  the 
lines  in  my  START.ASM  file  shown  be¬ 
low.  Because  the  stack  segment  follows 
the  DATA,  BSS,  and  CONST  segments, 
Mr.  Beaver  concludes  that  the  value  I 
calculate  for  the  start  of  RAM  actually 
points  past  all  these  segments.  How¬ 
ever,  there  is  an  additional  segment 
definition  line  a  little  farther  down  in 


the  START.  ASM  file: 

DGROUP  GROUP  _CONST,  _BSS, 
_DATA,  _STACK 

This  statement  causes  the  compiler  and 
linker  to  gather  all  four  of  these  seg¬ 
ments  together  into  one  segment.  This 
means  that  all  four  segments  are  col¬ 
lected  together,  and  the  pointer  to  the 
start  of  the  stack  segment  will  actually 
point  to  the  start  of  DGROUP,  which 
will  be  at  the  start  of  the  _CONST  seg¬ 
ment.  So,  if  you  use  the  START.ASM 
startup  file  as  I  required,  the  LO¬ 
CATE. EXE  program  will  work  properly. 
By  the  way,  Mr.  Beaver  “solved"  this 
problem  by  modifying  my  LOCATE pro¬ 
gram  to  read  in  a  MAP  file  that  the 
linker  has  produced.  Reading  in  MAP 
files  to  drive  a  Locate  program  is  not  a 
bad  approach.  In  fact,  Jensen  &  Part¬ 
ners  International  are  providing  a 
TSLOCATE  utility  with  their  new 
TopSpeed  C  compiler,  which  does  just 
that.  I  chose  to  avoid  this  approach  for 
a  couple  of  reasons.  First,  there  is  no 
standard  MAP file  format.  Every  linker 
is  free  to  create  their  own  format,  and 
a  good  LOCATE  program  would  be 
forced  to  continually  adapt  to  these. 
Second,  a  program  using  this  approach 
is  vidnerable  to  errors  caused  when  the 
MAP  file  is  not  actually  the  one  from 
the  latest  link.  Because  the  information 
I  wanted  was  in  the  EXE  file,  and  the 
EXE  format  is  standardized  across  all 
MS-DOS  compilers,  I  elected  to  not  read 
in  the  MAP  file.  I  hope  this  clears  up 
some  of  the  confusion.  Dealing  with 
program  segments  at  a  low  level  is  usu¬ 
ally  concealed  from  HLL  programmers 
by  the  compiler,  for  which  we  can  all 
give  thanks. 

Random  Structures 

Dear  DDJ, 

This  is  in  response  to  the  December 
1989  letter  by  Dan  W.  Crockett.  He  is 
treating  the  term  “structured”  and  the 
term  “modular”  as  being  equivalent.  A 
structured  module,  program,  or  system 
(continued  on  page  12) 


TEXT 

SEGMENT  BYTE  PUBLIC  ’CODE’ 

TEXT 

ENDS 

END_OF_ROM 

SEGMENT  PARA  PUBLIC  ’STARTUP  CODE’ 

END_OF_ROM 

ENDS 

CONST 

SEGMENT  PARA  PUBLIC  ’CONST’ 

CONST 

ENDS 

BSS 

SEGMENT  WORD  PUBLIC  ’BSS’ 

BSS 

ENDS 

DATA 

SEGMENT  WORD  PUBLIC  ’DATA’ 

DATA 

ENDS 

STACK 

SEGMENT  WORD  STACK  ’STACK 

MYSTACK 

DB  512  DUP  (?) 

STACK 

ENDS 
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( continued  from  page  8) 
need  not  be  modular,  and  a  module 
may  or  may  not  be  structured.  Also,  a 
module,  program,  or  system  that  has 
“spaghetti  code”  has  a  structure.  It  is 
called  a  random  structure. 

One  of  the  purposes  of  using  mod¬ 
ules  is  that  the  code  is  reusable.  We  use 
this  all  the  time.  The  modules  are  in 
libraries.  Examples  are  the  Fortran  li¬ 
brary  routine  SIN(x),  the  Cobol 
COPYLIB  file,  and  the  C  library  routine 
sin(x).  The  proper  term  for  module 
tree  relationship  is  a  “caller”  module 
and  a  “called"  module.  This  describes 
the  relationship  much  better  than  the 
“father”  -  “son”  model.  Further,  a  mod¬ 
ule  should  not  know  anything  about 
the  “caller”  module,  other  than  what 
is  in  its  argument  list.  Can  you  imagine 
the  chaos  that  would  result  if  we  had 
to  rewrite  SIN(  x  )  or  sin(  x  )  every  time 
they  had  more  than  one  caller? 

Ned  Logan 

Seattle,  Washington 

Pascal  Participation,  Pleeez 

Dear  DDf 

After  reading  Terry  Ritter's  letter  enti¬ 
tled  “Standardizing  the  Standardizing 
Process”  in  your  February  1990  “Let¬ 
ters”  column,  I  have  the  feeling  that 
many  readers  may  not  understand  the 
standardization  process  and  will  be 
given  a  false  impression. 

Membership  on  X3J9,  the  other  X3 
committees,  and  the  IEEE  committees 
is  not  restricted  to  some  elitist  group. 
Membership  is  open  to  all  interested 
parties  who  are  willing  to  participate. 
Users  are  especially  encouraged  to  par¬ 
ticipate. 

Decisions  are  not  made  in  a  back 
room  behind  closed  doors.  Committee 
meetings  are  open  to  the  public  with 
visitors  and  observers  not  only  wel¬ 
come  but  encouraged.  Likewise,  com¬ 
mittee  documents  are  open  to  the  pub¬ 
lic  and  people  who  cannot  attend  meet¬ 
ings  can  become  official  observers  and 
receive  all  committee  mailings. 

Consensus  is  the  method  by  which 
most  decisions  are  made  both  at  the 
international  level  and  at  the  domestic 
level  for  Pascal.  Flowever,  it  is  the  con¬ 
sensus  of  those  who  participate. 

It  was  not  only  the  consensus,  but 
the  unanimous  vote  of  both  the  Inter¬ 
national  Working  Group  on  Pascal  and 
the  American  National  Standards  Com¬ 
mittee  on  Pascal  that  no  action  be  taken 
on  some  of  Mr.  Ritter’s  comments  for 
the  Extended  Pascal  standard.  The  main 
reason  for  this  was  that  major  changes 
and  development  would  have  been  re¬ 
quired  and  it  was  felt  that  this  should 
be  handled  separately  rather  than  un¬ 
duly  delay  the  standard,  which  was  in 


its  final  stages  of  review. 

This  does  not  mean  that  his  com¬ 
ments  have  been  shoved  under  the 
table.  Many  of  the  areas  brought  up 
by  his  comments,  including  exception 
handling,  alphanumeric  labels,  and  mul¬ 
tiple  arithmetic  data  types,  are  being 
worked  on  by  the  committee.  The  in¬ 
tent  is  to  issue  information  bulletins, 
technical  reports,  and  addenda  to  stan¬ 
dards  when  work  on  them  is  completed. 
User  participation  is  encouraged  in  this 
work,  especially  now  when  it  is  still  in 
a  nearly  stage  of  development. 

The  committee  is  also  now  begin¬ 
ning  to  look  at  object-oriented  exten¬ 
sions  to  Pascal,  and  has  submitted  a 
project  proposal  to  its  parent  bodies 
for  approval  of  this  work.  It  is  expected 
that  approval  will  be  received  early  this 
year.  When  this  approval  is  received, 
announcements  will  be  submitted  to 
all  publications  (including  Dr.  Dobb’s 
and  similar  user-oriented  publications) 
that  might  have  an  interested  audience. 

People  from  Apple,  Borland,  Micro¬ 
soft,  and  other  vendors  are  planning  to 
participating  in  the  object  work.  User’s 
views,  and  user  participation,  at  this  early 
stage  would  be  especially  welcome. 

I  encourage  Mr.  Ritter  and  other  us¬ 
ers  to  participate  in  Pascal  and  other 
standardization  efforts.  No  one  needs 
to  elect  you.  All  you  need  to  do  is 
participate. 

For  users  that  do  not  have  financial 
support,  there  are  organizations  (such 
as  SIGPLAN)  that  have  funds  allocated 
for  this  purpose. 

To  find  out  more  about  participating 
in  the  Pascal  standards  activity  please 
contact  me  by  letter,  phone,  FAX,  or 
e-mail. 

Thomas  N.  Turba 
Chairman  X3J9,  Pascal 
Unisys  Corp.,  MS:  WE3C 
P.O.  Box  64942 
St.  Paul,  MN  55164 
612-635-2349;  612-635-2003  (Fax) 
NET:  turba@rsvl. Unisys. 
comuunet!s5000!turba 

There’s  More  than  One  Way  to  Get 
From  Pascal  to  C,  or  Return  of  the 
Living  Fugu-Eaters 

Dear  DDf 

I  too  enjoy  Jeff  Duntemann’s  writings, 
though  not  for  the  same  reason  as  does 
Dale  Lucas  (“Letters,”  Jan.  1990).  I  love 
a  good  argument.  So  I  get  a  kick  out 
of  reading  Jeffs  ravings  against  C,  all 
the  while  thinking  up  incontrovertible 
(I’m  sure  they  must  be)  refutations. 

I  do  agree  with  him  that  C  is  ugly.  It 
looks  like  Dagwood’s  dialogue  after 
he  hammers  his  thumb,  %*!&()*#$@! 
But  I  put  up  with  that  for  the  sake  of 
the  language’s  abilities.  Jeff,  on  the  other 


hand,  sees  no  redeeming  value  in  C, 
whatsoever,  as  we  were  so  forcefully 
reminded  in  the  January  issue. 

Recall  that  Dale  Lucas  asked  him 
whether  there’s  a  way  to  call  a  third- 
party  ( sans  source)  C  library’s  routines 
from  a  Turbo  Pascal  program.  This  lit¬ 
tle  spark  lit  the  fuse  to  one  of  Jeff’s  best 
tirades  to  date,  in  which  he  accused  C 
programmers  of  acting  macho,  of  neglect¬ 
ing  to  neck  with  their  spouses  and  play 
with  their  dogs,  and  (this  was  the  killer 
blow)  of  EATING  FUGU! 

Oh  boy,  did  he  give  it  to  us.  Unfortu¬ 
nately,  he  got  so  carried  away  with  his 
ranting  twaddle  that  he  neglected  to 
help  his  Pascal  co-linguist.  He  told  Dale 
to  rewrite  the  whole  library  in  Pascal! 

If  you  don’t  mind  taking  advice  from 
a  fugu-eater,  Dale,  I  think  there’s  a  way 
to  hook  those  C  routines.  But  first  a 
question:  Doesn’t  Turbo  Pascal  have 
something  akin  to  Microsoft’s  “[C]”  at¬ 
tribute,  which  you  append  to  a  proce¬ 
dure  declaration  to  tell  the  compiler  to 
use  C’s  calling  and  naming  conventions? 
Guess  not,  or  the  problem  would  be 
trivial  and  you  wouldn’t  have  written. 

So  you’ll  need  to  turn  to  a  more 
powerful  language  —  ummmh,  let’s  say 
C  —  to  write  the  hooks.  Your  third- 
party  library  will  have  given  you  a 
header  file,  for  instance  “WINDOW.H,” 
declaring  its  functions.  For  example: 

int  WinCreate(int  height,  int  width,  int 

color); 

void  WinOpen(int  winnumber,  int 

xcord,  int  ycord); 

And  so  forth.  Add  to  this  file  a  new 
Pascal-callable  hook  function  for  each 
declaration,  thusly: 

int  pascal  HOOK_WinCreate(int  height, 
int  width,  int  color)  1 
return(  WinCreate(height,  width,  color 

));) 

void  pascal  HOOK_WinOpen(int  win- 
number,  int  xcord,  int  ycord.) 
{WinOpen( winnumber,  xcord,  ycord); 

return;) 

Rename  the  file,  say  to  “HOOK.C,”  and 
compile  it.  Finally,  translate  the  hook 
function  prototypes  into  declarations 
for  your  Pascal  modules: 

function  HOOKJWinCreate 
(height, width, color  :  integer)  :  integer; 

extern; 

procedure  HOOK_WinOpen  (winnum¬ 
ber,  xcord, ycord  :  integer)  :extern; 

(Do  I  have  that  right?  I  read  Pascal  but 
speak  it  poorly.)  The  C  code  above 
works  on  my  Watcom  compiler,  and 
(continued  on  page  14) 


12 


Dr.  Dobb’s  Journal ,  April  1990 

293 


LETTERS 


(continued  from  page  12) 
ought  to  work  on  QuickC  as  well.  Of 
course,  I’ve  begged  the  more  difficult 
questions  like  memory  models  and  trans¬ 
lating  C  strings  and  structures  into  Pas¬ 
cal.  But  this  might  be  enough  to  get 
you  started. 

A  couple  of  closing  questions. 
Dale  .  .  .  wouldn’t  it  be  easier  just  to 
code  your  app  in  a  real-man’s  language 
like  C?  And  Jeff .  .  .  what  the  hell  IS 
fugu,  anyhow? 

Bob  Twilling 

Bozeman,  Montana 

Dear  DDJ, 

In  your  January  issue,  you  printed  a 
letter  from  Dale  Lucas  asking  for  help 
interfacing  Turbo  Pascal  to  C.  Jeff  Dun- 
temann’s  response  spent  more  effort 
bashing  C  than  helping  Mr.  Lucas.  I’m 
not  particularly  fond  of  C  either,  but  I 
think  I  have  a  very  simple  solution. 

I  know  nothing  about  Turbo  Pascal, 
but  if  it  uses  (or  can  be  made  to  use) 
the  same  calling  convention  as  Micro¬ 
soft  Pascal,  we’re  in  luck.  Simply  use 
Microsoft  QuickC  to  create  one-line 
helper  functions  that  translate  the  call¬ 
ing  conventions.  These  helper  func¬ 
tions  would  be  declared  as  “pascal” 
functions,  and  thus  be  callable  directly 
by  Pascal.  The  only  statement  in  the 
function  would  be  a  call  to  the  library 
function  using  the  C  calling  conven¬ 
tion.  For  example: 

int  cdecl  foobarC(int,int);  /*  This  is  in 
the  library  V 

int  pascal  foobarPascal(int  argl,  int  arg2) 

( 

return  (  foobarC(argl,  arg2)  ); 


This  assumes  the  C-based  library  has  a 
function  called  foobarC( ),  which  has 


two  integer  arguments  and  an  integer 
return  value.  The  function  foobarPas- 
cal( )  passes  the  arguments  in  the  re¬ 
turn  value  out. 

Tim  Paterson 

Renton,  Washington 

Dear  DDJ, 

This  letter  is  in  response  to  Jeff  Dun- 
temann’s  answer  to  Dale  Lucas’s  letter 
in  the  January  1990  issue  of  Dr.  Dobb’s 
Journal. 

I  disagree  with  Jeffs  answer.  A  Pas¬ 
cal  routine  can  call  a  C  routine  by  using 
an  impedance  matching  routine  writ¬ 
ten  in  assembly.  The  routine  takes  the 
Pascal  arguments,  pushes  them  on  the 
stack,  calls  the  C  routine,  cleans  up  the 
arguments  pushed,  and  then  cleans  up 
the  stack  for  the  Pascal  caller.  A  macro 
can  be  built,  which  has  the  Pascal  entry 
point,  the  matching  C  entry  point,  and 
the  size  of  the  arguments  in  bytes.  The 
macro  CHook  in  Listing  One  (below) 
implements  this. 

The  Pascal  programmer  simply  calls 
the  Pascal  entry  point.  The  impedance 
matcher  handles  the  language  differ¬ 
ences  and  returns.  Simple,  easy,  and 
direct.  Much  better  than  recoding  a 
debugged,  commercial  library. 

By  placing  the  code  in  a  macro,  the 
user  can  just  build  a  table  of  macro 
calls  which  reflect  all  entries  to  the  C 
library.  Each  macro  expands  and  builds 
the  impedance  matching  code  for  each 
library  entry  point. 

Some  notes  involving  the  use  of  the 
macro: 

•  The  argument  size  is  given  in  bytes, 
not  number  of  arguments.  You  must 
determine  the  number  of  bytes  by  add¬ 
ing  the  number  of  bytes  in  each  argu¬ 
ment  that  is  passed. 

•  This  impedance  matcher  will  work 


for  Pascal  procedures.  For  functions, 
you  will  have  to  make  sure  that  your 
flavor  of  Pascal  uses  AX  for  1 6-bit  re¬ 
turn  values  and  DX:  AX  for  32-bit  return 
values.  If  you  need  to  map  the  function 
return  values,  just  add  this  to  the  macro. 

•  I  coded  this  macro  for  large  model 
programs.  Small  model  programs  must 
adjust  the  value  added  to  SI  from  6  to  4. 

•  If  SS  matches  DS  at  all  times,  the 
push/load/pop  of  DS  can  be  removed. 

•  The  argument  transfer  can  be  sped 
up  by  using  a  MOVSW  and  dividing 
the  count  stored  in  CX  by  2.  This  should 
always  work  because  C  requires  the 
minimum  argument  by  an  int  (2  bytes 
under  MSC). 

•  If  the  size  of  the  arguments  is  0,  the 
argument  transfer  code  can  be  elimi¬ 
nated  using  conditional  assembly. 

•  Normally,  the  name  of  a  C  routine 
starts  with  an  underscore.  This  could 
be  included  in  the  macro  instead  of 
requiring  an  underscore  for  every  CHook 
invocation. 

•  The  impedance  match  does  take  time. 
If  you  have  a  very  time-critical  call,  you 
may  have  to  recode  the  routine  in  Pas¬ 
cal  or  directly  in  assembly.  However, 
the  macro  can  get  you  up  and  running 
quickly. 

This  code  has  not  been  tested  with 
Turbo  Pascal.  It  has  only  been  tested 
using  a  Microsoft  C  program  (Listing 
One)  that  calls  the  Pascal  entry  using 
the  pascal  keyword.  If  the  macro  doesn’t 
work  with  Turbo  Pascal,  it  should  only 
take  a  small  amount  of  tweaking  to 
make  it  work.  The  key  is  to  draw  a 
picture  of  your  stack  frame  and  test  it 
in  Debug,  following  the  argument  flow. 

Jim  Shimandle,  Primary  Syncretics 

Santa  Clara,  Calif. 

DDJ 


Listing  One 

CALL  CEntry 

Call  the  C  routine 

;  c2pas.asm 

ADD  SP,  ArgSize 

Remove  arguments  from  stack 

;  C/PASCAL  impedence  matching  module 

POP  DS 

Restore  registers 

. model 

large 

POP  DI 

code  segment  para  public 

code' 

POP  SI 

POP  CX 

POP  BP 

Restore  frame 

CHook  MACRO • 

PascalEntry, 

CEntry,  ArgSize 

RET  ArgSize 

Exit 

EXTRN 

CEntry :FAR 

PUBLIC 

PascalEntry 

PascalEntry  ENDP 

PascalEntry 

PUSH 

PROC 

;  Make  stack  frame 

ENDM 

MOV 

BP,  SP 

;  Invoke  macro  for  test  routine 

PUSH 

CX 

;  Save  registers 

PUSH 

SI 

CHook 

p  sum3,  c  sum3,  6 

Invoke  macro  for: 

PUSH 

DI 

p  sum3  is  PASCAL  call 

PUSH 

DS 

c  sum3  is  C  library  routine 

6  is  the  number  of  argument  bytes 

MOV 

CX,  SS 

;  Set  DS  to  point  to  stack 

DS,  CX 

SUB 

SP,  ArgSize 

;  Save  space  for  arguments 

code 

ends 

MOV 

CX,  ArgSize 

;  Set  count  for  arg  transfer 

MOV 

SI,  BP 

;  Get  frame  pointer 

;  end 

of  c2pas.asm 

ADD 

SI,  6 

;  Point  to  start  of  PASCAL  arguments 

’MOV 

DI,  SP 

;  Point  to  start  of  C  arguments 

CLD 

REP  MQVSB 

;  Move  is  up 
;  Move  the  arguments 

End  Listing 
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Bidirectional  Associative 
Memory  Systems  in 

C++ 

Recent  innovation  makes  associative  memory  practical  for 

real-world  problems 


Adam  Blum 


Content-addressability  was  always  a  goal  of  early 
neural  network  pioneers.  It  is  a  quest  that  has  been 
pursued  by  computer  scientists  in  general  for  dec¬ 
ades.  However,  the  goal  has  proved  highly  elusive. 
Search  time  has  always  depended  on  the  amount 
of  data  stored,  although  much  research  has  gone  into  reduc¬ 
ing  the  slope  of  this  curve.  Real-time  pattern  recognition  (as 
applied  to  any  number  of  fields,  be  it  speech  recognition, 
radar  signature  identification,  or  part  classification)  is  still 
far  from  reality.  One  particular  neural-network  construct, 
bidirectional  associative  memory  (or  BAM),  has  promised 
some  solution  to  this  problem. 

I’ll  first  describe  the  BAM  concept,  then  show  you  how  a 
relatively  recent  construct,  the  Bam  System,  can  make  it 
immediately  feasible  for  real  problems.  Finally,  I’ll  present 
an  actual  implementation  of  the  Bam  System  written  in  C++. 

As  developed  by  Bart  Kosko,  BAMs  are  a  neural-network- 
based  attempt  at  content-addressable  memories.  They  are 
based  on  a  two-layer  feedback  neural  network.  They  at¬ 
tempt  to  encode  m  pattern  pairs  (A^Bj)  where  Ai  e  {-l,+l)n 
and  Bj  e  f-l,+l}p  in  an  n  x  p  matrix  M.  BAMs  are  globally 
stable  and  provide  instant  recall  of  either  of  the  two-pattern 
pair  elements.  However,  BAMs  face  some  limitations.  For 
large  pattern  lengths,  n,  storage  requirements  increase  0(n2). 
More  importantly,  storage  capacity  is  only,  on  an  average, 
m  <  min(n,p).  Thus,  for  moderate  pattern  lengths,  capacity 
of  the  matrix  M  becomes  a  problem.  Recent  research  prom¬ 
ises  help  for  this  problem.  However,  some  initial  description 
of  BAMs  should  be  made. 


Adam  is  a  programmer  analyst  at  Ketron  Inc.  of  Arlington, 
Virginia,  and  is  the  principal  developer  of  several  commer¬ 
cial  software  packages.  His  interests  include  compiler  de¬ 
sign,  C++,  and  (of  course)  applications  of  neural  nets.  He 
can  be  contacted  at  1700  N.  Moore  St.,  Ste.  1710,  Arlington, 
VA  22209,  or  on  CompuServe  at  72650, 1 773. 


Encoding 

BAM  encoding  is  accomplished  by  simply  summing  the 
correlation  matrices  of  each  of  the  pattern  pairs.  That  is,  the 
matrix  that  encodes  the  first  m  pattern  pairs,  M,  is  simply: 

m 

M  =  SAjTBi 
i=l 

Thus,  to  encode  a  pattern  pair,  simply  produce  its  correla¬ 
tion  matrix,  AjTBj,  and  add  the  values  to  the  current  matrix 
M.  For  discrete  implementations,  it  so  happens  that  the 
matrix  arithmetic  works  out  better  if  Os  and  Is  are  encoded 
as  -Is  and  +ls.  So  the  first  step  in  the  process  will  be  to 
convert  any  (0,1 1  string  to  i-1,+  1).  Example  1  shows  this 
process. 

Note  that  we  can  erase  association  (A;,Bj)  from  M  by 
adding  -XiTYi  to  M.  But  if  we  are  using  a  1-1, +11  representa¬ 
tion,  this  is  the  same  as  adding  (A^BC)  or  (AjC,Bj)  to  M 
(where  C  represents  the  pattern’s  complement).  This  fact 
will  become  important  in  our  implementation  of  the  BAM 
system. 

Decoding 

After  we  have  “trained”  our  BAM  with  the  m  pattern  pairs 
(A^Bp,  we  want  the  BAM  to  recall  pattern  Bj  every  time  A; 
is  presented  to  the  matrix  (and,  conversely,  recall  Aj  every 
time  Bj  is  presented  to  the  matrix).  It  turns  out  that  BAMs 
also  have  the  property  that  Bj  will  be  recalled  every  time 
something  close  to  Aj  is  presented.  Example  2  outlines  the 
steps  involved  in  the  decoding  process. 

But  it  won’t  go  on  forever.  As  shown  in  Example  2, 
eventually  the  fields  will  “resonate”  to  steady  patterns.  This 
property  of  BAMs  is  called  “global  stability.”  Lyapunov 
energy  functions  allow  us  to  prove  that  BAMs  are  globally 
stable. 
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Energy  Functions  and  Stability 

Lyapunov  showed  that  any  function  expressed  in  terms  of 
the  system  parameters  that  is  zero  at  the  origin  and  has 
nonincreasing  changes  is  globally  stable. 

An  energy  function  for  the  BAM  can  be  E(A,B)=  -AWBT. 
This  function  is  obviously  zero  at  the  origin  (that  is,  zero 
when  A  and  B  are  zero).  We  just  need  to  show  that  it  has 
nonincreasing  changes.  Well,  AEa(A,B)=  -AWBT  and  by  the 
definition  of  our  function/  each  A;  in  A  will  be  positive  only 
if  WjB  is  positive.  If  A  is  negative,  WjB  must  also  be  nega¬ 
tive.  Thus  the  change  in  energy  will  always  be  negative  or 
zero.  The  system  is  thus  globally  stable. 

Adaptive  BAM 

As  we  have  just  described  it,  the  connection  matrix  M  is 
simply  the  sum  of  the  correlation  matrices  of  the  patterns 
presented  to  it.  We  can  use  more  sophisticated  equations 
to  allow  faster  convergence  or  more  accurate  recall.  As  long 
as  such  equations  can  also  be  shown  to  converge,  we 
should  have  no  problem  with  this. 

The  simplest  of  these  learning  laws  is  called  Hebb’s  law: 
ire  =  -rrijj  +  f/Xj)  *  fj(Yj),  where  mi(.  is  the  connection  weight 
between  the  neuron  x(  and  neuron  y^  and  f  and  f  are  the 
threshold  activation  functions  for  x  and  y,  respectively. 

Other  laws  that  could  be  used  include  competitive  learn¬ 
ing  and  differential  Hebb;  there  is  much  research  on  which 
of  these  is  most  effective.  In  our  implementation,  we  will 
be  presenting  a  simple  nonadaptive  BAM.  However,  it  is 
easily  extensible  to  the  learning  function  of  choice. 

Problems 

BAM  faces  two  problems,  the  first  of  which  is  that  the 


amount  of  storage  taken  up  varies  0(n2),  where  n  is  the 
pattern  length  (actually,  it  will  vary  O(np)  where  n  is  pattern 
length  of  A  and  p  is  pattern  length  of  B). 

The  second  problem  —  capacity  —  is  more  critical.  Reli¬ 
able  retrieval  of  associations  begins  to  degrade  when  the 
number  of  patterns  stored,  m,  is  greater  than  the  minimum 
of  the  two-pattern  dimensions.  In  other  words,  to  be  reliable 
the  matrix  capacity  is  m  <  min(n,p). 

For  large  pattern  lengths,  this  is  not  so  much  of  a  problem, 
but  many  applications  have  inherently  moderate  pattern 
lengths.  We  intuitively  find  it  almost  obvious  that  if  a  BAM 
can  store  only  up  to  the  minimum  of  its  pattern  lengths,  it 
will  be  virtually  useless  for  real-world  applications. 

BAM  Systems 

In  1989,  Patrick  Simpson  of  General  Dynamics  published  a 
paper  introducing  the  concept  of  a  “BAM  System.”  This  is  a 
rather  uninformative  name  for  a  system  that  allows  for 
multiple  matrices  when  one  matrix’s  capacity  is  saturated. 
Perhaps  a  better  name  would  be  “Multi-Matrix  BAM”  or, 
because  each  matrix  is  just  a  representation  of  the  connec¬ 
tivity  between  the  two  patterns,  “Multi-Connective  BAM.” 
Anyway,  it  is  an  inventive  way  to  overcome  the  severe 
problem  of  matrix  capacity. 

The  Bam  System  operates  as  follows:  Pattern  pairs  are 
encoded  one  by  one  in  a  single  BAM  matrix,  M,.  After  each 
pattern  pair  is  encoded,  the  matrix  must  be  tested  to  ensure 
that  each  pattern  pair  stored  can  be  recalled.  If  a  pattern 
pair  cannot  be  recalled,  the  current  pair  is  removed  from  the 
matrix.  We  then  attempt  to  store  the  pair  in  another  connec¬ 
tion  matrix.  We  continue  to  try  to  store  it  in  other  matrices, 
M.,  until  it  is  stored  such  that  all  pattern  pairs  in  that  matrix 
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BAM  SYSTEMS 


can  be  recalled  successfully.  The  pattern  association  is  then 
permanently  stored  in  this  matrix. 

Decoding,  that  is  presenting  one-half  of  a  pattern  and 
recalling  the  other  half  of  the  pair,  is  a  bit  more  complicated. 
Because  we  now  have  several  matrices  storing  pattern  asso¬ 
ciations,  we  don’t  know  which  one  is  the  correct  one  to  look 
in  to  recall  the  pattern  pair.  To  choose  which  pattern  pair 
to  recall  from  each  matrix,  we  use  the  following  criterion. 

We  determine  all  the  returned  pattern  pairs  (X^Y;)  that 


If  we  are  trying  to  encode 

A,  =(101010)  B,=  (1100) 

A2  =  (111000)  B2  =  (1010) 

we  first  convert  to  {-1  ,+1 }. 

X,=  (1  -11-1  1  -1)  Y,=  (1  1  -1  -1) 

X2=  (1  11-1  -1  -1)  Y2=  (1  -1  1-1) 


X/  Y,=  1  1-1-1 
-1-111 
1  1-1-1 
-1111 
1  1-1-1 
-1-1  1  1 

X,tY2=1  -1  1  -1 
1-1  1-1 
1-1  1-1 
-11-1  1 
-11-11 
-11-11 


M  =  2  0  0-2 
0-220 
2  0  0-2 
-2  2  0  2 
0  2-20 
-2  0  0  2 


Example  1:  The  encoding  process 
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Each  neuron  b,  in  field  Fb  (Fa  and  Fb  will  be  used  to  refer  to  the 
two  pattern  fields  A  and  B)  receives  a  gated  input  of  all  the 
neurons  in  Fa  with  a  nonlinear  threshold  function  applied.  In  our 
bipolar  discrete  example  a  typical  function  might  be: 

f(x,y)  =1  if  x  >  0 
y  if  x  =  0 
0  if  x  <  0 

We  now  have  a  pattern  Br  Flowever,  we  aren't  done  yet.  The 
output  from  pattern  B  is  then  fed  back  through  the  transpose  of 
matrix  M  to  produce  pattern  A, .  That  is,  each  neuron  A,  in  A 
receives  gated  input  from  each  neuron  B^  in  B  and  applies  the 
same  threshold  function  to  it. 

A,  is  then  sent  back  through  the  matrix  again  to  produce  B2,  and 
on  this  goes. 

A  >  F(AM)  -->  B, 

A,  <~  F(B,MT)  <~  B, 

A,  ~>  F(A,M)  ~>  B2 


A;  ~>  F(Aj)  ~>  B; 

A  ~>  F(B,  M)  ~>  B( 


Example  2:  The  decoding  process 
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(continued  from  page  18) 

have  the  same  energy  as  the  pair  (A,Yp  (where  A  is  the 
presented  pattern).  Of  these  patterns  we  choose  that  pattern 
pair  whose  energy  is  closest  to  the  matrix’s  orthogonal  BAM 
energy.  (Orthogonal  BAM  energy  is  the  energy  a  matrix 
would  have  if  all  its  stored  patterns  were  orthogonal,  which 
turns  out  to  be  equal  to  the  negative  of  the  product  of  the 
pattern  lengths,  E*  =  -np.  Energy  of  a  pattern  pair  can  be 
calculated  the  same  way  as  in  our  previous  discussions, 
E  =-XMYT,  where  X  and  Y  are  the  two  patterns.) 

There  are  some  problems  with  the  Bam  System.  In  order 
to  keep  checking  that  the  patterns  were  stored  reliably  in 
each  matrix  (without  corrupting  the  other  patterns  already 
in  the  matrix)  the  patterns  need  to  be  stored  separately. 
Also,  the  need  to  compute  the  “best”  recall  from  each  of  the 
BAM  matrices  could  be  computationally  prohibitive.  Parallel 
hardware  (which,  presumably,  a  BAM  would  be  running 
on  anyway)  could  possibly  ease  this  burden. 

The  Implementation 

C++  provides  an  excellent  tool  for  implementing  neural  nets 
in  general  and  BAMs  in  particular.  Most  of  the  constructs  in 
this  discussion  of  BAMs  were  vectors  and  matrices.  This  is 
a  classic  application  of  object-oriented  programming.  Classes 
for  vectors  and  matrices  should  go  a  long  way  toward 
making  the  implementation  easier.  Listing  One  (page  84)  is 
BAM.HPP,  the  BAM  header  file  that  contains  the  class  defini¬ 
tions.  Listing  Two  (page  84)  is  BAM.CPP,  the  BAM  program 
file  that  contains  the  BAM  implementation. 

The  vector  class  is  implemented  in  classic  fashion  (almost 
identical  to  Stroustrup’s).  Methods  are  provided  for  assign¬ 
ment,  multiplication  by  scalar  constant,  and  dot  product. 
This  is  all  that  is  really  necessary,  but  a  few  more  methods 


are  provided  for  completeness.  Streams  input  and  output 
are  provided  to  read  the  patterns  in  and  display  patterns  to 
the  user.  The  streams  functions  do  the  necessary  (0,1)  to 
(-1,  +1)  conversion  discussed  earlier. 

The  matrix  class  is  implemented  as  an  array  of  pointers 
(int  **),  with  indicators  of  the  number  of  rows  and  columns. 
It  could  conceivably  have  been  implemented  as  an  array  of 
vector  objects.  I  chose  representation  for  efficiency.  There 
are  several  constructors  provided.  The  first  simply  initializes 
the  matrix  from  specified  dimensions.  These  dimensions 
default  to  the  particular  application’s  two  pattern  lengths 
(specified  by  the  ROWS  and  COLS  constants).  Other  con¬ 
structors  are  provided  to  form  a  matrix  from  a  pair  of  vectors 
by  multiplying  one  vector  by  the  transpose  of  another 
(M=ABt).  Standard  matrix  arithmetic  functions  are  included. 
Methods  are  also  provided  to  form  a  vector  from  a  row  or 
column  “slice”  of  the  matrix.  Streams  output  is  provided  for 
debugging  diagnostics. 

Another  fundamental  construct  is  the  pattern  pair.  This  is, 
after  all,  what  the  BAM  lets  us  do  —  retrieve  pattern  associa¬ 
tions.  Pattern  pairs  are  represented  by  the  “vecpair”  (vector 
pair)  class.  An  “encode”  operation  will  encode  a  vecpair.  A 
“recall”  operation  will  return  a  vecpair,  when  supplied  with 
a  pattern  (or  “vec”). 

Once  we  have  these  vector,  matrix,  and  vector  pair  classes, 
implementing  the  BAM  is  fairly  simple.  The  BAM  is  essen¬ 
tially  just  a  matrix.  We  use  the  C++  inheritance  mechanism 
to  inherit  the  matrix  and  all  its  functions.  We  made  the 
matrix’s  data  structures  “protected”  instead  of  “private”  so 
the  derived  BAM  matrix  class  could  use  the  matrix’s  data 
structures.  We  now  just  add  a  vecpair  pointer  for  the  pattern 
pair  list  and  the  BAM  matrix  functions. 

(continued  on  page  24) 
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(continued  from  page  20) 

These  consist  mainly  of  the  “encode”  and  “recall”  func¬ 
tions  central  to  the  BAM.  Encode  simply  takes  the  “vecpair” 
corresponding  to  the  association  and  adds  it  (with  matrix 
add)  to  the  current  BAM.  Recall  “feeds”  the  presented  pat¬ 
tern  through  the  matrix  (with  dot  products  and  by  applying 
a  threshold  function  as  discussed  earlier)  to  return  another 
vector.  We  keep  feeding  the  vectors  back  and  forth  until 
they  stabilize  to  a  consistent  pattern  association.  There  are 
also  some  auxiliary  functions  for  checking  the  integrity  of 
the  BAM,  returning  its  energy  for  a  particular  association  (as 
discussed  earlier),  and  for  “uncoding”  or  removing  an  asso¬ 
ciation  from  the  BAM. 

The  Bam  System  class  consists  of  an  array  of  pointers  to 

BAMs  are  a  neural-network-based 
attempt  at  content-addressable 
memories 


BAM  matrices.  Each  time  a  BAM  matrix  is  saturated,  a  new 
matrix  is  created,  and  the  new  pattern  association  is  stored 
in  it.  The  major  functions  are  again  “encode”  and  “recall.” 
Encode  attempts  to  store  the  pattern  association  in  each  of 
the  BAM  matrices  until  it  succeeds.  It  will  create  a  new  BAM 
matrix  if  it  runs  out  of  matrices.  Recall  performs  a  BAM 
matrix  recall  operation  on  each  of  the  BAM  matrices.  The 
returned  association  that  is  closest  to  the  presented  pattern 
and  has  the  lowest  energy  relative  to  its  matrix  (as  discussed 
earlier)  is  then  returned  as  the  “correct”  pattern  association. 
Another  function  is  provided  to  “train”  the  Bam  System  from 
a  specified  file  of  pattern  associations.  The  patterns  happen  to 
be  represented  as  01  strings,  but  this  could  be  easily  changed 
to  whatever  representation  (for  example,  floating-point  num¬ 
bers,  character  strings)  suits  the  specific  application. 

Thanks  to  the  wonders  of  C++,  the  code  is  very  readable. 
Most  of  the  algorithms  can  be  implemented  in  the  same 
vocabulary  as  the  theory.  Take  a  look  at  it  to  examine  the 
mechanics  in  detail.  It  should  even  be  clearer  (and  certainly 
more  specific)  than  the  discussion  above. 

The  Test  Program 

Eve  included  a  test  program  (TESTBAM.CPP,  Listing  Three, 
page  88)  that  demonstrates  an  actual  running  Bam  System. 
A  Bam  System  is  created  and  told  to  “train”  itself  from  the 
file  TEST.FIL  (see  Listing  Four,  page  88).  This  file  contains 
a  set  of  simple  “pattern  pairs,”  represented  as  (0,1)  strings 
delimited  by  commas  —  one  pattern  pair  to  a  line.  Once  the 
Bam  System  is  trained,  you  can  enter  any  pattern  you  want 
(using  the  01  format  mentioned)  and  the  correct  pattern 
association  will  be  recalled.  If  the  pattern  is  slightly  wrong, 
the  correct  pattern  association  will  still  most  likely  be  re¬ 
called.  The  make  file,  TESTBAM.MK  (Listing  Five,  page  88), 
shows  how  to  construct  this  test  program. 

What  Can  you  Do  With  It? 

Uses  of  the  Bam  System  are  constrained  only  by  your 
imagination.  Obvious  uses  include  optical  character  recog¬ 
nition  (the  pixel  patterns  scanned  in  would  be  associated 
with  the  actual  letters),  voice  recognition  (the  acoustic  pat¬ 
tern  would  be  associated  with  the  actual  word),  or  a  super 
spell  checker  (word  patterns  associated  with  phoneme¬ 
string  patterns).  You  can  use  a  Bam  System  in  just  about  any 
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(continued  from  page  24) 

application  where  you  have  a  large  number  of  “associa¬ 
tions”  that  you  would  like  to  be  able  to  recall  close  to 
instantaneously,  and  where  some  tolerance  for  error  would 
be  useful. 

A  successful  application  of  BAM  for  radar  signature  classi¬ 
fication  was  presented  at  the  January  1990  International 
Joint  Conference  on  Neural  Networks  (IJCNN).  However,  it 
was  not  a  Bam  System,  and  the  implementors  had  to  resort 
to  various  other  tricks  to  get  around  capacity  limitations. 
Several  other  associative  memory  applications  appeared; 
but  none  of  them  were  associative  memory  systems.  They 
all  would  probably  run  into  the  capacity  roadblock  eventu¬ 
ally  for  large  data  sets.  Associative  memories  and  BAMs 
have  begun  to  appear  implemented  in  VLSI,  but  again  the 
capacity  will  prove  to  be  a  limitation  for  practical  work.  Bam 
Systems  should  have  a  radical  effect  on  the  usefulness  of 
these  chips. 

Conclusion 

Bidirectional  associative  memories  appear  to  provide  the 
content-addressable  memory  long  sought  after  by  computer 
scientists.  They  provide  instant  recall  of  pattern  association, 
tolerance  for  error  and  fuzziness  in  the  provided  pattern, 
and  global  stability.  However,  by  themselves  they  face  some 
limitations.  Simple  BAM  matrices  cannot  encode  more  pat¬ 
tern  pairs  than  the  smaller  of  their  two  dimensions.  Some 
applications  have  inherently  smaller  pattern  length,  and,  for 
them,  matrix  capacity  will  prove  to  be  a  severe  limitation. 
However,  the  Bam  System  appears  to  overcome  this  prob¬ 
lem,  making  associative  memory  a  reality. 
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A  Neural  Network 
Instantiation  Environment 

Dynamically  creating  neural  nets  lets  you  concentrate  on 
network  response  characteristics 


Andrew  J.  Czuchry,  Jr. 


The  automatic  generation  of  tai¬ 
lored  neural  network  architec¬ 
tures  greatly  simplifies  the  tedi¬ 
ous  task  of  putting  together  neu¬ 
ral  networks.  Typically,  an  ar¬ 
chitecture  is  assembled  by  manually 
writing  and  modifying  a  collection  of 
software  routines;  automation  speeds 
this  standard  process  of  assembling  net¬ 
works.  However,  task  simplification 
through  the  automatic  generation  of 
network  architectures  often  implies  lim¬ 
ited  flexibility  when  applied  to  real- 
world  problems.  In  order  to  develop 
useful  network  architectures  in  an  effi¬ 
cient  manner,  the  provision  of  both 
task  simplification  and  complete  flexi¬ 
bility  is  an  inherent  design  principle  in 
the  research  environment  that  instanti- 
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ates  (dynamically  creates)  neural  net¬ 
works.  Instantiation  is  the  flexible  pro¬ 
cess  of  automatically  piecing  together 
architectures  based  upon  modifiable 
structures  that  represent  the  parame¬ 
ters  of  the  assembled  neural  networks. 

The  incorporation  of  network  instan¬ 
tiation  into  an  entire  research  environ¬ 
ment  for  neural  networks  results  in  a 
system  that  provides  both  task  simplifi¬ 
cation  and  complete  flexibility. 

Task  simplification  can  be  achieved 
by  using  a  variety  of  knowledge-repre¬ 


sentation  techniques.  Complete  flexi¬ 
bility  can  be  maintained  by  strictly  ap¬ 
plying  standard  software-modulariza¬ 
tion  techniques.  The  merging  of  these 
two  types  of  techniques  —  knowledge 
j  representation  and  software  modulariza- 
J  tion  —  provides  the  foundation  for  the 
instantiation  process  that  forms  the  ba¬ 
sis  of  a  powerful  neural  network  re¬ 
search  environment. 

In  this  article,  I  discuss  the  need  for 
such  an  environment  and  describe  a 
working  version.  In  so  doing,  I  de¬ 
scribe  the  knowledge-representation 
techniques  used,  and  the  essential  inte¬ 
gration  of  knowledge  representation 
and  software  modularization.  (The 
model  was  developed  on  a  Symbolics 
Lisp  machine,  chosen  for  its  flexibility 
and  power  in  symbolic  manipulation 
and  for  its  exploratory  programming 
environment.  The  implementation  lan¬ 
guage  is  Lisp.)  I  also  present  experi¬ 
mental  results  of  using  the  environ¬ 
ment  for  a  test-case  network,  and  fi¬ 
nally,  I  discuss  future  efforts  and  the 
evolution  of  the  environment. 

System  Overview 

The  task  of  generating  usable  neural 
network  architectures  for  real-world 
problems  is  quite  challenging.  Basic 
standard  networks  are  merely  skele¬ 
tons  for  useful  systems.  For  example, 
Fukushima’s  neocognitron1  is  really  a 
class  of  neural  networks.  Most  often 
only  specific  instances  (class  elements) 
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(continued  from  page  28) 
are  described  in  the  literature  —  the 
skeleton  for  a  neocognitron  is  a  multi¬ 
layer,  hierarchical  neural  network  for 
visual  pattern  recognition.  It  consists 
of  a  series  of  layers  of  subnetworks 
that  are  organized  according  to  spe¬ 
cific  guidelines.  The  system’s  exact  pa¬ 
rameters  (for  example,  the  number  of 
layers,  the  number  of  subnetworks  per 
layer,  and  the  size  of  each  subnetwork) 
are  often  tailored  to  the  problem  being 
addressed.  This  tailoring  is  the  meat  on 
the  skeleton  and  is  determined  by  the 
application’s  processing  requirements. 

Such  tailoring  is  evident  in  the  differ¬ 
ences  between  the  architectures  of  the 
neocognitron  described  by  Fukushima 
and  Miyake2  and  by  Fukushima.10 
Fukushima  and  Miyake2  describe  a 
seven-layer  system  for  type-written  or 
stylized  (that  is,  written  to  meet  certain 
specifications  of  consistency)  numeral 
recognition.  Each  layer  of  the  network 
has  24  subnetworks,  except  for  the  in¬ 
put  layer,  which  is  a  single  subnetwork 
layer.  In  contrast,  the  architecture  of 
the  neocognitron  for  hand-written  nu¬ 
meral  recognition,  as  described  in 
Fukushima,10  is  a  nine-layer  network 
with  1,  12,  8,  38,  19,  35,  23,  11,  and  10 
subnetworks  per  respective  layer. 

In  addition  to  these  architectural  dif¬ 
ferences,  the  setting  of  various  internal 
parameters  may  also  vary  according  to 
the  application.  More  noise  tolerance 
is  provided  by  decreasing  the  inhibitory 
(“negative”)  weights  and  shrinking  the 
number  of  connections  per  node  in  a 
subnetwork.  Finer  degrees  of  class  sepa¬ 
ration  are  provided  by  increasing  inhi¬ 
bition  and  increasing  the  number  of 
connections  between  the  nodes  in  each 
subnetwork.  A  variety  of  other  internal 
parameters  can  be  altered  as  well. 

Given  the  goal  of  efficiently  estab¬ 
lishing  useful  architectures  and  parame¬ 
ter  settings  for  real-world  applications, 
automatic  generation  of  neural  networks 
based  upon  a  flexible  representation 
of  the  desired  characteristics  is  vital. 
This  goal  has  been  realized  through 
the  development  of  the  research  envi¬ 
ronment  described  in  this  article.  The 
environment  dynamically  creates  neu¬ 
ral  networks  based  upon  the  informa¬ 
tion  encoded  in  underlying  knowledge- 
representation  structures.  The  research 
environment  automatically  builds  these 
structures  based  upon  parametric  speci¬ 
fication  of  the  desired  characteristics 
of  the  network  architecture. 

For  example,  passing  the  network 
creation  routines  the  network  type  of 
neocognitron ,  the  layer  number  9,  and 
the  subnetwork  size  list  of  (1,  12,  8, 
38,  19,  35,  23,  11,  10)  would  produce 
an  architecture  similar  to  the  one  de¬ 


scribed  by  Fukushima.10  An  exact  match 
to  Fukushima’s  architecture  could  be 
obtained  through  additional  parameter 
specifications.  The  key  point  is  that  the 
research  environment  comprises  a  com¬ 
bination  of  multipurpose  routines  that 
are  pieced  together  appropriately 
through  the  use  of  flexible  knowledge 
representation  structures.  The  environ¬ 
ment’s  flexibility  is  maintained  through 
the  strict  application  of  software-modu¬ 
larization  techniques.  For  example,  soft¬ 
ware  modularization  ensures  that  weight 
calculation  routines  can  be  adjusted 
independently  of  the  connection  calcu¬ 
lation  routines.  These  ideas  are  clari¬ 
fied  in  the  following  sections. 

Knowledge  Representation 

There  are  two  fundamental  ideas  be¬ 
hind  the  use  of  knowledge  representa¬ 
tion.  The  first  is  that  simple  parametric 
changes  can  significantly  alter  the  net¬ 
work  architecture’s  final  structure.  For 
example,  changing  the  size  (number 
of  nodes)  in  each  subnetwork  can 
greatly  affect  the  specific  connections 
between  the  nodes.  This  is  of  primary 
importance  in  networks  such  as  the 
neocognitron1  for  two  reasons: 

1 .  The  connections  are  between  subnet¬ 
works  rather  than  within  subnetworks. 

2.  The  nodes  are  not  completely  con¬ 
nected  (that  is,  every  node  is  connected 
to  only  a  subset  of  the  nodes  in  other 
subnetworks).  This  means  that  the  con¬ 
nection  architecture  is  heavily  influenced 
by  the  size  and  number  of  subnetworks. 

The  second  fundamental  idea  is  that 
many  routines  for  the  creation  of  neu¬ 
ral  networks  and  subsequent  network 
processing  are  common  to  entirely  dif¬ 
ferent  architectures.  As  a  result,  these 
routines  can  be  reused  and,  to  some 
degree,  tailored  automatically  by  com¬ 
bining  and  adapting  the  modules.  The 
realization  of  a  research  environment 
that  automatically  generates  flexible  neu¬ 
ral  network  architectures  has,  thus,  been 
based  upon  a  knowledge  representa¬ 
tion  in  which  every  structure  “carries 
around  with  it”  all  the  local  informa¬ 
tion  for  piecing  itself  into  the  network 
puzzle  and  for  subsequently  computing/ 
processing  data  once  the  architecture 
is  assembled. 

Three  main  knowledge  structures  — 
NETS,  LAYERS,  and  PLANEs  —  collec¬ 
tively  compose  the  knowledge  repre¬ 
sentation.  These  structures  are  presented 
in  Listing  One,  page  93-  The  NET struc¬ 
ture  consists  of  a  list  of  one  or  more 
layers  and  a  variety  of  local  parameters 
specific  to  the  global  processing  of  the 
particular  type  of  architecture  (for  ex¬ 
ample,  the  vigilance  parameter  in 
ART.3'5)  ZAKE/?  encodes  a  list  of  subnet- 


30 

302 


Dr.  Dobb’s  Journal,  April  1990 


NEURAL  NETWORK  ENVIRONMENT 


(continued  from  page  30) 
works  and  the  connections  between 
layers  (e.g.,  a  list  of  the  connections 
from  each  subnetwork  in  the  present 
layer  to  the  subnetworks  of  the  preced¬ 
ing  layer).  Local  parameters,  such  as 
inhibition  constants  or  gain  constants, 
are  also  stored  within  the  layer.  The 
type  of  the  layer  (for  example,  S  or  C 
for  the  neocognitron1  and  Fj  or  F2  in 
ART3  5)  is  also  recorded.  A  pointer  to 
the  previous  layer  is  provided  so  that 
the  routines  can  “get  around”  in  the 
network.  PLANE ,  a  subnetwork,  is  used 
to  store  the  connections  within  the 
subnetwork.  The  weights  for  both  inter- 
and  intraplane  connections  are  also  re¬ 
corded  in  the  PLANE  structure.  A  size 
parameter  for  the  plane  is  used  for 
instantiation  and  is  locally  encoded.  A 
pointer  to  the  layer  of  which  this  plane 
is  a  part  is  stored  as  well.  The  actual 
nodes  (cells)  or  processing  elements 
are  stored  as  an  array,  which  is  used 
to  record  output  activation  values. 

In  the  future,  this  array  will  be  ex¬ 
tended  so  that  each  node  is  itself  a 
knowledge  structure.  In  this  way,  the 
activation  functions,  output  functions, 
and  local  node  parameters  can  be  main¬ 
tained  locally.  Such  an  extended  repre¬ 
sentation  will  further  increase  the  environ¬ 
ment’s  flexibility  by  providing  for  the 
adjustment  of  input  and  output  activa¬ 
tion  functions  within  the  overall  archi¬ 
tecture  and,  thereby,  will  extend  the 
standard  of  common  activation  func¬ 
tions  for  each  cell  in  the  subnetwork. 
This  standard  for  specific  activation  func¬ 
tions  for  the  entire  subnetwork  is  not 
a  severe  restriction.  However,  the  ex¬ 
tended  representation  will  support  novel 
research  endeavors  and,  thus,  could 
prove  to  be  extremely  valuable. 

The  information  contained  in  these 
knowledge  structures  is  stored  at  the 
time  of  network  instantiation  and  is 
utilized  as  the  computational  map  by 
the  processing  routines.  The  structures 
thus  dynamically  control  the  routines 
to  be  called,  the  data  to  be  passed,  and 
the  amount  of  processing  to  be  per¬ 
formed.  Each  structure  has  been  de¬ 
signed  to  carry  locally  all  the  informa¬ 
tion  necessary  to  direct  processing 
through  the  contents  of  the  structure 
itself  rather  than  through  a  priori  rou¬ 
tines.  This  advantage  increases  process¬ 
ing  flexibility.  In  adapting  the  flow  of 
processing,  no  routines  need  to  be  al¬ 
tered;  only  the  information  in  the  struc¬ 
tures  is  modified. 

Modularity 

Great  care  has  been  taken  to  ensure 
software  modularity.  The  significance 
of  this  is  apparent  upon  analysis  of  the 
power  obtained  by  the  integration  of 


knowledge  representation  and  software 
modularization.  Before  discussing  the 
integration,  however,  I  will  briefly  de¬ 
scribe  the  modularity. 

Software  modularity  has  been  pre¬ 
served  in  all  three  of  the  main  phases 
of  neural  network  applications:  instan¬ 
tiation,  processing,  and  training.  The 
network  instantiation  routines,  high¬ 
lighted  in  Listing  Two,  page  93,  are  the 
pieces  that  are  meshed  to  dynamically 
create  network  architectures.  Instantia¬ 
tion  is  obviously  the  first  step  in  the  use 
of  neural  networks  for  any  application. 
The  instantiation  process  proceeds  from 
generic  net-level  creation  routines  to 
specific  layer-level  creation  routines  that 
are  tailored  to  the  specific  type  of  net¬ 
work.  Finally,  it  proceeds  to  generic 
plane-level  routines  that  perform  con¬ 
nection  and  connection  weight  calcu¬ 
lations  in  addition  to  creation  of  the 
plane  itself.  Upon  completion  of  the 
instantiation  process,  the  network  is 
ready  for  training. 

Listing  Three,  page  96,  indicates  the 
training  routines.  These  routines  are 
used  to  perform  the  processing  all  the 
way  from  the  network  level  down  to 
the  level  of  the  individual  cell.  Listing 
Three  is  abbreviated,  however,  and  de¬ 
picts  the  routines  only  down  to  the 
initial  processing  at  the  plane  level. 
Subsequent  processing  occurs  at  the 
plane,  connection,  and  cell  levels.  Af¬ 
ter  training,  the  network  can  be  used 
for  identification  tasks.  Identification 
functions  at  the  network  level  are  pre¬ 
sented  in  Listing  Four,  page  98.  Further 
processing  occurs  at  the  layer  and  plane 
levels  but  is  not  included  here. 

Integration 

The  knowledge  representation  struc¬ 
tures  function  as  generic  placeholders 
in  which  data  about  instantiated  neural 
networks  is  recorded.  As  mentioned 
previously,  the  instantiation  process  dy¬ 
namically  produces  an  entire  network 
based  on  the  parametric  specification 
of  the  desired  characteristics.  Instantia¬ 
tion  begins  by  calling  CREATE-NET(see 
Listing  Two)  and  passing  it  the  appro¬ 
priate  parameters  for  the  desired  net¬ 
work. 

Two  examples  of  the  parametric  set¬ 
tings  and  function  calls  for  different 
versions  of  a  neocognitron  are  depicted 
in  Listing  Five,  page  98.  Evaluating  *neo- 
cognitron-net*,  (that  is,  (eval  *neocogni- 
tron-net *))  returns  a  NET  structure  (see 
Listing  One)  that  contains  an  instanti¬ 
ated  network  meeting  the  characteris¬ 
tics  specified  in  the  parameters  recorded 
in  the  *neocognitron-net*vanab\e.  More 
specifically,  a  seven-layer  network 
would  be  created.  The  input  layer  would 
contain  one  subnetwork  (plane),  and 


each  of  the  other  layers  would  contain 
24  planes.  The  plane  in  the  input  layer 
would  contain  a  16  x  16  array  of  nodes 
(cells).  Each  of  the  planes  in  the  next 
layer  would  contain  a  16  x  16  array  of 
cells.  Subsequent  layers  would  be  com¬ 
posed  of  planes  with  10  x  10,  8  x  8,  6 
x  6,  2  x  2,  and  lxl  arrays  of  cells, 
respectively. 

Each  cell  in  a  plane  would  have  a 
“square”  projection  pattern;  cells  are 
connected  to  other  cells  that  occupy  a 
corresponding  square  area  in  another 
plane.  Connections  from  the  first  layer 
to  the  input  layer  would  cover  a  5  x  5 
array.  Connections  from  the  second 
layer  to  the  first  would  also  cover  a  5 
x  5  array,  and  similarly  for  all  the  con¬ 
nections  up  to  and  including  the  con¬ 
nections  from  the  sixth  layer  to  the  fifth 
layer.  Connections  between  the  last  (sev¬ 
enth)  and  the  sixth  layer,  however,  would 
cover  a  2  x  2  array.  Each  cell,  xp  would 
thus  become  an  input  to  multiple  other 
cells,  x  ,  and  each  x.  would  receive 
inputs  from  many  different  xk  cells. 

Each  of  these  connections  has  asso¬ 
ciated  with  it  a  connection  weight. 
Within  the  knowledge  representation, 
the  connection  weights  are  stored  sepa¬ 
rately  from  the  connections  themselves 
so  as  to  provide  for  adaptation  of  the 
weights  independently  of  the  connec¬ 
tion  structure.  In  addition  to  these  ele¬ 
ments  common  to  all  neural  networks 
(that  is,  one  or  more  layers,  one  or 
more  subnetworks  per  layer,  individ¬ 
ual  cells,  connections,  and  connection 
weights),  a  variety  of  other  parameters 
significant  for  the  neocognitron  would 
be  set  as  indicated  in  the  *neocognitron- 
net*v ariable  in  Listing  Five. 

An  additional  comment  about  the 
assignment  of  connections  is  impor¬ 
tant.  The  exact  connection  patterns  are 
calculated  based  upon  the  size  of  the 
sending  and  receiving  planes  and  the 
size  of  the  projection  area.  The  instan¬ 
tiation  routines  are  structured  such  that 
the  appropriate  connections  are  com¬ 
puted  based  upon  the  parameters 
passed  to  the  respective  routines.  For 
example,  if  each  element  in  a  5  x  5 
network  is  to  project  into  a  3  x  4  net¬ 
work  such  that  each  element  has  a  2  x 
2  projection  and  all  of  the  3x4  net¬ 
work  elements  are  covered,  then  the 
system  would  compute  that  the  ele¬ 
ment  in  position  (0,0)  of  the  5x5 
network  would  be  connected  to  the 
elements  in  positions  (0,0),  (0,1),  (1,0), 
and  (1,1)  of  the  3x4  network  (see 
Figure  1).  The  element  in  position  (4,4) 
of  the  5x5  network  would  be  con¬ 
nected  to  the  elements  in  positions  (1,2), 
(1,3),  (2,2),  and  (2,3)  of  the  3x4  net¬ 
work.  A  variety  of  standard  connection 
architectures  have  been  presented  in 
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the  neural  network  literature  —  for  ex¬ 
ample  ART,3'5'6’7  back  propagation,8 
Hopfield  networks,9  and  the  neocog- 
nitron.1  Because  the  connection  calcu¬ 
lation  routines  are  parameterized  and 
actually  calculate  the  connection  pat¬ 
terns,  arbitrary  algorithmically  expressed 
connection  patterns  can  be  realized. 

Experimental  Results 

To  investigate  the  viability  of  the  re¬ 
search  environment  presented  in  this 
article,  a  standard  neural  network  ar¬ 
chitecture  was  chosen  to  test  the  envi¬ 
ronment’s  instantiation,  training,  and 
identification  capabilities.  The  network 
chosen  was  the  neocognitron1  because 
of  its  large  size  and  the  complexity  of 
the  connection  architecture.  More  spe¬ 
cifically,  the  architecture  presented  by 
Fukushima  and  Miyake2  was  repro¬ 
duced  and  is  characterized  by  *neocog- 
nitron-net* in  Listing  Five.  For  this  ver¬ 
sion  of  a  neocognitron,  there  are  a  total 
of  more  than  2.3M  connections,  each 
with  its  own  weighting  factor,  between 
the  10K  cells  and  145  planes  in  the 
network.  Additionally,  several  parame¬ 
ters  interact  and  affect  the  behavior  of 
the  network.  For  example,  each  of  the 
layers  (excluding  the  input  layer)  has 
an  intensity-of-inhibition  parameter  to 
control  the  amount  of  noise  tolerated 
in  matching  a  pattern;  this  parameter 
interacts  with  both  the  excitatory  and 
inhibitory  weights  as  an  output  is  com¬ 
puted  for  a  particular  network  cell. 

Instantiation  of  the  network,  de¬ 
scribed  by  the  *neocognitr on-net*  v ari- 
able  in  Listing  Five,  and  subsequent 
training  and  identification  testing  yielded 
significant  results: 

1.  Different  patterns  produce  different 
excitation  patterns  within  the  net¬ 
work  (see  Figures  2  and  3). 

2.  Training  the  network  alters  its  exci¬ 
tation  patterns  (see  Figures  3  and  4). 

3.  After  training,  only  a  single  cell  fires 
at  the  recognition  layer  in  response 
to  different  stimulus  patterns  (Fig¬ 
ure  4). 

4.  Appropriate  clusterings  are  achieved 
for  multiple  versions  of  various  nu¬ 
meric  characters  (see  Figures  4,  5, 
and  6). 

The  input  pattern  is  depicted  at  the 
base  of  each  figure  in  Figures  2  through 

5.  Each  layer  is  represented  by  the  dou¬ 
ble  row  of  squares  (planes),  which  are 
respectively  labeled  Sa,  Cj,  S2,  C2,  S3, 
and  C3  on  the  right-hand  edge  of  the 
figures.  The  colored  areas  within  each 
square  represent  the  output  activities 
of  the  corresponding  nodes  (cells).  The 
color  scale  is  shown  on  the  left-hand 
edge  of  the  figures  and  indicates  that 


Figure  1:  Connections  calculated  for  2  x  2  projections  from  a  5x  5  network 
into  a  3x4  network 
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Figure  2:  Response  characteristics  of  an  instantiated  neocognitron  to  the 
input  pattern  0  before  training 
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Figure  3:  Response  characteristics  of  an  instantiated  neocognitron  to  the 
input  pattern  1  before  training 
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activity  ranges  from  a  low  level  of  black 
to  blue,  to  green,  to  red,  to  yellow,  to 
a  high  level  of  white.  These  pictures 
are  produced  within  the  research  envi¬ 
ronment  as  a  useful  utility  for  qualita¬ 
tively  observing  the  results  of  the  par¬ 
ticular  instantiated  architecture.  As  de¬ 
picted  herein,  the  results  correlated  well 
with  those  presented  by  Fukushima  and 
Miyake.2 

Future  Efforts 

The  research  environment  and  corre¬ 
sponding  instantiation  of  neural  net¬ 
works  have  many  possible  applications. 
From  a  general  perspective,  such  ap¬ 


plications  encompass  both  new-model 
development  and  the  analysis  of  stan¬ 
dard  network  models.  More  specifically, 
one  of  the  motivating  ideas  behind  this 
research  has  been  that  of  using  digi¬ 
tized  images  as  training  patterns.  The 
hypothesis  is  that  network  models  such 
as  the  neocognitron  should  theoreti¬ 
cally  be  able  to  extract  “useful”  infor¬ 
mation  from  such  images.  For  exam¬ 
ple,  through  training  an  instantiated 
network  using  a  variety  of  images  that 
contain  a  tree,  the  network  should  ex¬ 
tract  the  common  pattern  of  the  tree 
and,  thus,  be  able  to  indicate  the  pres¬ 
ence  of  a  tree  in  subsequent  test  images. 
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Figure  4:  Response  characteristics  of  an  instantiated  neocognitron  to  the 
input  pattern  1  after  training 
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A  possible  future  research  effort 
would  investigate  the  size  of  various 
networks  required  to  actually  perform 
such  recognition  and  to  characterize 
any  additional  requirements  (for  exam¬ 
ple,  use  of  Grossberg’s  Boundary  Con¬ 
tour/Feature  Contour  System  [S.  Gross- 
berg  and  E.  Mingolla,  “Neural  dynam¬ 
ics  of  perceptual  grouping:  Textures, 
boundaries,  and  emergent  segmenta¬ 
tions,”  Perception  &  Psychophysics,  38 
(1985),  141-171.]  as  a  preprocessor 
to  simplify  processing  within  an  appro¬ 
priate  version  of  a  neocognitron).  Ad¬ 
ditionally,  recent  extensions  to  the  neo- 
cognitron’s  architecture  (that  is,  feed¬ 
back  between  layers3)  could  be  incor¬ 
porated  into  the  currently  instantiated 
neocognitrons  and  could  possibly  pro¬ 
vide  for  segmentation  of  trees  within 
the  test  images  after  training  has  oc¬ 
curred.  A  significant  amount  of  work 
would  be  required  to  obtain  such  re¬ 
sults,  but  a  real  possibility  of  attaining 
them  does  exist. 

On  the  front  of  run-time  analysis  of 
instantiated  networks,  the  speed  and 
versatility  of  processing  related  to  the 
implementation  of  the  environment 
should  be  considered.  As  mentioned, 
the  present  implementation,  which  was 
developed  for  in-house  use,  was  de¬ 
veloped  on  a  Symbolics  Lisp  machine. 
The  lisp  machine  was  chosen  for  its 
flexibility  and  power  in  symbolic  ma¬ 
nipulation  and  for  its  exploratory 
programming  environment.  The  im¬ 
plementation  language  is  Lisp.  In  order 
to  enhance  processing  speed,  there  is 
a  plan  to  port  the  environment  to  a  Sun 
4/280.  Although  the  environment  is  cur¬ 
rently  organized  to  dynamically  create 
Fukushima’s  neocognitron,2  its  versatil¬ 
ity  will  be  tested  by  instantiating  addi¬ 
tional  neural  network  models. 

Conclusion 

The  main  virtue  of  the  environment 
described  here  is  that  it  frees  the  user/ 


programmer/researcher  from  the  need 
to  write  programs  that  assemble  neural 
networks;  the  environment  automati¬ 
cally  generates  flexible  neural  network 
architectures  based  upon  parametric 
specifications.  Flexibility  is  achieved 
through  the  integration  of  knowledge- 
representation  and  standard  software- 
modularization  techniques.  Together, 
these  two  types  of  techniques  form  the 
powerful  basis  of  a  research  environ¬ 
ment  for  neural  networks. 

The  mechanisms  through  which  the 
power  is  harnessed  and  utilized  are  the 
heart  of  this  article.  The  key  idea  is  that 
a  knowledge  representation  has  been 
developed  so  that  each  element  of  a 
neural  network  carries  around  with  it 
all  the  information  necessary  for  local 
processing  (for  example,  what  process¬ 
ing  to  perform  and  where  to  get  the 
inputs).  Because  this  information  stor¬ 
age  is  consistent  from  the  node  level 
to  the  network  level,  the  entire  net¬ 
work  is  executed  without  the  need  for 
global  routines  to  encode  its  structure. 
Generic  routines  become  specialized 
processors  as  they  are  adapted  by  the 
contents  of  the  knowledge  structures. 

The  viability  of  such  an  environment 
has  been  demonstrated  through  the  in¬ 
stantiation  and  testing  of  a  standard 
network  architecture,  the  neocognitron. 
The  results  correlate  accurately  with 
those  of  an  analogous  network  de¬ 
scribed  by  Fukushima  and  Miyake.  The 
present  work  suggests  many  signifi¬ 
cant  applications,  some  of  which  are 
currently  under  investigation. 

Knowledge  representation  and  soft¬ 
ware  modularization  are  key  tools  ide¬ 
ally  suited  for  the  empirical  analysis  of 
neural  networks.  Wrapping  an  envi¬ 
ronment  around  these  fundamental 
tools  facilitates  concentration  on  net¬ 
work-response  characteristics  rather 
than  on  monotonous  debugging  of  spe¬ 
cialized  routines  that  encode  network 
architectures. 
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Untangling 

Neural  Nets 

When  is  one  model  better  than  another? 


Jeannette  "Jet"  Lawrence 


Neural  networks,  which  are 
formed  by  simulated  neurons 
connected  together  much  the 
same  way  the  brain’s  neurons 
are,  are  able  to  associate  and 
generalize  without  rules.  They  have 
been  used  to  classify  undersea  sonar 
returns,  speech,  and  handwriting,  pre¬ 
dict  financial  trends,  evaluate  person¬ 
nel  data,  control  robot  arms,  model 
cognitive  phenomena,  and  much  more. 

The  kinds  of  problems  best  solved 
by  neural  networks  are  also  those  that 
people  do  well:  Association,  evaluation, 
and  pattern  recognition.  Neural  net¬ 
works  also  handle  problems  that  are 
difficult  to  compute  and  do  not  require 
perfect  answers  —  just  quick,  good  an¬ 
swers.  This  is  especially  true  in  real¬ 
time  robotics  or  industrial  controller 
applications. 

Other  appropriate  applications  are 
predicting  behavior  and  analyzing  large 
amounts  of  data,  such  as  in  stock  mar¬ 
ket  forecasting  and  consumer  loan  analy¬ 
sis.  New  applications  under  develop¬ 
ment  include  simple  vision  systems, 
weather  forecasting,  assistance  in  medi¬ 
cal  diagnosis,  and  estimation  of  the 
worth  of  insurance  claims. 


Jeannette  (Jet)  Laivrence  is  technical  pub¬ 
lications  manager  at  California  Sci¬ 
entific  Software,  and  the  author  of  their 
1989 publication  Introduction  to  Neural 
Networks.  She  can  be  contacted  at  160 
E.  Montecito  #E,  Sierra  Madre,  CA  91024. 


A  neural  network  is  not  always  the 
best  solution  for  certain  problems.  They 
are  poor  at  precise  calculations  and 
serial  processing,  nor  are  they  able  to 
predict  or  recognize  anything  that  does 
not  inherently  contain  some  sort  of  pat¬ 
tern.  This  is  why,  for  example,  a  neural 
net  cannot  predict  the  lottery,  because 
a  lottery  is  by  definition  a  random  pro¬ 
cess. 

It  is  unlikely  that  a  neural  network 
could  be  built  that  has  the  capacity  to 
think  as  well  as  a  person  does  for  two 


reasons:  Neural  networks  are  terrible 
at  deduction  (logical  thinking),  and  the 
human  brain  is  too  massively  complex 
to  simulate  completely.  A  human  brain 
contains  about  100  billion  neurons,  each 
of  which  connects  to  about  10,000  other 
neurons. 

A  brief  look  at  the  general  structure 
and  operation  of  neural  networks  will 
help  explain  the  limits  of  neural  net¬ 
works  abilities.  There  are  many  types 
of  neural  networks,  but  all  have  three 
things  in  common:  Distributed  process¬ 
ing  elements  (neurons),  the  connec¬ 
tions  between  them  (network  topol¬ 
ogy),  and  the  learning  rule.  These  three 
aspects  together  constitute  the  neural- 
network  paradigm. 

The  Formal  Model  of  a  Neuron 

Artificial  neurons  are  also  known  as 
processing  elements,  neurodes,  units, 
or  cells.  Figure  1  shows  the  canonical 
model  of  a  neuron.  Each  neuron  re¬ 
ceives  the  output  signals  from  many 
other  neurons.  The  point  where  two 
neurons  communicate  is  called  a  “con¬ 
nection.”  This  neural  connection  is  analo¬ 
gous  to  a  biological  synapse  in  the 
mammalian  brain.  A  neuron  calculates 
its  output  by  finding  the  weighted  sum 
of  its  inputs.  The  strength  of  a  particu¬ 
lar  connection,  called  its  weight,  is  noted 
w^,  where  t  is  the  receiving  neuron  and 
j  is  the  sending  neuron. 

At  any  point  in  time  (t),  the  activa¬ 
tion  function,  adds  up  the  weighted 
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(continued  from  page  38) 
inputs  to  produce  an  activation  value 
aj(t).  In  most  models,  input  signals  can 
either  be  excitatory  or  inhibitory,  that 
is,  they  either  tend  to  make  the  neuron 
fire  or  tend  to  suppress  its  firing.  This 
value  is  passed  through  an  output  (or 
transfer)  function  f,  which  produces 
the  actual  output  for  that  neuron  for 
that  time,  o^t). 

After  summation,  the  net  input  of  the 
neuron  is  combined  with  the  previous 
state  of  the  neuron  to  produce  a  new 
activation  value.  In  the  simplest  mod¬ 
els,  the  activation  function  is  the 
weighted  sum  of  the  neuron’s  inputs; 
the  previous  state  is  not  taken  into  ac¬ 
count.  In  more  complicated  models, 
the  activation  function  also  uses  the 
previous  output  of  the  neuron,  so  that 
the  neuron  can  self-excite.  These  acti¬ 
vation  functions  slowly  decay  over  time; 
an  excited  state  slowly  returns  to  an 
inactive  level.  Sometimes  the  activa¬ 
tion  function  is  stochastic,  that  is,  it 
includes  a  random  noise  factor. 

The  transfer  function  of  a  neuron 
defines  how  the  activation  value  is  out¬ 
put.  The  earliest  models  used  a  linear 
transfer  function.  However,  certain  prob¬ 
lems  are  not  entirely  reducible  by  purely 
linear  methods.  The  threshold  transfer 
function  is  the  simplest  of  the  non¬ 
linear  models.  This  function  is  an  all-or- 
nothing  function;  if  the  input  is  greater 
than  some  fixed  amount  (the  thresh¬ 
old),  the  neuron  will  output  a  1;  if  the 
value  is  below  the  threshold,  the  neu¬ 
ron  will  output  a  0. 

Sometimes  the  transfer  function  is  a 
saturation  type  of  function:  More  exci¬ 
tation  above  some  maximum  firing  level 
has  no  further  effect.  A  particularly  use¬ 
ful  transfer  function  is  called  the 
“sigmoid  function,”  which  has  a  highl¬ 
and  a  low-saturation  limit  and  a  pro¬ 
portionality  range  in  between.  This  func¬ 
tion  is  0  when  the  activation  value  is  a 
large  negative  number.  The  sigmoid 
function  is  1  when  the  activation  value 


is  a  large  positive  number  and  makes 
a  smooth  transition  in  between. 

The  behavior  of  the  network  depends 
heavily  on  the  way  the  neurons  are 
connected.  In  most  models,  the  indi¬ 
vidual  neurons  are  grouped  into  layers 
so  that  the  output  from  each  neuron 

The  transfer  function  of 
a  neuron  defines  how 
the  activation  value  is 
output 


in  one  layer  is  fully  interconnected  with 
the  inputs  of  all  the  neurons  in  the 
next  layer.  A  network  may  include  in¬ 
hibitory  connections  from  one  neuron 
to  the  rest  of  the  neurons  in  the  same 
layer  called  “lateral  inhibition.”  Some¬ 
times  a  network  has  such  strong  lateral 
inhibition  that  only  one  neuron  in  a 
layer,  usually  the  output  layer,  can  be 
activated  at  a  time.  This  effect  of  mini¬ 
mizing  the  number  of  active  neurons 
is  known  as  “competition.”  In  a  feed¬ 
forward  network,  neurons  in  a  given 
layer  do  not  take  inputs  from  subse¬ 
quent  layers  or  from  layers  prior  to  the 


Figure  1:  The  formal  model  of  a  neural- 
network  processing  element 


immediately  previous  layer.  Also,  the 
neurons  in  a  feed-forward  network  usu¬ 
ally  do  not  connect  to  each  other.  The 
back  propagation  network  typically  has 
three  feed-forward  layers:  Input,  hid¬ 
den,  and  output.  Feedback  models  ad¬ 
ditionally  include  connections  from  the 
outputs  of  one  layer  to  the  inputs  of  the 
same  or  a  previous  layer. 

A  neural  network  learns  by  adapting 
to  changes  in  the  input.  This  is  accom¬ 
plished  through  changes  in  the  weights 
as  the  network  gains  experience.  The 
learning  rule  is  the  very  heart  of  a  neu¬ 
ral  network;  it  determines  how  the 
weights  are  adjusted  as  the  neural  net¬ 
work  gains  experience.  Of  the  numer¬ 
ous  learning  rules  in  use,  the  most  well- 
known  are  Hebb’s  Rule  and  the  Delta 
Rule.  Nearly  all  other  rules  are  vari¬ 
ations  of  these  two. 

More  than  30  years  ago,  Donald  O. 
Hebb  theorized  that  biological  associa¬ 
tive  memory  lies  in  the  synaptic  con¬ 
nections  between  nerve  cells,  and  that 
the  process  of  learning  and  memory 
storage  involved  changes  in  the  strength 
with  which  nerve  signals  are  transmit¬ 
ted  across  individual  synapses.  Hebb’s 
Rule  states  that  pairs  of  neurons  that 
are  active  simultaneously  become 
stronger  by  synaptic  (weight)  changes. 
The  result  is  a  reinforcement  of  those 
pathways  in  the  brain.  Hebb’s  Rule  states 
Aw.  =  va^  where  V  is  the  learning  rate 
that  specifies  a  scaling  factor  for  changes 
during  training. 

The  Delta  Rule,  a  supervised  learn¬ 
ing  algorithm,  additionally  states  that 
if  there  is  a  difference  between  the 
actual  output  pattern  and  the  desired 
output  pattern  during  training,  then  the 
weights  are  adjusted  to  reduce  the  dif¬ 
ference.  The  Delta  Rule  states  Aw.  = 
v(tj  -  a^Oj,  where  L  is  the  training  (de¬ 
sired  output)  pattern.  The  back-propa¬ 
gation  rule  is  a  generalization  of  the 
Delta  Rule  for  a  network  with  hidden 
neurons. 

The  best  learning  rule  to  use  with 
linear  neurons  is  the  Delta  Rule.  This 
allows  arbitrary  associations  to  be 
learned,  provided  that  the  inputs  are 
all  linearly  independent.  Other  learn¬ 
ing  rules  (such  as  Hebb’s)  require  that 
the  inputs  also  be  orthogonal. 

The  Two  Major  Topologies 

Neural  networks  can  be  arbitrarily  cate¬ 
gorized  by  topology,  neuron  model, 
and  training  algorithm.  (Figure  2  shows 
one  method  of  classifying  neural  net¬ 
works.)  There  are  two  main  subdivi¬ 
sions  of  neural  network  models:  Feed¬ 
forward  and  feedback  topologies. 

Feedback  models  can  be  constructed 
or  trained.  In  a  constructed  model  the 


Figure  2:  A  taxonomy  of  neural-network  types 
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(continued  from  page  40) 
weight  matrix  is  created  by  taking  the 
outer  product  of  every  input  pattern 
vector  with  itself  or  with  an  associated 
input,  and  adding  up  all  the  outer  prod¬ 
ucts.  After  construction,  a  partial  or 
inaccurate  input  pattern  can  be  pre¬ 
sented  to  the  network,  and  after  a  time 
the  network  should  converge  so  that 
one  of  the  original  input  patterns  is  the 
result.  Hopfield  and  BAM  are  two  well- 
known  constructed  feedback  models. 

The  Hopfield  network  is  a  self-or¬ 
ganizing,  associative  memory.  It  is  the 
canonical  feedback  network.  It  is  com¬ 
posed  of  a  single  layer  of  neurons  that 
act  as  both  output  and  input.  The  neu¬ 
rons  are  symmetrically  connected  (w(.  = 
w..).  (See  Figure  3.)  Flopfield  networks 
are  made  of  nonlinear  neurons  capa¬ 
ble  of  assuming  two  output  values:  -1 
(off)  and  +1  (on).  The  linear  synaptic 
weights  provide  global  communication 
of  information.  In  spite  of  its  apparent 
simplicity,  a  Hopfield  network  has  con¬ 
siderable  computational  power. 

The  weight  matrix  is  created  by  tak¬ 
ing  the  outer  product  of  each  input 
pattern  vector  with  itself,  and  adding 
up  all  the  outer  products.  After  con¬ 
struction,  a  pattern  is  given  to  the  net¬ 
work.  A  process  of  reaction-stimulation- 
reaction  between  neurons  occurs  until 
the  network  settles  down  into  a  fixed 
pattern  called  a  “stable  state.”  Thus, 
the  network  result  comes  as  a  direct 
response  to  input. 

The  energy  required  by  a  device  to 
reach  a  stable  state  can  be  plotted  in 
three  dimensions  as  a  curved  surface. 
In  this  representation,  the  stable  states 
of  the  system  (the  energy  minimums) 
appear  as  valleys.  A  neural  network, 
which  is  used  to  find  “good  enough” 
solutions  to  optimization  problems,  may 
have  many  possible  energy  minimums 
or  valleys.  Depending  upon  the  initial 
state  of  the  network,  any  of  the  deepest 
valleys  may  end  up  as  the  answer.  In- 
puting  incomplete  information  to  an 
associative  memory  network  causes  the 
network  to  follow  paths  to  a  nearby 
energy  minimum  where  the  complete 
information  is  stored. 

Hopfield  networks  can  recognize  pat¬ 
terns  by  matching  new  inputs  with  the 
closest  previously  stored  patterns. 
Hopfield  networks  are  especially  good 
for  finding  the  best  answer  out  of  many 
possibilities.  They  are  also  good  at  re¬ 
calling  all  of  a  stored  piece  of  informa¬ 
tion  when  given  partial  data.  Hopfield 
networks  are  often  used  in  applica¬ 
tions  requiring  some  form  of  content 
addressable  memory. 

While  the  Hopfield  model  is  able  to 
associate  on  a  large  scale,  it  does  not 
learn;  the  weights  must  be  set  in  ad¬ 


vance.  A  serious  limitation  of  the 
Hopfield  model  is  that  the  maximum 
number  of  memories  M,  which  can  be 
stored  while  still  retaining  perfect  re- 

A  neural  network  learns 
by  adapting  to  changes 
in  the  input 


call  is  [M  less  than  or  equal  to  N/(4  log 
N)]  where  N  is  the  number  of  neurons. 
If  more  memories  are  stored,  then  the 
stable  states  begin  to  differ  significantly 
from  the  stored  information  and  even¬ 
tually  all  will  be  forgotten.  If  an  error 
rate  of  5  percent  is  tolerable,  then  the 
capacity  is  about  14  percent  of  N.  The 


hardware  efficiency  is  also  poor.  A  vari¬ 
ation  has  been  proposed,  called  the 
“Unary  or  Hamming”  network,  which 
uses  inhibitory  lateral  connections  in 
the  internal  neurons.  It  is  claimed  that 
this  model  has  a  capacity  of  M  »  N 
with  no  errors  in  the  final  state. 

Bart  Kosko  brought  the  Hopfield  net¬ 
work  to  its  logical  conclusion  with  the 
BAM.  The  BAM  (bidirectional  associa¬ 
tive  memory)  is  a  generalization  of  the 
Hopfield  network.  Instead  of  creating 
the  weight  matrix  with  the  dot  product 
of  a  pattern  with  itself  (auto-associa¬ 
tion),  pairs  of  patterns  are  used  (pair 
association).  After  construction  of  the 
weight  matrix,  either  pattern  can  be 
applied  as  input  to  elicit  as  output  the 
other  pattern  in  the  pair. 

A  trained  feedback  model  is  much 
more  complicated  because  adjustment 
of  the  weights  affects  the  signals  as 
they  move  forward  as  well  as  back- 


Figure  4:  The  topology  of  a  back  propagation  neural  network 


42 


Dr.  Dobb’s Journal,  April  1990 

309 


ward.  The  Adaptive  Resonance  Theory 
(ART)  model  is  a  complex  trained  feed¬ 
back  paradigm  developed  by  Stephen 
Grossberg  and  Gail  Carpenter  of  the 
Center  for  Adaptive  Systems  at  Boston 
University.  ART  is  considered  by  some 
to  be  very  powerful,  but  the  number 
of  patterns  that  can  be  stored  is  limited 
to  exactly  the  number  of  nodes  in  the 
storage  layer.  No  production  applica¬ 
tions  have  been  published  to  date;  ART 
is  presently  considered  a  research  tool. 

Feed-Forward  Topologies 

The  second  division  of  neural  networks 
is  the  feed-forward  category.  The  earli¬ 
est  neural  network  models  were  linear 
feed-forward.  In  1972,  two  simultane¬ 
ous  papers  independently  proposed  the 
same  model  for  an  associative  mem¬ 
ory,  the  linear  associator.  J.A.  Ander¬ 
son,  a  neurophysiologist,  and  Teuvo 
Kohonen,  an  electrical  engineer,  were 
not  aware  of  each  other’s  work. 

The  linear  associator  uses  the  simple 
Hebb’s  Rule.  The  only  case  where  as¬ 
sociation  is  perfect  when  simple  Heb- 
bian  learning  is  used  is  when  the  input 
patterns  are  orthogonal.  This  puts  an 
upper  limit  on  the  number  of  patterns 
that  can  be  stored.  The  system  will 
work  very  well  for  random  patterns  if 
the  maximum  number  of  patterns  to 
be  stored  is  10  -  20  percent  of  the  num¬ 
ber  of  neurons.  If  the  input  patterns  are 
not  orthogonal,  there  will  be  interfer¬ 
ence  among  them;  fewer  patterns  can 
be  stored  and  correctly  retrieved.  One 
of  the  predictions  of  the  linear  associa¬ 
tor  is  interference  between  nonorthogo- 
nal  patterns.  Much  of  Kohonen’s  book, 
Self-Organization  and  Associative  Mem¬ 
ory  (Springer- Verlag,  1984)  is  concerned 
with  correcting  the  errors  caused  by 
interference. 

The  nonlinear  feed-forward  models 
are  the  most  commonly  used  today. 
Feed-forward  networks,  for  historical 
reasons,  are  less  often  considered  to 
be  associative  memories  than  the  feed¬ 
back  networks,  even  though  they  can 
provide  exactly  the  same  functionality. 
It  can  be  shown  mathematically  that 
any  feedback  network  has  an  equiva¬ 
lent  feed-forward  network  that  performs 
the  same  task. 

Types  of  Learning  Algorithms 

There  are  two  main  types  of  training 
algorithms:  Supervised  and  unsuper¬ 
vised.  Supervised  learning  is  the  most 
elementary  form  of  adaptation.  It  re¬ 
quires  an  a  priori  knowledge  of  what 
the  result  should  be.  During  training, 
the  network’s  output  is  compared  to 
the  ideal  response,  and  any  error  is 
used  to  correct  the  network.  Learning 
occurs  as  a  result  of  changes  to  the 


weights  to  reduce  the  errors  as  the 
network  gains  experience.  For  one- 
layer  networks  this  is  easily  accom¬ 
plished  by  monitoring  each  neuron 
individually.  In  multi-layer  networks, 
supervised  learning  is  more  difficult 
due  to  the  correction  of  the  hidden 
layers.  Unsupervised  learning  differs 
in  that  it  does  not  have  specific  correc¬ 
tions  made  by  comparison  to  ideal  re¬ 
sults.  Supervised  and  unsupervised  learn¬ 
ing  are  methods  which  are  used  exclu¬ 
sively  of  each  other. 

The  supervised  back  propagation 
model  is  the  most  commonly  imple¬ 
mented  paradigm  today  because  it  is 
the  best  general-purpose  model  and 
probably  the  best  at  generalization.  (This 
model  is  used  by  the  “BrainMaker”  soft¬ 
ware  from  California  Scientific  Software.) 
Back  propagation  is  a  multi-layer  feed¬ 
forward  network  that  uses  the  General¬ 
ized  Delta  Rule. 

By  1985,  back  propagation  had  been 
simultaneously  discovered  by  three 
groups  of  people:  D.E.  Rumelhart,  G.E. 
Hinton,  R.J.  Williams;  Y.  Le  Cun;  and 
D.  Parker.  Back  propagation  is  the  ca¬ 


nonical  feed-forward  network  where 
an  error  signal  is  fed  back  through  the 
network,  altering  weights  as  it  goes,  in 
order  to  prevent  the  same  error  from 
happening  again.  (See  Figure  4.) 

The  error  on  an  output  neuron,  i,  for 
a  particular  pattern,  p,  is  defined  as  Epi 
=  (T  j  -  Opi)  where  T  is  the  training 
(desired)  pattern  and  O  is  the  actual 
output.  The  total  error  on  pattern  p,  E  , 
is  the  sum  of  the  errors  on  all  the  out¬ 
put  neurons  for  pattern  p.  The  total 
error,  E,  for  all  patterns  is  the  sum  of 
the  errors  on  each  pattern  over  all  p. 
The  simplest  method  for  finding  the 
minimum  of  E  is  known  as  “gradient 
descent.”  It  involves  moving  a  small 
step  down  the  local  gradient  of  the 
scalar  field.  This  is  directly  analogous 
to  a  skier  always  moving  down  hill 
through  the  mountains  until  he  hits  the 
bottom. 

Back  propagation  is  useful  because 
it  provides  a  mathematical  explanation 
for  the  dynamics  of  the  learning  pro¬ 
cess.  It  is  also  very  consistent  and  reli¬ 
able  in  the  kinds  of  applications  that 
can  currently  be  built.  The  biggest  limi- 
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tation  is  the  size  of  the  network.  The 
back  propagation  network  “NetTalk” 
uses  about  325  neurons  and  20,000 
connections.  A  useful  visual  recogni¬ 
tion  system  probably  requires  at  least 
125,000  connections.  Currently  avail¬ 
able  commercial  systems  provide  any¬ 
where  from  a  few  neurons  and  con¬ 
nections  to  1  million  neurons  and  1.5 
million  connections,  for  anywhere  from 
$200  to  $25,000. 

A  popular  unsupervised  feed-forward 
model  is  the  Kohonen  model.  The  ba¬ 
sic  system  is  a  one-  or  two-dimensional 
array  of  threshold-type  logic  units  with 
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short-range  lateral  connections  between 
neighboring  neurons.  The  system  modi¬ 
fies  itself  so  that  nearby  neurons  re¬ 
spond  similarly.  The  neurons  compete 
in  a  modified  winner-take-all  manner. 
The  neuron  whose  weight  vector  gen¬ 
erates  the  largest  dot  product  with  the 
input  vector  is  the  winner  and  is  per¬ 
mitted  to  output.  In  this  model  not  only 
the  weights  of  the  winner  but  also  those 
of  its  nearest  neighbors  (in  the  physical 
sense)  are  adjusted. 

One  of  the  problems  with  Kohonen 
learning  is  that  there  is  a  possibility 
that  a  neuron  will  never  “win,”  or  that 


one  will  almost  always  “win.”  The 
weight  vectors  get  stuck  in  isolated  re¬ 
gions.  One  way  to  prevent  the  weight 
vectors  from  getting  stuck  is  to  start  off 
with  all  the  weight  vectors  equal.  The 
network  is  first  fed  fractional  amounts 
of  the  patterns.  The  inputs  are  then 
slowly  built  up  to  the  full  input  pat¬ 
terns.  This  method,  called  “convex  com¬ 
bination,”  works  well  but  it  slows  down 
learning.  Another  preventative  method 
is  to  add  noise  to  the  data,  which  makes 
the  probability  density  function  posi¬ 
tive  everywhere.  The  probability  den¬ 
sity  function  is  a  real-valued  function 
that  gives  the  probability  that  a  random 
variable  has  values  in  the  set.  This 
method  works,  but  it  is  even  slower 
than  convex  combination.  Another  ap¬ 
proach  is  to  give  the  neurons  a  “con¬ 
science”;  if  the  neurons  realize  that 
they  are  winning  a  lot,  they  will  step 
out  of  the  competition  for  a  while. 

A  special  case  of  the  feed-forward 
model  is  the  Neocognitron.  The  origi¬ 
nal  model  was  unsupervised,  but  a  more 
recent  model  (1983)  uses  a  teacher. 
The  multi-layer  (seven-  or  nine-layer) 
system  assumes  that  the  builder  of  the 
network  knows  roughly  what  kind  of 
result  is  wanted.  All  the  neurons  are  of 
analog  type;  the  inputs  and  outputs 
take  nonnegative  values  proportional 
to  the  instantaneous  firing  frequencies 
of  actual  biological  neurons.  In  the  origi¬ 
nal  model,  only  the  maximum-output 
neurons  have  their  input  connections 
reinforced.  It  uses  a  variation  of  the 
Hebbian  Rule.  After  learning  is  com¬ 
pleted,  the  final  Neocognitron  system 
is  capable  of  recognizing  handwritten 
numerals  presented  in  any  visual  field 
location,  even  with  considerable  dis¬ 
tortion.  Drawbacks  of  the  Neocogni¬ 
tron  are  that  it  is  highly  specialized  and 
requires  a  large  number  of  neurons 
and  connections. 

Conclusion 

Neural  networks  are  capable  of  some 
impressive  things  but  they  are  also  lim¬ 
ited,  primarily  by  the  size  of  the  network 
and  the  complexity  of  the  problem.  They 
are  especially  good  at  association  and 
generalization,  but  poor  at  precise  com¬ 
putations  and  logic.  Some  models  are 
able  to  generalize  better  than  others, 
some  are  good  at  association. 

With  more  than  40  functioning  mod¬ 
els  to  choose  from,  it  is  important  to 
know  which  models  have  had  the  most 
success  and  to  understand  their  simi¬ 
larities  and  differences.  Currently,  back 
propagation  is  the  most  popular  model. 
Several  others  are  discussed  in  detail 
in  this  issue,  each  has  it  own  merits. 
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Implementing  the 
Rhealstone  Real-Time 
Benchmark 

Where  a  proposal’s  rubber  meets  the  real-time  road 


Rabindra  P.  Kar 


In  February  1989,  the  late  Kent  Por¬ 
ter  and  I  proposed  a  set  of  bench¬ 
marking  operations  for  real-time 
multitasking  systems  (see  “Rheal¬ 
stone:  A  Real-Time  Benchmarking 
Proposal,”  DDJ,  February  1989).  That 
article  generated  a  lot  of  interest  and 
many  valuable  suggestions  from  DDJ 
readers,  as  well  as  others  in  the  real¬ 
time  software  community.  The  reader 
response  made  it  possible  for  us  to 
refine  and  clarify  several  important  as¬ 
pects  of  the  original  benchmark  pro¬ 
posal.  I  am  very  grateful  to  those  of 
you  who  shared  your  insights  with  us. 

This  article  presents  the  refined  defi¬ 
nition  of  the  Rhealstone  benchmark.  It 
also  contains  a  suite  of  C  programs  that 
implement  the  benchmark  under  iRMX, 
a  real-time  operating  system  from  Intel. 
Refer  to  the  original  proposal  for  the 
rationale  behind  proposing  Rhealstones 
in  the  first  place,  and  for  background 
information  on  the  real-time  multitasking 
operations  that  comprise  it. 

First,  I’ll  give  a  quick  summary  of 
what  the  Rhealstone  benchmark  is  and 
what  it  seeks  to  measure.  The  bench¬ 
mark  identifies  the  execution  times  (or 
time  delays)  associated  with  six  opera¬ 
tions  that  are  vital  indicators  of  real¬ 
time  multitasking  system  performance. 
These  six  operations  are  named  “Rheal¬ 
stone  components.”  When  a  real-time 
system  is  benchmarked,  each  of  these 


Robin  is  a  senior  engineer  with  the 
Intel  Systems  Group  and  can  be  reached 
at  5200  N.E.  Elam  Young  Parkway, 
Hillsboro,  OR  97124-6497. 


components  is  measured  separately.  The 
empirical  results  are  combined  into  a 
single  figure  of  merit  (Rhealstones  per 
time  unit).  There  are  two  ways  of  cal¬ 
culating  the  Rhealstone  number:  One 
of  them  generic  and  one  of  them  ap¬ 
propriately  weighted  for  a  particular 
type  of  application  (an  application- 
specific  Rhealstone). 

Rhealstones  are  intended  to  provide 
a  standard  of  comparison  between  real¬ 
time  computers  across  the  industry. 


Hence,  their  specification  is:  a.  Inde¬ 
pendent  of  the  features  found  in  any 
CPU;  b.  Independent  of  any  computer 
bus  architecture;  c.  Independent  of  the 
features  or  primitives  of  any  operating 
system  or  kernel  (collectively  referred 
to  hereafter  as  real-time  executives). 

The  C  language  implementation  of 
the  benchmarks  is,  of  course,  specific 
to  an  operating  system  (iRMX  in  this 
case).  However,  the  OS-specific  part 
of  the  code  is  confined  to  a  few  system 


Reader’s  Rhealstone 
Recommendations 


When  the  original  Rhealstone  pro¬ 
posal  was  put  forth  more  than  a  year 
ago,  DDJ  solicited  comments,  sugges¬ 
tions,  and  recommendations  from  read¬ 
ers.  In  addition  to  the  individuals  Robin 
has  acknowledged  in  this  article,  the 
following  readers  contributed  com¬ 
ments.  If  any  contributors  were  left 
off  this  list,  it  is  unintentional  and  we 


apologize  —  please  let  us  know  who 
you  are.  The  version  of  the  bench¬ 
mark  presented  in  this  article  does 
not  necessarily  represent  Rhealstone 
as  it  will  look  in  years  to  come.  We 
look  forward  to  your  suggestions  and 
recommendations  for  this  version  too. 

—  Eds. 


Mark  Smotherman,  Clemson  University;  Glenn  Yeager,  Applied  Integration 
Management  Corp.;  Colburn  L.  Norton,  Baytown,  Texas;  Gary  Osborne, 
Apricot  Computers;  Jim  D.  Hart,  Papillion,  Nebraska;  John  Morgan,  Belling¬ 
ham,  Washinton;  G.  Bruce  Lott,  Real  Time  Systems;  Michael  S.  Sossi,  Leo 
Burnett  USA;  Rudi  Borth,  Stratford,  Ontario;  Carol  Sigda,  Industrial  Program¬ 
ming  Inc.;  Phil  Daley;  Hillsboro,  New  Hampshire;  Tim  Olson,  Advanced  Micro 
Devices. 
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(continued  from  page  46) 
calls  (to  create  tasks,  put  them  to  sleep, 
accept/relinquish  semaphores,  and  so 
on)  that  are  found  in  almost  every  mul¬ 
titasking  executive.  The  C  benchmark 
source  is  easily  portable  to  most  other 
executives  if  the  iRMX  system  calls  in 
it  are  replaced  by  the  equivalent  sys¬ 
tem  calls  of  the  target  executive. 

When  a  computer  is  used  in  a  real-time- 
control  situation,  the  solution  usually 
fits  the  model  described  in  Figure  1. 

“Real-time  computer  system”  refers 
jointly  to  the  CPU  and  system  software 
(OS,  kernel,  or  combination  thereof) 
that  provide  a  base  execution  vehicle 
for  the  application  software.  The  Rheal- 
stone  benchmark  helps  the  real-time 
solution  designer  choose  the  highest- 
performance  real-time  computer  avail¬ 
able  as  the  execution  base  for  the  pro¬ 
ject.  Rhealstones  are  not  designed  to 
measure  how  good  the  complete  solu¬ 
tion  is,  and  they  may  not  be  an  appro¬ 
priate  measure  for  the  end  user. 

Rhealstone  Components 

The  specifications  for  the  six  real-time 
operations  (Rhealstone  components) 
that  comprise  the  benchmark  are  de¬ 
tailed  in  the  following  section.  For  a 
graphical  specification  of  each  compo¬ 
nent,  refer  to  Figures  2  through  7.  Each 
component’s  specification  is  followed 
by  a  paragraph  (or  two)  describing  the 
C  benchmark  program  used  to  meas¬ 
ure  the  Rhealstone  component  on  iRMX 
II.  It  is  important  to  realize  that  the 
verbal  and  graphical  specifications,  not 
the  C  programs,  are  the  essential  core  of 
the  benchmark.  It  is  entirely  possible  to 
obtain  more  accurate  Rhealstone  com¬ 
ponent  values  by  using  different  algo¬ 
rithms  or  programming  languages  or 
special  performance-analysis  hardware. 

The  task-switch  time  (see  Figure 
2)  is  the  average  time  to  switch  be¬ 
tween  two  active  tasks  of  equal  prior¬ 
ity.  The  tasks  should  be  independent  — 
that  is,  there  should  not  be  contention 
between  them  for  hardware  resources, 
semaphores,  and  so  on.  Task  switch¬ 
ing  must  be  achieved  synchronously 
(without  preemption)  —  for  example, 
when  the  running  task  puts  itself  to 
sleep  or  when  the  executive  imple¬ 
ments  a  round-robin  scheduling  algo¬ 
rithm  for  equal-priority  tasks. 

Listing  One  (tswit.c),  page  100,  is  a 
program  to  measure  task-switch  time. 
The  code  of  taskl  and  task2  is  identical 
and  very  simple:  A  loop  in  which  rqsleep 
gets  called  in  every  iteration.  The  iRMX 
system  call  rqsleep( sleep_time,  re- 
turn_code_  pointer )  lets  a  task  put  it¬ 
self  to  sleep  (suspend  execution)  for 
sleep_time  system  clock  ticks  (in  iRMX, 
the  default  clock  tick  is  10  milliseconds 


long).  If  sleep_time  is  0,  the  task  is  not 
necessarily  put  to  sleep;  rather,  iRMX 
will  switch  execution  to  any  other  equal- 
priority  task  that  is  ready  to  run  (which 
is  why  this  program  calls  rqsleep ). 

The  return_code_ pointer  is  the  last 
parameter  of  every  iRMX  system  call. 
It  points  to  an  unsigned  variable  in 
which  iRMX  places  the  status  of  the 
call.  If  the  status  returned  is  0,  the  call 
has  been  executed  correctly;  if  this  is 
not  so,  the  status  returned  is  an  error 
or  warning  code  indicating  why  the 
call  did  not  execute  as  it  should  have. 

The  call  rqgettime  ( return_code_ 
pointer )  returns  the  number  of  sec¬ 
onds  that  have  elapsed  since  a  fixed 
point  in  time.  It  is  called  twice,  to  meas¬ 
ure  the  elapsed  time  (in  seconds)  be¬ 
tween  any  two  points  in  a  program. 

The  call  rqcreatetask  ( priority  Jevel, 
start_address,  data_seg,  stack_  pointer, 
stack_size ,  task_flags,  return_code_ 
pointer  )  creates  a  new  task,  as  its  name 
suggests.  The  first  parameter  sets  the 
new  task’s  priority  between  0  (highest 
priority)  and  255  (lowest  priority).  The 


other  parameters  are  either  self-explana¬ 
tory  or  iRMX  programming  details.  This 
call  returns  a  task_token  that  becomes 
iRMX’s  identifier  for  the  task.  Conse¬ 
quently,  the  rqdeletetask(  taskjtoken,  re- 
turn_code_pointer )  call  uses  task_  to¬ 
ken  to  identify  which  task  is  to  be 
deleted.  If  task_token  is  NULL  or  0,  the 
task  deletes  itself. 

The  rqgetpriority(  task_token,  re- 
turn_code_  pointer)  call  lets  a  task  find 
out  the  priority  level  of  any  existing 
task  in  the  system.  If  task_token  is  NULL 
or  0,  the  priority  of  the  calling  task  itself 
is  returned. 

Finally,  the  call  rqsetpriority(  task_ 
token,  priority Jevel,  return_code_ 
pointer  )  lets  a  task  dynamically  change 
its  own  or  any  other  task’s  priority.  I’ve 
used  it  to  set  the  main  task’s  priority  to 
be  lower  than  those  of  taskl  and  task2 
so  those  tasks  can  run  to  completion 
without  interference  from  the  main  pro¬ 
gram. 

The  preemption  time  (see  Figure 
3)  is  the  average  time  for  a  high-priority 
task  to  preempt  a  running  low-priority 
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Figure  1:  Typical  real-time  control  model 
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Figure  3:  Preemption  time 
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(continued  from  page  48) 
task.  Preemption  usually  occurs  when 
the  high-priority  task  goes  from  a  sus¬ 
pended  or  sleeping  state  to  a  ready 
state  because  either  the  high-priority 
task  wakes  up  from  a  previously  initi¬ 
ated  sleep,  or  some  event  or  signal  that 
the  task  was  waiting  for  is  recognized. 
The  first  case  will  likely  yield  a  lower 
preemption  time  on  most  systems,  and 
that  value  is  acceptable  for  the  Rheal- 
stone  benchmark. 

Listing  Two  (preempt. c),  page  100, 
measures  preemption  time  in  an  iRMX 
II  system,  taskl  (lower  priority)  merely 
sits  in  a  delay  loop,  waiting  to  be 
preempted.  task2  loops  on  an  rqsleep 
call.  Every  time  it  calls  rqsleep  a  (non- 
preemptive)  switch  to  taskl  takes  place. 
When  one  sleep  period  is  over,  task2 
wakes  up  and  preempts  taskl. 

Interrupt  latency  (see  Figure  4)  is 
the  average  delay  between  the  CPU’s 
receipt  of  an  interrupt  request  and  the 
execution  of  the  first  application-spe¬ 
cific  instruction  in  an  interrupt-service 
routine.  The  time  required  to  execute 
machine  instructions  that  save  the  CPU’s 
context  (CPU’s  and  coprocessor’s  data 
registers,  mode  registers,  and  so  on) 
are  part  of  the  interrupt  latency. 

As  just  defined,  interrupt  latency  re¬ 
flects  only  the  delay  introduced  by  the 
executive  and  the  CPU  itself.  It  does 
not  include  delays  that  occur  on  the 


Figure  4:  Interrupt  latency 


Figure  5:  Semaphore-shuffle  time 


system  bus  or  electrical  delays  in  con¬ 
trol  circuitry  external  to  the  computer 
system  because  control  circuitry  is  usu¬ 
ally  specific  to  the  application. 

Interrupt  latency  can  be  measured 
under  iRMX  II  on  a  PC/AT-compatible 
computer  using  ltncy.c  (Listing  Three, 
page  100)  and  latch. asm  (Listing  Four, 
page  101).  The  benchmarking  technique 
used  here  is  different  from  the  one  I’ve 
used  for  the  other  Rhealstone  compo¬ 
nents  because  interrupt  latency  is  about 
an  order  of  magnitude  smaller  than 
those  components  (under  iRMX),  hence 
the  need  for  greater  accuracy  in  meas¬ 
urement.  The  first  difference  is  that  this 
benchmark  involves  a  C  and  an  assem¬ 
bler  program.  Secondly,  the  latency  is 
measured  by  reading  the  8254  timer 
chip  directly  (bypassing  iRMX).  Of 
course,  this  makes  the  benchmark  hard¬ 
ware-dependent,  which  is  the  major 
disadvantage  of  this  technique. 

The  code  in  ltncy.c  sets  up  a  new 
interrupt  vector  (pointing  to  the  assem¬ 
bler  code  in  latch. asm)  with  the  rqset- 
interruptC encoded_int_level,  int_task_ 
flag ,  int_handler,  int_handler_data_ 
seg,  return_code_ pointer  )  call,  reads 
the  timer  chip,  and  simulates  a  hard¬ 
ware  interrupt  with  an  INT( causeinter- 
rupt)  instruction  in  software.  The  pro¬ 
cessor  vectors  to  latch.asm,  which  saves 
context  (by  pushing  CPU  registers  on 
the  stack)  and  reads  the  timer  again. 
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The  difference  in  the  two  timer  count 
values  is  used  to  calculate  interrupt 
latency  in  microseconds. 

The  call  rqresetintemipt(  encoded_ 
interrupt_level,  return_code_  pointer ) 
merely  restores  the  interrupt  vector  to 
its  default  value  (before  the  rqsetinter- 
rupt  call). 

Semaphore-shuffle  time  is  the  de¬ 
lay/overhead,  within  the  executive,  be¬ 
fore  a  task  acquires  a  semaphore  that 
is  in  the  possession  of  another  task 
when  the  acquisition  request  is  made. 
Figure  5  illustrates  what  is  being  meas¬ 
ured.  task2  requests  a  semaphore  that 
taskl  owns.  Semaphore-shuffle  time  is 
the  delay  within  the  executive  (exclud¬ 
ing  the  run  time  of  taskl  before  it  relin¬ 
quishes  the  semaphore)  between  task2s 
request  and  its  receipt  of  the  semaphore. 

The  objective  here  is  to  measure  over¬ 
head  when  a  semaphore  is  used  to 
implement  mutual  exclusion.  Many  real¬ 
time  applications  involve  multiple  tasks 
needing  access  to  the  same  resource. 
Semaphore-based  mutual  exclusion  is 
a  convenient  way  to  ensure  that  the 
resource  is  not  interrupted  by  a  second 
task  before  it  finishes  an  operation 
started  by  the  first  task. 

Listing  Five  (semshuf.c,  page  101) 
shows  a  program  that  measures  sema¬ 
phore-shuffle  time,  taskl  and  task2  are 


first  executed  a  fixed  number  of  times, 
without  any  semaphore-related  calls. 
Then  these  tasks  are  executed  again, 
the  same  number  of  times,  with  a  sema- 

The  Rhealstone 
benchmark  identifies 
the  execution  times  (or 
time  delays )  associated 
with  six  operations  that 
are  vital  indicators  of 
real-time  multitasking 
system  performance 


phore  being  shuffled  between  them  at 
every  iteration.  The  difference  in  exe¬ 
cution  time  with  and  without  sema¬ 
phore  shuffling  is  the  overhead  within 
the  executive.  This  program  uses  the 
following  three  iRMX  system  calls  asso¬ 
ciated  with  semaphores. 

The  call  sem_token  =  rqcreatesema- 


phore(  initial_value,  max_value,  queu- 
ing_method,  retum_code_  pointer  )  cre¬ 
ates  a  new  counting  semaphore.  A  count¬ 
ing  semaphore  can  be  incremented  up 
to  the  max_value  parameter.  Because 
this  program  sets  max_value  to  1,  it  is 
using  a  simple  binary  semaphore.  The 
parameter  queuing_method  is  set  to  0 
for  a  FIFO  queuing  scheme  when  more 
than  one  task  is  waiting  on  the  sema¬ 
phore;  a  value  of  1  would  make  it  a 
priority-based  queue. 

The  rqsendunits( sem_token,  units_ 
sent,  return_code_  pointer )  call  incre¬ 
ments  the  value  of  the  semaphore.  In 
this  program,  the  calling  task  uses  it  to 
relinquish  the  semaphore. 

Finally,  the  call  remaining_units  = 
rqreceiveunits( sem_token,  units_re- 
quested,  max_wait_time,  return_code_ 
pointer )  decrements  the  value  of  the 
semaphore.  The  task  makes  this  call  to 
acquire  the  semaphore  if  available.  The 
max_wait_time  parameter  specifies  (in 
system  clock  ticks)  the  period  it  is  will¬ 
ing  to  wait  for  the  semaphore.  A  value 
of  Oxffff  means  “wait  forever.” 

Deadlock-break  time  is  the  aver¬ 
age  time  to  break  a  deadlock  caused 
when  a  high-priority  task  preempts  a 
low-priority  task  that  is  holding  a  re¬ 
source  the  high-priority  task  needs. 

Figure  6  illustrates  how  a  deadlock 
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(continued  from  page  51 ) 
situation  occurs.  Task  1  gains  control 
of  the  resource  and  is  preempted  by 
medium-priority  task  2.  High-priority 
task  3  preempts  task  2  and  requests  the 
resource  from  the  executive  at  some 
point.  Because  task  1  still  holds  the 
resource,  task  3  is  now  blocked.  At  this 
point,  an  unsophisticated  executive 
would  resume  task  2.  Task  2  knows 
nothing  about  the  critical  resource  and 
may  block  higher-priority  task  1  indefi¬ 
nitely  (a  deadlock  situation!).  A  good 
real-time  executive  would  not  resume 
task  2  here  (below  the  ?  in  Figure  6). 
To  avoid  the  deadlock,  the  executive 
might  temporarily  raise  task  l’s  priority 
to  the  same  level  as  task  3’s,  until  it 
relinquishes  the  resource.  In  any  case, 
the  benchmark  measures  the  delay  be¬ 
tween  task  3’s  request  and  its  acquisi¬ 
tion  of  the  resource,  excluding  task  l’s 
run  time  before  it  relinquishes  the  re¬ 
source. 

The  program  deadbrk.c  (Listing  Six, 
page  102)  measures  deadlock-break 
time  in  iRMX  II.  The  algorithm  is  simi¬ 
lar  to  the  semaphore-shuffle  benchmark. 
Three  tasks  of  different  priorities  are 
executed  a  fixed  number  of  times  with¬ 
out  competing  for  a  critical  resource. 
The  same  tasks  are  executed  again,  but 
this  time  task 1  and  task3  both  access 
the  same  resource,  with  a  potential  dead¬ 
lock  situation  occurring  in  each  itera¬ 
tion.  The  difference  in  total  execution 
time  between  the  two  cases  is  a  meas¬ 
ure  of  the  deadlock  break  time. 

Access  to  a  critical  resource  is  guarded 
by  an  iRMX  object  called  a  “region.” 
The  region  is  created  by  the  region_ 
token  =  rqcreateregion(  queuing_met- 
bod,  return_code_  pointer  )  system  call. 
The  queuing_method  parameter  has  the 
same  function  here  as  in  the  rqcreate- 
semaphore  call.  Because  only  one  task 
should  access  the  critical  resource  at  a 
time  (mutually  exclusive  access),  each 
task  waits  at  the  rqreceivecontrol(  re¬ 
gion _  token,  return_code_  pointer  )  call 
until  the  region  is  free.  The  task  must 
relinquish  control  with  the  rqsendcon- 
trol  (  return_code_  pointer  )  call  when 
it  has  finished  with  the  resource. 

Intertask  message  latency  is  the 
latency/ delay  within  the  executive  when 
a  nonzero-length  data  message  is  sent 
from  one  task  to  another  (see  Figure 
7).  To  best  measure  intertask  message 
latency,  the  sending  task  should  stop 
executing  immediately  after  sending  the 
message  and  the  receiving  task  should 
be  suspended  while  waiting  for  it. 

The  message-passing  mechanism 
must  obey  two  important  conditions: 
First,  the  intertask  message-passing  link 
must  be  established  at  run  time.  (Pass¬ 
ing  data  in  a  predefined  memory  area, 
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t  =  task  requests  resource 
a  =  task  relinquishes  resource 
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Figure  6:  Deadlock-break  time 
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such  as  a  global  variable,  is  not  permit¬ 
ted.)  Second,  if  multiple  messages  are 
sent  on  the  same  link,  the  sending  task 
must  not  be  allowed  to  overwrite  an 
old  message  with  a  new  one  before  the 
receiving  task  gets  a  chance  to  read  it. 
Multitasking  executives  typically  offer 
mechanisms  such  as  pipes,  queues,  and 
stream  files  for  intertask  data  commu¬ 
nications. 

The  program  itjmsg.c  (Listing  Seven, 
page  104)  measures  message  latency 
in  iRMX  II.  Data  messages  are  passed 
between  tasks  in  an  iRMX  mailbox. 
The  mailbox  is  created  by  the  mail- 
box_token  =  rqcreatemailbox(  type_ 
flags,  return_  cod_  pointer  )  system  call. 
A  task  sends  a  data  message  to  another 
task  by  calling  rqsenddata(  mail- 
box_token,  message_  pointer,  mes- 
sage_length,  return_code_  pointer  ). 

The  receiving  task  calls  message_ 
length  =  rqreceivedata(  mailbox_token, 
receive_buffer,  max_wait_time,  re- 
turn_code_  pointer  )  to  receive  the  mes¬ 
sage,  if  available.  If  not,  the  task  is 
made  to  wait  until  maxjwait_time  clock 
ticks  have  elapsed  (if  this  parameter  is 
Oxffff,  the  receiving  task  is  willing  to 
wait  as  long  as  is  necessary). 

Note:  This  Rhealstone  component  is 
a  modification  of  “datagram  through¬ 
put,”  which  was  proposed  in  the  origi¬ 
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nal  article.  The  specification  of  inter¬ 
task  message  latency  partly  reflects 
reader  input  (see  acknowledgment  1). 

Computing  a  Rhealstone  Performance 
Number 

Measurement  of  all  six  Rhealstone  com¬ 
ponents  yields  a  set  of  time  values  (in 
the  tens  of  microseconds  to  millisec¬ 
onds  range,  for  most  PCs).  Although 
the  individual  measurements  are  of  sig¬ 
nificance  by  themselves,  it  is  useful  to 
combine  them  into  a  single  real-time 
figure  of  merit,  so  overall  comparisons 
between  real-time  computers  can  be 
made.  To  get  a  single  Rhealstone  per¬ 
formance  number,  the  following  com¬ 
putational  steps  are  necessary: 

1.  All  Rhealstone  component  time  val¬ 
ues  should  be  expressed  in  the  same 
unit  (seconds). 

2.  The  arithmetic  mean  of  the  compo¬ 
nents  must  be  computed. 

3.  The  mean  (from  step  2)  must  be 
arithmetically  inverted  to  obtain  a 
consolidated  real-time  figure  of  merit, 
in  Rhealstones/second. 

Given  the  following  set  of  measured 
values: 

task-switch  time  =  tl  seconds 
preemption  time  =  t2  seconds 
interrupt  latency  =  t3  seconds 


semaphore-shuffle  time  =  t4  seconds 
deadlock-break  time  =  t5  seconds 
intertask  message  latency  =  t6  seconds 

the  arithmetic  average  of  the  Rheal¬ 
stone  components  is: 

t’  =  (tl  +  t2  +  t3 . +  t6)  /  6 

and  the  system’s  consolidated  real¬ 
time  performance  number  is: 

1/t’  Rhealstones/second 

Application-Specific  Rhealstones 

The  operational  definition  of  Rheal¬ 
stones,  in  the  previous  section,  is  ge¬ 
neric  for  any  application  that  may  be 
executed  on  a  real-time  computer.  It 
treats  all  the  Rhealstone  components 
as  equally  important  parameters  of  real¬ 
time  performance.  Generic  benchmarks 
are  useful  when  evaluating  real-time 
system  performance  without  a  particu¬ 
lar  application  in  mind. 

When  a  real-time  computer  is  “dedi¬ 
cated”  to  a  type  of  application,  the 
Rhealstone  figure  can  be  computed  in 
a  way  that  is  appropriate  to  it.  This 
performance  figure  is  called  an  “appli¬ 
cation-specific  Rhealstone."  It  gives  un¬ 
equal  weight  to  different  Rhealstone 
components  because  the  application’s 
performance  is  not  influenced  by  all 
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of  them  equally.  For  example,  the  ap¬ 
plication  may  be  heavily  interrupt- 
driven,  and  the  software  may  not  use 
semaphores  at  all.  The  application’s 
designer  can  compute  the  application- 
specific  number  if  he/she  knows  (or 
can  estimate)  the  relative  frequency  of 
different  Rhealstone  components  in  the 
application. 

The  steps  for  computing  application- 
specific  Rhealstones  are  as  follows: 

1.  Measure  the  individual  components 
(tl  to  t6)  as  before. 

2.  Estimate  the  relative  frequency  of 
each  Rhealstone  component’s  occur¬ 
rence  when  the  application  is  executed, 
and  assign  nonnegative  real  coefficients 
(nl  to  n6)  proportional  to  the  frequen¬ 
cies.  For  example,  if  interrupts  occur 
five  times  more  often  than  task  switches 
do,  and  semaphores  and  intertask  com¬ 
munication  are  not  used  in  the  applica¬ 
tion  code,  the  value  of  n3  should  be 
three  times  the  value  of  nl,  and  n4  and 
n6  should  be  set  to  0. 

3.  Compute  a  weighted  average  of  the 
Rhealstone  components: 

t’  =  (nlhl  +  n2*t2  +  n3*t3  + _ + 

n6*t6)  /  (nl  +  n2  +  n3  .  .  .  +  n6) 

4.  Invert  the  average  to  get  the  re¬ 


sult  1/t’  application-specific  Rheal¬ 
stones/ second. 

The  procedure  for  computing  generic 
and  application-specific  Rhealstones  out¬ 
lined  in  this  article  is  different  from 
that  specified  in  the  original  proposal. 
The  original  procedure  specified  that 
each  Rhealstone  component  should  be 
arithmetically  inverted  separately  and 
the  average  taken  thereafter.  I  am  grate¬ 
ful  to  the  many  readers  who  wrote  to 
point  out  that,  with  the  previous  proce¬ 
dure,  a  computer  system  with  high  per¬ 
formance  in  one  or  two  components 
and  bad  performance  in  the  others 
would  outshine  one  with  moderately 
good  performance  in  all  categories. 

The  revised  algorithm  specifies  that 
the  components  be  averaged  first  and 
then  arithmetically  inverted  (see  acknowl¬ 
edgment  2).  This  algorithm  ensures  that 
if  a  real-time  system  shows  bad  perfor¬ 
mance  in  even  one  category,  its  overall 
score  will  suffer  badly.  This  is  intentional, 
because  to  guarantee  quick  response  time, 
moderately  good  performance  is  needed 
in  all  Rhealstone  categories.  In  other 
words,  a  real-time  system  that  takes  sev¬ 
eral  seconds  to  respond  to  an  interrupt 
will  have  a  low  Rhealstone  rating,  even 
if  it  delivers  microsecond-range  perfor¬ 
mance  when  switching  context  or  ex¬ 
changing  semaphores. 
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Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  100.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  4. 
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Bounding  Box 
Data  Compression 

An  optimized  font  data  compression  method  for 
fast  screen  I/O  environments 


Glenn  Searfoss 


The  optimal  data  compression 
method  for  a  given  situation  is 
determined  by  the  type  of  data 
to  be  used  and  its  intended  ap¬ 
plication.  To  date,  a  variety  of 
methods  have  been  used  to  effect  a 
balance  between  compression  and  dis¬ 
play  speed  of  bit-mapped  font  data. 

One  school  of  thought  maintains  that 
only  noncompressed  font  data  be  used. 
While  this  data  can  be  displayed  rap¬ 
idly,  the  amount  of  data  storage  re¬ 
quired  for  fonts  can  be  prohibitive,  par¬ 
ticularly  when  used  with  higher  dis¬ 
play  resolutions  and  colors. 

Another  school  stresses  maximum 
compression  of  font  data  at  all  times. 
In  this  situation,  each  time  a  character 
is  accessed,  the  cell  data  must  be  re¬ 
constituted.  This  saves  data  storage 
space  but  sacrifices  access  speed  dur¬ 
ing  screen  display. 

A  third  approach  attempts  to  incor¬ 
porate  both  aspects.  Here  font  data 
remains  compressed  until  accessed,  at 
which  point  all  data  is  uncompressed. 
A  font  may  then  be  used  at  optimal 
speed.  As  additional  fonts  are  uncom¬ 
pressed,  the  data  storage  limitation  of 
the  first  method  is  encountered.  This 
limitation  can  be  ameliorated  by  each 
caching  system  in  which  only  the  most 
recently  used  characters  are  available 
in  uncompressed  form  (at  the  expense 
of  additional  code  complexity). 

Because  none  of  these  methods  are 
completely  satisfactory  for  font  screen 
display,  it  is  important  to  develop  a 


Glenn  works  at  Data  Transforms  Inc., 
and  can  be  reached  at  616  Washing¬ 
ton  Street,  Denver,  CO  80203- 


better  balance  between  efficient  access 
and  efficient  storage. 

The  terms  “fast-access”  or  “on-the- 
fly”  have  been  used  to  describe  bit¬ 
mapped  font  data  optimized  for  fast 
screen  I/O.  It  is  ultimately  desirable  in 
this  environment  to  achieve  maximum 
data  compression  while  maintaining  or 
increasing  data  access  speed.  To  this 
end,  it  is  essential  to  understand  cer¬ 
tain  restrictions  inherent  with  the  graph¬ 
ics  display  of  bit-mapped  font  data. 

First,  there  must  be  minimal  calcula¬ 
tion  of  font  data.  Vector  format  and 
highly  compressed  bit-mapped  fonts 
both  require  recalculation  of  character 
data  at  display  time.  This  greatly  re¬ 
stricts  their  usefulness  in  a  fast-access 
environment.  Speed  optimization  oc¬ 
curs  when  there  is  little  or  no  data 
compression  and  reconstruction. 

Second,  character  size  must  relate 
to  the  display  resolution.  As  screen  dis¬ 
play  resolution  increases,  larger  char¬ 
acters  are  required  to  maintain  the  same 
relative  size  and  quality  as  characters 
used  on  lower-resolution  displays. 

Third,  font  data  storage  requirements 
must  not  impinge  upon  code  space. 
As  bit-mapped  fonts  increase  in  size, 
their  data  storage  needs  quickly  reach 
mammoth  proportions.  Realistically, 
some  form  of  data  compression  is  re¬ 
quired  for  a  program  and  several  large 
font  sets  to  coexist  in  memory. 

Fourth,  the  amount  of  code  neces¬ 
sary  must  be  functional,  effective,  and 
preferably  compact.  Coding  require¬ 
ments  are  reduced  with  minimal  data 
compression  and  decompression. 

The  data  compression  method  best 
suited  for  this  application  will  achieve 


a  dynamic  balance  between  these  four 
criteria.  The  Bounding  Box  method  of 
data  compression  is  such  a  method. 

To  illustrate  its  effectiveness  in  this 
situation,  a  comparison  with  a  com¬ 
monly  used  method  of  data  compres¬ 
sion,  run  length  bit  encoding  (RLE),  is 
useful.  This  comparison  is  useful  even 
though  the  two  approaches  are  not 
mutually  exclusive:  One  can  store  run 
length  encoded  characters  in  the  Bound¬ 
ing  Box  format. 

A  valid  comparison  depends  upon 
establishing  a  common  reference  point. 
Because  noncompressed  data  is  the  ba¬ 
sic  requirement  for  both  compression 
schemes,  a  brief  outline  of  this  font 
data  format  may  be  useful. 

Noncompressed  fonts  are  used  as  is. 
The  font  data  is  comprised  of  header 
information  and  complete  character  cell 
data.  The  header  may  detail  as  many 
character  formatting  aspects  as  desired. 

A  typical  header  for  standard  non¬ 
compressed  font  data  is  shown  in  Listing 
One,  page  108.  In  this  case,  I’m  using 
the  C  language  data  structure  of  Data 
Transforms’  Fontrix  (Fontl)  Format. 

Each  font  has  a  header  that  defines 
the  font  and  points  to  the  character 
bitmaps.  Immediately  following  the  font 
header  is  the  character  bitmap  data. 
Character  bitmaps  are  stored  as  scan- 
rects  in  scanline  order  from  top  to  bot¬ 
tom.  Each  scanline  is  stored  byte  wise 
left  to  right,  left  justified,  and  rounded 
to  byte  length.  Each  byte  is  stored  8 
bits  per  byte  where  MSB  is  the  leftmost 
pixel.  Using  this  as  a  standard  font 
header  to  describe  Figure  1,  we  can 
proceed  to  specifics  concerning  meth¬ 
ods  of  compressing  this  data. 
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(continued  from  page  56) 

Bounding  Box  Compression 

The  Bounding  Box  Compression 
Method  (see  Figure  2)  involves  outlin¬ 
ing  a  cell’s  “bit-on”  character  data  with 
the  smallest  box  possible.  Coordinates 
that  position  the  “box”  relative  to  the 
original  character  cell  are  saved  in  the 
font  header.  This  compression  method 
is  automatic  within  the  Data  Transforms 
Font  Editor  when  a  font  over  32  x  32 
pixels  in  size  is  saved.  A  sample  header 
for  a  font  compressed  using  the  Bound¬ 
ing  Box  method  is  shown  in  Listing 
Two,  page  108  (again  using  Data  Trans¬ 
forms’  Fontrix  [Font2]  Format). 

The  data  listed  in  the  struct  font2 
portion  of  the  (Font2)  font  structure 
above  is  defined  as  follows: 

•  The  font  header  is  the  same  as  de¬ 
scribed  in  the  struct  fontlbead  of  the 
noncompressed  font  data  format;  font 
cell  segments  are  an  array  of  segment 
pointers  to  characters  kept  as  offsets 
from  the  beginning  of  the  font  file.  For 
example,  if  an  array  value  for  a  charac¬ 
ter  =  10,  then  the  starting  address  of  a 
character's  “bounding  box”  data  =  (the 
start  of  file  address  +  size  of  [struct 
font2])Jr  (10  x  16),  where  1  segment  = 
16  bytes. 

•  The  horizontal  size  is  the  actual  width 
in  bits  of  the  bounding  box. 

•  The  horizontal  offset  is  the  distance 
in  bits  from  the  left  edge  of  the  cell  to 
the  upper  lefthand  corner  of  the  bound¬ 
ing  box. 

•  Horizontal  bytes  refers  to  the  actual 
size  in  bytes  of  the  interior  of  the  bound¬ 
ing  box. 

•  The  vertical  size  is  the  actual  height 
in  bits  of  the  bounding  box. 

•  The  vertical  offset  is  the  distance  in 
bits  from  the  top  edge  of  the  cell  to  the 
upper  edge  of  the  bounding  box. 

The  character  data  is  never  com¬ 
pressed;  rather,  the  empty  space  out¬ 
side  the  “bounding  box”  is  discarded. 
The  analogy  of  a  shrinkwrap  bag  can 
be  used  to  illustrate. 

Imagine  a  character  cell  placed  within 
a  shrink-to-fit  bag.  The  noncompressed 
cell  is  the  unshrunk  bag.  Now  shrink 
the  bag  until  all  edges  contact  the  outer 
limits  of  bit-on  data,  forming  a  rectan¬ 
gular  bounding  box.  For  some  charac¬ 
ters  —  such  as  a  lowercase  “i”  —  this 
correlates  to  a  major  amount  of  shrink¬ 
age,  and  the  shrinkage  correlates  to 
saved  data  space,  hence,  compression. 
An  uppercase  “W”  may  fill  most  of  a 
cell.  In  this  instance  minimal  shrinkage 
will  occur,  with  little  or  no  saved  data 
space.  However,  the  overall  net  sav¬ 
ings  in  data  space  for  an  entire  font  set 
will  be  great  because  few  characters  fill 
an  entire  cell  (see  Figures  2,  3,  and  4). 


Figure  1:  A  noncompressed  character 
cell.  A.  Vertical  cell  size  16 pixels.  R 
Horizontal  cell  size  1 7 pixels.  C  Baseline 
character  cell  12 pixels 
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Figure  2:  A  character  cell  compressed 
using  the  Bounding  Box  method.  The 
data  listed  is  saved  for  each  character 
when  the  font  was  created  and  stored 
in  a  look-up  table  in  the  font  header. 

A.  Horizontal  offset  6 pixels.  R  Vertical 
offset  4  pixels.  C.  Vertical  size  of  bound¬ 
ing  box  8 pixels.  D.  Horizontal  size  of 
bounding  box  2 pixels 


Figure  3:  Noncompressed  character 
cell.  Vertical  cell  size  16 pixels. 
Horizontal  cell  size  1 7 pixels.  Baseline 
character  cell  12 pixels 


Figure  4:  Actual  data  saved  when  a 
character  cell  is  compressed  using  the 
Bounding  Box  method 
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(continued  from  page  58) 

Run  Length  Bit  Encoding 

A  RLE  font  would  possess  a  header 
similar  to  the  font  header  described  in 
the  “struct  fontlhead”  of  the  noncom- 
pressed  font  data  format.  The  main  dif¬ 
ferences  between  RLE  and  the  Bound¬ 
ing  Box  lies  in  the  method  of  character 
data  storage  and  how  code  points  to  it. 

In  a  simple  case  of  run  length  bit 
encoding,  bit  mapped  data  is  com¬ 
pressed  by  reading  each  scanline  of  a 
character  cell,  grouping  adjacent  bit¬ 
on  or  bit-off  data  and  saving  the  infor¬ 
mation  as  pairs  of  ASCII  digits.  For 
example,  by  using  RLE  the  marked  scan¬ 
line  in  Figure  5  could  be  compressed 
as  follows: 

•  0x06  (6  identical  bits  in  a  row),  0x00 
(those  bits  are  bit-off  data) 

•  0x02  (2  identical  bits  in  a  row),  0x01 
(those  bits  are  bit-on  data) 

•  0x09  (9  identical  bits  in  a  row),  0x00 
(those  bits  are  bit-off  data) 

Having  established  the  basic  structure 
of  the  two  methods,  it  now  remains  to 
compare  their  differences  in  access 
speed,  compression  efficiency,  and  cod¬ 
ing  requirements. 

Speed  of  Compressed  Data  Access 

When  a  Bounding  Box  compressed  char¬ 
acter  is  used,  there  is  no  run-time  pen¬ 
alty  during  screen  display.  A  character 
cell  is  not  reconstituted.  Rather,  the 
character  data  is  used  as  is  and  posi¬ 
tioned  relative  to  the  original  cell  size 
information. 

Fonts  compressed  with  run  length 
bit  encoding  pay  a  run-time  penalty 


during  screen  display.  If  a  font  remains 
compressed  while  being  accessed,  each 
time  a  character  is  displayed  to  the 
screen,  the  entire  character  cell  must 


scan  line  Y.  Each  portion  of  data  is 
compressed  into  a  pair  of  ASCII  digits. 
A.  0x06  OxOO  B  0x02  0x01  C.  0x09 
OxOO 


Figure  6:  Run  length  bit  encoding  for 
scan  line  X.  Each  portion  of  data 
is  compressed  into  a  pair  of  ASCII  dig¬ 
its.  The  more  data  dispersal  on  a 
scan  line,  the  more  detailed  this  method 
of  compression  becomes.  A.  0x04 
0x00  B  0x03  0x01  C.  0x03  0x00 
D.  0x03  0x01  E.  0x04  0x00 


be  reconstructed.  In  a  case  like  this, 
you’ll  be  watching  the  clock. 

Compression  Efficiency 

The  Bounding  Box  routine  can  run  at 
up  to  90  percent  of  the  overall  com¬ 
pression  efficiency  of  more  computa¬ 
tionally  expensive  compression  algo¬ 
rithms.  The  actual  character  bits-on  data 
is  never  compressed. 

For  this  reason,  the  Bounding  Box 
approach  is  more  properly  called  a  tech¬ 
nique  or  a  character  storage  format, 
rather  than  an  algorithm.  Information 
regarding  the  bounding  box  (size,  [x,y] 
position  within  the  original  cell,  and 
so  on)  is  kept  for  each  character  in  a 
lookup  table  in  the  font  header  (see 
Figures  2  and  4). 

Using  this  compression  method  on 
the  character  cell  in  Figure  1  (lower¬ 
case  i),  the  net  gain  in  savings  is  94 
percent  of  the  original  character  cell 
size.  For  Figure  3  (uppercase  W),  the 
net  savings  is  31  percent  of  the  original 
character  cell  size.  The  percentage  in 
savings  correlates  to  the  discarded  zero 
(bit  off)  data  outside  the  bounding  box 
(see  Figure  4). 

The  run  length  bit  encoding  (simple 
case)  compression  method  can  run  at 
up  to  98  percent  of  overall  compres¬ 
sion  efficiency,  but  will  be  computa¬ 
tionally  expensive.  Using  this  compres¬ 
sion  method  on  the  character  cell  in 
Figure  1  (lowercase  i),  the  net  gain  in 
savings  is  78  percent  of  the  original 
character  cell  size.  For  Figure  3  (upper¬ 
case  W),  the  net  savings  is  57  percent 
of  the  original  character  cell  size  (see 
Figures  5  and  6).  Table  1  provides  a 
complete  RLE  table  for  Figure  5.  Read 
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( continued  from  page  60) 
each  scan  line  left  to  right,  top  to  bot¬ 
tom,  numbered  0  to  15.  Table  2  is  the 
complete  RLE  table  for  Figure  6.  Again, 
read  each  scan  line  left  to  right,  top  to 
bottom,  0  to  15. 

Coding  Requirements 

The  Bounding  Box  method  is  invoked 
at  a  time  when  display  speed  is  not  an 
issue  —  during  font  creation.  All  the 
data  needed  to  use  a  character  is  saved 
in  a  lookup  table  in  the  font  header  at 
this  time.  Because  the  actual  data  within 
the  bounding  box  is  not  compressed, 
no  coding  is  required  to  reconstruct  a 


0]  0X1 7  0x00 

1]  0x17  0x00 

2]  0x17  0x00 

3]  0X17  0x00 

4]  0x06  0X00  0x02  0x01  0x09  0x00 

5]  0X1 7  0X00 

6]  0x06  0x00  0x02  0x01  0x09  0x00 

7]  0x06  0x00  0x02  0x01  0x09  0x00 

8]  0x06  0x00  0x02  0x01  0x09  0x00 

9]  0X06  0x00  0x02  0x01  0x09  0x00 

1 0]  0x06  0x00  0x02  0x01  0x09  0x00 

11]  0x17  0x00 

12]  0x1 7  0x00 

13]  0x17  0x00 

14]  0x17  0x00 

15]  0x17  0x00 


Table  1:  RLE  table  for  Figure  5.  Read¬ 
ing  each  scan  line  left  to  right,  top  to 
bottom,  and  numbered  0-  15 


character  cell.  Code  need  only  index 
into  the  data  and  index  the  screen  pixel 
position. 

Run  length  bit  encoding  requires  code 
to  do  more  than  access  font  data.  It 
must  also  handle  the  peculiarities  in¬ 
volved  with  compressing  and  uncom¬ 
pressing  data.  Font  characters  that  re¬ 
main  compressed  while  being  used 
must  be  reconstructed  each  time  they 
are  accessed.  Font  data  that  is  reconsti¬ 
tuted  once  and  thereafter  accessed  as 
noncompressed  data,  can  instigate  a 
data  storage  conflict.  As  additional  fonts 
are  uncompressed,  their  combined  data 
storage  requirements  begin  to  compete 


with  code  and  operational  program 
space. 

The  Nitty  Gritty 

The  Bounding  Box  method  is  most  ef¬ 
fective  when  the  data  to  be  compressed 
is  bit-mapped  data;  all  bit-on  data  is 
concentrated  and  confined  in  one  area, 
as  is  often  the  case  with  alphanumeric 
character  fonts;  the  ratio  of  bit-off  to 
bit-on  data  is  high;  fast  usage  of  com¬ 
pressed  data  is  of  most  importance  (for 
example,  screen  I/O,  graphics  print¬ 
ing,  and  so  on);  and  it  is  preferred  that 
font  data  remain  compressed  when  be¬ 
ing  accessed. 


0]  0x17  0x00 

1]  0x02  0x01  0x13  0x00  0x02  0x01 

2]  0x02  0x01  0x13  0x00  0x02  0x01 

3]  0x01  0x00  0x02  0x01  0x13  0x00  0x02  0x01  0x01  0x00 

4]  0x01  0x00  0x02  0x01  0x13  0x00  0x02  0x01  0x01  0x00 

5]  0x02  0x00  0x02  0x01  0x13  0x00  0x02  0x01  0x02  0x00 

6]  0x02  0x00  0x02  0x01  0x04  0x00  0x01  0x01  0x04  0x00  0x02  0x01  0x02  0x00 

7]  0x03  0x00  0x02  0x01  0x02  0x00  0x03  0x01  0x02  0x00  0x02  0x01  0x03  0x00 

8]  0x03  0x00  0x02  0x01  0x01  0x00  0x02  0x01  0x01  0x00  0x02  0x01  0x01  0x00  0x02  0x01  0x03  0x00 

9]  0x04  0x00  0x03  0x01  0x03  0x00  0x03  0x01  0x03  0x00 

10]  0x04  0x00  0x03  0x01  0x03  0x00  0c03  0x01  0x04  0x00 

11]  0x05  0x00  0x01  0x01  0x05  0x00  0x01  0x01  0x05  0x00 

12]  0x17  0x00 

13]  0x17  0x00 

14]  0x17  0x00 

15]  0x17  0x00 


Table  2:  RLE  table  for  Figure  6.  Reading  each  scan  line  left  to  right,  top  to 
bottom,  and  numbered  0—15 
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Run  length  bit  encoding  is  most  ef¬ 
fective  when  all  bit-on  data  is  widely 
dispersed  or  present  at  a  majority  of 
the  cell  edges;  the  ratio  of  bit-off  to 
bit-on  data  is  low;  and  the  usage  of 
data  storage  must  be  maximized  or  is 
of  higher  priority. 

RLE  and  the  Bounding  Box  are  two 
good  methods  of  data  compression. 
Each  has  limits  in  its  ability  to  handle 
graphics  information.  The  decision  to 
use  a  RLE  or  Bounding  Box  compres¬ 
sion  scheme  should  be  based  on  the 
likely  distribution  of  bit-on  data  and 
the  preferred  ratio  of  data  compression 
to  access  speed. 


BOUNDING  BOX  METHOD 


As  mentioned  earlier,  in  situations 
where  memory  is  extremely  tight,  the 
Bounding  Box  method  can  profitably 
be  used  in  conjunction  with  RLE  or 
other  algorithms.  Of  the  various  com¬ 
pression  methods  currently  used  in  fast- 
access  screen  I/O  environments,  the 
Bounding  Box  method  is  recommended 
for  maintaining  maximum  data  com¬ 
pression  while  allowing  the  greatest 
access  speed  of  bit-mapped  font  data. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 


ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  108.) 

Vote  tor  your  favorite  feature/article. 

Circle  Reader  Service  No.  5. 
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Advanced  memory  management  (N.  Margulis),  Apr., 
p.  24 

Protected  mode  and  multitasking  under  MS-DOS 
(T.  Green),  Sept.,  p.  64 


Actor 

For  developing  applications  for  MS  Windows  (J. 

Duntemann),  Dec.,  p.  153 
Writing  filters  in  an  object-oriented  language  (M. 
Franz),  Dec.,  p.28 

Multiple  inheritance  (M.  Swaine),  March,  p.  107 

Algorithms 

Boyer-Moore  and  brute-force  for  string  searches 
(C.  Menico),  July,  p.  74 

Autorouting  with  Al-based  (A*)  search  algorithms 
(R.  Nevin),  Sept.,  p.  16 

Simulated  annealing  and  optimization  (M.P.  McLaugh¬ 
lin),  Sept.,  p.  26 

For  precedence  trees  (M.  Peterson),  Sept.,  p.  44 
LZWdata compression  algorithm  (M.  Nelson),  Oct., 
p.  29 

Sequential  algorithm  and  multitasking  (R.  Kar),  Nov., 

p.  16 

ANSIC 

From  K&R  to  (S.R.  Ladd),  Aug.,  p.  74 
Discussion  of  changes  and  uniformity  (A.  Stevens), 
Nov.,  p.  133 

Update  (A.  Stevens)  Dec.,  p.  144 

Dennis  Ritchie  on  (A.  Stevens),  C  Sourcebook,  p.  8 

APL*PLUS/PC 

Review  of  STSC's  product  (C.  Burke),  Feb.,  p.  72 

Assemblers 

MS-DOS  reviewed  (M.  Schmidt),  Jan.,  p.  70 

Assembler  code 

Customizing  for  speed  and  reliability  (M.  Abrash, 
D.  Illowsky),  Sept.,  p.  52 

Asynchronous  communications 

TINYCOMM  (A.  Stevens),  Feb.,  p.  115 

AWK 

Writing  AWK-like  extensions  to  C  (J.  Mischel),  June, 
p.  64 

Revisited  (“Letters”),  Oct.,  p.  12 


Back  propagation 

Neural  networks  and  noise  filtering  (C.  Kli- 
masauskas),  Jan.,  p.  32 

Algorithm  for  multilevel  neural  net  work  (M.  Swaine), 
Aug.,  p.  134 

Benchmarks 

an  apologia  (G.  Vose,  D.  Weil),  Feb.,  p.  36 
C  statements  (D.  Fox),  Feb.,  p.  60 
Rhealstone  (R.  Kar,  K.  Porter),  Feb.,  p.  14 
Turbo  C  and  QuickC  (S.R.  Ladd),  Aug.,  p.  89 

Binary  trees 

Ordered  by  precedence  trees  (M.  Peterson),  Sept., 
p.  44 

Vs.  B-trees  (“Letters”),  Nov.,  p.8 
Blackjack  simulation 
C  programming  (A.  Stevens),  July,  p.  113 
Boyer-Moore  algorithm 
For  faster  string  searches  (C.  Menico),  July,  p.  74 
Vs.  brute  force  ("Letters"),  Oct.,  p.  12 
Breadth-first  search  algorithm 
Autorouting  with  the  A*  algorithm  (R.  Nevin),  Sept., 
p.  16 

Brute-force  method 

Combined  with  Boyer-Moore  for  string  searches 
(C.  Menico),  July,  p.  74 
Vs.  Boyer-Moore  (“Letters”),  Oct.,  p.  12 


C++ 

Compared  to  Modula-2  (S.  Ladd),  Jan.,  p.  62 
Extended  directory  searches  (J.  Dlugosz),  March, 
p.  55 

Multitasking  kernel  (T.  Green),  Feb.,  p.  45 
TAWK  — a  simple  interpreter  (B.  Eckel),  May,  p.  50 
The  wave  of  tomorrow?  (A.  Stevens),  Aug.,  p.  141 


1989 


DDJ 


INDEX 


Implementing  simulation  systems  (T.  King),  Sept., 
p.  40 

Books,  compilers,  window  object  (A.  Stevens),  Sept., 

p.  121 

Linked  list  class;  some  compilers  and  preproces¬ 
sors  (A.  Stevens),  Nov.,  p.  133 
Flome  brew,  table  driven  parser  generator  (J. 
Dlugosz),  Dec.,  p.  40 

Object-Oriented  Program  Design  by  M.  Mullins  (A. 

Stevens),  Dec.,  p.  144 
C  to  C++  (A.  Stevens),  C  Sourcebook,  p.  32 
String  Classes  (S.  Ladd),  C  Sourcebook,  p.  8 

C Interpreter 

Build  your  own  (H.  Schildt),  Aug.,  p.  38 
SI:  a  C-like  script  interpreter  (A.  Stevens),  May, 
p.  117 

C  interpreter  for  OS/2  and  run-time  linking  (A. 

Schulman),  Nov.,  p.  46 
C  Programming  (Al  Stevens) 

Microsoft  C  bridge  added  to  project,  Jan.,  p.  Ill 
TINYCOMM,  Feb.,  p.  115 
TINYCOMM  begets  SMALLCOM,  March,  p.  113 
A  phone  directory  and  XModem  for  SMALLCOM, 
Apr.,  p.  109 

SI:  a  C-like  script  interpreter,  May,  p.  117 
Scripts  for  SMALLCOM,  June,  p.  1 1 9 
Blackjack  simulation  program,  July,  p.  113 
C++  the  wave  of  tomorrow,  and  typedef  misuse, 
Aug.,  p.  141 

C++  books,  compilers,  a  window  object,  and  exten¬ 
sions,  Sept.,  p.  121 

C++  tools,  menu  classes,  the  string  class,  and 
ANSI,  Oct.,  p.  123 

Linked  list  class  for  C++,  Nov.,  p.  133 
Compilers  and  preprocessor,  Nov.,  p.  133 
TEXTSRCH  (document  retrieval  system),  ANSI  up¬ 
date,  Dec.,  p.  144 

C  Programming 

"C’erious  Toolkit,  TSR  Systems,  review  (K. 
Weiskamp),  Apr.,  p.  92 

Writing  AWK-like  extensions  to  C  (J.  Mischel),  June, 
p.  64 

And  Smalltalk  (D.  Thomas,  R.  Best),  August,  p.  16 
C-to-Fortran — C  tools  and  Fortran  libraries  (M. 
Floyd),  Aug.,  p.  22 

Conversion  medium  (PCX  images  to  Postscript 
printers)  (K.  Quirk),  Aug.,  p.  30 
Building  your  own  C  interpreter  (H.  Schildt),  Aug., 
p.  38 

C  multidimensional  arrays  at  run  time  (P.  Ander¬ 
son),  Aug.,  p.  50 

C  dynamic  memory  use  (R.  Merilatt),  Aug.,  p.  62 
C  procedure  tables  (T.  Berens),  Aug.,  p.  68 
ANSI  C  from  K&R  (S.R.  Ladd),  Aug.,  p.  74 
A  generic  Heapsort  algorithm  in  C  (K.  Russell), 
Aug.,  p.  81 

Turbo  C  and  QuickC  (Examining  Room,  S.R.  Ladd), 
Aug.,  p.  89 

C  Windows  Toolkit  &  PCX  Programmer's  Toolkit 
(Examining  Room,  T.  Castle),  Aug.  p.  91 
Concurrent  C  for  real-time  programming  (N.  Ge- 
hani,  W.  Roome),  Nov.,  p.  38 
Concurrent  C  for  discrete  event  simulation  (N.  Ge- 
hani,  W.  Roome),  C  Special,  p.  24 
C  Windows  Toolkit 

Examining  Room  review  (T.  Castle),  Aug.,  p.  91 

cdev 

And  Object  C  on  the  Mac  (B.  Waters),  Mac  Journal, 
p.  50 

Cellular  automata 

A  new  way  of  simulation  (J.  Coppola,  F.  Marchese), 
Sept.,  p.  34 

Code  optimization 

Optimization  technology  for  writing  faster  code  (K. 
Rowe),  June,  p.  56 

Color  QuickDraw 

Adding  color  and  using  multiple  monitors  (C. 

Derossi),  Mac  Journal,  p.  8 
Combinatorial  optimization 
Solving  with  the  technique  of  simulated  annealing 
(M.P.  McLaughlin),  Sept.,  p.  26 
CommonView 

Examining  Room  review  (N.  Bergman),  Oct.,  p.  74 


Communication 

RC-to-minicomputer  communication  (M.  Servello), 
Oct.,  p.  18 

Hamming-code  decoding  (B.  White),  Oct.,  p.  52 

Communications  protocols 

Finite  state  machine  for  XModem  (D.  Smith),  Oct., 
p.  45 

Kermit  meets  Modula-2  (B.  Anderson),  May,  p.  22 

TINYCOMM  (A.  Stevens),  Feb.,  p.  115 

Compaction  technique 

Memory  allocation  compaction  system  (S.  Peter¬ 
son),  Apr.,  p.  50 

Compilers 

Routines  for  use  with;  QuickPak  Professional;  re¬ 
view  (B.  Tonkin),  Apr.,  p.  96 

Also  see  “Examining  Room” 

Container  objects 

Turbo  Pascal,  packaged  in  library  modules  (A. 
Hejlsberg),  Nov.,  p.  56 

Coprocessors 

Multitasking  OS  and  graphics  (Amiga)  (C.  McMa- 
nis),  July,  p.  36 


Data  acquisition 

A  real-time  system  (M.  and  M.  Bunnell),  June,  p.  36 

Data  communications 

Finite  state  machine  for  XModem  (D.  Smith),  Oct., 
p.  45 

PC-to-minicomputer  communication  (M.  Servello), 
Oct.,  p.  18 

Hamming-code  decoding  (B.  White),  Oct.,  p.  52 
High-speed  file  transfers  (C.  Menico),  Oct.,  p.  38 

Data  compression 

All-purpose  technique  for  programming  toolbox 
(LZW)  (M.  Nelson),  Oct.,  p.  29 
RLE  reduces  storage  requirements  (R.  Zigon),  Feb., 
p.  126 

Another  approach  to  RLE  (P.  Daley),  May,  p.  130 
More  on  RLE  (“Letters”),  Oct.,  p.  12 

Data-flow 

Diagrams  —using  mapping  to  improve  the  quality 
of  (G.  Lazarev),  Oct.,  p.  61 
Multitasking  and  sequential  algorithm  (R.  Kar),  Nov., 

p.  16 

Debugging 

TSR  Programs  with  Turbo  Debugger  (C.  Menico), 
Feb.,  p.  67 

Edward  K.  Ream's  Sherlock  debugger  (Examining 
Room,  A.  Lane)  Apr.,  p.  91 
With  Borland’s  Turbo  debugger  (B.  Catchings,  M. 
Van  Name),  July,  p.  64 

C  programs,  (B.  Edgar),  C  Sourcebook,  p.  56 

Demand  paging 

Demand  paged  virtual  memory  (K.  Dahlgren),  Apr., 
p.  32 

Advanced  80386  memory  management  (N.  Mar¬ 
gulis),  Apr.,  p.  24 

DESQview 

Using  the  API  to  develop  the  parallel  dvmake  (M. 
Streich),  Nov.,  p.  28 

Device  drivers 

That  support  true  global  variables  (J.  Mischel), 
Oct.,  p.  70 

Loading  with  an  INIT  on  the  Mac  (J.  Rosford),  Mac 
Journal,  p.  15 

Mac  Device  Manager,  template  with  Think  C  (B. 
Waters),  Mac  Journal,  p.  36 

Directories 

Extended  searches  using  C++  (J.  Dlugosz),  March, 
p.  55 

DOS 

Three  utilties  for  with  Modula-2  (K.  Porter),  Jan., 
p.  120 

Undocumented  DOS  (R.  James),  June,  p.  26 

DOS  Exec 

More  memory  through  swapping  calling  programs 
(K.  Kokkonen),  April,  p.  14 
Dynamic  link  libraries  (DLLs) 

Under  MS  Windows  (M.  Johnson,  M.  Solinski), 
March,  p.  28 
Dynamic  linking 

Linking  while  the  program  is  running  (A.  Schulman), 
Nov.,  p.  46 
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Dynamic  memory 

Coping  with  C  dynamic  memory  problems  (R.  Meri- 
latt),  Aug.,  p.  62 


Editors 

VEdit  Plus  (Examining  Room,  T.A.  Elkins),  Aug., 
p.  90 

An  icon  editor  (K.  Weiskamp,  L.  Heiny),  July,  p.  24 

Eiffel 

Its  development  and  use  (B.  Meyer),  Dec.,  p.  48 
Multiple  inheritance  (M.  Swaine),  March,  p.  107 

EGA 

Matching  colors  (K.  Porter),  April,  p.  116 
Examining  Room  product  reviews 
Microsoft’s  MASM  5.1,  Borland’s  TASM  1.0,  and 
SLR’s  OPTASM  1 .5  (M.  Schmidt),  Jan.,  p.  70 
STSC’s  APL'PLUS  II  (C.  Burke),  Feb.,  p.  72 
Advanced  Programming  Institute's  XVT  Toolkit  (M. 
Johnson),  March,  p.  70 

Crescent  Software’s  QuickPak  (B.  Tonkin),  Apr., 
p.  96 

QuickC  vs.  Turbo  C  (S.R.  Ladd),  May,  p.  68;  Aug., 
p.  89 

Abraxas  Software's  PCYACC  (A.  Lane),  June, 
p.  76 

Borland’s  Turbo  Debugger  (B.  Catchings,  M.  Van 
Name),  July,  p.  64 

Genus’s  C  Tools  and  PCX  Programmer’s  Toolkit 
(T.  Castle),  Aug.,  p.  91 

CompuView’s  VEdit  Plus  (T.A.  Elkins),  Aug.,  p.  90 
Watcom  C7.0  (J.  Dlugosz),  Sept.,  p.  74 
CommonView  (N.  Bergman),  Oct.,  p.  74 
Silicon  Graphics  (SGI)  parallelization  scheme  (B. 
Bauer),  Nov.,  p.  72 

Crescent  Software's  PDQ  for  QuickBasic  (B.  Tonkin), 
Dec.,  p.  88 

Extended  memory 

Using  on  the  PC  AT  (P.  Thomson),  Jan.,  p.  106 

Extensible  hashing 

Keyed  random  access  method  (S.  Heller),  Nov., 

p.  66 

Extensible  Virtual  Toolkit  (XVT) 

API’s  product  reviewed  (M.  Johnson),  March,  p.  70 
External  Commands  (XCMDs) 

Quick  drawing  with  (J.  Anderson),  May,  p.  63 


File  transfers 

High  speed  with  NetBIOS  (C.  Menico),  Oct.,  p.  38 

Filters 

With  an  object-oriented  language  (M.  Franz),  Dec., 

p.  28 

Finite  state  machines 

For  XModem,  but  general  enough  for  other  proto¬ 
cols  (D.  Smith),  Oct.,  p.  45 
Programming  (“Letters”),  Nov.,  p.  12 
Force-based  simulations 
C++  and  implementing  simulation  systems  (T.  King), 
Sept.,  p.  40 
Forth 

A  timed  event  network  scheduler  in  (G.  Ilg,  R. 
Brown),  Feb.,  p.  52 

An  extension  of  with  TENS,  Feb.,  p.  52 
Forth  Column,  The  (M.  Tracy) 

Forth  news  and  Mandlebrot  plotting  program,  Feb., 
p.  136 

Fortran 

Connecting  with  C  (M.  Floyd),  Aug.,  p.  22 
Functional  Programming 
Report  on  FPCA  '89  and  Haskell  language  (R. 
Fischer),  Dec.,  p.  96 


Global  variables 

A  global  variable  device  driver  (J.  Mischel),  Oct., 
p.  70 

Graphics 

Coprocessors  with  multitasking  OS  (Amiga)  (C. 
McManis),  July,  p.  36 


Line-of-best-fit  (W.  Murray,  C.  Pappas),  July,  p.  14 
An  Icon  editor  (K.  Weiskamp,  L.  Heiny),  July,  p.  24 
Image  mathematics  (V.  Duvanenko),  July,  p.  45 
Graphics  Programming  (K.  Porter) 

How  to  draw  a  pixel  on  the  EGA/VGA,  Feb.,  p.  121 
Lines  galore,  March,  p.  118 
Matching  colors  on  the  EGA,  Apr.,  p.  116 
GRAFIX  viewport,  May,  p.  124 
A  routine  that  senses  pixels;  filling  closed  figures, 
June,  p.  124 

Virtual  coordinates,  July,  p.  119 
And  curves,  Aug.,  p.  146 

Greedy  algorithm 

For  locating  a  global  optimum  in  a  discrete  space 
(M.P.  McLaughlin),  Sept.,  p.  26 


Hamming-code  theory 

In  “Hamming-Code  Decoding"  (B.  White),  Oct., 
p.  52 

Hardenbergh,  Hal 

Interview  with  about  neural  nets  (M.  Swaine),  July, 
p.  100 

Haskell  language 

In  report  on  Functional  Programming  Conference 
'89  (R.  Fischer),  Dec.,  p.  96 

Heapsort  algorithm 

A  sorting  tool  for  any  language  (K.  Russell),  Aug., 
p.  81 

HyperCard 

XCMDs  provide  access  to  QuickDraw  (J.  Ander¬ 
son),  May,  p.  63 


Icon  editor 

Roll  your  own  icons  w/mouse  (K.  Weiskamp,  L. 
Heiny),  July,  p.  24 

Image  processing 

Arithmetic  functions  to  combine  and  enhance  im¬ 
ages  (V.  Duvanenko),  July,  p.  45 

Index 

DDJ 1988  (K.  Ralston),  March,  p.  93 

INIT 

Loading  device  drivers  with,  on  the  Mac  (J.  Rosford), 
Mac  Journal,  p.  15 

Interprocess  communications 

In  OS/2  (R.  Duncan),  June,  p.  15 

Interpreters 

Build  your  own  (H.  Schildt),  Aug.,  p.  38 
SI:  a  C-like  script  interpreter  (A.  Stevens),  May, 
p.  117 

C  interpreter  for  OS/2  and  run-time  linking  (A. 
Schulman),  Nov.,  p.  46 

Small  languages  for  specific  tasks  (M.  Abrash,  D. 
Illowsky),  Sept.,  p.  52 


K&R 

Differences  with  ANSI  C  (S.R.  Ladd),  Aug.,  p.  74 

KRAM 

Keyed  random  access  method  — extensible  hash¬ 
ing  (S.  Heller),  Nov.,  p.  66 

Kermit 

Meets  Modula-2  (B.  Anderson),  May,  p.  22 


LabView 

Visual  OOP  with  (R.  Dye),  Mac  Journal,  p.  30 

Languages 

Variable-level  programming  (R.  Fischer),  June, 
p.  46 

Small  languages  for  specific  tasks  (M.  Abrash,  D. 
Illowsky),  Sept.,  p.  52 


Linked  lists 

A  class  for  C++  (A.  Stevens),  Nov.,  p.  133 

Logic  gates 

And  neural  networks  (T.  King),  Jan.,  p.  15 


Macintosh 

XVT  for  developing  portable  applications  (M. 
Johnson),  March,  p.  70 

Color  QuickDraw  (C.  DeRossi),  Mac  Journal,  p.  8 
Avoiding  INIT  collisions  (J.  Rosford),  Mac  Journal, 
p.  14 

Memory  management  with  MacAPP  (C.  Bianchi), 
Mac  Journal,  p.  22 

Visual  object-oriented  programming  (R.  Dye),  Mac 
Journal,  p.  30 

Writing  Macintosh  device  drivers  (B.  Waters),  Mac 
Journal,  p.  36 

Persistent  objects  (C.  Rovira),  Mac  Journal,  p.  40 
Wizardcopy  for  fast  backups  (D.  Gaspar),  Mac 
Journal,  p.  44 

Object  C  and  the  Macintosh  control  panel  (B.  Wa¬ 
ters),  Mac  Journal,  p.  50 

On  being  or  becoming  a  Macintosh  developer  (J. 

Custer),  Mac  Journal,  p.  54 
XCMDs  provide  access  to  QuickDraw  (J.  Ander¬ 
son),  May,  p.  63 

Network  graphs  in  Object  Pascal  (S.  Kienle),  Dec., 
p.  17 

make 

dvmake  with  the  DESQview  API  (M.  Streich),  Nov., 
p.  28 

MASM 

Microsoft's  assember  (Version  5.1)  reviewed  (M. 
Schmidt),  Jan.,  p.  70 

Mathematics 

Arithmetic  functions  can  enhance  imaging  (V.  Duva¬ 
nenko),  July,  p.  45 

Memory 

Using  extended  memory  on  the  PC  AT  (P.  Thom¬ 
son),  Jan.,  p.  106 

More  memory  for  DOS  Exec  (K.  Kokkonen),  Apr., 
p.  14 

Advanced  80386  memory  management  (N.  Mar- 
gulis),  Apr.,  p.  24 

Demand  paged  virtual  memory  (K.  Dahlgren),  Apr., 
p.  32 

SWAP  — application-independent  method  (N.  Mak), 
Apr.,  p.  44 

Memory  allocation  compaction  system  (S.  Peter¬ 
son),  Apr.,  p.  50 

Management  with  MacApp  (C.  Bianchi),  Mac  Jour¬ 
nal,  p.  22 

Microsoft  C 

Surrogate  library  makes  “C  Programming”  project 
compatible  with  MSC,  (A.  Stevens),  Jan., 
p.  Ill 

Mini-interpreters 

Define  small  languages  for  specific  tasks  (M.  Abrash , 
D.  Illowsky),  Sept.,  p.  52 

Minilanguages 

Roll  your  own  with  mini-interpreters  (M.  Abrash,  D. 
Illowsky),  Sept.,  p.  52 

Modula-2 

Compared  to  C++  (S.R.  Ladd),  Jan.,  p.  62 
Three  utilities  for  DOS  (K.  Porter),  Jan.,  p.  120 
Meets  Kermit  (B.  Anderson),  May,  p.  22 

MS-DOS 

Assemblers  compared  (M.  Schmit),  Jan.,  p.  70 
Real-time  modeling  with  (D.  Bowling),  Feb.,  p.  26 
Application-independent  method  (N.  Mak),  Apr. 
p.  44 

Undocumented  DOS  (R.  James),  June,  p.  26 

MS  Windows 

DLLs  under  (M.  Johnson,  M.  Solinski),  March,  p.  28 
XVT  for  developing  portable  applications  (M. 
Johnson),  March,  p.  70 

Microsoft  Windows  SDK  and  Actor  (J.  Duntemann), 
Dec.,  p.  153 

Multitasking 

C  ++  kernel  (T.  Green),  Feb.,  p.  45 

80386  protected  mode  (T.  Green),  Sept.,  p.  64 
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Multitasking  OS 

And  graphics  coprocessors  (Amiga)  (C.  McManis), 
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VESA  VGA  BIOS 

Extensions 

A  software  standard  for  Super  VGA 


Bo  Ericsson 


n  integral  part  of  IBM’s  PS/2 
announcement  in  April  1987 
was  the  video  graphics  array 
(VGA)  system.  Based  on  the 
architecture  of  the  enhanced 
graphics  adapter  (EGA),  the  VGA  of¬ 
fered  extended  resolutions  and  a  new 
256-color  video  mode.  Since  that  time, 
the  VGA  has  grown  in  importance  and 
is  today  an  established  PC  video  stan¬ 
dard.  As  a  matter  of  fact,  all  "old”  video 
standards  —  the  monochrome  display 
adapter  (MDA),  color  graphics  adapter 
(CGA),  Hercules  Graphics  Adapter,  and 
EGA  —  are  quickly  losing  ground  to 
the  VGA. 

There  are  several  reasons  for  the 
VGA’s  success.  For  one  thing,  the  new 
VGA  resolutions  (see  Figure  1),  together 
with  lower-priced  multi-frequency  moni¬ 
tors,  have  made  the  VGA  a  more  attrac¬ 
tive  solution  than  previous  standards. 
Also,  a  multitude  of  VGA  offerings  and 
fierce  competition  have  made  a  baseline 
VGA  an  economically  attractive  choice. 

As  a  matter  of  fact,  competition  in 
the  VGA  marketplace  not  only  has 
driven  the  prices  of  VGA  boards  to  the 
bottom,  but  has  pushed  up  the  features 
and  capabilities  of  these  boards.  Virtu¬ 
ally  all  VGA  controllers  available  today 
are  compatible  down  to  the  register 
level  with  the  IBM  VGA,  and  almost  all 
of  them  implement  some  extensions 
to  the  IBM  VGA. 

The  term  “Super  VGA”  is  used  in  this 
article  to  identify  video  hardware  that 
implements  a  full  superset  of  the  stan- 


Bo  is  a  software  engineering  manager 
at  Chips  and  Technologies  Inc.,  3050 
Zanker  Road,  San  Jose,  CA  95134. 


dard  VGA,  including  register  compati¬ 
bility.  Extensions  to  the  IBM  VGA  can 
be  classified  into  three  different  cate¬ 
gories: 

1.  Backwards  compatibility 

2.  Functional  extensions 

3.  Higher  spatial  and  color  resolutions 

Backwards  Compatibility 

The  basic  IBM  VGA  is,  at  best,  compat¬ 
ible  with  older  video  standards  only  at 
the  BIOS  level.  There  is  a  large  popula¬ 
tion  of  older  programs  written  specifi¬ 
cally  for,  and  directly  to,  the  CGA  or 
Hercules  Graphics  Adapter  that  bypass 
the  BIOS  partially  or  completely.  Be¬ 
cause  of  this,  none  of  these  applica¬ 
tions  run  on  a  standard  VGA. 


However,  most  VGA  products  offer 
some  register-level  support  for  these 
older  standards.  These  implementations 
either  attempt  to  automatically  detect 
older  programs  and  switch  into  a  suit¬ 
able  compatible  video  mode  or  require 
a  utility  program  to  lock  the  video  hard¬ 
ware  into  a  compatible  video  mode. 

Functional  Extensions 

The  basic  VGA  is  a  pretty  dumb  device; 
the  CPU  (that  is,  the  application  pro¬ 
gram)  is  required  to  do  almost  all  graph¬ 
ics  processing.  Only  certain  logical  op¬ 
erations  on  the  graphics  data  can  be 
performed  by  the  standard  VGA  hard¬ 
ware.  There  are  no  functions  for  BitBlts 
(bit-block-transfers),  line  drawing,  and 
so  on. 
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In  graphics-intensive  applications,  such 
as  MS-Windows,  OS/2  Presentation  Man¬ 
ager,  and  GEM,  manipulating  the  graph¬ 
ics  bitmap  takes  considerable  time  and 
affects  system  performance.  For  this 
reason,  several  VGA  controller  vendors 
have  put  various  graphics  capabilities 
directly  into  the  VGA  hardware. 

For  instance,  certain  VGA  controllers 
implement  a  graphics  cursor  in  hard¬ 
ware.  All  graphics  user  interfaces  (such 
as  Windows,  GEM,  X-Windows,  Presenta¬ 
tion  Manager,  etc.)  use  a  graphics  cur¬ 
sor.  The  graphics  cursor  is  an  icon  (usu¬ 
ally  an  arrow)  that  moves  around  the 
screen  as  the  mouse  is  moved.  A  lot  of 
CPU  processing  is  required  to  move 
the  graphics  cursor  even  one  pixel  on 
the  screen.  Instead  of  refreshing  the 
actual  bitmap  on  a  standard  VGA,  these 
controllers  need  only  the  coordinate 
of  the  “hot-spot.”  The  actual  display 
of  the  cursor  is  done  in  hardware; 
bitmap  manipulation  is  not  necessary. 

Other  VGA  controllers  implement 
more  sophisticated  write  modes,  ele¬ 
mentary  BitBlt  capabilities,  or  other  func¬ 
tions  that  relieve  the  CPU  of  some  graph¬ 
ics  processing. 

Higher  Resolutions,  More  Colors 

The  most  exciting  aspect  of  all  Super 
VGA  implementations,  however,  is  the 
higher  resolutions  and  the  increased 
number  of  simultaneous  colors  on  the 
screen.  The  standard  VGA  can  display 
16  simultaneous  colors  in  640  x  480 
resolution  and  256  colors  in  320  x  200, 
as  described  in  Figure  1.  In  contrast,  a 
typical  Super  VGA  board  can  do  1024 
x  768  in  16  colors  and  640  x  480  in  256 
colors.  In  the  near  future,  a  range  of 
VGA  controllers  will  be  able  to  do  1024 
x  768  in  256  colors.  And  a  little  further 


down  the  line,  some  controllers  will 
have  the  capability  of  1280  x  1024  reso¬ 
lution  in  16  colors. 

Developments  in  the  monitor  mar¬ 
ket  make  these  extended  resolutions 
especially  important.  Multifrequency 
monitors  capable  of  resolutions  up  to 
1024  x  768  are  available  today  for  less 
than  $1000,  and  the  price  is  expected 
to  drop  even  further. 

Planar  vs.  Packed  Pixel  Modes 

Before  beginning  a  discussion  on  Su¬ 
per  VGA  graphics,  a  brief  summary  of 
the  basic  video  memory  modes  is  re¬ 
quired.  VGA  graphics  video  modes  use 
either  planar  or  packed  pixel  video 
memory  architecture. 

In  planar  mode,  the  video  memory 
is  divided  into  four  separate  planes. 
One  pixel  is  defined  by  4  bits,  1  bit  per 
plane.  Eight  pixels  are  defined  by  4 
bytes,  1  byte  per  plane.  Because  one 
pixel  is  defined  by  4  bits,  16  colors  can 
simultaneously  be  displayed. 

Normally,  only  one  plane  can  be 
accessed  at  one  time  by  the  CPU.  To 
access  another  plane,  the  hardware  reg¬ 
isters  of  the  VGA  have  to  be  repro¬ 
grammed.  For  rapid  fills  of  a  large  area 
to  a  certain  color,  the  VGA  can  be 
programmed  for  32-bit  operation,  al¬ 
lowing  simultaneous  access  to  all  four 
planes. 

In  packed  pixel  mode,  only  one  mem¬ 
ory  plane  is  available.  One  pixel  is 
defined  by  1  byte  in  the  memory,  yield¬ 
ing  256  simultaneous  colors. 

The  Developer's  Dilemma 

In  spite  of  this  revolution  and  the  fan¬ 
tastic  opportunities  that  SuperVGA  pro¬ 
vides,  software  development  has  been 
slow  in  tapping  into  the  capabilities. 


Very  few  applications  have  Super  VGA 
support,  and  only  OEM-specific  dis¬ 
play  drivers  (software  tied  directly  to  a 
certain  VGA  controller)  can  generally 
exploit  Super  VGA  resolutions  and  ca¬ 
pabilities. 

There  are  several  reasons  why  soft¬ 
ware  development  for  Super  VGA  has 
been  sluggish.  The  most  important  rea¬ 
son  is  that  almost  all  Super  VGA  hard¬ 
ware  implementations  are  different  from 
one  another  —  a  Super  VGA  controller 
from  manufacturer  A  is  usually  signifi¬ 
cantly  different  from  manufacturer  B’s 
because  no  common  hardware  or  soft¬ 
ware  interface  exists. 

The  software  developer  has  to  gather 
a  significant  understanding  of  intimate 
details  of  each  Super  VGA  controller 
(of  which  there  are  at  least  ten  at  pre¬ 
sent)  and  each  implementation  (of 
which  there  are  dozens,  maybe  hun¬ 
dreds)  that  he/she  intends  to  support. 
The  cost  of  acquiring  this  knowledge 
and  supporting  these  disparate  envi¬ 
ronments  is  prohibitively  high;  software 
developers  have  shunned  Super  VGA 
for  this  reason. 

Non-standard  Initialization 

Super  VGA  implementations  differ  sig¬ 
nificantly  in  the  video  mode  initializa¬ 
tion  procedure.  One  piece  of  mode 
setting  code  will  not  work  on  more 
than  one  Super  VGA  board  because 
the  I/O  addresses  for  the  extended  reg¬ 
isters  required  for  Super  VGA  opera¬ 
tion  vary  from  implementation  to  im¬ 
plementation.  In  addition,  the  specific 
parameters  for  the  registers  all  depend 
on  the  VGA  controller. 

Another  aspect  of  this  problem  is 
that  there  is  no  uniform  BIOS  support 
for  mode  initialization  across  Super  VGA 
products.  No  video  mode  number 
scheme  exists.  A  640  x  480  256  color 
video  mode  is  called  79  in  one  im¬ 
plementation  and  43  in  another.  Also, 
no  standardized  mode  initialization  call 
exists. 

All  this  means  that  an  application 
cannot  program  the  hardware  directly 
(because  no  standard  hardware  exists), 
nor  can  it  call  a  BIOS  to  initialize  the 
mode  (because  a  standardized  mode 
number  doesn’t  exist,  and  because  no 
standardized  calling  sequence  is  estab¬ 
lished). 

Different  Windowing  Schemes 

Another  area  where  Super  VGA  imple¬ 
mentations  differ  greatly  is  in  how  the 
video  memory  is  accessed.  In  the  IBM 
PC,  a  maximum  of  128K  is  devoted  to 
the  video  system.  This  address  space 
is  located  between  A0000  and  BFFFF 
hex.  For  compatibility  reasons,  only 
the  64K  at  A0000  is  normally  used  for 
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Figure  1:  PC  graphics  resolutions  and  colors 


Resolution 

Colors 

Pixels 

Bits  per 
pixel 

Total 

memory 

(bytes) 

Planes 

CPU 

memory 

(bytes) 

640x480 

16 

307200 

4 

153600 

4 

38400 

800  x  600 

16 

480000 

4 

240000 

4 

60000 

1024x768 

16 

786432 

4 

393216 

4 

98304 

640x400 

256 

256000 

8 

256000 

1 

256000 

640x480 

256 

307200 

8 

307200 

1 

307200 

800x600 

256 

480000 

8 

480000 

1 

480000 

1024x768 

256 

786432 

8 

786432 

1 

786432 

Figure  2:  Memory  requirements  of  Super  VGA  modes 
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Super  VGA  resolutions  (another  video 
board  in  the  system  might  be  located 
at  B0000-BFFFF). 

Flowever,  Super  VGA  video  modes 
consume  more  video  memory  than  is 
available  in  the  CPU  address  space. 
Figure  2  details  typical  memory  require¬ 
ments  of  Super  VGA  modes.  As  is  evi¬ 
dent  from  this  table,  there  has  to  be  a 
mechanism  for  the  CPU  to  reach  into 
the  video  memory  using  the  64K  (or 
128K)  “window”  available  in  the  CPU 
address  space. 

Unfortunately,  there  are  almost  as 
many  windowing  schemes  as  there  are 
Super  VGA  controllers.  Some  control¬ 
lers  have  one  window  into  the  video 
memory,  while  others  have  two.  Some 
controllers  have  separate  read  and  write 
windows,  while  others  allow  read / 
write  in  both  windows.  Some  control¬ 
lers  implement  a  “sliding”  windowing 
scheme,  whereby  a  window  can  be 
placed  on  any  boundary  in  the  video 
memory,  while  others  allow  placement 
of  the  window  only  on  a  64K  boundary. 

On  top  of  this,  the  hardware  regis¬ 
ters  that  control  the  windowing  scheme 
are  located  at  different  I/O  addresses 
and  require  different  parameters. 

Enter  the  VESA  BIOS  Extension 

The  Super  VGA  BIOS  extension  stan¬ 
dard,  as  defined  by  the  Video  Electron¬ 
ics  Standards  Association  (VESA),  in¬ 
tends  to  remedy  the  incompatibility  is¬ 
sues  addressed  earlier.  The  standard 
tries  to  address  all  major  problems  a 
software  developer  faces  when  writing 
software  for  Super  VGA. 

Technically,  the  VESA  BIOS  exten¬ 
sion  is  implemented  as  an  addition  to 
the  regular  video  BIOS,  accessed 
through  software  interrupt  10  hex.  Stan¬ 
dard  video  BIOS  functions  are  called 
by  placing  function  numbers  in  the 
range  from  0  to  1C  hex,  depending  on 
the  function,  in  the  AH  CPU  register 
and  then  generating  a  software  inter¬ 
rupt  10  hex.  To  call  a  VESA  BIOS  func¬ 
tion,  the  application  would  place  the 
value  4F  hex  in  the  AH  register,  place 
a  function  number  in  the  AL  register, 
and  then  generate  an  interrupt  10  hex. 
Figure  3  describes  the  VESA  BIOS  exten¬ 
sion  functions. 

The  VESA  BIOS  extension  may  be 
placed  in  ROM  together  with  the  regu¬ 
lar  BIOS.  It  may  also  be  implemented 
as  a  device  driver,  loaded  by  the  oper¬ 
ating  system  at  boot  time.  Initially,  most 
VESA  BIOS  extensions  will  be  avail¬ 
able  as  TSR  programs.  To  the  applica¬ 
tion,  the  method  of  implementation  is 
irrelevant;  functionally,  the  BIOS  ex¬ 
tension  behaves  the  same. 

The  VESA  BIOS  extension  provides 
two  fundamental  services  to  the  appli¬ 


cation  program: 

1.  Information 

2.  Hardware  setup 

Global  Information 

To  be  able  to  adapt  to  a  specific  Super 
VGA  environment,  an  application  needs 
several  important  pieces  of  informa¬ 
tion.  First  and  foremost,  an  application 
needs  to  know  whether  the  specific 
environment  is  indeed  capable  of  Su¬ 
per  VGA  resolutions.  The  application 
also  needs  to  know  whether  any  VESA 
support  is  available.  In  addition,  cer¬ 
tain  applications  might  want  to  identify 
a  specific  VGA  controller. 

This  kind  of  global  information  is 
provided  by  VESA  BIOS  function  0, 
Return  Super  VGA  mode  information. 
Before  the  application  calls  this  func¬ 
tion,  it  has  to  allocate  a  buffer  of  256 


bytes.  The  VESA  BIOS  extension  will 
fill  this  buffer  with  various  types  of 
information. 

One  of  the  most  important  pieces  of 
information  returned  by  function  0  is 
a  pointer  to  a  list  of  Super  VGA  modes 
supported  by  the  display  adapter.  These 
video  modes  can  be  VESA-defined 
modes  as  well  as  OEM-defined  modes. 
See  Figure  4  for  a  list  of  VESA-defined 
video  modes. 

Mode-specific  Information 

To  determine  the  characteristics  of  a 
particular  video  mode,  the  application 
would  then  call  VESA  BIOS  function 
1,  Return  Super  VGA  mode  informa¬ 
tion.  Like  function  0,  the  application 
has  to  allocate  a  256-byte  buffer  prior 
to  making  the  function  call. 

On  return  from  the  function,  the  VESA 
BIOS  extension  will  have  filled  a  struc- 


The  following  functions  are  defined  by  the  VESA  BIOS  extension.  They  are  all  accessible  through 
interrupt  10  hex  with  AH  set  to  4F  hex. 

Every  function  returns  status  information  in  the  AX  register.  The  format  of  the  status  word  is  as 
follows: 

AL==4Fh:  Function  is  supported 

AL!=4Fh:  Function  is  not  supported 

AH==00h:  Function  call  successful 

AH==  01  h:  Functiion  call  failed 

Function  0  -  Return  Super  VGA  Information 

Input:  AH=4Fh  Super  VGA  support 

AL=0Oh  Return  Super  VGA  information 

ES:DI=  Pointer  to  information  block 

Output:  AX=  Status 

Ail  other  registers  are  preserved 

The  information  block  has  the  following  structure: 

VgalnfoBlock  struc 


VESASignature 

db 

’VESA’ 

;  4  signature  bytes 

VESAVersion 

dw 

? 

;  VESA  version  number 

OEMStringPtr 

dd 

? 

:  Pointer  to  OEM  string 

Capabilities 

db 

4  dup(?) 

;  capabilities  of  the  video  environment 

VideoModePtr 

dd 

? 

;  pointer  to  supported  Super  VGA  modes 

VgalnfoBlock  ends 

Function  1  -  Return  Super  VGA  mode  information 


Input:  AH=4Fh 

Super  VGA  support 

AL=01h 

Return  Super  VGA  information 

CX= 

Super  VGA  video  mode 

ES:DI= 

Pointer  to  information  block 

Output:  AX= 

Status 

All  other  registers  are  preserved 

Function  2  -  Set  Super  VGA  video  mode 

Input:  AH=4Fh 

Super  VGA  support 

AL=02h 

Set  Super  VGA  video  mode 

BX= 

D0-D14  =  video  mode 

D1 5  =  Clear  memory  flag 

0  =  Clear  video  memory 

1  =  Don’t  clear  video  memory 

Output:  AX= 

Status 

All  other  registers  are  preserved 

Function  3  -  Return  current  video  mode 

Input:  AH=4Fh 

Super  VGA  support 

AL=03h 

Return  current  video  mode 

Output:  AX= 

Status 

BX= 

Current  video  mode 

All  other  registers  are  preserved 


Figure  J:  VESA  BIOS  extension  functions  (accessible  through  interrupt  10 
hex  with  AH  set  to  4F  hex) 
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ture,  called  the  ModelnfoBlock,  with  all 
relevant  information  about  this  video 
mode.  See  Figure  5  for  a  description 
of  the  ModelnfoBlock. 

Mode  Attributes 

The  first  word  (16  bits)  in  the  Modeln¬ 
foBlock ,  the  ModeAttributes  field,  speci¬ 
fies  several  important  characteristics  of 
the  video  mode.  See  Figure  6  for  the 
layout  of  this  field. 

Bit  DO  in  the  ModeAttributes  field 
specifies  whether  the  mode  is  supported 
by  the  present  hardware  configuration. 
If  a  particular  video  mode  requires  a 
certain  monitor,  and  this  monitor  is 
presently  not  connected  to  the  system, 
this  bit  can  be  cleared  to  block  access 
to  the  mode.  Applications  should  never 
try  to  initialize  a  video  mode  whose 
ModeAttributes  DO  is  set  to  0. 

As  will  be  evident  in  the  discussion 
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later,  the  VESA  BIOS  function  0  returns 
a  lot  of  information  to  the  application. 
Some  of  this  information  is  mandatory, 
some  is  optional.  Bit  D1  of  the  ModeAt¬ 
tributes  specifies  whether  any  optional 
information  is  available. 

Bit  D2  indicates  whether  the  output 
functions  (TTY  output,  set/get  pixel, 
scroll  window,  etc.)  of  the  regular  video 
BIOS  can  be  used  in  this  video  mode. 
It  is  not  mandatory  for  a  VESA  BIOS 
extension  to  support  all  or  any  output 
functions  in  Super  VGA  modes.  The 
primary  reason  for  this  is  that  high- 
performance  applications  handle  all  out¬ 
put  themselves  anyway,  for  performance 
reasons.  The  fact  that  output  support 
consumes  a  lot  of  precious  memory 
space  in  a  ROM-based  implementation 
was  also  important  in  making  this  sup¬ 
port  optional.  If  bit  D2  is  cleared,  then 
no  output  support  is  available. 


Bit  D3  specifies  whether  the  mode 
is  monochrome  ( D3=0 )  or  color  (D3=l). 
Bit  D4  defines  the  mode  as  either  text 
mode  (.D4=0)  or  graphics  mode  (. D4=l ). 

Window  Description 

The  characteristics  of  the  windowing 
system  are  described  in  the  next  field 
in  the  ModelnfoBlock  structure.  The 
WinAAttributesand  WinBAttributes iden¬ 
tify  whether  window  A  and  B  exist  and 
are  readable  or  writeable.  All  Super 
VGA  boards  capable  of  resolutions  be¬ 
yond  640  x  400  in  256  colors  and  800 
x  600  in  16  colors  have  at  least  one 
window  into  the  video  memory.  Appli¬ 
cations  can  determine  the  existence  of 
a  second  window  by  testing  bit  DO  of 
WinBAttributes. 

The  WinGranularity  identifies  the 
smallest  address  boundary  that  the  win¬ 
dow  can  be  placed  upon.  In  today’s 
Super  VGA  boards,  this  varies  from  IK 
to  64K.  The  WinSize  field  identifies  the 
size  of  the  windows.  In  a  single-win¬ 
dow  system,  the  size  is  normally  64K, 
while  in  a  dual  window  system,  the 
size  is  normally  32K. 

The  location  of  the  windows  within 
the  CPU  address  space  is  specified  by 
the  fields  WinASegment  and  WinBSeg- 
ment.  Normally  Window  A  is  located 
at  address  A0000.  If  a  second  window 
is  present,  it  would  typically  be  located 
at  A8000  or  B0000.  If  the  VGA  control¬ 
ler  implements  different  read  and  write 
windows,  the  second  window  could 
be  located  at  the  same  CPU  address  as 
the  first  window.  In  such  a  system,  a 
CPU  read  will  access  the  read  window, 
while  a  CPU  write  will  access  the  write 
window. 

The  WinFuncAddr  field  specifies  a 
direct  address  to  the  windowing  func¬ 
tion  (Figure  3,  VESA  BIOS  function  5). 
The  standard  way  to  access  the  video 
BIOS  and  the  VESA  BIOS  extension  is 
to  generate  an  int  10.  However,  due 
to  the  large  number  of  subfunctions 
using  int  10,  function  dispatching  may 
take  considerable  time.  This  makes  int 
1 0  too  slow  for  some  graphics  opera¬ 
tions.  One  such  time-critical  operation 
is  changing  the  windowing  registers. 
By  using  the  absolute  address  to  the 
function,  an  application  can  issue  a  far 


Mode 

number 

Resolution 

Colors 

lOOh 

640x400 

256 

101  h 

640x480 

256 

102h 

800  X  600 

16 

103h 

800  x  600 

256 

104h 

1024x768 

16 

105h 

1024x768 

256 

106h 

1280x1024 

16 

lOOh 

1280x1024 

256 

Figure  4:  VESA-defined  Super  VGA 
modes 
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Function  4 

-  Save/Restore  Super  VGA  video  state 

Input: 

AH=4Fh 

Super  VGA  support 

AL=04h 

Save/restore  Super  VGA  video  state 

DL=00h 

Return  save/restore  state  buffer  size 

CX= 

Requested  states 

D0=Save/restore  video  hardware  state 

D1  =Save/restore  video  BIOS  data  state 
D2=Save/restore  video  DAC  state 
D3=Save/restore  Super  VGA  state 

Output: 

AX= 

Status 

BX= 

Number  of  64-byte  blocks  to  hold  the  state  buffer 

All  other  registers  are  preserved 

Input: 

AH=4Fh 

Super  VGA  support 

AL=04h 

Save/Restore  Super  VGA  state 

DL=01  h 

Save  Super  VGA  video  state 

CX= 

Requested  states  (see  above) 

ES:BX= 

Pointer  to  buffer 

Output: 

AX= 

Status 

All  other  registers  are  preserved 

Input: 

AH=4Fh 

Super  VGA  support 

AL=04h 

Save/Restore  Super  VGA  state 

DL=02h 

Restore  Super  VGA  video  state 

CX= 

Requested  states  (see  above) 

ES:BX= 

Pointer  to  buffer 

Output: 

AX= 

Status 

All  other  registers  are  preserved 

Section  5  - 

CPU  Video  Memory  Window  Control 

Input: 

AH=4Fh 

Super  VGA  support 

AL=05h 

Super  VGA  video  memory  window  control 

BH=00h 

Select  Super  VGA  video  memory  window 

BL= 

Window  number 

0=Window  A 

1  =Window  B 

DX= 

Window  position  in  video  meory 

Output: 

AX= 

Status 

Input: 

AH=4Fh 

Super  VGA  support 

AL=05h 

Super  VGA  video  memory  window  control 

BH=01h 

Return  Super  VGA  video  memory  window 

BL= 

Window  number 

0= Window 

1=Window 

Output: 

AX= 

Status 

DX= 

Window  position  in  video  memory 

VESA  VGA 


call  directly  into  it,  speeding  up  execu¬ 
tion  considerably. 

Optional  Information 

Only  a  portion  of  the  ModelnfoBlock 
is  obligatory  information.  The  other  sec¬ 
tion  is  optional  and  is  provided  if  the 
specific  mode  is  nonstandard.  None 
of  the  modes  defined  by  VESA  (see 
Figure  4)  require  the  optional  informa¬ 
tion.  For  an  OEM-specific  mode,  how¬ 
ever,  the  VESA  BIOS  extension  needs 
to  inform  the  application  about  items 
such  as  screen  resolution,  number  of 
planes,  and  bits  per  pixel. 

Refer  to  the  VESA  BIOS  extension 
specification  for  information  on  how 


to  use  these  optional  fields. 

Video  Mode  Initialization 

One  main  objective  of  the  VESA  BIOS 
extension  is  to  help  applications  set 
up  video  modes.  This  is  realized  through 
VESA  BIOS  Function  2,  Set  Super  VGA 
video  mode.  The  application  simply 
places  the  video  mode  to  be  initialized 
in  the  BX  register  and  calls  this  func¬ 
tion.  Normally,  the  video  memory  will 
be  cleared,  but  if  the  application  sets 
bit  D15  of  the  BX  register  prior  to  call¬ 
ing  the  function,  the  memory  will  be 
preserved. 

VESA  mode  numbers  are  15  bits  wide 
(see  Figure  4).  OEM-defined  mode  num¬ 


bers  are  7-bits  wide  and  are  imple¬ 
mented  as  a  subset  of  VESA-defined 
modes.  Due  to  this  numbering  conven¬ 
tion,  VESA  modes,  OEM-specific  modes, 
and  regular  VGA  modes  can  be  initial¬ 
ized  by  using  VESA  BIOS  Function  2. 

If  an  application  needs  to  know  the 
present  video  mode,  it  would  call  VESA 
BIOS  Function  3,  Return  current  video 
mode.  For  applications  (especially  TSR 
programs)  that  need  to  interrupt  other 
programs,  the  VESA  BIOS  Function  4, 
Save/Restore  Super  VGA  video  state , 
comes  in  handy. 

The  Windowing  Function 

Finally,  the  VESA  BIOS  extension  pro¬ 
vides  a  mechanism  to  control  the  posi¬ 
tion  of  the  video  memory  windows. 
This  is  handled  by  Function  5,  CPU 
video  memory  window  control.  To  re¬ 
position  a  window  into  the  video  mem¬ 
ory,  the  application  simply  places  the 
window  position  in  the  DX  register, 
the  window  number  ( 0  for  Window  A 
and  1  for  Window  B)  in  the  BL  register, 
and  calls  Function  5. 

The  window  position  is  not  speci¬ 
fied  as  a  byte  offset,  but  rather  in  terms 
of  granularity  units.  As  stated  earlier, 
the  window  granularity  expresses  the 
smallest  boundary  on  which  the  win¬ 
dow  can  be  placed.  Today’s  SuperVGA 
boards  have  granularities  between  4K 
and  64K.  Thus,  if  the  granularity  is  16K, 
and  the  application  wants  to  position 
the  window  at  64K,  the  window  posi¬ 
tion  is  64/16  =  4  granularity  units. 

Conclusion 

The  VESA  BIOS  extension  provides  all 
necessary  information  and  programming 
support  to  Super  VGA  applications.  For 
the  first  time,  it  is  possible  to  develop 
generic  graphics  software,  tapping  into 
the  exciting  capabilities  of  Super  VGA. 

However,  just  because  the  VESA  BIOS 
extension  has  made  it  possible  to  write 
such  applications  doesn’t  mean  it  will 
be  trivial.  Most  of  the  complexity  in 
dealing  with  Super  VGA  stems  from 
managing  windows  into  the  video  mem¬ 
ory.  Anyone  already  familiar  with  writ¬ 
ing  software  for  one  Super  VGA  board 
should  have  no  difficulty  in  program¬ 
ming  others  using  the  VESA  BIOS  ex¬ 
tension. 
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Field  name 

ModeAttributes 

WinAAttributes 

WinBAttributes 

WinGranularity 

WinSize 

WinASegment 

WinBSegment 

WinFuncPtr 

BytesPerScanLine 

XResolution 

YResolution 

XCharSize 

YCharSize 

NumberOfPlanes 

BitsPerPixel 

NumberOfBanks 

MemoryModel 

BankSize 


Size 

word 

byte 

byte 

word 

word 

word 

word 

doubleword 

word 

word 

word 

byte 

byte 

byte 

byte 

byte 

byte 

byte 


Description 

mode  attributes 
window  A  attributes 
window  B  attributes 
window  granularity 
window  size 
window  A  start  segment 
window  B  start  segment 
pointer  to  window  function 
bytes  per  scan  line 
extended  information 
horizontal  resolution 
vertical  resolution 
character  cell  width 
character  cell  height 
number  of  memory  planes 
bits  per  pixel 
number  of  banks 
memory  model  type 
bank  size  in  kb 


|  mandatory  information 


j  optional  information 


Figure  5:  Mode  information  block  structure 


15 

14 

13 

12 

11 

10 

9 

8 

7 

6 

5 

0 

3 

2 

1 

0 

V 


Reserved 


Mode  type 


0  =  text  mode 
1  =  graphics  mode 


Monochrome/color  - 
0  =  monochrome 
1  =  color 


BIOS  output  - 

functions  supported 
0  =  no 
1  =  yes 


Mode  supported 
in  hardware 
0  =  no 
1  =  yes 


Extended  information 
available 
0  =  no 
1  =  yes 


Figure  6:  Mode  attribute  field 
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E  X  A  MIN  I  N  G  ROOM 


Cruising 
with  TopSpeed 

A  full-featured  toolset  is 
the  real  value  in  this  C  compiler 


Alex  Lane 


It  is  fashionable  in  some  circles  to 
yawn  upon  hearing  that  a  new  C 
compiler  has  hit  the  market.  Such 
folks  see  the  C  world  as  divided 
into  two  main  camps  —  the  Micro- 
softs  and  the  Turbos  —  with  a  smatter¬ 
ing  of  fanatics  representing  an  insig¬ 
nificant  fringe.  That  fringe,  however, 
has  lately  succeeded  in  whipping  up 
the  C  market,  the  result  being  a  lively 
free-for-all  as  new  arrivals  such  as  Wat- 
com,  Zortech,  and  now  TopSpeed  C 
attempt  to  prove  their  worth  to  pro¬ 
grammers.  Readers,  familiar  with  the 
TopSpeed  name,  will  associate  it  with 
a  popular  Modula-2  compiler  and  a 
recently  introduced  Pascal  compiler,  mar¬ 
keted  by  Jensen  &  Partners  Interna¬ 
tional.  JPI,  a  company  established  in 
1987  by  a  group  of  former  Borland 
employees,  is  a  relatively  small  com¬ 
pany  with  unquestionably  large  vision. 
They  intend  to  develop  an  integrated 
multilanguage  environment  that  will  let 
programmers  seamlessly  mix  and  match 
routines  from  a  broad  spectrum  of  lan¬ 
guages,  including  ISO  Pascal,  C,  C++, 
Modula-2,  and  Ada.  What  JPI  in  effect 
proposes  to  do  is  to  link  each  language 
dynamically  into  the  system  as  an  over¬ 
lay  at  run  time,  thus  allowing  each 
language  compiler  to  use  the  same  op¬ 
timizing  code  generator.  If  TopSpeed 
C  is  any  indicator,  JPI  has  its  sights  set 
on  a  worthwhile  goal. 


Alex  is  a  knowledge  engineer  for  Tech¬ 
nology  Applications  Inc.  in  Jackson¬ 
ville,  Florida.  He  can  be  reached  on 
BIX  as  a.lane  or  through  MCI  mail  as 
ALANE. 


What  You  Get 

I  reviewed  the  TopSpeed  C,  Version 
1.02,  Extended  Edition,  which  is  basi¬ 
cally  the  standard  package  (comprised 
of  an  optimizing  100  percent  ANSI  C 
compiler  and  high-speed  linker,  an  auto¬ 
matic  make  facility,  an  editing  environ¬ 
ment,  and  source-level  debugger)  com¬ 
bined  with  the  TopSpeed  C  TechKit, 
which  provides  enhanced  functional¬ 
ity  in  the  form  of  library  source  code, 
Windows  support,  DOS  dynamic  link¬ 
ing,  profiling,  and  post-mortem  debug¬ 
ging,  among  other  features.  The  stan¬ 
dard  TopSpeed  package  consists  of 
seven  diskettes  and  nearly  three  inches 
of  paperback  documentation,  consist¬ 
ing  of  a  user  manual,  a  language  refer¬ 
ence,  a  library  reference,  and  a  lan¬ 
guage  tutorial.  The  TechKit  comes  on 
an  additional  four  disks  and  has  sepa¬ 
rate  documentation. 

Finding  Files 

I  dread  installing  software  that  needs 
to  use  DOS  environment  variables  to 
find  files  on  my  disk.  For  one  thing,  I 
only  have  so  much  DOS  environment 
space;  for  another,  I  often  find  that  two 


Figure  1:  A  sample  redirection  file 


different  packages  use  the  same  DOS 
environment  variable  name  in  different 
ways,  and  that  no  amount  of  fiddling 
with  SET  statements  shall  allow  the 
twain  to  meet  on  a  consistent  basis.  If 
you  have  two  or  more  C  compilers 
installed  on  your  hard  disk,  you  prob¬ 
ably  know  what  I  mean. 

If  you  want  TopSpeed  C  to  use  DOS 
environment  variables,  you  can  so  spec¬ 
ify  by  using  the  /y  flag  from  the  com¬ 
mand  line,  but  why  bother?  I  took  an 
immediate  liking  to  TopSpeed’s  redi¬ 
rection  file  feature,  which  acts  as  a  sort 
of  private  environment.  A  sample  redi¬ 
rection  file,  TS.RED,  is  reproduced  in 
Figure  1.  The  syntax  is  similar  to  that 
of  DOS  paths.  The  first  line  indicates 
that  all  KABOOOOM.*  files  are  found 
in  the  directory  C:\  KABOOOOM.  Analo¬ 
gously,  all  other  *.C  files  may  be  found 
either  in  the  current  directory  (denoted 
by  the  or  in  CATS  \ EXAMPLES, 
CATS\  SRC,  or  in  DA  FRAC  \PROGS. 
The  remaining  lines  are  self-explana¬ 
tory,  except  perhaps  for  the  line  that 
refers  to  *.A  files  that  are  TopSpeed 
assembler  files. 

By  editing  TS.REG,  then  automati- 


KABOOOOM.*  = 

C:\KABOOOOM 

*.C 

C:\TS\EXAMPLES;  C:\TS\SRC;  D:\FRAC\PROGS; 

*.PRJ 

C:\TS\PRJ;  C:\TS\EXAMPLES; 

*.H 

C:\TS\INCLU DE;C:\TS\EXAMPLES;  D:\FRAC\PROGS; 

*.A 

C:\TS\LIB;  C:\TS\EXAMPLES;  C:\TS\SRC 

*.OBJ 

C:\TS\OBJ;  C:\TS\LIB; 

*.LIB 

C:\TS\L1B;  D:\FRAC\PROGS; 

*.DOC 

C:\TS\DOC; 

TS.RED 

C:\TS\SYS; 

72 
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cally  saving  and  reloading  it,  you  can 
change  the  file  search  (and  storage) 
behavior  of  the  environment  on-the- 
fly.  If,  despite  your  best  intentions,  you 
repeatedly  end  up  with  all  your  *.c, 
*.obj,  *.h,  and  *.exe  files  in  one  giant 
directory,  this  feature  is  for  you. 

Integrated  Development  Environment 

The  cornerstone  of  the  integrated  envi¬ 
ronment  is,  of  course,  the  editor.  Out 
of  the  box,  TopSpeed’s  editor  is  config¬ 
ured  to  use  the  WordStar  command 
set.  You  can  change  part  or  all  of  that 
hy  editing  a  configuration  file. 

Actually,  the  TopSpeed  configura¬ 
tion  file  TSCFG.TXT  affords  the  user 
quite  a  bit  of  control  over  not  just  the 
editor  but  the  TopSpeed  environment 
in  general.  The  file  is  a  33K  ASCII  text 
file  that  defines  the  menu  structure, 
every  menu  option,  the  editor  com¬ 
mands,  and  even  compilation  error  mes¬ 
sages  used  by  the  TopSpeed  system. 
This  is  the  file  you  edit  if  you  want  to 
make  the  environment  editor  act  more 
like,  say,  Brief  than  WordStar.  A  disk 
file  explains  how  to  make  the  changes, 
and  after  only  a  few  minutes,  I  was 
able  to  change  the  main  menu  format 
from  vertical  to  horizontal  and  to  de¬ 
fine  the  Ctrl-FlO  keychord  as  a  way  to 
directly  access  the  optimization  menu. 
While  there  are  many  things  you  can 
change,  there  are  others  (such  as  an 
inability  to  extend  the  undo  feature 
past  one  event)  you  have  no  control 
over.  Once  you’ve  finished  making 
changes,  you  can  incorporate  them  into 
the  TopSpeed  environment  by  running 
the  TSCFG.EXE  program. 

Although  the  editor  handles  up  to 
ten  windows  (0-9),  you’d  normally 
edit  in  windows  #1  through  #9,  be¬ 
cause  window  #0  is  a  special  window, 
called  the  “error  editor  window.”  This 
window  comes  into  play  after  errors 
and  warnings  are  found  during  compila¬ 
tion  of  a  source  file.  The  flawed  file  is 
displayed  in  this  window  with  the  cur¬ 
sor  positioned  at  the  first  error,  and  the 
corresponding  error  message  appears 
at  the  bottom  of  the  window.  Pressing 
F8  moves  you  forward  to  the  location 
of  the  next  error;  F7,  back  to  the  previ¬ 
ous  one. 

When  you  exit  from  the  TopSpeed 
environment,  the  system  remembers  the 
contents  and  status  of  each  window 
and  reloads  the  same  files  the  next  time 
you  enter  the  environment.  You  can 
alternatively  start  with  a  “clean  slate” 
by  supplying  the  /n  option  on  the  com¬ 
mand  line.  Another  nice  touch  is  a 
prompt  reminding  you  to  save  your 
work  when  you  call  up  the  source- 
level  visual  interactive  debugger  (VID) 
from  the  TopSpeed  menu. 


There  are  a  number  of  useful  op¬ 
tions  available  under  the  Utilities  menu, 
including  an  ASCII  table,  a  program¬ 
mer’s  calculator  that  works  in  decimal, 
hex,  or  binary,  and  a  window  that  lets 
you  see  the  scan  codes  for  keyboard 
keys.  There  is  a  multiple-file  string 
search  capability  that  works  a  bit  such 
as  grep ,  albeit  without  the  powerful 
regular  expression  capabilities  of  that 
Unix  utility.  Other  options  include  the 
ability  to  print  files,  to  view  files  as  data 
(that  is,  in  hex),  and  to  display  system 
information.  “System  Info”  shows  the 
current  date,  time,  and  directory,  the 
names  of  the  files  being  edited  in  the 
TopSpeed  windows,  and  a  summary 
of  free  space  on  all  disks.  Be  prepared 
to  wait  for  this  report  if  you  have  a 
CD-ROM  disk  attached  to  your  system, 
for  even  though  there  is  no  “free  space” 
available  on  a  CD-ROM,  there  is  no  way 
to  tell  TopSpeed  to  ignore  the  drive, 
which  gets  interrogated  in  turn  along 
with  the  other  drives  in  your  system. 

There  are  a  number  of  other  features 
I  found  useful  in  this  environment,  too 
many  in  fact  to  list.  Particularly  note¬ 
worthy  to  me,  however,  are  the  ability 
to  have  up  to  nine  generations  of 
backup  copies  (I  have  mine  set  to  3), 
and  the  ability  to  record,  load,  save, 
and  playback  keystroke  macros.  The 
instructions  for  recording  a  macro  were 
clear,  and  it  took  only  a  couple  of 
minutes  for  me  to  create  a  macro  that 
toggled  all  optimization  on  and  off. 
About  the  only  criticism  I  have  of  the 
editing  environment  is  the  lack  of  mouse 
support  and  the  lack  of  Unix-style  regu¬ 
lar  expression  parsing  (as  in  Brief,  for 
example),  but  those  are  relatively  mi¬ 
nor  annoyances. 

Compiling 

While  the  editor  and  its  features  form 
an  important  part  of  the  TopSpeed  C 
package,  you  can’t  forget  that  this  is, 
after  all,  a  C  compiler,  and  the  worth 
of  the  package  ultimately  hinges  on 
how  well  it  compiles  code. 

To  help  put  TopSpeed  C  through  its 
paces,  I  worked  with  a  file  that  had 
been  written  in  Microsoft  C  for  a  fairly 
simple-minded  game  of  deduction.  The 
playing  “field”  for  this  game  is  a  9  x  15 
grid  that  contains  some  number  of  hid¬ 
den  mines,  and  the  player  uses  the 
numeric  keypad  to  “walk”  a  happy- 
face  character  through  this  mine  field 
to  a  goal.  To  give  the  player  a  fighting 
chance,  the  number  of  mines  in  adja¬ 
cent  squares  is  displayed  as  the  player 
moves  from  square  to  square,  thus  al¬ 
lowing  the  player  to  deduce  the  loca¬ 
tion  of  the  mines  without  “stepping” 
on  them.  To  make  life  easier,  the  loca¬ 
tion  of  mines  may  be  marked  by  press¬ 


ing  M  and  an  appropriate  key  on  the 
numeric  keypad.  In  addition,  if  an  /s 
parameter  is  passed  on  the  command 
line  when  the  program  is  invoked,  the 
program  won’t  let  the  player  step  on 
such  marked  squares.  Finally,  typing  ? 
at  the  start  of  the  game  causes  the 
program  to  start  playing  by  itself  until 
it  either  gets  to  the  goal  or  is  unable  to 
proceed  further  through  the  grid.  Aside 
from  being  fun  to  play,  the  file 
KABOOOOM.C  (see  Listing  One,  page 
109)  is  just  under  1000  lines  in  length 
and  offers  a  substantial  chunk  of  source 
code  for  the  compiler  to  process. 

The  first  attempt  to  compile  the  code 
resulted  in  a  couple  of  errors.  The  first 
error,  in  the  function  DisplayCell ,  had 
to  do  with  a  failure  to  read  an  embed¬ 
ded  ASCII  2  (the  happy-face)  in  the 
source  code.  The  TopSpeed  editor  did 
not  read  this  character,  resulting  in  the 
assignment  Char  =  and  a  subse¬ 
quent  error.  Changing  the  line  to  Char 
=  2;  fixed  the  problem. 

The  second  error  came  in  a  line  of 
the  DisplayChar  function,  which  read: 
FP_SEG(cPos)  =  OxObOOO; 

While  a  legitimate  statement  in  Mi¬ 
crosoft  C,  this  use  of  FP_SEG( )  gener¬ 
ated  a  “left  operand  of  assignment  must 
be  a  modifiable  lvalue”  error  message 
from  the  TopSpeed  compiler.  Pressing 
FI  for  help  brought  up  an  explanation 
of  the  message,  which  is  comfortably 
verbose  as  it  is.  I  moved  off  the  offend¬ 
ing  line  and  again  pressed  FI,  and 
shortly  was  reading  the  help  screen 
associated  with  FP_SEG(  ).  It  referred 
me  to  MK_FP(  ),  which  permitted  me 
to  replace  the  offending  line  (and  the 
line  after  it)  with:  cPos  =  MK_FP( 
0x0b800,  ((x + y*80)  «  1));  which  elimi¬ 
nated  the  problem.  A  quick  check 
showed  that  Turbo  C  2.0  also  required 
the  MK_FP(  )  syntax  in  order  to  com¬ 
pile  without  error.  I  later  learned  that 
the  FP_SEG  macro  is  defined  differ¬ 
ently  for  the  Microsoft  and  TopSpeed 
compilers,  which  explains  the  failure 
to  compile. 

Once  the  bugs  were  corrected,  the 
initial  compilation  pass  with  TopSpeed 
C  took  about  13  seconds  on  my  16- 
MHz  ARC  386i  computer,  and  optimi¬ 
zation  took  another  18  seconds  or  so. 
With  all  optimizations  turned  off  (there 
are  nine  forms  of  optimization,  includ¬ 
ing  optimization  for  time  and  space  as 
well  as  constant,  jump,  peephole,  loop, 
and  alias  optimization),  the  compile 
time  was  cut  down  to  28  seconds  over¬ 
all.  This  compared  favorably  with  a  run 
through  Microsoft  C  5.1,  which  took 
37  seconds  to  compile  without  optimi¬ 
zation,  yet  was  slower  than  Turbo  C 
2.0,  which  compiled  and  linked  the 
program  in  about  13  seconds. 
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I  ran  the  compiler  from  within  the 
editing  environment,  but  you  can  also 
run  TopSpeed  C  from  the  command 
line,  where  a  comprehensive  set  of  com¬ 
mand-line  options  give  the  programer 
complete  control  of  compilation  and 
linking.  In  fact,  there  are  four  ways  to 
set  compiler  options  in  the  TopSpeed 
C  compiler:  From  a  menu,  from  the 
command  line,  via  directives  in 
TopSpeed’s  make  facility,  and  by  in¬ 
cluding  pragmas  in  the  source  code. 

One  very  topical  option  in  the  com¬ 
piler  is  the  ability  to  check  for  ANSI 
compatibility.  JPI  has  made  a  point  of 
maintaining  100  percent  conformance 
to  the  ANSI  C  definition,  and  now  that 
the  seemingly  interminable  deliberations 
of  the  ANSI  C  committee  have  appar¬ 
ently  come  to  a  close,  this  feature  should 
be  a  point  in  TopSpeed  C’s  favor. 

Making  it  With  Project  Files 

TopSpeed’s  project  files  make  it  easy 
to  admit  to  hating  traditional  make  pro¬ 
grams.  Like  its  traditional  counterpart, 
TopSpeed’s  Make  uses  a  text  file  (called 
a  “project  file”)  to  figure  out  what  kind 
of  file  to  produce  with  what  objects 
and  libraries,  and  using  which  memory 
model.  Project  files  are  collections  of 
“directives"  that,  in  addition  to  the  usual 
specification  of  object  modules,  librar¬ 
ies,  and  so  on,  establish  various  com¬ 
piler  and  linker  options  (such  as  inclu¬ 
sion  of  debugger  information  in  the 
.EXE  file),  override  options  for  specific 
files  or  groups  of  files,  and  specify  what 
programs  to  run  (if  any)  after  the  make 
process  is  complete.  You  could,  for 
example,  copy  the  .EXE  file  to  a  disk¬ 
ette  every  time  you  compiled  and  linked 
the  source  code.  In  short,  the  project 
file  is  the  mechanism  by  which 
TopSpeed  source  code  is  transformed 
into  executable  files. 

Two  valuable  features  aid  in  the  link 
process.  Type-safe  linking  involves  catch¬ 
ing  function  calls  made  with  the  wrong 
parameter  types.  You  will  bless  this 
feature  the  first  time  it  saves  you  from 
calling  an  external  function  with  the 
wrong  parameter  types.  The  technique 
of  smart  linking  helps  keep  executable 
file  size  down  and  reduces  the  com¬ 
plexity  associated  with  maintaining  li¬ 
braries.  When  you  link  a  program, 
TopSpeed  will  only  include  those  rou¬ 
tines  that  are  referenced  in  the  code, 
leaving  all  the  other  routines  out  of  the 
executable  file.  Strangely  enough,  this 
means  that  sometimes  you  must  make 
an  extraneous  reference  to  a  variable 
in  order  to  make  sure  certain  routines 
are  linked  into  the  .EXE  file.  A  case  in 
point  is  the  need  to  include  a  line  in- 
cludePMD  =  1;  in  one  of  the  functions 
that  handles  critical  program  errors  so 


that  TopSpeed  loads  the  appropriate 
routines  to  perform  a  post-mortem 
dump  in  case  the  program  bombs. 

Debugging 

The  VID  is  a  full  source-level  symbolic 
debugger  that  uses  overlapping  win¬ 
dows  in  an  interactive  environment. 
Like  the  parent  TopSpeed  environment, 
there  is  no  mouse  support  in  VID. 

VID  is  easy  to  run  from  the  TopSpeed 
environment,  which  wisely  prompts  you 
to  save  your  files  before  it  swaps  itself 
to  disk,  leaving  room  for  your  program 
and  VID.  To  use  VID,  you  need  to 
generate  VID  information  during  com¬ 
pilation  and  a  .MAP  file  during  the  link 
process.  All  required  files  are  found 
using  the  redirection  file,  if  necessary. 

All  the  usual  debugging  features  are 
here.  You  can  set  and  clear  breakpoints, 
create  “sticky”  breakpoints,  examine 
different  types  of  variables,  find  proce¬ 
dures,  evaluate  expressions,  all  the  usual 
stuff.  While  not  as  powerful  as,  say,  the 
Borland  Turbo  Debugger  (there  is  no 
equivalent  to  the  Inspect  command, 
for  example,  which  shows  record  struc¬ 
ture,  or  the  CPU  window,  which  shows 
registers,  memory,  and  disassembled 
code  all  at  once)  the  VID  is  neverthe¬ 
less  a  competent  piece  of  software  that 
is  able  to  do  the  job. 

TechKit 

The  TechKit  is  what  distinguishes  the 
Extended  Edition  ($395  list  price)  from 
the  Standard  Edition  ($195)  of  TopSpeed 
C.  What  you  get  for  your  money  is  a 
collection  of  programs,  files,  and  utili¬ 
ties  that  add  functionality  to  TopSpeed 
C.  It  includes  support  for  Windows  pro¬ 
gramming  and  dynamic  link  libraries 
(DLLs),  including  DLLs  that  can  be  used 
under  DOS.  (A  DLL  is  an  OS/2  innova¬ 
tion  that  allows  applications  to  share 
common  data  and  code  by  linking  li¬ 
brary  routines  at  run  time.) 

A  major  piece  of  the  Techkit  is  the 
source  code  to  the  TopSpeed  libraries. 
This  collection  of  files  fills  over  1.5 
Mbytes  of  disk  space.  The  code  is  de¬ 
signed  not  only  for  use  by  TopSpeed 
C,  but  also  for  use  with  other  TopSpeed 
languages.  Many  of  the  files  are  written 
in  TopSpeed’s  assembler  language, 
which  makes  for  speedy  routines,  but 
also  requires  you  to  learn  a  new  dialect 
of  assembler. 

The  TopSpeed  Assembler  attempts 
to  gain  in  simplicity  and  speed  by  deviat¬ 
ing  from  “standard”  8086  assemblers 
in  several  ways.  For  example,  the  lexi¬ 
cal  structure  of  the  assembler  is  de¬ 
rived  from  Modula-2,  memory  oper¬ 
ands  and  segment  overrides  must  al¬ 
ways  be  explicitly  stated,  and  there  are 
no  macros  used  in  the  language.  While 
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I  can  understand  JPI’s  reason  for  doing 
it  this  way,  I  don’t  look  forward  to 
becoming  familiar  with  yet  another  as¬ 
sembler  scheme. 

An  interesting  utility  included  in  the 
TechKit  is  WATCH,  which  lets  you  spec¬ 
ify  groups  or  individual  DOS  functions 
to  monitor  during  program  execution. 
I  ran  the  program  and  specified  the 
date/time  functions  for  monitoring,  with 
output  to  be  sent  to  my  printer  (as 
opposed  to  the  screen  or  disk  file). 
When  I  ran  KABOOOOM.EXE,  a  brief 
report  was  sent  to  the  printer  when  the 
program  called  DOS  to  get  the  time 
during  the  initialization  phase.  The  Alt- 
backspace  keychord  toggles  WATCH 
on  and  off,  and  in  order  to  change  the 
scope  of  the  DOS  functions  monitored, 
I  found  it  necessary  to  unload  WATCH 
and  then  reload  it  from  scratch.  (If  you 
send  WATCH’S  output  to  the  screen, 
however,  you  are  able  to  interact  more 
with  the  program  [setting  and  clearing 
functions  to  monitor],  albeit  at  the  ex¬ 
pense  of  interfering  greatly  with  the 
screen.)  WATCH,  of  course,  will  not 
work  if  the  program  it  is  monitoring 
does  not  use  DOS  to  accomplish  its 
ends. 

Other  pieces  of  the  TechKit  aid  in 
the  debug  and  streamline  process.  The 
post-mortem  debugger  was  undoubt¬ 
edly  created  for  those  who’ve  wished 


their  bug-ridden  programs  could  leave 
some  indication  behind  them  of  what 
went  wrong  before  they  exit  to  never- 
never  land.  This  feature  is  set  by  in¬ 
cluding  the  PMD.H  file  and  referencing 
the  includePMD  variable  in  the  source 
code.  Should  anything  go  wrong  and 
a  critical  error  function  is  called,  your 
program  creates  a  file  that  details  the 
state  of  the  system  just  before  lights 
out.  This  file  can  be  examined  using 
the  VID. 

I’ve  always  gritted  my  teeth  when 
sitting  down  to  work  with  a  profiler, 
but  I  found  the  TopSpeed  TSPROF  pro¬ 
filer  easy  to  use.  All  you  need  to  use 
TSPROF  is  a  .MAP  file,  which  is  created 
when  the  program  is  made.  I  ran  the 
profiler  for  KABOOOOM  and  found 
that  over  half  the  program’s  time  is 
spent  executing  DOS  routines,  nearly 
half  the  program’s  time  is  spent  in  the 
BIOS,  and  only  three  percent  or  so  of 
the  time  is  in  the  code. 

Conclusion 

Working  with  the  TopSpeed  C  com¬ 
piler  was  a  wholly  pleasant  experience. 
The  advantage  of  having  the  file  redi¬ 
rection  and  project  file  features  are  alone 
almost  worth  the  price  of  admission, 
and  the  overall  flexibility  of  the  system 
is  a  big  plus.  Though  it  remains  to  be 
seen  whether  JPI  will  be  able  to  suc¬ 


cessfully  market  the  idea  of  a  common 
programming  environment  with  plug-in 
language  modules,  TopSpeed  C  certainly 
deserves  to  be  a  contender  in  the  fight 
for  a  share  of  the  C  compiler  market. 
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Neural  Networks  and 
Image  Processing 


Finding  edges  only  a  human  can  see 


Casimir  C.  "Casey"  Klimasauskas 


One  of  the  key  problems  fac¬ 
ing  the  machine  vision  in¬ 
dustry  is  how  to  detect  spe¬ 
cific  features  in  an  image.  It 
turns  out  that  even  finding  a 
simple  feature  such  as  an  edge  can  be 
difficult,  if  not  impossible.  Even  though 
a  person  looking  at  a  video  camera 
image  on  a  monitor  can  readily  see  the 
boundary  between  two  objects,  it  may 
not  be  so  easy  to  find  it  with  an  algo¬ 
rithm.  Researchers  studying  how  the 
eye  preprocesses  information  for  the 
brain  use  the  term  “early  vision”  for  the 
function  of  the  eye  that  assists  in  pat¬ 
tern  recognition.  We  can  use  insights 
from  research  in  early  vision  to  solve 
the  problem  of  edge  detection  by  com¬ 
puter. 

This  article  presents  an  engineering 
approximation  of  early  vision,  written 
from  the  perspective  of  an  engineer 
investigating  useful  applications  of  neu- 
rally  inspired  technology.  Although  the 
techniques  discussed  here  were  sug¬ 
gested  by  the  processes  of  the  human 
eye,  they  are  not  intended  to  be  bio¬ 
logically  accurate,  nor  is  the  solution 
intended  to  be  biologically  plausible. 
The  architecture  of  the  edge  detection 
system  presented  here  is  the  empirical 
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result  of  exploring  many  blind  alleys 
and  dead  ends.  For  this  reason,  some 
of  the  assumptions  and  function  values 
used  here  may  seem  somewhat  arbi¬ 
trary.  Their  only  justification  is  that  they 
worked. 

The  edge  enhancement  system  pre¬ 
sented  here  can  be  implemented  in 
various  ways,  using  different  technolo¬ 
gies.  This  article  presents  two  imple¬ 
mentations  in  software  (one  using  the 
C  language  and  the  other  using  Lotus 
1-2-3)  and  also  describes  a  third  im¬ 
plementation  using  commercially  avail¬ 
able  image  processing  hardware  and 
software. 


Figure  1:  Effect  of  a  processing  ele¬ 
ment  on  its  neighbors.  A  “+  ”  near  a 
processing  element  indicates  that  the 
center  processing  element  in  the  dia¬ 
gram  will  excite  it  if  it  is  excited.  A 
near  a  processing  element  indicates  it 
will  be  inhibited  if  the  center  process¬ 
ing  element  is  excited 


A  Logical  Edge  Enhancement  Model 

You  might  think  of  the  receptive  sur¬ 
face  of  the  eye  as  an  array  or  grid  of 
photoreceptive  elements.  Light  from  the 
outside  world  impinges  on  this  photo¬ 
receptive  array  and  provokes  output 
from  each  of  the  array  elements.  The 
output  of  each  of  these  photoreceptors 
is  passed  on  to  another  layer  of  corre¬ 
sponding  neurons  that  work  together 
to  enhance  the  image. 

For  purposes  of  this  article,  we  will 
call  our  two-layer  network  the  edge 
enhancement  system  (EES).  Figure  1 
shows  the  effect  of  one  of  the  EES 
processing  elements.  The  connections 
are  shown  only  from  the  processing 
element  in  the  center  of  the  array.  This 
processing  element  excites  its  nearest 
neighbors  (shown  by  “+”  near  the  pro¬ 
cessing  elements)  and  inhibits  those  a 
little  further  away  (shown  by  “  -  ”  near 
the  processing  elements).  The  actual 
strength  of  the  excitation  or  inhibition, 
as  a  function  of  distance  from  the  cen¬ 
ter,  is  shown  in  Figure  2.  When  plotted 
in  three-dimensions,  with  the  magni¬ 
tude  of  the  excitation  or  inhibition  as 
the  Z-axis,  the  resulting  shape  looks 
like  a  Mexican  hat.  For  this  reason,  it 
is  sometimes  called  a  “Mexican  hat  func¬ 
tion”  (MHF)  or  “on-center  off-surround.” 
The  effect  of  the  Mexican  hat  function 
is  similar  to  that  of  a  standard  image 
processing  filter  known  as  a  “differ¬ 
ence  of  Gaussians.” 

The  connections  are  shown  only  for 
the  center  processing  element  in  Fig¬ 
ure  1,  all  the  other  processing  elements 
are  connected  in  a  similar  fashion. 
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The  EES  processing  element  (shown 
in  Figure  3)  computes  an  internal  acti¬ 
vation  value  by  computing  the  weighted 
sum  of  the  outputs  of  its  neighbors  and 
the  weights  connecting  them.  This  in¬ 
ternal  activation  value  is  then  trans¬ 
formed  by  a  nonlinear  transfer  func¬ 
tion  (such  as  the  clamped  linear  one 
shown)  to  produce  an  actual  output. 
The  clamped  linear  transfer  function 
was  found  to  work  best  after  sigmoid 
and  hyperbolic  tangent  transfer  func¬ 
tions  were  tried  and  found  not  to  work. 
Notice  that  the  current  output  of  a  pro¬ 
cessing  element  is  fed  back  onto  itself 
as  part  of  the  input  for  computing  its 
internal  activation. 

Readers  familiar  with  neural-network 
types  will  recognize  the  EES  array  of 
processing  elements  described  as  a  kind 
of  feedback  neural  net,  (similar  to  a 
Hopfield  network,  but  with  a  fixed  pat¬ 
tern  of  inter-connections).  The  connec¬ 
tions  are  such  that  each  processing  ele¬ 
ment  is  trying  to  decide  if  it  is  on  an 
edge  or  not.  When  this  constraint  is 
satisfied,  the  processing  elements  reach 
a  stable  output  state. 

In  operation,  the  outputs  of  the  re¬ 


ceptor  array  are  passed  on  to  the  EES. 
The  initial  values  of  each  of  the  ele¬ 
ments  in  the  EES  are  equal  to  their 
corresponding  values  in  the  receptor 
array.  After  initialization,  the  EES  goes 
through  several  iterations.  During  each 
iteration  the  processing  elements  ob¬ 
tain  inputs  from  their  neighbors  (either 
excitatory  or  inhibitory)  as  well  as  from 
their  current  state.  From  these  inputs, 
they  compute  a  new  output  transformed 
through  some  nonlinear  function.  In 
the  eye,  these  processes  evolve  as  a 
dynamical  system  obeying  a  set  of  con¬ 
tinuous  differential  equations  defined 
by  the  synapses  connecting  them. 

An  EES  Engineering  Approximation 

To  develop  a  good  engineering  ap¬ 
proximation,  we  need  to  be  able  to 
implement  the  EES  inexpensively  and 
efficiently.  This  section  looks  at  tech¬ 
niques  for  accomplishing  this  with  read¬ 
ily  available  off-the-shelf  image  pro¬ 
cessing  hardware  and  software.  The 
two  principal  image  processing  tech¬ 
niques  discussed  here  are  convolution 
and  look-up  tables. 

Convolution  is  a  common  and  pow¬ 


erful  technique  for  filtering  images.  Very 
simply,  a  convolution  is  a  specially  de¬ 
signed  matrix  (or  filter)  that  is  com¬ 
bined  together  with  a  portion  of  an 
image  to  compute  a  transformed  pixel 
value.  The  filter  is  centered  at  each 
pixel  in  the  initial  image  and  the  “con¬ 
volution”  of  the  filter  and  the  image 
beneath  it  is  computed.  The  result  is 
the  transformed  value  of  the  center 
pixel.  The  matrix  is  then  moved  one 
pixel  to  the  right  and  the  transformed 
value  of  the  next  pixel  is  computed. 
When  the  filter  has  been  applied,  cen¬ 
tered  at  each  pixel  in  the  initial  image, 
the  resulting  transformed  image  is  com¬ 
plete.  This  is  shown  in  Figure  4. 

The  convolution  of  filter  and  image 
is  arrived  at  by  computing  the  pair¬ 
wise  product  of  corresponding  elements 
of  the  filter  and  the  underlying  portion 
of  the  image  and  summing  them  to¬ 
gether.  Notice  that  this  is  the  same  as 
computing  the  internal  activation  of  the 
EES  processing  element  shown  in  Fig¬ 
ure  3.  This  means  we  can  implement 
the  EES  neural  net  by  using  standard 
image  processing  hardware  that  sup¬ 
ports  convolution. 


Excitation 


Figure  2:  Impact  of  a  processing  element  on  its  neighbors. 
As  the  distance  from  the  processing  element  in  the  center  of 
the  diagram  increases,  it  excites  its  nearest  neighbors.  As  the 
distance  increases,  the  excitation  turns  to  inhibition,  and 
finally  all  effects  cease.  This  curve  is  sometimes  called  a 
“Mexican  Hat  Function’’  or  “Difference  of  Gaussians’’ 


Figure  4:  Operation  of  a  two-dimensional  convolution.  The 
3  x  3  filter  is  laid  over  the  initial  image,  centered  at  a 
particular  pixel.  The  value  of  the  matrix  is  multiplied  by  the 
pixel  value  just  beneath  it.  The  result  of  these  pair-wise 
products  are  summed  together  to  form  the  transformed  pixel 
value  in  the  transformed  image 


Figure  3:  Details  of  a  single-processing  element  in  the  Edge 
Enhancement  System.  The  “+”  symbols  indicate  that  the 
input  will  be  excitatory.  The  ”  symbols  indicate  that  the 
input  will  be  inhibitory 


Figure  5:  Hardware  block  diagram  of  an  image  processing 
system  adapted  to  be  used  to  implement  the  Edge  Enhance¬ 
ment  System.  The  basic  building  blocks  are  a  pair  of  frame 
buffers,  a  convolver,  and  a  look-up  table  for  performing 
nonlinear  transformations 
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Image  filtering  by  use  of  convolu¬ 
tions  is  one  of  the  cornerstones  of  ma¬ 
chine  vision.  By  properly  selecting  the 
coefficients  of  the  filter,  you  can  detect 
edges,  create  high-  or  low-pass  filters, 
grow  or  shrink  light  regions,  and  quite 
a  variety  of  other  functions.  You’ll  find 
more  information  on  digital  image  fil¬ 
tering2  at  the  end  of  this  article.  In 
practice,  implementing  an  edge  detector 
using  a  convolution  filter  is  not  diffi¬ 
cult.  The  problem  that  arises  is  that  of 
finding  good  filter  coefficients,  which 
do  an  effective  job  of  finding  the  edges 
rather  than  losing  or  obscuring  them. 

A  second  commonly  used  technique 
in  image  processing  is  called  a  “look¬ 
up  table.”  Just  as  the  name  implies,  the 
value  of  a  pixel  is  applied  to  the  input 
of  a  look-up  table  (usually  the  address 
lines  of  a  static  RAM  array)  and  a  “trans¬ 
formed”  value  is  produced  at  the  out¬ 
put  (the  contents  of  that  memory  loca¬ 
tion).  The  mapping  function  is  typically 
arbitrary  and  can  be  defined  by  the  user. 

Look-up  tables  are  used  to  enhance 
contrast,  convert  images  to  black  and 
white  (from  gray  or  color),  and  to  pro¬ 
duce  special  effects.  The  Cherry  Coke 
commercials  use  this  to  make  the  can 
of  Cherry  Coke  be  in  color  and  all  else 
black  and  white.  In  our  case,  they  can 
be  used  to  implement  a  clamped  linear 


transfer  function.  To  implement  a 
clamped  linear  transfer  function  in  an 
8-bit  system,  set  the  mapping  RAM  to 
output  zero  whenever  an  input  in  the 
range  0x80  through  Oxff  (negative  val¬ 
ues)  is  applied.  For  locations  0x00 
through  0x7f,  set  the  mapping  RAM  to 
output  the  same  value  as  the  input. 

Implementing  the  EES 

Both  the  convolution  and  look-up  ta¬ 
ble  techniques  are  such  common  tools 
that  both  are  included  in  most  com¬ 
mercial  image  processing  systems.  To¬ 
gether  with  a  pair  of  frame  buffers  (also 
common),  we  can  actually  implement 
a  very  fast  and  moderately  priced  edge 
enhancement  system.  Companies  that 
supply  suitable  hardware  and  software 
include  Imaging  Technologies  (ITT),  Da- 
taCube,  Data  Translation,  and  Matrox. 

A  block  diagram  of  the  hardware  to 
implement  the  EES  is  shown  in  Figure 
5.  To  set  up  the  system,  we  load  the 
block  shown  as  “Filter  Coefficients” 
with  the  coefficients  from  the  MHF, 
and  the  look-up  table  “Transfer  Func¬ 
tion”  with  the  values  for  a  clamped 
linear  transfer  function;  7  x  7  is  the 
minimum-sized  convolution  to  use  for 
the  MHF.  Some  of  the  systems  men¬ 
tioned  also  support  9x9  and  larger 
convolutions. 


The  sequence  of  processing  is  as 
follows: 

1.  Acquire  an  image  from  the  camera 
to  frame  buffer  1 . 

2.  Transform  frame  buffer  1  to  frame 
buffer  2  using  the  MHF  filter  and 
clamped  linear  look-up  table  map 
function. 

3.  Transform  frame  buffer  2  to  frame 
buffer  1  using  the  Mexican  hat  func¬ 
tion  filter  and  clamped  linear  look¬ 
up  table  map  function. 

4.  Repeat  steps  2  and  3  as  many  times 
as  desired. 

Because  most  systems  are  designed 
to  work  with  small  integers,  it  will  be 
necessary  to  make  the  appropriate  trans¬ 
lations.  This  is  an  example  of  how  neural- 
network  technology  can  be  grafted  into 
existing  technology  to  enhance  its  per¬ 
formance.  With  a  little  thought,  it  is 
possible  to  apply  similar  techniques  to 
a  variety  of  other  problems. 

Software  Implementations  of  EES 

When  I  began  doing  research  on  these 
filters  for  a  project  we  are  working  on, 
I  wanted  something  that  would  be  easy 
to  work  with,  and  I  could  quickly  try 
out  a  variety  of  parameters.  After  a  little 
thought,  I  decided  to  try  out  my  new 
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copy  of  Lotus  1-2-3.  The  spreadsheet 
instance  described  in  this  section  is  the 
result  of  those  efforts.  Though  I  used 
Lotus  1-2-3,  Release  3  0,  it  should  be 
possible  to  implement  this  with  most 
spreadsheet  packages  and  computers 
that  support  a  graphing  option. 

As  it  turns  out,  a  variety  of  other 
techniques  could  have  also  been. used 
to  do  this  research.  Listing  One,  page 
114,  shows  a  C  program  that  imple¬ 
ments  the  same  functions  as  the  spread¬ 
sheet,  but  without  the  nice  graphics  or 
ability  to  change  data  as  easily  as  with 
the  spreadsheet.  Both  the  C  language 
implementation  and  the  spreadsheet 
implementation  deal  with  the  more  lim¬ 
ited  problem  of  a  one-dimensional  data 
stream  rather  than  the  two-dimensional 
image  processing  we  have  been  dis¬ 
cussing.  Later  in  this  article,  I’ll  discuss 
how  to  extend  the  one-dimensional 
model  to  two-dimensions. 

Listing  Two,  page  114,  shows  the 
spreadsheet  constructed.  The  numbers 
to  the  right  are  the  row  numbers.  The 
letters  along  the  bottom  represent  the 
column  numbers.  The  Graph  capabil¬ 
ity  of  Lotus  1-2-3  is  used  to  display  the 
results  from  processing  the  one-dimen¬ 
sional  signal  or  data  stream.  Although 
not  every  aspect  of  the  spreadsheet  is 
discussed  here,  the  entire  spreadsheet 
is  available  on-line  or  on  disk  from 
DDJ 

The  first  step  in  constructing  the  spread¬ 
sheet  is  to  set  up  the  “static”  data.  This 
consists  of  all  titles,  the  “Bias”  (cell 
D7),  “Low  Pass  Filter”  (range  C20.  .C28), 
“MHF  Filter”  (range  D20.  .D28),  and 
“Raw  Input  Data”  (range  El6.  .E124). 
Everything  else  in  the  spreadsheet  is 
computed.  This  static  data  is  entered 
exactly  as  shown.  For  the  Raw  Input 
Data,  0.00  represents  “black”  and  1.00 
represents  “white.”  Intermediate  val¬ 
ues  may  be  used.  Be  careful  to  put 
everything  in  the  cell  locations  shown. 
After  the  spreadsheet  is  constructed, 
you  can  move  things  around  to  suit 
your  taste. 

The  calculations  for  the  Low  Pass 
Output  data  are  as  follows,  assuming 
that  you  have  entered  the  static  data  in 
the  rows  and  columns  shown.  Enter 
the  following  equation  in  cell  B20: 

+$C$20*El6+$C$21*E17 

+$C$22*E18+$C$23*E19 

+$C$24*E20+$C$25*E21 

+$C$26*E22+$C$27*E23 

+$C$28*E24 

or  with  Lotus  1-2-3,  Release  3: 

@SUMPRODUCT 

($C$20.  ,$C$28,El6.  .E24) 

Then  replicate  cell  B20  throughout  the 
range  B21.  .B120.  This  column  is  la¬ 


beled  as  “Graph  A”  as  a  reminder  of 
which  graph  range  to  use  to  display  it. 
(Line  14  of  the  spreadsheet.) 

Calculations  for  the  neural-network 
filter  are  done  in  a  single  step.  Com¬ 
pute  the  internal  activation  and  transfer 
function  as  follows: 

@MAX(0.0,@MIN(1.0, 

$D$20*El6+$D$21*E17 

+$D$22*E18+$D$23*E19 

+$D$24*E20+$D$25*E21 

+$D$26*E22+$D$27*E23 

+$D$28*E24-$D$7)) 

or  with  Lottus  1-2-3,  Release  3: 

@MAX(0.0,@MIN(1.0, 

@SUMPRODUCT($D$20.  . 
$D$28,El6.  .E24)-$D$7)) 

Then  replicate  cell  F20  throughout  the 
range  F21.  .M120.  The  @MAX(0,  .  .) 
clamps  the  output  so  it  can  never  go 
below  zero.  @MIN(1,  .  .)  clamps  the 
output  so  it  can  never  go  above  one. 
The  sum  of  the  pair-wise  products  (or 
SUMPRODUCT)  computes  the  effect 
of  the  neighborhood  processing  ele¬ 
ments  on  the  current  one,  and  includes 
feedback  of  the  current  state.  The 
-  $D$  7  subtracts  off  the  bias  from  the 
internal  activation. 

The  first  four  and  the  last  four  cells 
in  columns  F  through  M  are  a  copy  of 
the  values  of  the  cells  just  prior  to  them. 
To  replicate  the  values  of  the  top  of  the 
columns,  enter: 

Cell  Fl6:  +F$20 

Then  replicate  it  throughout  the  range 
Fl6.  ,M19.  To  replicate  the  values  at 
the  bottom  of  the  columns,  enter: 

Cell  F121:  +F$120 

Then  replicate  it  throughout  the  range 
F121.  .M124.  The  computation  portion 
of  the  spreadsheet  is  now  complete. 
Use  the  graphing  feature  of  your  spread¬ 
sheet  to  construct  the  graphs  described 
in  Figure  6.  These  two  graphs  will  be 
used  to  display  the  processing  effects 
of  various  types  of  inputs  and  filters 
on  the  output  data. 

Testing  the  Spreadsheet 
Implementation 

Having  constructed  the  spreadsheet  just 
described,  the  graph  EES  should  look 
like  the  one  in  Figure  7a.  Figure  7b  is 
the  same  graph  with  the  input  range 
(Range  B)  reset,  so  it  shows  only  the 
output  of  the  network  as  it  evolves. 
Figure  7c  shows  the  input  data  and  the 
final  (eighth)  iteration  of  the  network 
with  intermediate  ranges  reset  (Ranges 
C,  D,  E). 

The  edge  data  for  this  experiment 


was  selected  to  show  profiles  of  two 
kinds  of  edges  often  found  in  images. 
In  the  first  kind,  light  shines  on  a  curved 
edge  or  rounded  edge  resulting  in  a 
gradation  in  intensities.  The  gradually 
changing  light  intensities  on  the  left 
side  of  the  graph  are  typical  of  this  kind 
of  edge.  The  second  kind  of  edge  is  a 
ragged  edge  such  as  from  torn  metal. 
This  type  shows  wide  variations  in  gray 
level  due  to  specular  reflectivity  as  well 
as  sharp  variations  in  the  curvature  of 
the  material.  This  is  shown  as  the  very 
noisy  edge  on  the  right  of  center  of  the 
diagram.  Notice  that  the  EES  does  a 
very  nice  job  of  sharpening  both  edges. 

To  the  far  right  is  a  small  “blip”  in 
intensities.  This  blip  is  of  the  same  mag¬ 
nitude  as  the  one  in  the  center  of  the 
main  pulse.  Notice  that  the  EES  was 
able  to  pick  this  out,  because  of  its 
contrast  to  the  background,  while  ig¬ 
noring  the  noise  on  the  top  of  the 
pulse.  A  little  experimentation  will  show 
that  this  is  quite  a  powerful  technique. 
The  bias  value  (in  cell  D7)  can  be 
changed  to  alter  the  sensitivity  to  vari¬ 
ous  features.  Changing  the  shape  of 
the  MHF  also  changes  the  nature  of 
edges  detected.  Figure  8  shows  the 
MHF  used  in  the  filter. 

As  it  turns  out,  both  edges  used  in 
this  test  tend  to  be  difficult  to  find 
using  standard  image  processing  tech¬ 
niques.  Figure  9  shows  what  happens 
when  a  simple  sobel  operator  is  ap¬ 
plied  to  the  input.  The  resulting  de¬ 
rivative  function  does  not  provide  much 
information  about  where  the  edges 
might  be.  The  problem  is  not  that  such 
a  filter  is  difficult  to  implement,  but 
that  finding  a  set  of  coefficients  and  a 
filter  length,  which  enhances  the  edges 
rather  than  missing  or  obscuring  them, 
is  a  highly  heuristic  and  often  frustrat¬ 
ing  task.  My  own  experience  is  that  it 
is  sometimes  impossible. 

There  are  a  variety  of  experiments 
you  can  do  with  the  edge  enhance¬ 
ment  system.  One  of  the  things  you 


EES  (Edge  Enhancement  System): 

Format:  Lines  only 

Graph 

Range 

Contents 

B 

E16.  -E124 

input  data 

C 

F16.  .FI 24 

1st  iteration 

D 

H16.  .H124 

3nd  iteration 

E 

J16.  J124 

5th  iteration 

F 

Ml  6.  .M124 

8th  iteration 

HIGHPASS  (High  Pass  Filter): 

Format:  Lines  only 

Graph 

Range 

Contents 

A 

B20.  .B120 

Low-pass  filtered  data 

B 

E20.  .E120 

input  data 

Figure  6:  Constructing  the  gi'apbs 
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will  discover  is  that  the  system  can  be  based  on  biological  insights.  It  was  de¬ 
sensitive  to  the  shape  of  the  MHF  as  veloped  heuristically  starting  with  a  bio¬ 
well  as  the  bias.  In  some  ranges,  the  logical  model  and  studying  it  until  the 

detected  edges  actually  set  up  standing  mechanics  of  its  operation  were  well 

waves,  which  emanate  out  from  the  understood.  As  such,  there  is  no  formal 

edges!  theory  of  operation. 

Functionally  what  happens  is  that 
How  It  Works  the  MHF  acts  as  a  difference  of  Gaus- 

As  I  mentioned  at  the  beginning  of  this  sians  filter.  The  transfer  function  clips 

article,  the  EES  is  an  engineering  ap-  the  negative  part  of  the  output,  leaving 

proach  to  image  or  signal  processing  only  the  positive  center  peak  when  the 


Figure  7a:  Output  of  graph  EES  of  the  Edge  Enhancement  System  spreadsheet. 
The  inputs ,  as  well  as  the  network  outputs  after  1,  3,  5,  and  8  iterations,  are 
shown  super-imposed 


Figure  7b:  Output  of  the  network  as  it  evolves.  This  shows  only  the  network, 
outputs  after  1,  3,  5,  and  8  iterations 
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Figure  7c:  The  original  input  to  the  network,  and  the  output  after  eight 
iterations  are  shown  super-imposed 


Figure  8:  The  Mexican  Hat  Function  used  in  the  Edge  Enhancement  System 


Figure  9:  Results  of  applying  a  sobel  (simple  edge  detection)  filter  to  the  input 
data.  The  sobel  computes  the  derivative  of  the  image 


filter  is  directly  over  the  edge.  When 
the  MHF  is  applied  again  to  the  result¬ 
ing  output,  it  will  tend  to  enhance  sin¬ 
gle  peaks  but  reduce  plateaus.  As  such, 
lots  of  noise  in  the  vicinity  of  an  edge 
will  be  ignored.  However,  a  single  sub¬ 
stantial  variation  against  a  constant  back¬ 
ground  will  be  significantly  enhanced. 
Iterating  on  this  process  eventually  re¬ 
sults  in  groups  of  saturated  processing 
elements,  at  most  the  width  of  the  exci¬ 
tatory  part  of  the  MHF.  All  other  pro¬ 
cessing  elements  are  turned  off. 

Extending  the  EES  to  Two-Dimensions 

The  same  principles  used  in  develop¬ 
ing  the  one-dimensional  EES  apply  to 
the  two-dimensional  version.  Instead 
of  using  a  single-dimensional  vector,  a 
two-dimensional  matrix  is  used.  One 
example  of  a  9  x  9  MHF  is  shown  in 
Example  1. 

The  process  of  computing  the  con¬ 
volution  (sum  of  pair-wise  products) 
with  the  corresponding  portion  of  a 
pixel  array  is  the  same.  Likewise,  the 
clamped  linear  transfer  function  uses 
the  same  equation  used  in  the  spread¬ 
sheet.  Implementing  this  on  an  image 
processing  system  will  require  convert¬ 
ing  everything  to  work  with  small  inte¬ 
gers,  but  the  process  is  quite  straight¬ 
forward. 

Summary 

Insights  from  the  operation  of  the  hu¬ 
man  eye  can  be  used  to  build  improved 
image  enhancement  systems,  particu¬ 
larly  edge  enhancement  systems.  The 
basic  mechanisms  involved  are  capable 
of  turning  an  image  (or  one-dimensional 
signal)  with  fuzzy  and  noisy  edges  into 
a  sharp  clean  edge-enhanced  image. 

This  technology  can  enhance  the  so¬ 
lution  of  a  variety  of  problems  includ¬ 
ing  character  recognition,  part  track¬ 
ing,  part  inspection,  printed  circuit  board 
inspection,  ultrasonic  image  interpreta¬ 
tion,  target  recognition,  and  so  on. 
Enough  similarities  exist  with  traditional 
image  processing  techniques  that  these 
neural  networks  can  be  implemented 
with  traditional  image  processing  hard¬ 
ware  and  software  systems. 
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Listing  One  ( Text  begins  on  page  16.) 

1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1  n  1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 

//  BAM.HPP  Provide  vector,  matrix,  vector  pair,  matrix,  BAM  matrix,  and 
//  BAM  system  classes  and  methods  to  implement  BAM  system  concept. 

//  Extended  note: 

//  This  is  an  implementation  of  the  concept  of  Bidirectional 
//  Associative  Memories  as  developed  by  Bart  Kosko  and  others. 

//It  includes  the  extended  concept  introduced  by  Patrick  Simpson 
//of  the  "BAM  System".  Where  reasonable  Simpson's  notation  has  been 
//  been  maintained.  The  presentation  benefits  from  C++  and  OOP,  in  that 
//  (I  believe)  it  is  both  easier  to  understand  than  a  "pseudocode"  version, 

//  yet  more  precise  (in  that  it  works!) 

//  Developed  with  Zortech  C++  Version  2.0  —  Copyright  (c)  Adam  Blum,  1989,90 

#include<stdlib.h> 

#include<io.h> 

#include<stdio.h> 

#include<string.h> 

#include<limits .h> 

#include<ctype . h> 

#include<stream.hpp> 

#define  D(x)  {if  (trace) (x)} 
extern  int  trace; 

//  where  are  Zortech' s  min, max? 

♦define  max(a,b)  (((a)  >  (b) )  ?  (a)  :  (b) ) 

♦define  min(a,b)  (((a)  <  (b) )  ?  (a)  :  (b) ) 

//  will  be  changed  to  much  higher  than  these  values 
const  ROWS=16;  //  number  of  rows  (length  of  first  pattern) 

const  COLS=8;  //  number  of  columns  (length  of  second  pattern) 

const  MAXMATS=10;  //  maximum  number  of  matrices  in  BAM  system 
const  MAXVEC=16;  //  default  size  of  vectors 

class  matrix; 
class  bam_matrix; 
class  vec  { 

friend  class  matrix; 
friend  class  bam_matrix; 
friend  class  bam_system; 
int  n; 
int  *v; 

public: 

//  see  BAM.CPP  for  implementations  of  these 
vec (int  size=MAXVEC, int  val=0) ;  //  constructor 
~vec();  //  destructor 
vecfvec  &vl);  //  copy-initializer 
int  length (); 

vec&  operator3 (const  vec&  vl);  //  vector  assignment 

vec&  operator+ (const  vec4  vl);  //  vector  addition 

vec&  operator+= (const  vec&  vl);  //  vector  additive-assignment 

vec&  operator*3 (int  i);  //  vector  multiply  by  constant 

//  supplied  for  completeness,  but  we  don't  use  this  now 

int  operator* (const  vec&  vl);  //  dot  product 

vec  operator* (int  c) ;  //  multiply  by  constant 

//  vector  transpose  multiply  needs  access  to  v  array 

int  operator33 (const  vecs  vl); 

int&  operator [] (int  x) ; 

friend  istreams  operator» (istreams  s,vec&  v)  ; 
friend  ostream&  operator«  (ostreamS  s,  vec&  v) ; 

};  //vector  class 

class  vecpair; 

class  matrix  { 

protected: 

//  bam_matrix  (a  derived  class)  will  need  to  use  these  members 
//  preferred  to  "friend  class",  since  there  may  be  many  derived 
//  classes  which  need  to  use  this 

int  **m;  //  the  matrix  representation 
int  r,c;  //  number  of  rows  and  columns 

public: 

//  constructors 

matrix (int  n=ROWS,int  p=COLS); 

matrix(const  vec&  vl, const  vec&  v2) ; 

matrix (const  vecpairfi  vp)  ; 

matrix (matrixS  ml);  //  copy-initializer 

'matrix () ; 

int  depth (); 

int  width (); 

matrix&  operator3 (const  matrixS  ml); 
matrixS  operator+ (const  matrixS  ml); 
matrixS  operator+=  (const  matrixS  ml); 
vec  colslice(int  col); 
vec  rowslice(int  row); 

friend  ostreams  operator« (ostreams  s, matrixS  ml); 

};  //  matrix  class 

class  vecpair  { 

friend  class  matrix; 
friend  class  bam_matrix; 
friend  class  bam_system; 

int  flag;  //  flag  signalling  whether  encoding  succeeded 
vec  a; 
vec  b; 

public: 

vecpair(int  n=R0WS,int  p=C0LS) ;  //  constructor 
vecpair (const  vec&  A, const  vec&  B) ; 
vecpair (const  vecpairS  AB) ;  //  copy  initializer 
'vecpair () ; 

vecpairS  operator3 (const  vecpairS  vl); 
int  operator33 (const  vecpair&  vl); 
friend  istreamS  operator» (istream&  s,vecpair&  v) ; 
friend  ostream&  operator« (ostreamS  s,vecpair&  v) ; 
friend  matrix: :matrix (const  vecpair&  vp) ; 

}  ; 

class  bam_matrix:  public  matrix  { 
private: 

int  K;  //  number  of  patterns  stored  in  matrix 
vecpair  *C;  //  actual  pattern  pairs  stored 


int  feedthru (const  vec&A,vec&  B) ; 

int  sigmoid(int  n) ;  //  sigmoid  threshold  function 

public: 

bam_matrix (int  n=R0WS,int  p=C0LS); 

~bam_matrix () ; 

//  but  we  supply  it  with  the  actual  matrix  AIB  (W  is  implied) 

void  encode (const  vecpairS  AB) ;  //  self-ref  version 

//  uncode  only  necessary  for  BAM-system 

void  uncode (const  vecpairS  AB) ;  //  self-ref  version 

vecpair  recall (const  vec&  A) ; 

int  check  (); 

int  check (const  vecpairs  AB) ; 

//  Lyapunov  energy  function:  E=-AWBtranspose 

int  energyfconst  matrixS  ml);  //  Lyapunov  energy  function 

);  //  BAM  matrix 

class  bam_system  { 

bam_matrix  *W[MAXMATS]; 
int  M;  //  number  of  matrices 

public: 

bam_system(int  M=l); 

~bam_system() ; 

void  encode (const  vecpairs  AB) ; 
vecpairs  recall (const  veci  A) ; 

//  train  equiv.  to  Simpson's  encode  of  all  pairs 
void  train(char  *patternf ile) ; 

friend  ostreams  operator« (ostreams  s, bam_system&  b) ; 

);  //  BAM  system  class 

End  Listing  One 

Listing  Two 

/////////////////////////////////////// 

//  BAM.CPP  Provide  vector,  matrix,  vector  pair,  matrix,  BAM  matrix,  and  BAM 
//  system  classes  to  implement  BAM  systems 
//  Extended  note: 

//  This  is  an  implementation  of  the  concept  of  Bidirectional 
//  Associative  Memories  as  developed  by  Bart  Kosko  and  others. 

//  It  includes  the  extended  concept  introduced  by  Patrick  Simpson 
//  of  the  "BAM  System".  Where  reasonable  Simpson's  notation  has  been 
//  been  maintained.  The  presentation  benefits  from  C++  and  OOP,  in  that 
//  (I  believe)  it  is  both  easier  to  understand  than  a  "pseudocode"  version, 

//  yet  more  precise  (in  that  it  works!) 

//  Developed  with  Zortech  C++  Version  2.0  —  Copyright  (c)  1989,90  Adam  Blum 
# inc 1 ude "bam . hpp " 

/////////////////////////////////// 

//  vector  class  member  functions 

vec:: vec (int  size, int  val)  { 
v  =  new  int [size] ; 
n=size; 

for (int  i=0;i<n;i++) 
v[i]=0; 

)  //  constructor 

vec::~vec()  {  delete  v; )  //  destructor 
vec: :vec (vec&  vl)  //  copy-initializer 
{ 

v=new  int[n=vl.n]; 
for (int  i=0;i<n;i++) 
v ( i ] =v 1 . v [ i ] ; 

) 

vec&  vec: : operator3 (const  vec&  vl) 

{ 

delete  v; 

v=new  int  (n=vl.. n]  ; 
for (int  i=0;i<n;i++) 
v(i]=vl . v ( i ] ; 
return  *this; 

I 

vec&  vec: :operator+ (const  vec&  vl) 

{ 

vec  sum(vl.n); 
sum.n=vl .n; 

for (int  i=0;i<vl.n;i++) 

sum . v [ i ] =vl . v [ i ] +v [ i ] ; 
return  sum; 

} 

vec&  vec: :operator+= (const  vec&  vl) 

{ 

for (int  i=0;i<vl.n;i++) 
v [ i ] +=vl . v { i ] ; 
return  *this; 

I 

vec  vec: :operator* (int  c) 

{ 

vec  prod (length () )  ; 
for(int  i=0;i<prod.n;i++) 
prod. v[i]=v[i] *c; 
return  prod; 

} 

int  vec: : operator* (const  vec&  vl)  //  dot -product 

{ 

int  sum=0; 

for(int  i=0;i<min(n,  vl.n) ;i++) 
sum+=(vl.v[i] *v[i] ) ; 

//D (cout  «  "dot  product  "  «  *this  «  vl  «  sum  «  "\n";) 
return  sum; 

) 

int  vec: : operator33 (const  vec&  vl) 

( 

if (vl.n!=n) return  0; 
for(int  i=0; i<min (n, vl .n) ;i++) { 
if (vl.vfi] ! =v [ i] ) { 
return  0; 

} 

} 

return  1; 
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} 

ints  vec :  .-operator  []  (int  x) 

{ 

if (x<length()  &&  x>=0) 
return  v[x]; 

else 

cout  «  "vec  index  out  of  range"; 

1 

int  vec: : length () {return  n; }  //  length  method 

istream&  operator» (istreams  s,vec  &v) 

//  format:  list  of  ints  followed  by 

{ 

char  c; 
v.n=0; 

v. v=new  int [MAXVEC) ; 
for ( ; ; ) { 

s»c; 

if  (s .eof () ) return  s; 
if (c==' ,') return  s; 
if (isspace (c) ) continue; 
v.v[v.n++]=( (c ! =' 0' ) ?1:-1) ; 

) 

) 

ostream&  operator«  (ostreams  s,  vec&  v) 

//  format:  list  of  ints  followed  by  ' , ' 

{ 

for(int  i=0;i<v.n;i++) 

s  «  (v. v [i] <0?0 : 1)  ; 

s  << 

return  s; 

} 

/////////////////////////////// 

//  matrix  member  functions 
matrix: :matrix (int  n,int  p) 

{ 

//D(cout  «  "Constructing  "  «  n  «  "  x  "  «  p  «  "  matrix. \n";) 

m=new  int  *(n]; 

for (int  i=0;i<n;i++) { 

m[i] =new  int [p] ; 
for (int  j=0;j<p;j++) 
m(i] [ j ] =0 ; 

) 

r=n; 

c=p; 

)  //  constructor 

matrix: :matrix (const  vecpairS  vp) 

{ 

//D(cout  «  "Constructing  matrix  from:  "  «  vp;) 

r=vp. a. length () ; 

c=vp.b. length () ; 

m=new  int  * [ r ] ; 

for(int  i=0;i<r;i++) ( 

m[i]=new  int [c] ; 
for (int  j=0;j<c;j++) 

m[i] [j]=vp.a.v(i] *vp.b.v[]) ; 

} 

}//  constructor 

matrix: :matrix (const  vec&  vl, const  vec&  v2) 

{ 

//D(cout  «  "Constructing  matrix  from  "  «  vl  «  v2  «  "\n";) 

r=vl . length () ; 

c=v2. length () ; 

m=new  int  * [ r ] ; 

for(int  i=0;i<r;i++) ( 

m[i]=new  int[cj; 
for (int  j=0;j<c;j++) 

m[i] [ j ] = v 1 . v [ i J *v2.v[ j] ; 

) 

)//  constructor 

matrix: :matrix (matrixS  ml)  //  copy-initializer 

I 

//D(cout  «  "matrix  copy-initializer\n";  ) 

r=ml.r; 

c=ml.c; 

m=new  int  * [ r ] ; 
for(int  i=0;i<r;i++) ( 

m[i]=new  int [c] ; 
for (int  j=0;j<c;j++) 

m[i] [j]=ml.m[i] ( j] ; 

) 

1 

matrix: :~matrix() 

( 

for(int  i=0;i<r;i++) 
delete  m [ i ] ; 
delete  m; 

}  //  destructor 

matrix&  matrix: :operator= (const  matrixS  ml) 

{ 

for (int  i=0;i<r;i++) 
delete  m[i] ; 

r=ml . r; 
c=ml .c; 

m=new  int*[r]; 
for (i=0;i<r;i++) ( 

m[i]=new  int[c]; 
for (int  j=0;j<r;j++) 

m[i] ( j]=ml.m(i] [ j] ; 

} 

return  *this; 

1 

matrixS  matrix: :operator+ (const  matrixS  ml) 

{ 

matrix  sum(r,c); 
for (int  i=0;i<r;i++) 

for (int  j=0;j<r;j++) 

sum.m[i] ( j]=ml.m(i] [ j ] +m ( i J (j); 

(Listing  continued  on  page  86) 
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Listing  Two  (Listing  continued,  text  begins  on  page  16.) 

) 

matrix*  matrix: :operator+= (const  matrix*  ml) 

{ 

//D(cout  «  "matrix  additive  assignment\n"; ) 
for(int  i=0;i<r**i<ml.r;i++j 

for(int  j=0; j<c&& j<ml .c; j++) 

nt[i]  [ j ]  +=  (ml -m [i]  [  j] )  ; 

return  ‘this; 

} 

vec  matrix: icolslice (int  col) 

{ 

vec  temp(r); 

for (int  i=0;i<r;i++) 

temp.v[i]=m[i] [col] ; 
return  temp; 

1 

vec  matrix: : rowslice (int  row) 


vec  temp(c); 

for (int  i=0;i<c;i++) 

temp. v [i] =m[ row] [i] ; 
return  temp? 

) 

int  matrix: : depth () {return  r; } 
int  matrix: : width () {return  c; } 


ostreamS  operator«  (ostream&  s, matrix*  ml) 

//  print  a  matrix 
{ 

for(int  i=0;i<ml.r;i++) { 

for (int  j=0; j<ml .c; j++) 

s  «  ml .  m  ( i  ]  [  j  ]  «  " 
s  «  "\n"; 

) 


} 

////////////////////////////////////////// 

//  vecpair  member  functions 
//  constructor 

vecpair : :vecpair (int  n,int  p)  {  } 

vecpair :: vecpair (const  vec*  A, const  vec*  B)  (a=A;b=B;) 
vecpair: : vecpair (const  vecpair*  AB)  (*this=vecpair (AB.a, AB.b) ; ) 
vecpair: : 'vecpair ()  ()  //  destructor 
vecpair*  vecpair: :operator= (const  vecpair*  vl) 

( 

a=vl .a; 
b=vl .b; 
return  *this; 


) 

int  vecpair : :operator== (const  vecpair*  vl) 

{ 

return  (a  ==  vl.a)  &&  (b  ==  vl.b); 

} 

istream*  operator»  (istream*  s, vecpair*  vl) 
//  input  a  vector  pair 
{ 

s»vl  .a»vl  .b; 
return  s; 


) 

ostream&  operator«  (ostream*  s, vecpair*  vl) 

//  print  a  vector  pair 

I 

return  s«vl ,a«vl .b«"\n"; 

} 

///////////////////////////////// 

//bam_matrix  member  functions 
bam_matrix: :bam_matrix (int  n,int  p):(n,p) 

( 

//  the  maximum  number  of  pattern  pairs  storable 
//  is  around  min(n,p)  where  n  and  p  are 
//  the  dimensionality  of  the  matrix 
C=new  vecpair [min (n, p) *2] ; 

K=0; 

} 


bam_matrix: :~bam_matrix () 

{ 

}  //  destructor 

void  bam_matrix: : encode (const  vecpair*  AB) 

//  encode  a  pattern  pair 

{ 

//D(cout  «  "BAM  Matrix  encoding:  "  «  AB;) 
matrix  T(AB); 

(*this)+=T;  //  add  the  matrix  transpose  to  the  current  matrix 
C [ K ] =AB ; 

K++; 


) 

void  bam_matrix: : uncode (const  vecpair*  AB) 

//  get  rid  of  a  stored  pattern  (by  encoding  A-B  complement) 

{ 

/ /D (cout  «  "uncode\n";) 
vec  v=AB.b*-l? 

matrix  T(AB.a,v);  //  T  is  A  transpose  B  complement 
*this+=T;//  add  the  matrix  transpose  to  the  current  matrix 
K— ; 


1 

vecpair  bam_matrix: : recall (const  vec*  A) 

//  BAM  Matrix  recall  algorithm  (used  by  BAM  SYSTEM  recall) 

( 

int  gi venrow= (A . length ( ) ==width ( ) ) ; 

D(cout«"BAM  matrix  recall  of"  «  A  «  givenrow?"  (row)  \n"  :  "  (col)  \n"; ) 
vec  B(givenrow?depth() :width() , 1) ; 

for ( ; ; ) {  //  feed  vectors  through  matrix  until  "resonant"  pattern-pair 
feedthru  (A, B) ; 

if (feedthru (B, A) ) break;  //  stop  when  returned  A  =  input  A 

1 

D(cout«  "resonant  pair  "  <<  A  «  "\n  and  "  «  B  «  "\n";) 
if (givenrow) 

return  vecpair (B, A) ; 

else 

return  vecpair (A, B) ; 


} 

int  bam_matrix: : feedthru (const  vec*A,vec&  B) 

( 

//D(cout  «  "Feeding  "  «  A  «  "\n";  ) 
vec  temp=B;int  n; 
for (int  i=0;i<B.length() ;i++) { 
if (A. length () ==width () ) 

n=sigmoid(A*rowslice (i) ) ; 

else 

n=sigmoid (A*colslice (i) ) ; 

if  (n) 

B . v [ i ] =n ; 

) 

return  B==temp; 

j 

int  bam_matrix: : sigmoid  (int  n) 

//  VERY  simple  (but  classic  one  for  BAM)  threshold  function 

// 

//  ! - 

//  : 

//  -  + 

//  -1 

( 

if (n<0) return  -1; 
if (n>0) return  1; 
return  0; 

1 

int  bamjnatrix: : check () 

//  check  to  see  if  we  have  successfully  encoded  pattern-pair  into  this  matrix 

{ 

D(cout  «  "Check  BAM  matrix  for  "  «  K  «  "  pattern  pairs\n";) 

vecpair  AB; 

for(int  i=0;i<K;i++) { 

AB=recall (C [ i ] .a)  ; 
if ( ! (AB==C[i] ) )  { 

D(cout  «" failed  check\n  ";) 
return  0; 


} 

D(cout  «  "passed  check\n  ";) 
return  1; 

I 

int  bamjnatrix: : check (const  vecpairs  AB) 

[ 

//  different  check  routine  for  orthogonal  construction  BAM 
//check  to  see  energy  of  present  pattern  pair  to  matrix 
//  is  equal  to  orthogonal  BAM  energy 
matrix  T (AB) ; 

return  energy (T)==  -depth () ‘width () ; 

) 

int  bamjnatrix: : energy (const  matrix*  ml) 

I 

int  sum=0; 

for (int  i=0; i<depth () ; i++) 

for (int  j=0; j<width() ; j++) 

sum+=(ml.m[i) [ j] *this->m[i] [ j] ) ; 

D(cout  «  "Energy  of  matrix  "  «  -sum  «  "\n";) 
return  -sum; 

} 

/////////////////////////////////////////// 

//  bam  system  functions 

//  top  level  of  system  (for  now) 

//  constructor 

bam_system: :bam_system(int  n) 

[ 

M=n; 

for (int  i=0;i<M;i++) 

W[i]=new  bam_matrix; 

} 

bam_system: :~bam_system()  //  destructor 

{ 

for (int  i=0;i<M;i++) 
delete  W[i]; 

) 

void  bam_system: : encode (const  vecpair*  AB) 

//  encode  the  pattern  pair  AB  into  the  BAM  system 

1 

D(cout  «  "BAM  System  encode\n";) 
for(int  h=0;h<M;h++) { 

W [h] ->encode (AB) ; 
if { ! W[h] ->check () ) 

W[h] ->uncode (AB) ; 

else 


if (h==M) (  //  all  matrices  full,  add  another 
if (h<MAXMATS) ( 

W[M]=new  bam_matrix () ; 

W[M] ->encode (AB) ; 

M++; 

) 

else{ 

cout  «  "BAM  System  full\n"; 
exit  (1) ; 


} 

vecpair*  bam_system: : recall (const  vec*  A) 

//  presented  with  pattern  A,  recall  will  return  pattern-PAIR 
{ 

vecpair  XY  [MAXMATS]  .-matrix  *M1,*M2; 
int  E,minimum=0, emin=INT_MAX; 

D(cout  «  "BAM  System  recall\n" ;) 
for(int  h=0;h<M;h++) { 

XY [h] =W [h] ->recall  (A)  ; 

D(cout  «  h  «"-th  matrix,  returned  vecpair  "«  XY[h];) 

Ml=new  matrix (XY [h] ) ; 

(Listing  continued  on  page  88) 


86 


Dr.  Dobb’s Journal,  April  1990 

345 


BAM  SYSTEMS 


Listing  Two  (Listing  continued,  text  begins  on  page  16.) 

E=W[h]->energy(*Ml) ; 

if (A. length ( ) ==W[h] ->width () ) 

M2=new  matrix (XY [h] .a,  A) ; 

else 

M2=new  matrix (A, XY [h] .b) ; 
if  (  (  E- (W [h] ->depth () *W[hj ->width () )  <  emin  ) 

&&  (E==W[h]->energy(*M2) ) 

) 

{ 

emin=E- (W [h] ->depth() *W[h]->width () ) ; 
minimum=h; 

} 

delete  Ml; 
delete  M2; 

} 

return  XY [minimum]; 

} 

void  bam_system: : train (char  *patternfile) 

//A  "multiple-pair"  encode  -  which  Simpson  calls  "encode" 

//  this  could  be  used  for  initial  BAM  Sys  training.  However  an  up 
//  and  running  BAM  Sys  should  only  need  to  use  "encode". 

{ 

FILE  *f=fopen (patternfile, "r") ; int  n=0; 

filebuf  sfile(f); 

istream  s(&sfile,0); 

vecpair  AB; 

for ( ; ; ) ( 

s  »  AB; 

if (s.eof () )break; 

D (cout  «  "Encoding  "  «  n++  «  "-th  pattern  pair:\n"  «  AB;) 
encode (AB) ; 

} 

D(cout  <<  "Completed  training  from  "  «  patternfile;) 

1  . 


# i nc 1 ude " bam . hpp " 

vec  v; 
vecpair  AB; 
bam_system  B; 
char  *p; 

char  patternfile[16]="TEST.FIL";  //  file  where  test  data 
int  trace=0;  //  SET  TRACE=<whatever>  at  DOS  prompt  to  tu: 
main  () 

{ 

cout  «  "Interactive  BAM  System  Demonstration\n" ; 

trace= (p=getenv ("TRACE" ) ) ?1 : 0; 

cout  «  "Training  from  "  «  patternfile  «  "\n"; 

B. train (patternfile) ; 

D(cout  «  "Resulting  BAM  SystemNn"  «  B;) 
cout  «"Enter  patterns  as  0's  and  l's  terminated  by 
«"Patterns  must  be  length  of  "  «  ROWS  «  "  or  "  < 
«  "Null  vector  (just  to  end.\n\n"  ; 

for (;;) { 

cout  «  "Enter  pattern:  "; 
cin  »  v; 

if ( ! v. length () ) break; 

if (v. length () !=ROWS  &&  v. length () !=COLS) { 
cout  «  "Wrong  length. \n"; 
continue; 

} 

AB=B. recall (v) ; 

cout  «  "Recalled  pattern  pair\n"  «  AB; 

} 

I 


Listing  Four 


ostreams  operator« (ostreamS.  s, bam_system&  b) 

//  operator  to  print  out  contents  of  entire  BAM  system 

{ 


} 


for  (int  i=0;i<b.M;i++) 

s«  "BAM  Matrix  "  «  i  «  \n"  «  *(b.W[i])  «  "\n"; 


End  Listing  Two 


Listing  Three 

//////////////////////// 

//  TESTBAM. HPP 

//  Interactive  BAM  System  Demonstration  Program.  Used  to  verify  BAM  system 
//  algorithms  and  demonstrate  them  on  an  abstract  (i.e.  just  Os  and  Is)  case. 
//  Developed  with  Zortech  C++  2.0  —  Copyright  (c)  1989,90  Adam  Blum 


1100101011010011,11101010, 
0110110111110110,11010101, 
1101111001010101,11110010, 
1010101000010111,11001101, 
0011001101011011,11110100, 
1100101011010011,11101010, 
0110100111110110, 11010101, 
1101110101010101,11110010, 
1011101010010111,11001101, 
0001011101011011,11110100, 
1100101001010011,11101010, 
0110110110110110,11010101, 
1100111011010101,  11110011, 
1010000100010111,11001101, 
0001101101011011,11110110, 
1100100011010011,11100110, 
0110110011110110,11010101, 
1101111001010101,11110011, 
1010100000011111,11001101, 
0001100101111011,11111000, 
1100101011010011,11011010, 
0010100111110110, 11010101, 
1101111101010101, 11110010, 
1010111000010111,11101101, 
0001000001011011, 11110100, 
1100101011010011,11101010, 
0110110111110110, 11010101, 
1101111000010101, 11110110, 
1010100111010111,11001101, 
0001000101011011,11110100, 
0110110101110110, 11010111, 
1101111001010101,11110110, 
1010111100110111,11001101, 
0001000101011011, 11110100, 
1100101010010011,11101010, 
0110110111110110, 11010101, 
1101111001010101,11110010, 
1010110000010111, 11001101, 
0011000101011011, 11110100, 
0011010101111011,10010111, 


Listing  Five 

#  TESTBAM. MK 

#  Make  file  for  BAM  System  implementation  tester 

#  Uses  Microsoft  Make 

#  Compiler:  Zortech  C++  2.0 

#  To  make  with  diagnostics  enabled: 

#  make  CFLAGS="-DDEBUG=1"  testbam.mk 

# 

CFLAGS= 

.cpp.obj: 

ztc  -c  $ (CFLAGS)  $* . cpp 
bam.obj:  bam. cpp  bam. hpp 
testbam.obj:  testbam.cpp  bam. hpp 
testbam.exe:  testbam.obj  bam.obj 
blink  testbam  bam; 


is  stored 
:n  trace  on 


comma . \n" 

:  COLS  «" .  \n" 


End  Listing  Three 


End  Listing  Four 


End  Listings 
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Listing  One  (Text  begins  on  page  28.) 

...  _*_  Mode:  LISP;  Syntax:  Common- lisp;  Package:  andy;  Base:  10  -* 


A  Research  Environment  for  the  Instantiation  of  Neural  Networks 
Andrew  J.  Czuchry,  Jr.  —  Georgia  Institute  of  Technology 
Georgia  Tech  Research  Institute  —  Artificial  Intelligence  Branch 


Knowledge  Representation  Structure  definitions 


(defstruct  (NET 

( : print- 

layers 

local-parameters 

) 

(defstruct  (LAYER 

( :print- 

planes 

e-connections 

i-connections 

local-parameters 

prev-layer 

type 


(defstruct  (PLANE 


;  structure  for  a  network 
function  net-printer))  ;  printer  function 

;  list  of  layers 

;  list  of  local  parameters  for  net 

;  structure  for  a  layer 

function  layer-printer) )  ;  printer  function 

;  list  of  planes 

;  list  of  offsets  for  excitatory  connections 
;  list  of  offsets  for  inhibitory  connections 
;  list  of  local  parameters  for  layer 
;  "ptr"  to  preceding  layer  structure 
;  layer  type  (e.g.,  "S"  or  "C"  in 
;  neocognitron;  "FI"  or  "F2"  in  ART) 

;  structure  for  a  plane  (sub-network) 


( :print-function  plane-printer))  ;  printer  function 


(cells  nil  :type  array) 
e-connections 
i-connections 
e-weights 


local-parameters 

layer 


cell  values  for  plane 

list  of  offsets  for  excitatory  connections 
list  of  offsets  for  inhibitory  connections 
list  of  excitatory  weights  (real] 

(same  order  as  list  of  connections) 
list  of  inhibitory  weights  (real] 

(same  order  as  list  of  connections] 
size  of  plane  (list  N  x  M) 
list  of  local  parameters  for  plane 
"ptr"  back  to  layer  of  which  plane  is  a  part 


Structure  Printer  Functions  —  Written  by  Harold  S.  Forbes 


;;;  The  function  OBJECT-ADDRESS  gets  the  memory  address  of  any  LISP  object. 

(defun  OBJECT-ADDRESS  (object) 

;;  Symbolics  implementation. 

(sys:%pointer  object) 

) 

(defun  NET-PRINTER  (structure  stream  ignore) 

(declare  (ignore  ignore)) 

(format  stream  "#<net  ~X>"  (object-address  structure))) 

(defun  LAYER-PRINTER  (structure  stream  ignore) 

(declare  (ignore  ignore)) 

(format  stream  "#<~A-layer  ~X>"  (layer-type  structure) 

(object-address  structure) ) ) 

(defun  PLANE-PRINTER  (structure  stream  ignore) 

(declare  (ignore  ignore) ) 

(format  stream  "#<plane  ~X>"  (object-address  structure))) 


End  Listing  One 


Listing  Two 


*-  Mode:  LISP;  Syntax:  Common-lisp;  Package:  andy;  Base:  10 


A  Research  Environment  for  the  Instantiation  of  Neural  Networks 
Andrew  J.  Czuchry,  Jr.  —  Georgia  Institute  of  Technology 
Georgia  Tech  Research  Institute  —  Artificial  Intelligence  Branch 


Net  CREATION  functions 


; ;  Create  a  new  net . 

;  Creates  a  version  of  a  5-layer  neocognitron  by  default. 

(defun  CREATE-NET  (&key 

(num-of-layers  5) 

(num-of-planes-per-layer-list  '(1  24  24  24  24)) 
(plane-size-list  '((16  16)  (16  16)  (10  10)  (4  4) 

(1  1))) 

(connection-pattern  'square) 

(mask-size-list  '((5  5)  (5  5)  (5  5)  (2  2))) 

(net-parameters  '(:  0.5)) 

(additional -parameter-list 
'(:net-type  neocognitron 

(:r-val-list  '(4.0  1.5  1.5)) 

(:q-val-list  '(1.0  16.0  16.0)) 

( :b-val-list  ' (0.0  0.0  0.0) ) 

(: orientation-list  '(8  1  8  1)) 

))) 

(let*  ((layer-list 

(create-layer-list  num-of-layers 

num-of-planes-per-layer-list 

plane-size-list 

connection-pattern 

mask-size-list 

additional-parameter-list) )  ;  create  layers 

;  meeting  specification 
;  parameters 

(net  (make-net  : local-parameters  net-parameters 

: layers  layer-list)))  ;  create  knowledge  structure 


;  storing  new  net 


;;  Create  a  list  of  NUM-OF-LAYERS  layers  of  the  approriate  type  (type 
;;  key  recorded  in  ADDITIONAL-PARAMETER-LIST). 

(defun  CREATE-LAYER-LIST  (num-of-layers  planes-per-layer-list 
plane-size-list  con-pattern 
mask-size-list 
additional-parameter-list) 

(let  ((layer-type  (zl:lexpr-funcall  #' extract-type-key 

additional-parameter-list) ) ) 

;  determine  type  of  net  to  which  layers  are  to  belong 
;  and  create  appropriate  type  of  layers 
(zl:selectq  layer-type 
(neocognitron 

(create-neocognitron-layer-list 
num-of-layers  planes-per-layer-list 
plane-size-list  con-pattern  mask-size-list 
additional-parameter-list) ) 

(ART2 

(create-ART2-layer-list 
num-of-layers  planes-per-layer-list 
plane-size-list  con-pattern  mask-size-list 
additional-parameter-list) ) 

(backpropagation 

(create-backprop-layer-list 
num-of-layers  planes-per-layer-list 
plane-size-list  con-pattern  mask-size-list 
additional-parameter-list) ) 


;;  Create  a  list  of  NUM-OF-LAYERS  layers  for  the  neocognitron 

(defun  CREATE-NEOCOGNITRON-LAYER-LIST  (num-of-layers  planes-per-layer-list 

plane-size-list 

con-pattern 

mask-size-list 

additional-parameter-list) 

;  extract  parameters  specific  to  neocognitron 

(let*  ((r-val-list  (zl:lexpr-funcall  #' extract-r-val-list 

additional-parameter-list) ) 

(q-val-list  (zl : lexpr-funcall  #' extract-q-val-list 

additional-parameter-list) ) 

(b-val-list  (zl: lexpr-funcall  #' extract -b-val-list 

additional-parameter-list) ) 

(orientation-list  (zl : lexpr-funcall  #' extract-orientation-list 
additional-parameter-list) ) 
(number-of-processing-layers 
(-  num-of-layers  1)) 

(num-of-s-layers  (/  number-of-processing-layers  2))) 

;  error  checking  and  layer  creation 

(cond  ((not  (=  num-of-s-layers  (length  r-val-list) 

(length  q-val-list)  (length  b-val-list))) 

;  check  extracted  parameters 
(ferror  "Improper  parameters  for  a  net  with  ~D  S-layers: 
r  value  list  =  ~s, 
q  value  list  =  ~s, 
b  value  list  =  ~s." 

num-of-s-layers  r-val-list  q-val-list  b-val-list)) 

( (not  (=  num-of-layers 

(length  planes-per-layer-list) 

(length  plane-size-list)))  ;  check  passed  parameters 

(ferror  "Improper  parameters  for  a  net  with  ~D  layers: 

Either  not  enough  planes  sizes  listed  in  ~s,  OR 
not  enough  plane  sizes  listed  in  ~s." 
num-of-layers  planes-per-layer-list 
plane-size-list) ) 

{(not  (=  number-of-processing-layers  (length  mask-size-list))) 

;  check  projection  masks 

(ferror  "Improper  parameters  for  a  net  with  ~D  layers  beyond 
input  layer: 

Not  enough  connection  mask  sizes  listed  in  ~s." 
number-of-processing-layers  mask-size-list) ) 

;  Create  appropriate  number  of  layers,  one  at  a  time,  and  record  as  a  list. 

;  For  each  layer,  extract  appropriate  parameter  settings  and  sizes. 

(t 

(do*  ((i  1  (+  i  1)) 

(r-val-list  r-val-list  (cdr  r-val-list)) 

(r-val  (car  r-val-list)  (car  r-val-list)) 

(q-val-list  q-val-list  (cdr  q-val-list)) 

(q-val  (car  q-val-list)  (car  q-val-list)) 

(b-val-list  b-val-list  (cdr  b-val-list)) 

(b-val  (car  b-val-list)  (car  b-val-list)) 

(rest-orientations  orient at ion-list 

(cddr  rest-orientations)) 

(s-orientations  (car  rest-orientations) 

(car  rest-orientations)) 

(c-orientations  (cadr  rest-orientations) 

(cadr  rest-orientations)) 

(prev-plane-num  (car  planes-per-layer-list) 

(cadr  planes-per-layer) ) 

(planes-per-layer  (cdr  planes-per-layer-list) 

(cddr  planes-per-layer)) 

(num-of-s-planes  (car  planes-per-layer) 

(car  planes-per-layer) ) 

(mask-list  mask-size-list  (cddr  mask-list)) 

(mask-size  (car  mask-list)  (car  mask-list)) 

(plane-sizes-list  (cdr  plane-size-list) 

(cddr  plane-sizes-list)) 

(prev-c-plane-size  (car  plane-size-list) 
c-plane-size) 

(s-plane-size  (car  plane-sizes-list) 

(car  plane-sizes-list)) 

(c-plane-size  (cadr  plane-sizes-list) 

(cadr  plane-sizes-list)) 

;  create  input  layer 

(input-layer 
(make-layer  :planes 


( continued  on  page  95) 
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'C) 


'C)) 


Listing  Two  (Listing  continued,  text  begins  on  page  28.) 

(create-plane-list 
1  prev-c-plane-size 
(do  |(i  1  (+  i  1) ) 

(times  (apply  #'*  prev-c-plane-size)) 

(res  '((0))  (cons  '(0)  res))) 

( (>=  i  times)  res) ) 

001  mask-size  'C) 

:type  'C)) 

;  create  connections 

(s-connect ion-list 

(create-connection-list  1  prev-c-plane-size  s-plane-size 
con-pattern  mask-size  'S) 

;  Connections  same  for  for  all  planes 
(create-connection-list  1  prev-c-plane-size  s-plane-size 
con-pattern  mask-size  'S)) 

(c-connection-list 

(create-connection-list  1  s-plane-size  c-plane-size 
con-pattern  (cadr  mask-list) 

;C-cells  connect  one  S-plane 
(create-connection-list  1  s-plane-size  c-plane-size 
con-pattern  (cadr  mask-list) 

;  create  planes 
(s-planes 

(create-plane-list  num-of-s-planes  s-plane-size  s-connection-list 

prev-plane-num  b-val  s-orientations  mask-size  'S) 
(create-plane-list  num-of-s-planes  s-plane-size  s-connection-list 

prev-plane-num  b-val  s-orientations  mask-size  'S)) 

(c-planes 

(create-plane-list  (cadr  planes-per-layer)  c-plane-size  c-connection-list 
num-of-s-planes  b-val  c-orientations  mask-size  'C) 
(create-plane-list  (cadr  planes-per-layer)  c-plane-size  c-connection-list 
num-of-s-planes  b-val  c-orientations  mask-size  'C)) 

; assign  layers 

(new-s-layer  (make-layer  :planes  s-planes  : e-connections  s-connection-list 
: local-parameters  '(:net-type  neocognitron  :r  , r-val  :q  , q-val) 
:prev-layer  input-layer  :type  'S) 
(make-layer  :planes  s-planes  : e-connections  s-connection-list 
: local-parameters  '(:net-type  neocognitron  :r  , r-val  :q  , q-val) 
:prev-layer  (car  (last  layers) ) 

:type  'S)) 

(new-c-layer  (make-layer  :planes  c-planes  :e-connections  c-connection-list 
: local-parameters  '(:net-type  neocognitron  :r  , r-val  :q  ,q-val) 
:prev-layer  new-s-layer  :type  'C) 
(make-layer  -.planes  c-planes  : e-connections  c-connection-list 
:  local-parameters  '(•' net-type  neocognitron  :r  ,  r-val  :q  ,q-val) 
:prev-layer  new-s-layer  :type  ' C) ) 

;  add  new  layers  to  layer  list 

(layers  ;  S  and  C  layers 

(list  input-layer  new-s-layer  new-c-layer) 

(append  layers 

(list  new-s-layer  new-c-layer)))) 

( (>=  i  num-of-s-layers)  layers)))  ;  return  list  of  layers 


) 


) 


; ; ;  Keyword  and  Parameter  EXTRACTION  functions 

(defun  EXTRACT-TYPE-KEY  (&key  net-type  &allow-other-keys) 
net-type)  ;;  Extract  the  NET-TYPE  keyed  value 

(defun  EXTRACT-R-VAL-LIST  (&key  r-val-list  &allow-other-keys) 

r-val-list)  ;;  Extract  the  R-VAL-LIST  keyed  value 

(defun  EXTRACT-Q-VAL-LIST  (&key  q-val-list  &allow-other-keys) 
q-val-list)  ;;  Extract  the  Q-VAL-LIST  keyed  value 

(defun  EXTRACT-B-VAL-LIST  (&key  b-val-list  &allow-other-keys) 
b-val-list)  ;;  Extract  the  B-VAL-LIST  keyed  value 

(defun  EXTRACT-ORIENTATION-LIST  (&key  orientation-list  &allow-other-keys) 
orientation-list)  ;;  Extract  the  ORIENTATION-LIST  keyed  value 

(defun  EXTRACT-NET-  (net)  ;;  Extract  the  parameter  from  a  NET 

(zl:lexpr-funcall  #' extract-net-  -aux 

(net-local-parameters  net))) 

(defun  EXTRACT-NET-  -AUX  (Skey  &allow-other-keys) 

)  ;;  Extract  the  keyed  value 

(defun  EXTRACT-LAYER-R  (layer)  ;;  Extract  the  R  parameter  from  a  LAYER 
(zl:lexpr-funcall  #' extract-layer-r-aux 

(layer-local-parameters  layer))) 

(defun  EXTRACT-LAYER-R-AUX  (&key  r  &allow-other-keys) 
r)  ;;  Extract  the  R  keyed  value 

(defun  EXTRACT-LAYER-Q  (layer)  ;;  Extract  the  Q  parameter  from  a  LAYER 

(zl:lexpr-funcall  #' extract-layer-q-aux 

(layer-local-parameters  layer) ) ) 

(defun  EXTRACT-LAYER-Q-AUX  (&key  q  &allow-other-keys) 
q)  ;;  Extract  the  Q  keyed  value 


(defun  EXTRACT-PLANE-B  (plane)  ;;  Extract  the  B  parameter  from  a  PLANE 
(zl : lexpr-funcall  #' extract-plane-b-aux 

(plane-local-parameters  plane) ) ) 

{defun  EXTRACT-PLANE-B-AUX  (&key  b  &allow-other-keys) 
b)  ; ;  Extract  the  B  keyed  value 


Keyword  and  Parameter  INSERTION  functions 


(defun  INSERT-KEYED-VAL  (old-list  insertion-list) 
(do  ((list  (cddr  old-list)  (cddr  list)) 

(i-key  (car  insertion-list)) 

(o-key  (car  old-list)  (car  list)) 

(o-val  (cadr  old-list)  (cadr  list)) 
(result  insertion-list 
(append  result 

(if  (not  (equal  o-key  i-key) ) 
(list  o-key  o-val) ) ) ) ) 
((null  o-key)  result))) 


; ;  Insert  a  keyed  value 


;  insert  new  keyed  value 
;  keep  old  values 
;  for  other  keys 


End  listing  Two 
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Listing  Three  (Listing  continued,  text  begins  on  page  28.) 

...  _*_  M0cje:  LISP;  Syntax:  Common-lisp;  Package:  andy;  Base:  10  -*- 


A  Research  Environment  for  the  Instantiation  of  Neural  Networks 
Andrew  J.  Czuchry,  Jr.  —  Georgia  Institute  of  Technology 
Georgia  Tech  Research  Institute  —  Artificial  Intelligence  Branch 


Net  TRAINING  functions 


Top  level  function  for  training.  Trains  on  all  patterns  in  PATTERN-LIST. 
Sets  mappings. 

Trains  on  *neocognitron*  by  default. 

(defun  TRAIN-MAIN-LOOP  (&key 
(net  *neocognitron*) 

(pattern-list  (mapcar  #'item-misc  (scl:send  lrn-pattrns  :item-list) ) ) 

(iteration-list  '(4  4  4  4)) 

print-data) 

(let*  ((net-type  (x) : lexpr-funcall  &”extract-type-key 

(net-locate-parameters  net))) 

(iterations  (compute-iteration-list  net-type  i  iteration  list) 
(actual-its  (  iterations  1))) 

(do*  ( (i  0  (+il)) 

(conditioned-it-list  (select-iteration-list  net-type  i  iteration-list))) 
(terminate-iterations  net-type  i  iterations)) 

(do*  ((patterns  pattern-list  (cdr  patterns))  ;  loop  over  all  patterns 

(pattern  (car  patterns)  (car  patterns)) 

(actual-its  (length  pattern-list))) 

(cond  (print-data 

(format  t  "“%“%") 

(time:print-current-time) 

(format  t  "~%%  **  training  ~s  on  pattern  ~s. 

(Iteration  ~d  of  ~d,  ~d  more  patterns.)" 

net  pattern  i  actual-its  (length  (cdr  patterns))))) 

(train  pattern  net  iteration-list)  ;  perform  training 


;  record  mapping  between  pattern  and 
;  most  active  "output  layer"  cell 


(create-mappings  net  pattern-list) 

(cond  (print-data 

(format  t  "~%~%") 

(time:print-current-time) ) ) 

) 

} 

;;  Trains  a  net  to  recognize  a  pattern.  Returns  the  plane/cell  of  the  final 
;  layer  which  responds  most  actively  to  the  pattern. 

(defun  TRAIN  (pattern-plane  net 

&optional  (iterations-per-layer-list  '(4  4  4  1))) 

(let*  ( (layers-to-be-trained  (cdr  (net-layers  net))) 

(num-layers  (length  layers-to-be-trained))) 

(cond  ((not  (=  num-layers  (length  iterations-per-layer-list))) 

(ferror  Improper  training  iteration  count  list  for 
training  ~D  layers:  ~s" 

num-layers  iterations-per-layer-list) ) 

(t 

(setf  (plane-cells  (car  (layer-planes  (car  (net-layers  net))))) 
pattern-plane)  ;  assign  input  pattern 
(do*  ((layer-list  (cdr  (net-layers  net))  (cdr  layer-list)) 

;  loop  over  all  layers 
(layer  (car  layer-list)  (car  layer-list)) 

(iteration-list  iterations-per-layer-list 
(cdr  iteration-list)) 

(iterations  (car  iteration-list)  (car  iteration-list)) 

;  #  times  to  train  layer 
(result  (caar  (train-layer  layer  iterations)) 

;  train  each  layer  in  succession 
(caar  (train-layer  layer  iterations)))) 

;  (result  (caar  (update-layer  layer))  ;  update  the  layer 

;  (caar  (update-layer  layer) ) ) ) 

((null  (cdr  layer-list))  result)) 

;  return  most  active  cell  in  final  layer 

) 

) 

) 

) 

Trains  a  layer  in  a  net  to  recognize  a  pattern.  Continues  training  until 
updating  layer  produces  no  more  changes  in  the  representative  list 
(returned  by  UPDATE-LAYER).  At  some  point  I'd  like  to  remove  the 
ITERATIONS  parameter  and  work  only  from  changes  in  rep  list,  but 
it  is  computationally  prohibitive  in  the  current  version  of  the  system. 

(defun  TRAIN-LAYER  (layer  ^optional  iterations) 

(do*  ((old-reps  nil  new-reps)  ;  record  most  active  cell 
(new-reps  (update-layer  layer)  (update-layer  layer) ) 

;  re-adjust  after  training 

(i  0  (+  i  1))) 

((or  (equal  old-reps  new-reps)  (>=  i  iterations))  new-reps) 

;  check  if  training  complete 

(train-layer-aux  layer  new-reps) )  ;  perform  training 

) 

;  Trains  a  layer  in  a  net  to  recognize  a  pattern 
(defun  TRAIN-LAYER-AUX  (layer  Soptional  (representative-data-list 
(update-layer  layer) ) ) 

(let  ( (net -type  (zl: lexpr-funcall  #' extract-type-key 

(layer-local-parameters  layer) ) ) ) 

;  select  appropriate  training  routine 
(zl:selectq  net-type 
(neocognitron 

(train-neocognitron-layer-aux 

layer  representative-data-list)) 

(DIANN 

(train-DIANN-layer-aux 
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layer  representative-data-list) ) 

(ART2 

(train-ART2-layer-aux 

layer  representative-data-list) ) 
(backpropagation 

(train-backprop-layer-aux 

layer  representative-data-list) ) 


;  Trains  a  layer  in  a  neocognitron  to  recognize  a  pattern 

(defun  TRAIN-NEOCOGNITRON-LAYER-AUX  (layer  Soptional  (representative-data-list 
(update-layer  layer) ) ) 

(cond  ( (>  *trace*  3) 

(format  t  "~%training  layer. ~%  Chosen  Representative  list:~%  ~s" 
representative-data-list) ) ) 

(cond  ( (eq  (layer-type  layer)  'S)  ;  only  train  S-layers 

(mapcar 

#' (lambda  (representative-data) 

(let*  ( (plane  (car  representative-data) ) 

(pos  (cadadr  representative-data) ) 

(prev-layer  (layer-prev-layer  layer) ) 

(q-val  (extract-layer-q  layer) ) 

(results 

(do*  ( (all-connections  (layer-i-connections  layer) 

(cdr  all-connections) ) 

(connections  (connections-for-pos  layer  plane  pos) ) 

;  extract  connections 
(all-i-vals-list  (plane-i-weights  plane) 

(cdr  all-i-vals-list)) 

;  extract  current  weights 
(old-i-vals  (car  all-i-vals-list) 

(car  all-i-vals-list)) 
(all-i-vals-list  (plane-i-weights  plane) 

(cdr  all-i-vals-list)) 
(all-i-vals  (car  all-i-vals-list) 

(car  all-i-vals-list)) 
(all-i-weights-list  (plane-i-weights  plane) 

(cdr  all-i-weights-list)) 
(all-i-weights  (car  all-i-weights-list) 

(car  all-i-weights-list) ) 
(raw-result  (train-plane  prev-layer 

connections  old-i-vals 
all-i-vals  all-i-weights  q-val) 

;  perform  training  on  excitatory  connections 
(train-plane  prev-layer  connections  old-i-vals 
all-i-vals  all-i-weights  q-val)) 
(result  raw-result 

(list  (append  (car  result) 

(car  raw-result)) 

(+  (cadr  result) 

(cadr  raw-result))))) 

;  record  result 

((null  (cdr  all-connections) )  result))) 

;  return  result 


(new-i-weight-list  (car  results) ) 

;  adjust  inhibitory  weights 
(new-b-val  (*  q-val  (compute-inhib-input  (connections-for-pos  layer  plane  pos) 

(c-weights-for-pos  plane  pos) 
prev-layer) ) ) ) 


(setf  (plane-i-weights  plane) 

(transpose-on-type  new-i-weight-list  (layer-type  layer))) 
(setf  (plane-local-parameters  plane) 

(insert-keyed-val  (plane-local-parameters  plane)  '  (:b  , new-b-val) ))) ) 
representative-data-list) ) 

( (eq  (layer-type  layer)  ' C )  representative-data-list) 

;  for  C-layers,  return  representatives 


IDENTIFICATION 


;  Attempts  to  recognize  a  pattern  using  NET  as  a  trained  net 
;  Returns  the  plane  of  the  final  layer  which  responds  to  the  pattern. 

(defun  IDENTIFY  (pattern-plane  net) 

(setf  (plane-cells  (car  (layer-planes  (car  (net-layers  net))))) 

pattern-plane)  ;  assign  input  pattern 

(let  ((result  (caar  (last  (update-net  net)))))  ;  update  net 

(if  (listp  result) 

(car  result))  ;  return  most  active  cell  of  final  layer 

)) 


;  Updates  entire  net 

;  Returns  maximum  value  as  nested  set  of  lists 
;  (((plane  (value,  pos))  ...  (plane  (value,  pos))  layerl) 

;  (((plane  (value,  pos))  ...  (plane  (value,  pos))  layer2)  ...) 

(defun  UPDATE-NET  (net) 

(let  ((  (extract-net-  net))) 

(do*  ((layer-list  (cdr  (net-layers  net))  (cdr  layer-list)) 

?  loop  over  all  layers 

(layer  (car  layer-list)  (car  layer-list)) 

(layer-max  (update-layer  layer)  (update-layer  layer)) 

;  update  the  layer 

(max  (list  (append  layer-max  (list  layer))) 

;  max  value  ((value,  pos)  plane)...  layer)  list 
(append  max  (list  (append  layer-max  (list  layer)))))) 

;  append  each  layer 

( (null  (cdr  layer-list) )  max) 

) 

) 


End  Listing  Four 


Listing  Five 

...  Mode:  LISP;  Syntax:  Common-lisp;  Package:  andy;  Base:  10  -*- 
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Andrew  J.  Czuchry,  Jr;  —  Georgia  Institute  of  Technology 
Georgia  Tech  Research  Institute  --  Artificial  Intelligence  Branch 


Sample 


Variables  of 


instantiated 


(defvar  *neocognitron-net* 

' (create-net 

:num-of-layers  7 

:num-of-planes-per-layer-list  ' (1  24  24  24  24  24  24) 
:plane-size-list  '((16  16)  (16  16)  (10  10)  (8  8)  (6  6)  (2  2)  (1  1)) 
: connection-pattern  'square 

:mask-size-list  '((5  5)  (5  5)  (5  5)  (5  5)  (5  5)  (2  2)) 

: net-parameters  '(:  0.5) 

: additional-parameter-list  ' (: net-type  neocognitron 

:r-val-list  (4.0  1.5  1.5) 

:q-val-list  (1.0  16.0  16.0) 

:b-val-list  (0.0  0.0  0.0) 
:orientation-list  (8181)) 


; Trains  a  plane's  CONNECTIONS  to  all  planes  in  previous  layer 

(defun  TRAIN-PLANE  (prev-layer  connections  old-i-val-lists  all-i-val-lists 

all-i-weight-lists  q-val) 

(do*  ((connection-list  connections  (cdr  connection-list)) 

;  extract  connections 

(connection  (car  connection-list)  (car  connection-list)) 

(c-val-list  all-i-val-lists  (cdr  c-val-list))  ;  extract  current  weights 
(c-vals  (car  c-val-list)  (car  c-val-list)) 

(c-weight-list  all-i-weight-lists  (cdr  c-weight-list) ) 

(c-weights  (car  c-weight-list)  (car  c-weight-list)) 

(rev-old-i-vals  (reverse  old-i-val-lists)) 

(old-i-vals  (car  old-i-val-lists) 

(nth  (-  (length  c-val-list)  1)  rev-old-i-vals)) 

(con-vals  (train-plane-aux  prev-layer  connection  old-i-vals 
c-vals  c-weights  q-val) 

(train-plane-aux  prev-layer  connection  old-i-vals 

c-vals  c-weights  q-val) )  ;  perform  actual  training 

(new-i-weights  (list  (car  con-vals) ) 

(nconc  new-i-weights 

(list  (car  con-vals) )) ) 

(vtotal  (cadr  con-vals)  (+  vtotal  (cadr  con-vals)))) 

((null  (cdr  connection-list))  (list  (list  new-i-weights)  vtotal))) 

;  return  new  connection  weights 


) 


End  Listing  Three 


) 

(defvar  *neocognitron-net2* 

'  (create-net 

:num-of-layers  7 

:num-of-planes-per-layer-list  ' (1  15  20  20  24  20  10) 
:plane-size-list  '((24  24)  (18  18)  (12  12)  (9  9)  (8  8)  (4  4)  (1  1)) 
: connection-pattern  'square 

: mask-size-list  '((7  7)  (3  3)  (3  3)  (4  4)  (5  5)  (4  4)) 

: net-parameters  '  (:  0.5) 

: additional-parameter-list  '(:net-type  neocognitron 

: r-val-list  (3.0  1.0  1.0) 

:q-val-list  (10.0  18.0  18.0) 
:b-val-list  (0.0  0.0  0.0) 
:orientation-list  (12  1  12  1)) 

) 

) 


End  Listings 


Listing  Four 

...  Mode:  LISP;-  Syntax:  Common-lisp;  Package:  andy;  Base:  10  -*- 
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R  H  E  A  L  S  T  0  N  E 


Listing  One  (Text  begins  on  page  46.) 

*  tswit.c  —  iRMX  II  task  switch  time  measurement. 

*  Compiler:  iC-286  V4.1  (LARGE  model).  Q1  1989,  by  R.  P.  Kar 

♦include  <stdio.h> 

♦include  <rmxc.h> 


**\ 


*/ 


♦define  MAX  LOOPS  500000L 


unsigned 
unsigned  long 
selector 
unsigned  long 
float 


el_time,  pri,  status; 
strt_sec,  end_sec; 
taskl_t,  task2_t; 
count 1,  count2; 
ts_time; 


/*  "union"  used  to  decompose  a  pointer  into  segment : offset  */ 
typedef  struct  (unsigned  offset;  selector  sel;}  ptr_s; 
union  {  unsigned  ‘pointer;  ptr_s  ptr;  }  ptr_u; 

void  taskl () 

( 

for  ( count 1  =  0;  count 1  <  MAX_LOOPS;  count 1++) 

rqsleep(0,  &status);  /*  Task  switch  happens  here  */ 

rqdeletetask (NULL,  istatus);  /*  delete  self  */ 

} 


void  task2 () 


for  (count2  =  0;  count2  <  MAX_LOOPS;  count2++) 
rqsleep(0,  ^status);  /*  Task  switch  happens  here  */ 

rqdeletetask (NULL,  &status);  /*  delete  self  */ 


/*************************  MAIN  PROGRAM 


/*  "union"  used  to  decompose  a  pointer  into  segment : offset  */ 
typedef  struct  (unsigned  offset;  selector  sel;)  ptr_s; 
union  {  unsigned  ‘pointer;  ptr_s  ptr;  }  ptr_u; 

/*  The  lower  priority  task.  It  sits  in  delay  loop  waiting  to  be  preempted.  */ 
void  taskl () 

( 

unsigned  loc_status; 

for  ( count 1  =  0;  count 1  <  MAX_LOOPS;  count 1++) 

for  (i  =  0;  i  <  ONEJTICK;  i++)  ++spare;  /*  Waste  time  */ 

printf ("deleting  task  l\n\n"); 

rqdeletetask (NULL,  &loc_status) ;  /*  delete  self  */ 

} 

/*  The  higher  priority  task.  When  it  goes  to  sleep  (once  in  every  loop)  iRMX 

*  makes  a  non-preemptive  switch  to  the  other  task;  when  the  sleep  period  ends 

*  this  task  preempts  the  other  task. 

*/ 

void  task2 () 

( 

unsigned  loc_status; 

for  (count2  =  0;  count2  <  MAX_LOOPS;  count2++) 

/*  When  rqsleep  is  called,  task  switch  to  lower  priority  task  happens. 

*  When  1  clock  period  is  over,  other  task  is  preempted  and  control 

*  returns  to  the  next  line. 

*/ 

rqsleep(l,  &loc_status) ; 
printf ("\ndeleting  task  2\n"); 

rqdeletetask (NULL,  &loc_status) ;  /*  delete  self  */ 


main () 

( 


printf ("\nPreemption  time  benchmark\n  Each  task  runs  %D  times ... \n\n", 
MAX_LOOPS) ; 


main  () 

{ 

printf ("\nTask  Switch  measurements  Each  task  runs  %D  times ... \n\n", 
MAX_LOOPS) ; 

/*  Measure  execution  time  of  taskl  and  task2  when  they  are  executed 
serially  (without  task  switching) .  */ 

strt_sec  =  rqgettime (&status) ;  /*  Start  of  timing  period  */ 

for  (countl  =  0;  countl  <  MAX_LOOPS;  countl++) 

/*  rqsleep (0,  & status)  */  ; 
for  (count2  =  0;  count2  <  MAX_LOOPS;  count2++) 

/*  rqsleep (0,  Sstatus)  */  ; 

end_sec  =  rqgettime (Sstatus) ;  /*  End  of  timing  period  */ 

el_time  =  (unsigned) (end_sec  -  strt_sec); 

/*  Place  a  pointer  to  any  variable  in  union  "ptr_u",  so  the  data  segment 
of  this  program  becomes  known.  */ 
ptr_u. pointer  =  ^status; 

/*  Get  main  program's  priority  level  */ 
pri  =  rqgetpriority  (NULL,  &status) ; 


/*  Measure  execution  time  of  taskl  and  task2  when  they  are  executed 
*  serially  (without  task  switching  or  preemption) . 

*/ 

strt_sec  =  rqgettime (&status) ;  /*  Start  of  timing  period  */ 

for  (countl  =  0;  countl  <  MAX_LOOPS;  countl++) 
for  (i  =0;  i  <  ONEJTICK;  i++)  ++spare; 
for  (count2  =  0;  count2  <  MAX_LOOPS;  count2++) 
end_sec  =  rqgettime (Sstatus) ;  /*  End  of  timing  period  */ 

el_time  =  (unsigned) (end_sec  -  strt_sec); 

printf ("  Execution  without  premption  &  task  switching  took  %u  seconds\n", 
el_time) ; 

/*  Place  a  pointer  to  any  variable  in  union  "ptr_u",  so  the  data  segment 
of  this  program  becomes  known. 

*/ 

ptr_u. pointer  =  Sstatus; 

/*  Get  main  program's  priority  */ 
pri  =  rqgetpriority  (NULL,  &status); 

taskl_t  =  rqcreatetask  (pri+2,  taskl,  ptr_u .ptr . sel,  0L,  512,  0,  &status) ; 
if  (status  !=  0)  printf ("rqcreatetask  error\n"); 


/*  Create  two  (identical)  tasks,  which  just  switch  between  themselves  */ 
taskl_t  =  rqcreatetask  (pri+1,  taskl,  ptr_u.ptr . sel,  0L,  512,  0,  Sstatus); 
if  (status  !=  0)  printf ("rqcreatetask  error\n"); 


task2_t  =  rqcreatetask  (pri+1,  task2,  ptr_u.ptr.sel,  0L,  512,  0,  &status); 
strt_sec  =  rqgettime (istatus) ;  /*  Start  of  timing  period  */ 


task2_t  =  rqcreatetask  (pri+1,  task2,  ptr_u.ptr.sel,  0L,  512,  0,  &status); 
strt_sec  =  rqgettime (Sstatus) ;  /*  Start  of  timing  period  */ 

/*  Set  main  program's  priority  below  task  1,2  so  they  run  to  completion  */ 
rqsetpriority (  (selector) 0,  pri+2,  ^status  ); 
rqsleep (  0,  &status  ); 

end_sec  =  rqgettime (Sstatus) ;  /*  End  of  timing  period  */ 

/*  Set  main  program  back  to  initial  priority  */ 
rqsetpriority (  (selector)O,  pri,  Sstatus  ); 

el_time  =  (unsigned) (end_sec  -  strt_sec)  -  el_time; 
ts_time  =  (  (float) el_time  *  1000000.0  )  /  ( (float )MAX_LOOPS  *  2.0)  ; 
printf ("  Task  switch  time  =  %5.1f  microseconds\n",  ts_time) ; 
dqexit (0) ; 

1  End  Listing  One 


/*  Set  main  program's  priority  below  task  1,2  so  they  run  to  completion  */ 
rqsetpriority (  (selector) 0,  pri+3,  Sstatus  ); 
rqsleep (  0,  Sstatus  ); 

end_sec  =  rqgettime (^status) ;  /*  End  of  timing  period  */ 

/*  Set  main  program  back  to  initial  priority  */ 
rqsetpriority (  (selector) 0,  pri,  Sstatus  ); 
el_time  =  (unsigned) (end_sec  -  strt_sec)  -  el_time; 
preempt_time  =  (  ( float )el_time  /  ( float )MAX_LOOPS  )  *  1000000.0; 
printf  ("  Preemption  time  +  task  switch  time  =  %5.1f  microseconds\n", 
preempt_time) ; 

dqexit (0) ; 

1 

End  Listing  Two 

Listing  Three 


Listing  Two 


/*■ 


\* 


preempt. c  —  iRMX  II  preemption  time  benchmark. 

Measures  the  time  for  1  preemptive  task  switch  +  1  non-preemptive  task 
switch.  Compiler:  iC-286  V4.1  (LARGE  model).  Q4  1989,  by  R.  P.  Kar 


♦include  <stdio.h> 
♦include  <rmxc.h> 


ltncy.c  —  iRMX  II  interrupt  latency  benchmarking  program. 

Method:  This  program  first  sets  up  an  interrupt  handler  for  an  unused 
interrupt  level.  It  then  reads  the  count  in  the  system  timer  (timer 
0  on  the  8254  chip)  and  simulates  an  external  interrupt  to  the  CPU  by 
a  cause$interrupt  instruction.  The  interrupt  handler  latches  timer  0, 
so  this  program  can  read  it  again  after  the  handler  returns  control. 
The  difference  in  the  two  timer-count  values  is  the  interrupt  latency. 

Oct  1989,  by  R.  P.  Kar 


/*  NOTE:  100,000  iterations  takes  about  35  minutes  on  a  16  MHz  386  PC  */ 
♦define  MAX  LOOPS  100000L 


♦include  <stdio.h> 
♦include  <rmxc.h> 


/*  Note:  This  is  a  CPU-dependent  value.  It  must  be  set  such  that 

*  the  execution  time  for  this  loop:  for  (j=0;  j  <  ONEJTICK;  j++)  spare++ 

*  is  slightly  longer  than  one  iRMX  sleep  period. 

*/ 

♦define  ONE  TICK  4200 


unsigned 
unsigned  long 
selector 
unsigned  long 
float 


pri,  status,  i,  spare,  el_time; 
strt_sec,  end_sec; 
taskl_t,  task2_t,  co_conn; 
countl,  count2; 
preempt_time; 


/*  Define  base  address  of  8254  (Programmable  Interval  Timer)  chip  */ 
♦define  PIT_ADDR  0x40 

unsigned  status,  ticks,  timer_cntl,  timer_cnt2; 

unsigned  dummyw; 

unsigned  char  pri,  lo_cntl,  hi_cntl,  lo_cnt2; 
extern  void  int_hndlr(); 

/***************************  MAIN  PROGRAM  **************************/ 
main  () 
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{ 

print f ("  ***  WARNING  ***\n\n"); 

printf("  This  program  assumes  that  timer  and  interrupt  controller\n") ; 
printf("  hardware  is  fully  compatible  with  the  IBM  PC/AT\n\n"); 

/*  Set  up  local  handler  for  IRQ3  on  master  8259  */ 

rqsetinterrupt (  0x38,  0,  int_hndlr,  (selector) 0,  &status  ); 

disable ();  /*  Disable  interrupts  */ 

/*  Latch  and  read  timer  0  value.  Interrupt  handler  will  latch  it  again  */ 
outbyte (  PIT_ADDR  +3,  0  ); 

/*  The  following  two  instructions  read  the  value  latched  in  counter  0.  They 
are  unavoidable  measurement  overhead  and  inflate  the  interrupt  latency 
by  a  few  clock  cycles. 

*/ 

lo_cntl  =  inbyte (  PIT_ADDR  ) ; 
hi_cntl  =  inbyte (  PIT_ADDR  ); 

/*  Activate  the  interrupt  handler.  It  will  latch  timer  0  and  return.  */ 
causeinterrupt (59) ; 

/*  The  interrupt  handler  has  latched  the  timer  0  count.  Now  read  it.  */ 

lo_cnt2  =  inbyte {  PIT_ADDR  ); 

dummy _w  =  (unsigned  int) inbyte (  PIT_ADDR  ); 

timer_cnt2  =  (unsigned  int)lo_cnt2  +  (dummy _w  «  8); 

enable ();  /*  Re-enable  interrupts  */ 


dummy _w  =  (unsigned  int)hi_cntl; 

timer_cntl  =  (unsigned  int)lo_cntl  +  (dummy_w  «  8); 

/*  Calculate  difference  in  timer  counts  (timer  counts  DOWN  to  0)  */ 
if  (timer_cntl  >  timer_cnt2) 

ticks  =  timer_cntl  -  timer_cnt2; 

else  /*  Rare  case  when  timer  has  wrapped  around  */ 

ticks  =  timer_cntl  +  (Oxffff  -  timer_cnt2  +  1); 


/*  Display  results  */ 

printf("  Interrupt  latency  =  %u  timer  ticks\n",  ticks); 

/*  Note  that  timer  is  pulsed  by  1.19  MHz  crystal  */ 

printf("  =  %4 . If  microseconds\n\n",  ( (float) ticks) /I . 19  ); 


rqresetinterrupt (  0x38,  &status  ); 
dqexit  (0) ; 


Listing  Four 


End  listing  Three 


;  latch. asm  --  Interrupt  handler.  Merely  latches  timer  0  in  a 
;  PC/AT  (or  hardware  compatible  computer) . 


NAME  latch 


latch  SEGMENT  PUBLIC 


int_hndlr  PROC  FAR 
PUBLIC  int_hndlr 
PUSHA 
XOR  AX, AX 

OUT  43H,  AL  ;  Latch  8254  counter  0 

POPA 

IRET 

int_hndlr  ENDP 
latch  ENDS 
END 


End  listing  Four 


Listing  Five 


semshuf.c  —  iRMX  II  semaphore  shuffle  measurement. 

Measures  the  latency  (within  iRMX)  for  a  task  to  acquire 
a  sempahore  that  is  owned  by  another  equal-priority  task. 
Compiler:  Intel  iC-286  V4.1  (LARGE  model).  Q3  1989,  by  R.  P.  Kar 


♦include  <stdio.h> 
♦include  <rmxc.h> 


♦define  MAX  LOOPS  100000L 


enum  YESNO  (NO,  YES)  sem_exch; 
unsigned  el_time,  status; 

selector  taskl_t,  task2_t,  sem_t; 

unsigned  char  pri; 

unsigned  long  count 1,  count2,  maxloop2; 
unsigned  long  strt_sec,  end_sec; 
float  semshuf  time; 


/*  "union"  used  to  decompose  a  pointer  into  segment : offset  */ 
typedef  struct  (unsigned  offset;  selector  sel;}  ptr_s; 
union  {  unsigned  *pointer;  ptr_s  ptr;  }  ptr_u; 

void  taskl () 

{ 

unsigned  rem_units,  tl_status; 

for  (countl  =  0;  countl  <  MAX_LOOPS;  countl++) 

( 

/*  Task  waits  here  until  other  task  relinquishes  semaphore  */ 
if  (sem_exch  ==  YES) 

rem_units  =  rqreceiveunits (  sem_t,  1,  Oxffff,  &tl_status  ); 
rqsleep(0,  &tl_status); 
if  (sem_exch  ==  YES) 

rqsendunits(  sem_t,  1,  &tl_status  ); 
rqsleep(0,  &tl_status) ; 

(continued  on  page  102) 
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Listing  Five  (Listing  continued,  text  begins  on  page  46.) 

\ 

rqdeletetask (  (selector) 0,  &tl_status  );  /*  delete  self  */ 


void  task2 () 

{ 

unsigned  rem_units,  t2_status; 

for  (count2  =  0;  count2  <  MAX_LOOPS;  count2++) 

( 

/*  Task  waits  here  until  other  task  relinquishes  semaphore  */ 
if  (sem_exch  ==  YES) 

rem_units  =  rqreceiveunits (  sem_t,  1,  Oxffff,  &t2_status) ; 
rqsleep(0,  &t2_status) ; 
if  (sem_exch  ==  YES) 

rqsendunits(  sem_t,  1,  &t2_status  ); 
rqsleep(0,  &t2_status); 

} 

rqdeletetask (  (selector) 0,  &t2_status  );  /*  delete  self  */ 


main  ( ) 
( 


printf ("\nSemaphore  shuffle  benchmark\n  %U  shuffles  —  \n\n",  MAX_LOOPS*2) ; 

/*  Get  priority  of  main  program  */ 

pri  =  rqgetpriority (  (selector) 0,  Sstatus  ); 

/*  Create  2  tasks;  measure  their  execution  time  WITHOUT  semaphore  shuffling  */ 
sem_exch  =  NO; 

taskl_t  =  rqcreatetask (  pri+1,  taskl,  ptr_u.ptr.sel,  0L,  512,  0,  Sstatus  ); 
if  (status  !=  0)  printf ("Create  task  error\n"); 

task2_t  =  rqcreatetask (  pri+1,  task2,  ptr_u.ptr.sel,  0L,  512,  0,  Sstatus  ); 

strt_sec  =  rqgettime (Sstatus) ;  /*  Start  of  timing  period  */ 

/*  Set  main  program's  priority  below  task  1,2  so  they  run  to  completion  */ 
rqsetpriority (  (selector) 0,  pri+2,  Sstatus  ); 
rqsleep(  0,  sstatus  ); 

end_sec  =  rqgettime (Sstatus) ;  /*  End  of  timing  period  */ 

el_time  =  (unsigned) (end_sec  -  strt_sec) ; 

printf ("  Execution  time  without  semaphore  shuffle  =  %u  secs\n", el_time) ; 

/*  Set  main()  back  to  original  priority  level  */ 
rqsetpriority (  (selector) 0,  pri,  Sstatus  ); 

sem_t  =  rqcreatesemaphore (  1,  1,  0,  Sstatus  ); 
if  (status  !=  0)  printf ("Create  sem  error\n"); 

/*  Re-create  2  tasks.  This  time  they  will  shuffle  semaphore  between  them.  */ 
sem_exch  =  YES; 


taskl_t  =  rqcreatetask)  pri+1,  taskl,  ptr_u.ptr.sel,  0L,  512,  0,  sstatus  ); 
if  (status  !=  0) .printf ("Create  task  error\n"); 

task2_t  =  rqcreatetask!  pri+1,  task2,  ptr_u.ptr.sel,  0L,  512,  0,  Sstatus  ); 

strt_sec  =  rqgettime (Sstatus) ;  /*  Start  of  timing  period  */ 

/*  Set  main  program's  priority  below  task  1,2  so  they  run  to  completion  */ 
rqsetpriority (  (selector) 0,  pri+2,  Sstatus); 
rqsleep(  0,  Sstatus  ); 

end_sec  =  rqgettime (Sstatus) ;  /*  End  of  timing  period  */ 

el_time  =  (unsigned) (end_sec  -  strt_sec)  -  el_time; 

printf ("  %U  semaphore  exchanges  took  %u  seconds\n",  MAX_LOOPS*2,  el_time) 

semshuf_time  =  (  (float)el_time  /  ( (float) MAX_LOOPS  *  2.0)  )  *  1000000.0; 
printf  ("  .  % 5 . 1 f  microseconds  per  shuffle\n\n",  semshuf_time) ; 


dqexit (0) ; 
} 


End  Listing  Five 


Listing  Six 


*\ 


deadbrk.c  —  iRMX  II  Deadlock  break-time  measurement. 

A  low,  medium  and  high  priority  task  is  created.  Deadlock  occurs 
when  the  following  chronological  sequence  happens: 

(1)  low  priority  task  takes  exclusive  control  of  a  critical  resource 

(2)  medium  or  high  priority  task  preempts  it. 

(3)  high  priority  task  requests  resource;  gets  suspended 

(4)  Medium  priority  task  runs,  blocking  other  two  tasks  indefinitely 
This  situation  is  handled  in  iRMX  by  acquiring  a  "region"  before 
using  critical  resource,  and  relinquishing  it  after  use.  This  benchmark 
measures  the  overhead  involved  in  "breaking  the  deadlock" . 

Compiler:  Intel  iC-286  V4.1  (LARGE  model).  Q3  1989,  by  R.  P.  Kar  ^ 


♦include  <stdio.h> 
♦include  <rmxc.h> 


♦define  MAX_LOOPS  10000 

/*  Note:  This  is  a  CPU-dependent  value.  It  must  be  set  such  that  the 

*  execution  time  for  this  loop:  for  (j=0;  j  <  DELAY;  j++)  spare++ 

*  is  slightly  longer  than  one  iRMX  sleep  period. 

*/ 

♦define  DELAY  4000 


unsigned 
selector 
unsigned  char 
enum 


el_time,  spare,  status; 

taskl_t,  task2_t,  task3_t,  region_t; 

pri; 

YESNO  (NO,  YES)  dead_brk; 
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unsigned  long  countl,  count2,  count3,  max_loops; 
unsigned  long  strt_sec,  end_sec; 
float  deadbrk_time; 

/*  "union"  used  to  decompose  a  pointer  into  segment : offset  */ 
typedef  struct  {unsigned  offset;  selector  sel;}  ptr_s; 
union  {  unsigned  ‘pointer;  ptr_s  ptr;  }  ptr_u; 

/*  Low  priority  task  */ 
void  taskl () 

{ 

unsigned  tl_status,  j; 
while  (1) 

{ 

if  (countl,  ==  max_loops) 

{  printf ("deleting  tasklW); 

rqdeletetask(  (selector) 0,  &tl_status  );  /*  delete  self  */ 

} 

/*  Get  control  over  critical  region  */ 
rqreceivecontrol (  region_t,  &tl_status  ); 

for  (j  =  0;  j  <  DELAY;  j++)  spare++;  /*  delay  loop  */ 

count 1++; 

rqsendcontrol (  &tl_status  ); 

} 

1 

/*  Medium  priority  task.  Only  uses  CPU  time  and  sleep  periodically.  */ 
void  task2 () 

( 

unsigned  j,  t2_status; 

while  (1) 

( 

if  (count2  ==  max_loops) 

(  printf ("deleting  task2\n"); 

rqdeletetask (  (selector) 0,  &t2_status  );  /*  delete  self  */ 

} 

for  (j  =  0;  j  <  DELAY/4;  j++)  spare++;  /*  delay  loop  */ 

rqsleep(l,  &t2_status); 
count2++; 

} 


/*  High  priority  task.  Potential  deadlock  when  it  tries  to  gain  control 
of  the  "region"  resource,  because  low-priority  task  holds  region  mostly. 

*/ 

void  task3 () 

{ 

unsigned  t3_status; 

while  (1) 

( 

if  (count3  ==  max_loops) 

{  printf ("deleting  task3\n"); 

rqdeletetask (  (selector) 0,  &t3_status  );  /*  delete  self  */ 

1 

rqsleep(l,  &t3_status) ; 

/*  Ask  for  control  of  the  region.  Relinquish  control  immediately  after 
receiving  it.  If  taskl  is  not  already  holding  region,  this  should 
take  very  little  time.  Otherwise,  OS  must  break  deadlock. 

*/ 

if  (dead_brk  ==  YES) 

(  rqreceivecontrol (  region_t,  &t3_status  ); 
rqsendcontrol (  &t3_status  ); 

) 

count3++; 

} 

1 

/**********************  Main  program  ***********************/ 
main(  argc,  argv  ) 

unsigned  argc; 
char  *argv[]; 

( 

if  (argc  >  1) 

max_loops  =  (unsigned) atoi (argv(l] ) ; 
else  max_loops  =  MAX_LOOPS; 

printf ("NnDeadlock  break  time  benchmark\n  %U  loops. . .\n\n",max_loops) ; 

/*  Get  priority  of  main  program  */ 

pri  =  rqgetpriority (  (selector) 0,  Sstatus  ); 

/*  Create  three  tasks.  Taskl  has  lowest  priority,  task3  has  highest. 

*  Measure  their  execution  time  WITHOUT  deadlocks. 

*/ 

countl  =  count 2  =  count 3  =  0; 
dead_brk  =  NO; 

taskl_t  =  rqcreatetask (  pri+3,  taskl,  ptr_u.ptr.sel,  0L,  512,  0,  fistatus  ); 
if  (status  !=  0)  printf ("Create  task  error\n"); 

task2_t  =  rqcreatetask (  pri+2,  task2,  ptr_u.ptr.sel,  0L,  512,  0,  Sstatus  ); 

task3_t  =  rqcreatetask (  pri+1,  task3,  ptr_u.ptr.sel,  0L,  512,  0,  fistatus  ); 

strt_sec  =  rqgettime (&status) ;  /*  Start  of  timing  period  */ 

/*  Set  main  program's  priority  below  task  1,2,3  so  they  run  to  completion  */ 
rqsetpriority (  (selector) 0,  pri+4,  fistatus  ); 

while  (  (countl  <  max_loops)  ! !  (count2  <  max_loops)  ! I  (count3  <  max_loops)  ) 
rqsleep(  10,  Sstatus  ); 

(continued  on  page  104) 
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RHEA L STONE 


Listing  Six  (Listing  continued,  text  begins  on  page  46.) 

end_sec  =  rqgettime (4status) ;  /*  End  of  timing  period  */ 

el_time  =  (unsigned) (end_sec  -  strt_sec) ; 

printf("  Execution  time  without  deadlocks  =  %u  secs\n\n",el_time) ; 

/*  Set  main()  back  to  original  priority  level  */ 
rqsetpriority (  (selector) 0,  pri,  4status  ); 

/*  Create  a  "region".  To  ensure  mutually  exclusive  access  to  a  critical 
resource  a  task  must  acquire  the  region  first  */ 
region_t  =  rqcreateregion(  1,  4status  ); 
if  (status  !=  0)  printf ("Create  region  errorXn"); 

count 1  =  count 2  =  count 3  =  0; 
dead_brk  =  YES; 

/*  Re-create  tasks  1,2,3.  Now  tasks  143  will  compete  for  region  */ 
taskl_t  =  rqcreatetask (  pri+3,  taskl,  ptr_u.ptr.sel,  0L,  512,  0,  4status  ); 
if  (status  !=  0)  printf ("Create  task  errorXn"); 

task2_t  =  rqcreatetask (  pri+2,  task2,  ptr_u.ptr.sel,  0L,  512,  0,  4status  ); 

task3_t  *  rqcreatetask (  pri+1,  task3,  ptr_u.ptr.sel,  0L,  512,  0,  4status  ); 

strt_sec  =  rqgettime(4status) ;  /*  Start  of  timing  period  */ 

/*  Set  main  program's  priority  below  tasks  1,2,3  so  they  run  to  completion  */ 
rqsetpriority (  (selector) 0,  pri+4,  4status); 

while  (  (countl  <  max_loops)  I \  (count2  <  max_loops)  ! !  (count3  <  max_loops)  ) 
rqsleep(  10,  4status  ) ; 

end_sec  =  rqgettime (4 status ) ;  /*  End  of  timing  period  */ 

el_time  *  (unsigned) (end_sec  -  strt_sec)  -  el_time; 

printf ("  %U  deadlock  resolutions  took  %u  seconds\n",  count3,  el_time) ; 

deadbrk_time  =  (  ( float )el_time/ (float) count 3  )  *  1000000.0; 

printf ("  .  %6.1f  microseconds  per  resolution\n\n",  deadbrk_time) ; 

dqexit (0) ; 

} 

End  Listing  Six 


Listing  Seven 


it_msg.c  —  iRMX  II  inter-task  data  message  latency  measurement. 
First  run  the  code  of  two  tasks  serially  (no  messages  sent) .  Then 
create  two  tasks  and  a  "mailbox"  and  measure  how  much  extra  time  is 
needed  to  send  a  fixed  number  of  messages  from  task  1  to  task  2. 
Compiler:  iC-286  V4.1  (LARGE  model).  Q4  1989,  by  R.  P.  Kar 


A 


♦include  <stdio.h> 
♦include  <rmxc.h> 


♦define  MAX  LOOPS  200000L 


unsigned  long 

selector 

unsigned 

unsigned  long 

float 

char 


strt_sec,  end_sec; 

taskl_t,  task2_t,  mbox_t; 

pri,  el_time,  msg_length,  status; 

countl,  count2; 

it_msg_time; 

msg_buf (10)  =  "MESSAGE\0", 
recv_buf [ ] ; 


/*  "union"  used  to  decompose  a  pointer  into  segment : offset  */ 
typedef  struct  (unsigned  offset;  selector  sel; )  ptrs; 
union  (  unsigned  "pointer;  ptr_s  ptr;  )  ptr_u; 

/*  This  task  sends  data  messages,  to  task  2  that  is  waiting  to  receive  */ 
void  taskl () 

( 

unsigned  loc_status; 

for  (countl  =  0;  countl  <  MAX_LOOPS;  countl++) 

(  /*  Put  a  serial  ♦  on  the  message  */ 

msg_buf[8]  =  (unsigned  char) countl  /  256; 
rqsenddata(  mbox_t,  msg_buf,  10,  4loc  status  ); 

) 

printf ("Task  1  exiting. ... \n") ; 

rqdeletetask (NULL,  4status);  /*  delete  self  */ 


/*  This  task  receives  the  data  messages  */ 
void  task2 () 


unsigned  loc_status; 

for  (count2  =  0;  count2  <  MAX_LOOPS;  count2++) 
msg_length  =  rqreceivedata (  mbox_t,  recv_buf,  Oxffff,  4loc_status  ); 
printf ("  Last  message  received...  %s  %u  (length  %u)\n",  recv_buf, 
(unsigned) recv_buf [8] ,  msg_length  ); 

rqdeletetask (NULL,  4status);  /*  delete  self  */ 


/***************************  main  PROGRAM  ***************************/ 

/*  First  parameter  to  "rqcreatemailbox"  ==>  data  mailbox,  FIFO  queues  */ 
♦define  MBOX_FLAG  0x0020 

main  () 

{ 

printf ("  Inter-task  message  latency  measurement^") ; 
printf ("  Sending  %D  data  messages ... \n\n",  MAX_LOOPS) ; 

/*  Set  up  a  mailbox  for  inter-task  data  communication  */ 
mbox_t  =  rqcreatemailbox (  MBOX_FLAG,  4status  ); 
if  (status  !=  0)  printf ("rqcreatemailbox  errorXn"); 

/*  Measure  serial  execution  time  of  tasks  1,2  (without  messages)  */ 

strt_sec  =  rqgettime (4status) ;  /*  Start  of  timing  period  */ 

for  (countl  =  0;  countl  <  MAX_LOOPS;  countl++) 

(  /*  Put  a  serial  ♦  on  the  message  */ 

msg_buf[8]  =  (unsigned  char) countl  /  256; 

/"  rqsenddata (  mbox_t,  msg_buf,  10,  4loc_status  );  */ 

) 

for  (count2  =  0;  count2  <  MAX_LOOPS;  count2++) 

/*  msg_length  =  rqreceivedata (  mbox_t,  recv_buf,  Oxffff,  4loc_status  )  */; 
end_sec  =  rqgettime (4status) ;  /*  End  of  timing  period  */ 

el_time  =  (unsigned) (end_sec  -  strt_sec); 

/*  Place  a  pointer  to  any  variable  in  union  "ptr_u",  so  the  data  segment 
of  this  program  becomes  known. 

*/ 

ptr_u. pointer  =  4status; 

/*  Get  main  program's  priority  level  */ 
pri  =  rqgetpriority  (NULL,  4status); 

taskl_t  =  rqcreatetask  (pri+2,  taskl,  ptr_u.ptr .sel,  0L,  512,  0,  4status) ; 
if  (status  !=  0)  printf ("rqcreatetask  errorXn"); 

/*  Task  2  is  created  with  a  higher  priority  than  task  1.  This  ensures  that  if 

*  it  is  waiting  at  a  mailbox  for  a  message  from  task  1,  it  will  be  scheduled 

*  as  soon  as  the  message  is  sent. 

*/ 

task2_t  =  rqcreatetask  (pri+1,  task2,  ptr_u.ptr.sel,  0L,  512,  0,  4status); 

strt_sec  =  rqgettime (4status) ;  /*  Start  of  timing  period  */ 

/*  Set  main  program's  priority  below  task  1,2  so  they  run  to  completion  */ 
rqsetpriority (  (selector) 0,  pri+3,  4status  ); 
rqsleep(  0,  4status  ); 

end_sec  =  rqgettime (4status) ;  /*  End  of  timing  period  */ 

/*  Set  main  program  back  to  initial  priority  */ 
rqsetpriority (  (selector) 0,  pri,  4status  ); 

el_time  =  (unsigned) (end_sec  -  strt_sec)  -  el_time; 

it_msg_time  =  (  ( float ) el_time  *  1000000.0  )  /  ( float ) MAX_LOOPS  ; 

printf ("  Inter-task  message  latency  +  task  switch  time  =  %6.1f 

microsecs\n", 

it_msg_time) ; 

/*  Delete  mailbox  */ 
rqdeletemailbox (  mbox_t,  4status  ); 

dqexit (0) ; 

)  End  listings 
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BOUNDING  BOX  METHOD 


Listing  One  (Text  begins  on  page  56.) 

/*  FONT1  STRUCTURE  DEFINITIONS  */ 

struct  fontlhead  {  /*  standard  character  font  header  */ 

unsigned  char  fnttype;  /*  font  structure  type:  */ 

/*  non-compressed  type  =  0x16  or  compressed  type  =  0x14  */ 
char  fntname[13] ;  /*  font  name:  always  followed  with  a  '.set'  extension*/ 

unsigned  char  fntcheck;  /*  check  digit:  verifies  a  Data  Transforms  font:  */ 
/*  non-compressed  font  =  Oxba,  compressed  font  =  Oxdc  */ 
unsigned  char  fntbase; 

/*  baseline  count  (in  pixels)  from  top  to  bottom,  top  =  0  */ 
unsigned  char  fnttotal;  /*  total  characters  in  font:*/ 

/*  limited  to  the  lower  94  ASCII  characters:  0x21  -  0x7E  */ 


unsigned  char  fntstart; 
unsigned  char  fntstatus;  / 
unsigned  char  fnthsize; 
unsigned  char  fntvsize; 
unsigned  char  fntbytes; 
unsigned  char  fntspaceh; 
unsigned  char  fntchargap; 
unsigned  char  fntlfgap; 
int  fntlength; 
unsigned  char  fntpitch; 

/*  bits  0-6 
/*  bit  1  ... 
unsigned  char  fntinvert; 
unsigned  char  fnthbold; 
unsigned  char  fntvbold; 
unsigned  char  fnthmag; 
unsigned  char  fntvmag; 
unsigned  char  fnthfract; 
unsigned  char  fntvfract; 


/*  starting  character  */ 
proportional  or  non-proportional:  0=non-prop. */ 
/*  horizontal  cell  size  in  pixels  */ 

/*  vertical  cell  size  in  pixels  */ 

/*  number  of  horizontal  bytes  in  current  cell*/ 
/*  space  bar  horizontal  size  in  pixels  */ 

/*  pixels  between  characters  default  */ 

/*  pixels  between  linefeeds  default  */ 

/*  total  length  of  file  */ 

/*  italics  pitch  (0  =  none)  */ 

...  number  of  scanlines  to  skip  */ 

0  =  decrement  xpos,  1  =  increment  xpos  */ 

/*  0  =  dont  invert,  1  =  invert  */ 

/*  number  of  overlapping  bits  horizontal  */ 

/*  number  of  overlapping  bits  vertical  */ 

/*  integral  horizontal  bit  magnification  */ 

/*  integral  vertical  bit  magnification  */ 

/*  fractional  horizontal  bit  magnification  */ 
/*  fractional  vertical  bit  magnification  */ 


unsigned  char  fntdirection; 

/*  Print  direction  0=left  to  right, 1 . .3=counterclock  */ 
unsigned  char  fntrot90;  /*  rotation  0=up,  1 . . 3=counterclock  1...3  */ 


unsigned  char  fnthflip; 
unsigned  char  fntvflip; 
unsigned  char  fntcolor; 


/*  horizontal  flip  0  =  no,  1  =  yes  */ 
/*  vertical  flip  0  =  no,  1  =  yes  */ 

/*  color  of  font  */ 


/*  bits  0  -  3  . . .  foreground  color  */ 

/*  bit  0  ...  strike  black  ribbon  */ 

/*  bit  1  ...  strike  blue  ribbon  */ 

/*  bit  2  ...  strike  red  ribbon  */ 

/*  bit  3  ...  strike  yellow  ribbon  */ 

/*  bits  4  -  7  ...  background  color  */ 

/*  bit  4  ...  strike  black  ribbon  */ 

/*  bit  5  ...  strike  blue  ribbon  */ 

/*  bit  6  ...  strike  red  ribbon  */ 

/*  bit  7  ...  strike  yellow  ribbon  */ 

unsigned  char  fntsubtype;  /*  subcategory  type  of  this  font  */ 
/*  0  =  normal  font  subtype  */ 

/*  1  =  equation  roman  font  subtype  */ 

/*  2  =  equation  symbol  font  subtype  */ 
unsigned  char  fntunused[18] ;  /*  unused  bytes  */ 


struct  fontl  (  /*  standard  character  font  (type  =  0x16)  */ 

struct  fontlhead  fhd;  /*  font  header  */ 

char  *fntcellptr (FONT1TOTAL  +  1]; 

/*  offsets  from  beginning  of  file  to  character  bitmaps  */ 
char  fntcellwidch (FONT1TOTAL  +  1];  /*  cell  widths  if  proportional  */ 


End  Listing  One 


Listing  Two 


/*  FONT2  STRUCTURE  DEFINITIONS  */ 


struct  font2  { 

struct  fontlhead  fhd2;  /*  font  header  */ 

unsigned  int  fnt2cellseg [F0NT2T0TAL  +1]; 

/*  array:  segment  pointers  to  characters*/ 


int  fnt2cellhsize [FONT2TOTAL  ■ 


/*  array:  cell  horiz  sizes  in  bits  */ 


int  fnt2cellhof fset [FONT2TOTAL  +  1];  /*  array:  cell  horiz  offsets  in  bits*/ 


int  fnt2cellhbytes (FONT2TOTAL  +  1); 
int  fnt2cellvsize [FONT2TOTAL  +  1] ; 


/*  array:  cell  horiz  size  in  bytes  */ 
/*  array:  cell  vert  sizes  in  bits  */ 


int  fnt2cellvof fset [FONT2TOTAL  +  1];  /*  array:  cell  vert  offsets  in  bits  */ 


End  Listings 
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E  X  A  M  I  N  I  N  G _ R  0  0  M 


Listing  One  (Text  begins  on  page  72.) 


File:  Kaboooom.c 

Purpose:  Allows  the  user  to  'walk'  through  a  minefield;  a  detector  shows 
how  many  mines  are  immediately  adjacent  to  you.  As  you  visit  a  cell,  it 
leaves  a  marker  telling  you  how  many  were  next  to  you,  and  you  have  the 
ability  to  mark  cells  with  a  character  (assumably  to  mark  mines) . 

Changes : 

11/10/89  (tdeii)  If  you  call  the  program  with  "/s"  or  "/S",  it  gives 
you  a  "safer"  game,  where  it  does  not  let  you  walk  on  spaces  that  you 
have  marked  {whether  there  is  a  mine  there  or  not!) 

11/11/89  (tdeii)  Allows  you  to  press  "?"  and  get  some  help  starting  at  your 
current  position;  will  mark  mines  that  it  knows  (by  deducing  their  position) , 
and  "visit"  places  that  it  knows  are  safe.  This  propagates  until  it  cannot 
deduce  anything  else  (see  EvaluatePosition) . 

♦include  "stdio.h" 

♦include  "stdarg.h" 

♦include  "stdlib.h" 

♦include  "dos.h" 

♦include  "conio.h" 

♦include  "string.h" 

♦define  SCREEN_X  80 
♦define  SCREEN_Y  25 
♦define  GRID_X  15 
♦define  GRID_Y  9 
♦define  TRUE  1 
♦define  FALSE  0 

♦define  bEMPTY  0 
♦define  bVISITED  1 
♦define  bBOMB  2 
♦define  bCURRENT  3 
♦define  bFINISH  4 
♦define  bEXPLODED  5 

♦define  MAKECOLOR( fore, back)  ( (back) *16+ (fore) ) 
typedef  int  BOOL; 

typedef  struct  tagADJACENCYGROUP  { 

int  BombCount;  /*  Number  of  bombs  located  in  this  adj.  group  */ 

int  CellCount;  /*  Number  of  cells  filled  */ 

int  Cell [8) (2] ;  /*  x,y  coordinates  of  up  to  8  cells  */ 

)  ADJACENCYGROUP; 


int  Board [GRID_X] [GRID_Y]; 
int  UserMark [GRID_X] [GRID_Y] ; 
int  nNumMines; 
int  UserX,  UserY; 

BOOL  bShowBombs; 

BOOL  bSafeGame; 


/*  Board;  see  codes  above  (bXXX) 

/*  User  marks;  0  =  none,  'M'  =  mine 
/*  Number  of  mines  on  board 
/*  Current  user  X  and  Y  position 
/*  TRUE  if  program  shows  bombs  (it 
/*  does  this  after  you  win  or  lose) 
/*  TRUE  if  program  does  not  let  you 
/*  walk  on  mines  you  have  marked 


return  (nCount); 

) 

void  DisplayCell (int  x,  int  y) 

{ 

int  Char; 

Char  =  UserMark [x] [y] ; 
if  (Char  ==  0)  { 

Char  =  32; 

} 

DisplayChar (x*4+l,  y*2+l,  Char,  MAKECOLOR (14, 1) ) ; 
DisplayChar (x*4+3,  y*2+l,  Char,  MAKECOLOR ( 1 4 , 1 )) ; 
switch  (Board[x) [y] )  { 
case  bEMPTY: 

Char  =  '  '  ; 
break; 

case  bVISITED: 

Char  =  '0'  +  CountMines (x,  y) ; 
break; 
case  bBOMB: 

if  (bShowBombs)  ( 

Char  =15; 

}  else  { 

Char  ='  ' ; 

} 

break; 

case  bCURRENT: 

Char  =  2; 
break; 

case  bFINISH: 

Char  =  19; 
break; 

case  bEXPLODED: 

Char  =  15; 
break; 

I 

if  (Char  !=  0)  { 

DisplayChar (x*4+2,  y*2+l,  Char,  MAKECOLOR ( 1 4 , 1 )) ; 

) 


ADJACENCYGROUP  Ad jacencyGroup [GRID_X] [GRID_Y] ;  /*  AG  for  each  board  pos 
char  szClear[79]  =  " 

void  Pause (void) 


void  Initialize (void) 

( 

unsigned  int  nRand;  /*  seed  for  randor 

struct  dostime_t  sDosTime;  /*  time  structure 

_dos_gettime (SsDosTime) ; 

nRand  =  (unsigned  int) { (sDosTime. hsecond  *  600) 
(sDosTime. second  *  10)  + 
(sDosTime. minute  /  6)); 

srand (nRand) ; 

) 

void  PaintBoard(void) 

{ 

int  x,  y,  i; 

for  (x=0;  x<SCREEN_X;  x++)  { 
for  (y=0;  y<SCREEN_Y;  y++)  ( 

DisplayChar (x,  y,  '  ' ,  MAKECOLOR ( 1 4 ,  1)); 


/*  seed  for  random  number  generator 
/*  time  structure;  used  for  above  seed 


if  (getch()  ==  0)  getch(); 


void  GetXY_(int  *pX,  int  *pY) 

{ 

union  REGS  regs; 
regs.h.ah  =  3; 
regs.h.bh  =  0; 
int86(0xl0,  &regs,  &regs); 
if  (pY  !=  NULL)  ( 

(*pY)  =  regs.h.dh; 

) 

if  (pX  ! =  NULL)  { 

(*pX)  =  regs.h.dl; 


void  GotoXY_(int  x,  int  y) 

{ 

union  REGS  regs; 
regs.h.ah  =  2; 

regs.h.dh  =  (unsigned  char)y; 
regs.h.dl  =  (unsigned  charjx; 
regs.h.bh  =  0; 
int86(0xl0,  &regs,  Sregs); 

) 

int  nRandom(int  nMax) 


/*  display  page  0  */ 


/*  display  page  0  */ 


/**  Draw  left  and  right  sides  **/ 

DisplayChar (0,  0,  218,  MAKECOLOR ( 1 4 , 1 )) ;  /*upper  left  corner  */ 
DisplayChar (GRID_X* 4,  0,  191,  MAKECOLOR (14, 1) ) ;  /*upper  right  corner  */ 
for  (y=l;  y<=GRID_Y;  y++)  ( 

DisplayChar (0,  y*2,  195,  MAKECOLOR ( 1 4 , 1 )) ;  /*  left  edge  */ 

DisplayChar (GRID_X*4,  y*2,  180,  MAKECOLOR ( 1 4 , 1 )) ;  /*  right  edge  */ 

} 

DisplayChar (0,  GRID_Y*2,  192,  MAKECOLOR ( 1 4 , 1 )) ;  /*  lower  left  corner  */ 

DisplayChar (GRID_X*4,  GRID_Y*2,  217,  MAKECOLOR (14, 1) ) ;  /*lower  right  */ 
/**  Draw  inside  corners  **/ 
for  (x=l;  x<GRID_X;  x++)  ( 

DisplayChar (x*4,  0,  194,  MAKECOLOR ( 1 4 , 1 )) ;  /*  top  edge  */ 
for  (y=l;  y<GRID_Y;  y++)  { 

DisplayChar (x*4,  y*2,  197,  MAKECOLOR ( 1 4 , 1 )) ;  /*  intersections  */ 

} 

DisplayChar (x*4,  GRID_Y*2,  193,  MAKECOLOR ( 1 4 , 1 )) ;  /*  bottom  edge  */ 

} 

/**  Draw  connecting  lines  **/ 
for  (x=0;  x<=GRID_X;  x++)  ( 

for  (y=0;  y<=GRID_Y;  y++)  {  — 

if  (y  ! =  GRID_Y)  { 

DisplayChar (x*4,  y*2+l,  179,  MAKECOLOR(14, 1) ) ;  /*  verticals  */ 

) 

if  (x  !=  GRID_X)  { 
for  (i=l;  i<4;  i++)  ( 

DisplayChar (x*4+i,  y*2,  196  ,  MAKECOLOR ( 1 4 , 1 )) ;  /*  horizontals  */ 


return  ( (int) ( (double) rand ()  /  RAND_MAX  *  (double) nMax)); 


void  DisplayChar (int  x,  int  y,  char  cChar,  int  nColor) 

I 

char  far  *cPos; 

if  { (x>=0  &&  x<SCREEN_X)  && 

(y>=0  &&  y<SCREEN_Y) )  { 
cPos  =  MK_FP (  0x0b800, ( (x  +  y*80)  «  1)); 

*cPos  =  cChar; 

* (cPos+1)  =  (char) nColor; 


int  CountMines (int  x,  int  y) 

{ 

int  i,  j; 
int  nCount; 
nCount  =  0; 

for  (i=-l;  i<=l;  i++)  ( 
for  ( j=— 1 ;  j<=l;  j++)  { 

if  ( (x+i  >=  0)  &&  (x+i  <  GRID_X)  && 

(y+j  >=  0)  &&  (y+j  <  GRID_Y) )  ( 
if  ( (Board[x+i] [y+ j]  ==  bBOMB) 

(Board[x+i] [y+j]  ==  bEXPLODED) )  { 
nCount ++; 


GotoXY_ (0,  SCREEN_Y  -  1); 
for  (x=0;  x<GRID_X;  x++)  { 
for  (y=0;  y<GRID_Y;  y++)  { 
DisplayCell (x,  y) ; 


void  SetUpBoard(void) 


int  i,  j; 
int  nMines; 

BOOL  bDone; 

char  cBuffer[80]; 

bShowBombs  =  FALSE; 

/**  First,  get  number  of  bombs  **/ 
nNumMines  =0; 

while  ((nNumMines  <  10)  !!  (nNumMines  >  40))  { 
GotoXY  (0,  24); 


(continued  on  page  110) 
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EXAM  ININ  G  ROOM 


Listing  One  (Listing  continued,  text  begins  on  page  72.) 


print f ("How  many  bombs  do  you  want?  (10-40)??  "); 
fgets (cBuffer,  sizeof (cBuffer) ,  stdin); 
sscanf (cBuffer,  "Id",  SnNumMines) ; 

} 

/**  next,  clear  out  board  &  user  scratchpad  **/ 
for  (i=0;  i<GRID_X;  i++)  ( 
for  ( j=0;  j<GRID_Y;  j++)  { 

Board[i] [j]  =  0; 

UserMark [i ] [ j ]  =  0; 

} 

) 

for  (nMines=0;  nMines<nNumMines;  nMines++)  ( 
bDone  =  FALSE; 
while  (! bDone)  ( 

i  =  nRandom(GRID_X) ;  /*  First  you  roll  it,  */ 

j  =  nRandom (GRID_Y) ;  /*  Then  you  pat  it,  */ 

if  ( (Board[i] ( j]  ==  bEMPTY)  && 

( !  ( (i  <=  1)  &&  (j  <=  1)))  && 

( !  ( (i  >=  GRID_X  -  2)  &&  (j  >=  GRID  Y  -  2))) 

)  ( 

bDone  =  TRUE; 

} 

) 

Board[i] [j]  =  bBOMB;  /*  Then  you  mark  it  with  a  'B'  */ 

/*  Set  user  at  position  0,  0  */ 

UserX  =  0; 

UserY  =  0; 

Board [0] [0]  =  bCURRENT; 

/*  Set  finish  (hq)  at  position  GRID_X,  GRID_Y  */ 

Board [GRID_X  -  1] [GRID_Y  -  1]  =  bFINISH; 

/*  Display  board  on  screen  */ 

PaintBoardO ; 

} 

BOOL  Travel (int  dx,  int  dy) 


int  NewX,  NewY; 
BOOL  blnvalid; 
BOOL  bAbort; 
BOOL  bBombWalk; 


/*  New  X  and  Y  coordinates  of  user  */ 
/*  TRUE  if  trying  to  walk  off  board  */ 
/*  TRUE  if  user  won  or  lost  (abort  game)  */ 
/*  TRUE  if  user  tried  to  walk  on  a  bomb  */ 


bAbort  =  FALSE; 

NewX  =  UserX  +  dx; 

NewY  =  UserY  +  dy; 
blnvalid  =  FALSE; 
bBombWalk  =  FALSE; 

if  ( (NewX  <  0)  ! I  (NewX  >=  GRID_X) )  { 
blnvalid  =  TRUE; 

} 

if  ((NewY  <  0)  : :  (NewY  >=  GRID_Y) )  { 
blnvalid  =  TRUE; 

) 

if  (((blnvalid)  &&  (bSafeGame)  &&  (UserMark [NewX] [NewY]  ==  'M'))  ( 
blnvalid  =  TRUE; 
bBombWalk  =  TRUE; 

) 

if  (blnvalid)  { 

GotoXY_ (0,  SCREEN_Y  -  1); 

printf ("**  INVALID  MOVE  **  ...  press  any  key..."); 
if  (bBombWalk)  { 

printf ("(You  must  un-mark  it.)"); 

} 

Pause  () ; 

GotoXY_(0,  SCREEN_Y  -  1); 
printf (szClear) ; 

}  else  { 

if  (Board [NewX] [NewY]  ==  bBOMB)  { 
bAbort  =  TRUE; 

Board[UserX] [UserY]  =  bVISITED; 

DisplayCell (UserX,  UserY); 

Board [NewX] [NewY]  =  bEXPLODED; 

DisplayCell (NewX,  NewY)  ; 

GotoXY_(0,  22); 

printf ("********  YOU  HAVE  STEPPED  ON  A  BOMB!!  ********■•); 

Pause  () ; 

GotoXY_(0,  22); 
printf (szClear)  ; 

GotoXY_(0,  22); 

}  else  { 

if  ((NewX  ==  GRID_X-1)  &&  (NewY  ==  GRID  Y-l) )  { 
bAbort  =  TRUE; 

Board [UserX] [UserY]  =  bVISITED; 

DisplayCell (UserX,  UserY); 

Board [NewX] [NewY]  =  bCURRENT; 

DisplayCell (NewX,  NewY) ; 

GotoXY_(0,  22); 

printf ("*************  YOU  HAVE  WON!!  *************"); 

Pause () ; 

GotoXY_(0,  22); 
printf (szClear) ; 

GotoXY_(0,  22); 

}  else  { 

Board[UserX] [UserY]  =  bVISITED; 

DisplayCell (UserX,  UserY); 

UserX  =  NewX; 

UserY  =  NewY; 

Board[UserX] [UserY]  =  bCURRENT; 

DisplayCell (UserX,  UserY); 

1 


GotoXY_(0,  GRID_Y*2+2) ; 

printf ("Number  of  mines  around  you:  Id",  CountMines (UserX,  UserY)); 
GotoXY_(0,  SCREEN_Y  -  1); 
return  (bAbort); 

1 

void  PlaceUserMark (void) 

{ 

BOOL  bDone,  bAbort; 


int  Ch; 

int  NewX,  NewY; 
int  dx,  dy; 


bAbort  =  FALSE; 

GotoXY_(0,  24); 

printf ("Mark  in  which  direction?  (ESC=abort) ") ; 
bDone  =  FALSE; 
while  (! bDone)  { 
bDone  =  TRUE; 

Ch  =  getch(); 
switch  (Ch)  { 
case  0: 

Ch  =  getch ( ) ; 
switch  (Ch)  { 

case  71;  /*  home  */ 

dx  =  -1; 
dy  =  -1; 


break; 

case  72:  /*  up  arrow  */ 

dx  =  0; 
dy  =  -1; 
break; 

case  73:  /*  page  up  */ 

dx  =  1; 
dy  =  -1; 
break; 

case  75:  /*  left  arrow  */ 

dx  =  -1; 
dy  =  0; 
break; 

case  77:  /*  right  arrow  */ 

dx  =  1; 
dy  =  0; 
break; 

case  79:  /*  end  */ 

dx  =  -1; 
dy  =  1; 
break; 

case  80:  /*  down  arrow  */ 

dx  =  0; 
dy  =  1; 
break; 

case  81:  /*  page  down  */ 

dx  =  1; 
dy  =  1; 
break; 

default: 

bDone  =  FALSE; 
break; 


break; 
case  ' 7' : 
dx  =  -1; 
dy  =  -1; 
break; 
case  ' 8'  : 
dx  =  0; 
dy  =  -1; 
break; 
case  ' 9' : 
dx  =  1; 
dy  =  -1; 
break; 
case  ' 4'  : 
dx  =  -1; 
dy  =  0; 
break; 
case  ' 6' : 
dx  =  1; 
dy  =  0; 
break; 
case  ' 1' : 
dx  =  -1; 
dy  =  1; 
break; 
case  ' 2' : 
dx  =  0; 
dy  =  1; 
break; 
case  ' 3' : 
dx  =  1; 


/*  home  */ 


/*  up  arrow  */ 


/*  page  up  */ 


/*  left  arrow  */ 


/*  right  arrow  */ 


/*  end  */ 


/*  down  arrow  */ 


/*  page  down  */ 


dy  =  1; 
break; 
case  27: 
case  13: 
case  10: 
case  8: 

bAbort  =  TRUE; 
break; 
default: 

bDone  =  FALSE; 
break; 


GotoXY_ (0,  24); 
printf (szClear) ; 
if  (! bAbort)  ( 

NewX  =  UserX  +  dx; 

NewY  =  UserY  +  dy; 

if  ((NewX  <  0)  I  1  (NewX  >=  GRID  X)  II  (NewY  <  0) 
GotoXY_(0,  24); 

printf ("ERROR:  Out  of  bounds!!"); 

Pause () ; 

GotoXY_(0,  24); 
printf (szClear)  ; 

)  else  ( 

GotoXY_(0,  24); 

if  (UserMark [NewX] [NewY]  !=  0)  ( 

Ch  =  0; 

}  else  ( 


(NewY  >=  GRID_Y) )  { 
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Ch  =  ' M' ; 

} 

UserMark [NewX] [NewY]  =  Ch; 
DisplayCell (NewX,  NewY) ; 


GotoXY_(0,  24); 

} 

void  ComputeAdjacency (int  x,  int  y) 

{ 

int  dX,  dY; 
int  BombCount; 
int  Cell; 

if  ((x  >=  0)  &&  (x  <  GRID_X)  &&  (y  >=  0)  &&  (y  <  GRID_Y) )  { 
if  ( (Board[x] [y]  ==  bVI SITED)  (Board[x] [y]  ==  bCURRENT) )  { 

BombCount  =  CountMines (x,  y) ; 

Cell  =  0; 

for  (dX— 1;  dX<=l;  dX++)  ( 
for  (dY— 1;  dY<=l;  dY++)  { 

if  ( ! ( (dX  ==  0)  &&  (dY  ==  0)))  { 

if  ((x+dX  >=  0)  &&  (x+dX  <  GRID_X)  && 

(y+dY  >=  0)  &&  (y+dY  <  GRID_Y) )  { 
if  ( (Board [x+dX] [y+dY]  !=  bVISITED)  && 

(Board [x+dX] [y+dY]  !=  bCURRENT))  { 
if  (UserMark [x+dX] [y+dY]  !=  0)  ( 

BombCount — ; 

}  else  { 

AdjacencyGroup[x] [y] .Cell [Cell] [0]  =  x+dX; 
AdjacencyGroup[x] [y] .Cell[Cell] [1]  =  y+dY; 
Cell++; 


} 


} 

AdjacencyGroup[x] [y ] .BombCount 
AdjacencyGroup [x] [y] .CellCount 
}  else  ( 

AdjacencyGroup [x] [y] .CellCount 
AdjacencyGroup [x] [yj .BombCount 

} 


BombCount; 

Cell; 


0; 

-1;  /**  Don't  look  flag  */ 


int  AddToPositionList (int  PositionList [GRID_X  *  GRID_Y](2], 
int  PositionListHead,  int  x,  int  y) 

{ 

int  nlndex; 

BOOL  bFound; 

ComputeAdjacency (x,  y) ; 
bFound  =  FALSE; 

for  (nlndex=0;  (nIndex<PositionListHead)  &&  (IbFound);  nlndex++)  ( 

if  ( (PositionList [nlndex] [0]  ==  x)  &&  (PositionList [nlndex] [1]  ==  y) )  { 
bFound  =  TRUE; 

} 

} 

if  (IbFound)  { 

PositionList [PositionListHead] [0]  =  x; 

PositionList [PositionListHead] [1]  =  y; 

PositionListHead++; 

} 

if  (PositionListHead  >  GRID_X  *  GRID_Y)  { 

GotoXY_(0,  22); 

printf ("ERROR!  PositionListHead  >  max  (%d)",  PositionListHead); 

Pause  ()  ; 

GotoXY_ (0,  22); 
printf (szClear) ; 

GotoXY_(0,  22); 

} 

return  (PositionListHead) ; 

} 

int  AddSurroundingToPositionList (int  PositionList [GRID_X  *  GRID_Y][2], 
int  PositionListHead,  int  x,  int  y) 

( 

int  dX,  dY; 

for  (dX— 1;  dX<=l;  dX++)  { 
for  (dY— 1;  dY<=l;  dY++)  { 

if  ((x+dX  >=  0)  &&  (x+dX  <  GRID_X)  &&  (y+dY  >=  0)  &&  (y+dY  <  GRID_Y) )  ( 
if  ( (Board [x+dX] [y+dY]  ==  bVISITED)  1! 

(Board [x+dX] [y+dY]  ==  bCURRENT) )  [ 

PositionListHead  =  AddToPositionList (PositionList,  PositionListHead, 
x+dX,  y+dY) ; 

} 


} 

} 

return  (PositionListHead) ; 

) 

BOOL  FindPos it ionlnAG (ADJACENCYGROUP  *pAG,  int  x,  int  y) 

\ 

int  nlndex; 

BOOL  bFound; 
bFound  =  FALSE; 

for  (nlndex=0;  nIndex<pAG->CellCount;  nlndex++)  ( 

if  ( (pAG->Cell [nlndex] [0]  ==  x)  &&  (pAG->Cell [nlndex] [1]  ==  y) )  { 
bFound  =  TRUE; 


} 

return  (bFound) ; 

} 

void  MarkBombCell (int  x,  int  y) 

{ 

UserMark [x] [y]  =  'M'; 

DisplayCell (x,  y) ; 
if  (Board[x] [y]  !=  bBOMB)  { 

GotoXY_(0,  22); 

printf ("LOGIC  ERROR:  I  tagged  a  phantom  bomb  @  (%d, %d).",  x,  y) ; 

Pause  ()  ; 

(continued  on  page  112) 
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Listing  One  (Listing  continued,  text  begins  on  page  72.) 

GotoXY_(0,  22); 
printf (szClear) ; 

GotoXY_(0,  24); 

) 

) 

void  VisitCell (int  x,  int  y) 

{ 

if  (Board[x] [y]  !=  bCURRENT)  | 
if  (Board[x) [y]  ==  bBOMB)  { 

GotoXY_(0,  22); 

printf ("LOGIC  ERROR:  I  walked  on  a  bomb  @  (%d, %d).",  x,  y); 

Pause  ()  ; 

GotoXY_(0,  22); 
printf (szClear) ; 

GotoXY_(0,  24); 

) 

Board[x] [y]  =  bVISITED; 

DisplayCell  (x,  y) ; 

) 

) 

int  CountCommonCells (ADJACENCYGROUP  ‘pGroupl,  ADJACENCYGROUP  *pGroup2) 

( 

int  Cell,  nCount; 
nCount  =  0; 

for  (Cell=0;  Cell<pGroupl->CellCount;  Cell++)  { 
if  (FindPositionlnAG (pGroup2, 

pGroupl->Cell [Cell] [0] ,  pGroupl->Cell [Cell] [1] ) )  { 

nCount++; 

} 

} 

return  (nCount) ; 

) 

BOOL  ProcessRule3 (ADJACENCYGROUP  *pCurrentAG,  ADJACENCYGROUP  ‘pTempAG, 
int  PositionList [GRID_X  *  GRID_Y][2], 
int  *pPositionListHead) 

( 

int  x; 

int  BombCount,  CellCount; 
int  PositionListHead; 
int  CellHolder [9] [2] ; 
int  CellHolderHead; 

BOOL  bRetVal; 

PositionListHead  =  *pPositionListHead; 
bRetVal  =  FALSE; 

BombCount  =  pCurrentAG->BombCount; 

CellCount  =  pCurrentAG->CellCount; 

if  (pTempAG->CellCount  ==  CountCommonCells (pTempAG,  pCurrentAG) )  ( 
BombCount  -=  pTempAG- >BombCount ; 

CellCount  -=  pTempAG->CellCount; 

if  ((CellCount  >  0)  44  ((BombCount  ==  CellCount)  !!  (BombCount  ==  0)))  { 
bRetVal  =  TRUE; 

CellHolderHead  =  0; 

CellCount  =  pCurrentAG->CellCount; 
for  (x=0;  x<CellCount;  x++)  { 

if  (! FindPositionlnAG (pTempAG,  pCurrentAG->Cell [x] [0] , 
pCurrentAG->Cell [x] [1] ) )  { 
if  (BombCount  ==  0)  ( 

VisitCell (pCurrentAG->Cell [x] [0],  pCurrentAG->Cell [x] [1] ) ; 

}  else  { 

MarkBombCell (pCurrentAG->Cell [x] [0] ,  pCurrentAG->Cell [x] [1] ) ; 

) 

/*  Queue  up  cells  to  put  in  position  list  for  later  */ 

CellHolder [CellHolderHead] [0]  =  pCurrentAG->Cell [x] [0] ; 

CellHolder [CellHolderHead] [1]  =  pCurrentAG->Cell [ x] [1] ; 
CellHolderHead++; 

) 

) 

for  (x=0;  x<CellHolderHead;  x++)  [ 

PositionListHead  =  AddSurroundingToPositionList ( 

PositionList, 

PositionListHead, 

CellHolder [x] [0], 

CellHolder [x] [ 1 ] ) ; 

} 


PositionListHead — ; 

ComputeAdjacency (CurrentX,  CurrentY) ; 

BombCount  =  AdjacencyGroup [CurrentX] [CurrentY] . BombCount; 

CellCount  =  AdjacencyGroup [CurrentX] [CurrentY] .CellCount; 
if  ((CellCount  >  0)  44  (BombCount  >  -1))  [ 

Rule  1:  if  number  of  bombs  =  number  of  cells,  all  are  bombs! 

if  (CellCount  ==  BombCount)  { 

for  (Cell=0;  CelKCellCount;  Cell++)  { 
x  =  AdjacencyGroup [CurrentX] [CurrentY] .Cell [Cell] [0]; 
y  =  AdjacencyGroup [CurrentX] [CurrentY] .Cell [Cell] [1] ; 

MarkBombCell (x,  y) ; 

PositionListHead  =  AddSurroundingToPositionList (PositionList, 

PositionListHead, 
x,  y)  ; 

bModifiedAny  =  TRUE; 

) 

)  else  { 

Rule  2:  if  number  of  bombs  =  0,  all  cells  are  ok! 

if  ((BombCount  ==  0)  44  (CellCount  >0))  { 
for  (Cell=0;  CelKCellCount;  Cell++)  ( 
x  =  AdjacencyGroup [CurrentX] [CurrentY] .Cell [Cell] [0] ; 
y  =  AdjacencyGroup [CurrentX] [CurrentY] .Cell [Cell] [1] ; 

VisitCell (x,  y); 

PositionListHead  =  AddToPositionList (PositionList, 

PositionListHead, 
x,  y) ; 

PositionListHead  =  AddSurroundingToPositionList (PositionList, 

PositionListHead, 
x,  y); 

bModifiedAny  =  TRUE; 

} 

}  else  ( 

Rule  3:  if  AG  completely  overlaps  another  AG,  subtract  2nd 

f  of  bombs  from  1st;  check  rules  1  &  2.  If  rule  1  or 
2  is  true  in  this  case,  stop  looking  in  rule  3. 

bDone  =  FALSE; 

for  (Cell=0;  (CelKCellCount)  44  (IbDone);  Cell++)  f 
x  =  AdjacencyGroup [CurrentX] [CurrentY] .Cell [Cell] [0] ; 
y  =  AdjacencyGroup [CurrentX] [CurrentY] .Cell [Cell] [1] ; 
for  (dX=-l;  (dX<=l )  44  (IbDone);  dX++)  ( 
for  (dY— 1;  (dY<=l)  44  (IbDone);  dY++)  ( 
if  ((x+dX  >=  0)  44  (x+dX  <  GRID_X)  44 
(y+dY  >=  0)  4 &  (y+dY  <  GRID_Y) )  ( 
pTempAG  =  4Ad jacencyGroup [x+dX] [y+dY] ; 

if  (pTempAG->BombCount  >  0)  (  /*  if  ==  0,  no  help!  */ 

bDone  =  ProcessRule3 (&AdjacencyGroup [CurrentX] [CurrentY] , 
pTempAG, 

PositionList, 

4PositionListHead) ; 

if  (bDone)  [ 

bModifiedAny  =  TRUE; 

} 

) 

) 

) 

} 

) 

) 

I 

) 

} 

if  (bModifiedAny)  ( 

for  (x=0;  x<GRID_X;  x++)  [ 
for  (y=0;  y<GRID_Y;  y++)  [ 

if  ((Boardfx] [y]  ==  bVISITED)  I !  (Board [x] [y]  ==  bCURRENT) )  { 
PositionListHead  =  AddToPositionList (PositionList, 

PositionListHead, 
x,  y); 

) 

} 


*pPositionListHead  =  PositionListHead; 
return  (bRetVal); 


) 

) 

BOOL  LetUserMove (void) 


void  EvaluatePosition (void) 

{ 

int  CurrentX,  CurrentY; 
int  x,  y; 
int  Cell; 
int  dX,  dY; 

int  BombCount,  CellCount; 

int  PositionList [GRID_X  *  GRID _ Y] [2 ] ,  PositionListHead; 

ADJACENCYGROUP  * pTempAG; 

BOOL  bDone; 

BOOL  bModifiedAny; 
bModifiedAny  =  TRUE; 
for  (x=0;  x<GRID_X;  x++)  [ 
for  (y=0;  y<GRID_Y;  y++)  { 

ComputeAdjacency (x,  y); 

) 

) 

PositionList [0] [0]  =  UserX; 

PositionList [0] [1]  =  UserY; 

PositionListHead  =  1; 
while  (bModifiedAny)  { 
bModifiedAny  =  FALSE; 
while  (PositionListHead  >  0)  { 

CurrentX  =  PositionList [0] [0] ; 

CurrentY  =  PositionList [0] [1] ; 

for  (x=0;  x<PositionListHead-l;  x++)  [ 

PositionList [x] [0]  =  PositionList [x+1] [0] ; 
PositionList [x] [1]  =  PositionList [x+1] [1] ; 

} 


BOOL  bDone; 

BOOL  bQuit; 
int  Ch; 
bDone  =  FALSE; 
while  (! bDone)  [ 

Ch  =  getch  ()  ; 
switch  (Ch)  { 
case  0: 

Ch  =  getch  ()  ; 
switch  (Ch)  [ 


case  71: 

/*  home  */ 

bDone  = 

Travel (-1,  -1); 

break; 

case  72: 

/*  up  arrow  */ 

bDone  = 

Travel (0,  -1); 

break; 

case  73: 

/*  page  up  */ 

bDone  = 

Travel (1,  -1); 

break; 

case  75: 

/*  left  arrow  */ 

bDone  = 

Travel (-1,  0); 

break; 

case  77: 

/*  right  arrow  */ 

bDone  = 

Travel (1,  0); 

break; 

case  79: 

/*  end  */ 

bDone  = 

Travel (-1,  1); 

break; 

case  80: 

/*  down  arrow  */ 
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bDone  =  Travel (0,  1); 
break; 

case  81:  /*  page  down  */ 

bDone  =  Travel (1,  1); 
break; 

> 

break; 

case  '7':  /*  home  */ 

bDone  =  Travel (-1,  -1); 
break; 

case  '8':  /*  up  arrow  */ 

bDone  =  Travel (0,  -1); 
break; 

case  '9':  /*  page  up  */ 

bDone  =  Travel (1,  -1); 
break; 

case  '4':  /*  left  arrow-*/ 

bDone  =  Travel (-1,  0) ; 
break; 

case  '6':  /*  right  arrow  */ 

bDone  =  Travel (1,  0)  ; 
break; 

case  ' 1' :  /*  end  */ 

bDone  =  Travel (-1,  1); 
break; 

case  '2':  /*  down  arrow  */ 

bDone  =  Travel  (0,  1); 
break; 

case  '  3' :  /*  page  down  */ 

bDone  =  Travel (1,  1); 
break; 
case  'Q' : 
case  ' q' : 
case  27: 

bDone  =  TRUE; 
break; 
case  'M' : 
case  'm' : 

PlaceUserMark () ; 
break; 
case  ' ?'  : 

EvaluatePosition  ( ) ; 
break; 


bShowBombs  =  TRUE; 

PaintBoard () ; 

GotoXY_ (0,  SCREEN_Y  -  1); 
printf ("Again  (Y/n)?  "); 
bDone  =  FALSE; 
while  (IbDone)  { 

Ch  =  getch () ; 

if  ( (Ch  ==  ' Y' )  ::  (Ch  ==  'y')  !!  (Ch  ==  13)  I!  (Ch  ==  10) ) 
bDone  =  TRUE; 
bQuit  =  FALSE; 
printf ("Y\n") ; 

} 

if  ((Ch  ==  'N')  : :  (Ch  ==  'n'))  ( 
bDone  =  TRUE; 
bQuit  =  TRUE; 
printf ("N\n") ; 

) 

if  (Ch  ==  NULL)  { 
getch ( ) ; 

) 

} 

return  (bQuit); 

> 

int  main(int  argc,  char  *argv[]) 

( 

BOOL  bDone; 

Initialize ( ) ; 
if  ( (argc  >1)  && 

<argv[l] [0]  ==  ' /' )  && 

( (argv[l] [1]  ==  's')  II  (argv[l] [1]  —  'S')))  { 
bSafeGame  =  TRUE; 
printf ("SAFE  GAME  in  effect.\n"); 

}  else  { 

bSafeGame  =  FALSE; 

} 

bDone  =  FALSE; 
while  (IbDone)  ( 

SetUpBoardO  ; 

bDone  =  LetUserMove () ; 

1 

return  (0) ; 


End  Listing 
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Listing  One  (Text  begins  on  page  77.) 

/*  eesc.c  —  edge  enhancement  system  in  C  */ 
♦include  <stdio.h> 

♦define  ASize(x)  (sizeof (x) /sizeof (x ( 0 ) ) ) 


/*  length  of  array  */ 


/*  PrintGraphO  -  print  out  graph  of  an  array  of  numbers*/ 

FILE  ‘PFOutFp  =  { stdout } ; 

int  PrintGraph(  PFarray,  ILen,  Iny  ) 

float  *PFarray;  /*  pointer  to  floating  pioi 

int  ILen;  /*  length  of  the  array  */ 

int  Iny;  /*  ♦  of  points  along  the  y 


FMin,  FMax; 
FSc,  FOff; 
Iwx; 

Ilx; 

ITx; 

IpTx; 

Ich; 


in},  i 

/*  pointer  to  floating  piont  array  */ 
/*  length  of  the  array  */ 

/*  ♦  of  points  along  the  y-axis  */ 

/*  minimum  and  maximum  values  */ 

/*  scale  &  offset  */ 

/*  work  index  */ 

/*  line  index  */ 

/*  temp  index  */ 

/*  prior  line  index  */ 

/*  character  to  display  */ 


/*  —  check  that  all  parameters  are  "reasonable"  —  */ 
if  (  PFarray  ==  (float  *)0  !!  ILen  <=  0  ! !  Iny  <=  1  ) 
return (  -1  ) ; 

/*  —  compute  minimum  and  maximum  values  for  array  —  */ 
FMin  -  PFarray [0]; 

FMax  =  PFarray [0]; 

for(  Iwx  =  1;  Iwx  <  ILen;  Iwx++  )  { 

if  (  FMin  >  PFarrayflwx]  )  FMin  =  PFarray [Iwx] ; 

if  (  PFarray [Iwx]  >  FMax  )  FMax  =  PFarray [ Iwx] ; 


if  (  FMin  >  0.0  )  FMin  =  0.0; 

/*  —  from  minimum  and  maximum,  compute  scale  and  offset  —  */ 
if  (  (FMax  -  FMin)  <  .0001  )  [ 

/*  —  assume  that  all  values  are  the  same  —  */ 

FSc  =  1.0; 

FOff  =  -FMin; 

}  else  ( 

FSc  =  Iny  /  (FMax  -  FMin) ; 

FOff  =  -FSc  *  FMin; 

} 

IpTx  =  0; 

fputc(  '\n',  PFOutFp  ); 

for(  Ilx  =  Iny;  Ilx  >=  0;  Ilx —  )  ( 

for(  Iwx  =  0;  Iwx  <  ILen;  Iwx++  )  { 

ITx  =  FSc  *  PFarray [Iwx]  +  FOff; 
if  (  ITx  <  0  )  ITx  =  0; 

if  (  ITx  >  Iny  )  ITx  =  Iny; 

if  {  Iwx  ==  0  )  IpTx  =  ITx; 
if  (  (IpTx  <  Ilx  &&  Ilx  <  ITx)  : : 

(ITx  <  Ilx  &&  Ilx  <  IpTx)  : : 


Ich  =  ' x' ; 
Ich  -  '  ' ; 


(ITx  ==  Ilx)  ) 

else 

fputc(  Ich,  PFOutFp  )  ; 
IpTx  =  ITx; 

} 

fputc(  '\n' ,  PFOutFp  ); 


/*  Convolve!)  -  Convolve  a  filter  with  a  one-dimensional  signal  */ 

int  Convolve (  PFilter,  IFLen,  PFInVec,  PFResVec,  ILen  ) 

float  *PFilter;  /*  pointer  to  filter  coefficients  */ 

int  IFLen;  /*  number  of  coefficients  in  filter  */ 

float  *PFInVec;  /*  input  signal  vector  */ 

float  ‘PFResVec;  /*  output  result  vector  */ 

int  ILen;  /*  length  of  input  &  result  vectors  */ 

{ 

int  IFx;  /*  filter  index  */ 

int  IResX;  /*  result  index  */ 

int  IResXLast;  /*  index  of  last  result  item  */ 

int  IResXFirst;  /*  index  of  first  result  item  */ 

double  DRv;  /*  result  value  */ 

/*  —  check  for  things  which  do  not  make  sense  —  */ 
if  (  IFLen  <=  0  1 !  ILen  <=  IFLen  )  return (  -1  ); 
if  (  PFilter  ==  (float  *)0  !! 

PFInVec  ==  (float  *)0  !!  PFResVec  ==  (float  *)0  )  return!  -1  ); 
/*  —  convolve  the  filter  with  the  signal  —  */ 

IResXFirst  =  IFLen  /  2; 

IResXLast  =  ILen  -  (IFLen-l)/2; 

for (  IResX  =  IResXFirst;  IResX  <  IResXLast;  IResX++  )  ( 

DRv  =  0.0; 

for (  IFx  =  0;  IFx  <  IFLen;  IFx++  ) 

DRv  +=  PFilter [IFx]  *  PFInVec [IResX-IResXFirst+IFx] ; 

PFResVec [IResX]  =  DRv; 

} 

/*  -  handle  left  edge  specially  —  */ 

DRv  =  PFResVec [ IResXFirst ] ; 

for(  IResX  =  0;  IResX  <  IResXFirst;  IResX++  )  PFResVec [IResX]  =  DRv; 
/*  —  likewise  right  edge  —  */ 

DRv  =  PFResVec [IResXLast-1] ; 

for (  IResX  =  IResXLast;  IResX  <  ILen;  IResX++  )  PFResVec [IResX]  =  DR 
/*  —  we  are  done  —  */ 
return (  0  ) ; 


if  (  PFilter  ==  (float  *) 0  i ! 

PFInVec  ==  (float  *)0  !!  PFResVec  ==  (float  *)0  )  return(  -1  ); 

/*  —  convolve  the  filter  with  the  signal  —  */ 

IResXFirst  =  IFLen  /  2; 

IResXLast  =  ILen  -  (IFLen-l)/2; 

for(  IResX  =  IResXFirst;  IResX  <  IResXLast;  IResX++  )  { 

DRv  =  -Bias;  /*  NN  special  */ 

for {  IFx  =  0;  IFx  <  IFLen;  IFx++  ) 

DRv  +=  PFilter [IFx]  *  PFInVec [ IResX-IResXFirst+IFx] ; 

/*  —  apply  clamped  linear  transfer  function  to  output  —  */ 
if  (  DRv  <0.0  )  DRv  =  0.0;  /*  NN  special  */ 

else  if  (  DRv  >  1.0  )  DRv  =  1.0;  /*  NN  special  */ 

PFResVec [IResX]  =  DRv; 

) 

/*  —  handle  left  edge  specially  —  */ 

DRv  =  PFResVec [IResXFirst] ; 

for (  IResX  =  0;  IResX  <  IResXFirst;  IResX++  )  PFResVec [IResX]  =  DRv; 

/*  -  likewise  right  edge  —  */ 

DRv  =  PFResVec [IResXLast-1 ] ; 

for(  IResX  =  IResXLast;  IResX  <  ILen;  IResX++  )  PFResVec [IResX]  =  DRv; 
/*  —  we  are  done  —  */ 
return  (  0  ) ; 


/*  main()  -  main  driver  routine  */ 
/*  —  Input  Signal  —  */ 
float  FSignalf]  =  ( 


0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.15, 

0.20, 

0.25, 

0.30, 

0.35, 

0.40, 

0.45, 

0.50, 

0.55, 

0.60, 

0.65, 

0.70, 

0.75, 

0.80, 

0.80, 

0.80, 

0.80, 

0.80, 

0.80, 

0.83, 

0.80, 

0.70, 

0.90, 

0.80, 

0.80, 

0.60, 

0.90, 

0.40, 

0.60, 

0.30, 

0.10, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.10, 

0.25, 

0.30, 

0.10, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20, 

0.20 

}; 

/*  —  Result  Signal  —  */ 

float  FResultl[  ASize (FSignal)  ]  -  (0); 

float  FResult2 [  ASize (FSignal)  ]  =  ( 0 ) ; 

/*  —  Convolver  for  Neural  Network  —  */ 
float  FMHF [ ]  =  { 

-0.10,  -0.60,  -0.30,  0.50,  1.10,  0.50,  -0.30,  -0.60,  -0.10 

/*  -  Standard  (sobel)  edge  detector  —  */ 

float  FSobel [ ]  -  {  -1.0,  0.0,  1.0  ); 


int  Iwx; 

float  ‘PFResA,  ‘PFResB,  ‘PFSwap; 

PrintGraph(  &FSignal[0],  ASize (FSignal) ,  40  ); 
fputs(  "\n —  Original  Signal  — \n\n",  PFOutFp  ); 

Convolve (  &FSobel[0],  ASize (FSobel) , 

&FSignal[0],  SFResultl [0] ,  ASize (FSignal)  ); 

PrintGraph(  iFResultl [0] ,  ASize (FResultl) ,  40  ); 

fputs(  "\n —  Result  of  applying  sobel  edge  detector  to  image — \n\n", 
PFOutFp  ) ; 

PrintGraph(  &FSignal[0],  ASize (FSignal) ,  40  ); 
fputs(  "\n —  Original  Signal  — \n\n",  PFOutFp  ); 

PFResA  =  &FSignal[0]; 

PFResB  =  SFResultl [0] ; 

PFSwap  =  &FResult2 [0] ; 

for(  Iwx  =  1;  Iwx  <=  8;  Iwx++  )  ( 

NNCycle (  .02,  4FMHF[0],  ASize (FMHF),  PFResA,  PFResB,  ASize (FSignal)  ); 

PrintGraph (  PFResB,  ASize (FResultl) ,  40  ); 

fprintf(  PFOutFp,  "\n —  Cycle  number  %d  — \n\n",  Iwx  ); 

PFResA  =  PFResB;  /*  swap  result  pointers  */ 

PFResB  =  PFSwap; 

PFSwap  =  PFResA;  /*  next  ResB  */ 


End  Listing  One 


Listing  Two 


Neural  Network  Based  "Edge  Enhancement  System" 
Written  by:  Casimir  C.  "Casey"  Klimasauskas 
January  6,  1990 

Lotus  1-2-3  version  3.0  spreadsheet 


/*  NNCycle ()  -  perform  one  iteration  with  Neural  Network  */ 
int  NNCycle (  Bias,  PFilter,  IFLen,  PFInVec,  PFResVec,  ILen  ) 
float  Bias;  /*  bias  for  PE  */ 

float  ‘PFilter;  /*  pointer  to  filter  coefficients  */ 

int  IFLen;  /*  number  of  coefficients  in  filter  */ 

float  ‘PFInVec;  /*  input  signal  vector  */ 

float  ‘PFResVec;  /*  output  result  vector  */ 

int  ILen;  /*  length  of  input  &  result  vectors  */ 

{ 

int  IFx;  /*  filter  index  */ 

int  IResX;  /*  result  index  */ 

int  IResXLast;  /*  index  of  last  result  item  */ 

int  IResXFirst;  /*  index  of  first  result  item  */ 

double  DRv;  /*  result  value  */ 

/*  -  check  for  things  which  do  not  make  sense  -  */ 

if  (  IFLen  <=  0  ! !  ILen  <=  IFLen  )  return (  -1  ); 


Low  Low  Raw 

Pass  Pass  MHF  Input 

Output  Filter  Filter  Data 


Iteration 

Graph 


0.20  0.00  0.00  0.00  0.00  0.00  0.00  0.00  0.00  16 

0.20  0.00  0.00  0.00  0.00  0.00  0.00  0.00  0.00  17 

0.20  0.00  0.00  0.00  0.00  0.00  0.00  0.00  0.00  18 

0.20  0.00  0.00  0.00  0.00  0.00  0.00  0.00  0.00  19 

(Listing  continued  on  page  116) 
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Listing  Two  (Listing  continued,  text  begins  on  page  77.) 
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‘‘Can  you  imagine —  the  Berlin  Wall 
breached! Free  elections  in  Poland  and 
Czechoslovakia!  The  Soviet  leader  pro¬ 
claiming  freedom  of  religion  while  vis¬ 
iting  the  pope!  The  Romanian  dictator 
getting  frosted  on  Christmas  Day!  Bush 
found  the  whole  sequence  of  events 
unbelievable,  dizzying,  even  a  little  bit 
frightening  —  and  yet,  unquestionably, 
the  fat  lady  had  opened  her  mouth  and 
was  hitting  high  C.  ” 

— Jamie  Malinowski 

//  ee,”  the  president  marveled 

»  *  /  in  his  trademark  nasal 
I  T  whine  and  1950s  sixth- 
grade  vocabulary,  “it  seems 
like  it  was  only  yesterday  that  their 
Premier  was  making  trouble  all  the  time 
and  saying  he  was  gonna  bury  us  and 
stuff,  and  now  their  whole  darn  evil 
empire  looks  like  it’s  coming  apart. 
Just  look  at  what’s  happened  with  their 
Mac  products  and  Turbo  Modula-2  and 
Turbo  Basic.  And  what  was  that  busi¬ 
ness  at  the  SD  ’90  conference  about 
Wallsoft’s  C  compiler?  Why’d  they  let 
a  competitor  speak  at  their  press  con¬ 
ference?  Well,  they  must  have  got  some 
bad  Perrier  down  in  Scotts  Valley. 

“It’s  pretty  neat  for  us  guys,  that’s  for 


Michael  Swaine 


sure,”  he  told  Steve  “Wally”  Ballmer, 
his  squeaky-voiced  confidante.  “Now 
maybe  the  press  will  talk  about  that 
instead  of  always  picking  on  us  about 
our  problems  here  at  home  or  our  prob¬ 
lems  with  our  so-called  buddies  at  IBM.” 
Blood  brother  oaths  sworn  in  the  child¬ 
hood  of  the  industry  didn’t  seem  to 
mean  much  in  these  grown-up  days. 

Chastened  by  this  thought  of  the  chal¬ 


lenges  that  still  lay  before  him,  the  presi¬ 
dent  frowned  at  his  long-time  friend. 
“Gee.  It’s  tough  being  big,  Wally,”  he 
said. 

Drugs,  Bugs,  and  the  DoD 

Having  joked  about  bugs  as  drugs  in 
my  February  “Flames,”  I  was  interested 
to  see  that  familiar  DDJ  author  Do- 
While  Jones  was  speaking  about  de¬ 
buggers  as  a  drug  at  Miller-Freeman’s 
Software  Development  ’90  in  February. 

“When  you  get  sick,”  Jones  said,  “you 
should  take  medicine  until  you  get  well. 
Then  you  should  stop."  When  your  soft¬ 
ware  is  sick,  he  reasoned,  you  should 
use  a  debugger  to  find  the  problem. 
When  you  find  the  problem,  you  should 
put  the  debugger  back  on  the  shelf. 

Debugger  abuse,  Jones  says,  comes 
from  using  a  debugger  when  the  pro¬ 
gram  really  isn’t  sick.  Sick  programs 
include  those  inherited  in  a  messed-up 
state  from  someone  else,  and  your  own 
programs  when  they  quit  working  sud¬ 
denly,  perhaps  due  to  a  change  in  the 
hardware  or  compiler  or  operating  sys¬ 
tem.  If  something  like  this  isn’t  wrong 
with  the  program,  you  shouldn’t  use  a 
debugger,  he  says,  because  you  will 
get  hooked,  starting  a  cycle  of  abuse: 
Dependence  on  a  debugger  makes  for 
weak  programmers  who  write  sick  soft¬ 
ware  that  can’t  be  debugged  without  a 
debugger. 

His  point  is  that  you  usually  don’t 
need  a  debugger,  that  your  knowledge, 
skills,  and  insight  into  the  structure  of 
the  code  constitute  the  best  possible 
debugger.  But  you  can’t  use  your  knowl¬ 
edge  of  the  structure  of  code  that  has 
none.  Writing  well-structured  programs 
is  the  prerequisite  to  rediscovering  “the 
lost  art  of  debugging.” 

As  Jones  describes  it,  the  lost  art  is 


one  of  analyzing  data  flow.  In  a  hierar¬ 
chically  structured  program,  modules 
at  one  level  invoke  modules  at  the 
next  lower  level,  passing  data  to  them, 
typically  as  parameters,  getting  data 
back,  possibly  as  function  values.  De¬ 
bugging  a  program  consists  of  examin¬ 
ing  this  data  flow.  The  techniques  he 
describes  shouldn’t  be  a  revelation  to 
any  DDJ  reader,  but  the  kind  of  rigor 
he  promotes  in  their  use  is  perhaps 
uncommon. 

You  can  test  the  data  flow  into  and 
out  of  a  module  by  writing  a  driver  for 
the  module.  The  driver  sends  selected 
data  to  the  module  and  examines  the 
results.  This  tests  the  module  in  isola¬ 
tion,  but  doesn’t  reflect  its  interaction 
with  other  modules. 

For  this,  you  need  an  integration  test 
driver  that  calls  the  module  one  level 
higher  than  the  modules  you  want  to 
test.  Data  values  are  fed  to  it  in  order 
to  check  the  interaction  of  the  modules 
it  invokes. 

Finally,  you  can  substitute  a  diag¬ 
nostic  module  for  any  module  in  your 
program.  A  diagnostic  module  has  the 
same  name  and  parameters  as  the  real 
module,  but  has  a  body  that  is  simple 
and  diagnostic.  That  is,  it  isn’t  so  com¬ 
plicated  that  it  could  reasonably  be  a 
source  of  errors,  and  it  does  nothing 
but  give  useful  information  on  the  data- 
passing  structure  of  which  the  module 
is  a  part. 

In  making  his  point,  Jones  used  the 
word  “hacker”  to  refer  to  one  who 
pokes  at  the  problem  more  or  less  at 
random  until  finding  a  fix  that  works. 
The  word  has  a  range  of  meanings, 
some  good,  some  not,  and  this  use  is 
a  legitimate  use  from  the  pejorative 
end  of  the  word’s  meaning  range.  It 
was  interesting,  then,  to  find  that  he 
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espoused  a  distinctly  hackerish  phi¬ 
losophy  in  another  talk  at  SD  '90. 

This  was  a  discussion  of  the  differ¬ 
ence  between  engineers  and  computer 
scientists.  Most  of  what  he  said  was 
uncontroversial:  Engineers  are  typically 
better  educated  in  the  physical  sciences, 
computer  scientists  better  grounded  in 
a  variety  of  programming  languages. 
But  the  key  differences,  he  said,  are 
philosophical.  Computer  scientists  and 
engineers  have  different  ideas  of  econ¬ 
omy;  engineers  are  trained  to  look  at 
the  whole  system,  while  computer  sci¬ 
entists  see  the  hardware  as  the  plat¬ 
form,  that  is,  as  a  given;  computer  sci¬ 
entists  want  to  apply  the  best  algorithm 
for  the  task  (and  are  better  equipped 
to  do  so),  while  engineers  let  the  task 
dictate  criteria  for  acceptability  of  an 
algorithm. 

Jones  is  an  engineer,  and  presented 
the  engineering  approach  as  the  more 
hackerish,  the  more  ad  hoc  of  the  two: 
Solve  the  problem  no  matter  what.  Here 
are  some  of  the  kinds  of  ad  hoc,  hack¬ 
erish  things  Jones  was  saying: 

•  Most  embedded  systems  don't  need 
any  kind  of  operating  system. 

•  Data  structures  aren’t  important  if  you 
only  have  a  few  variables  and  RAM 
is  limited. 

•  Tools  are  overrated. 

Taken  together,  the  talks  make  a  point 
at  a  higher  level.  On  the  one  hand, 
structure  your  code  so  that  you  can 
debug  it  by  hand,  and  structure  your 
approach  to  debugging.  On  the  other, 
get  the  job  done,  meet  the  target  launch 
date,  satisfy  the  client.  Together,  the 
talks  say  simply,  suit  the  tactic  to  the 
task.  Every  programmer  should  have  a 
rich  collection  of  ways  of  approaching 
a  problem  —  a  full  set  of  intellectual 
tools.  Structure  is  essential  but  so  is 
flexibility. 

Flexibility  is  a  good  trait  for  any  soft¬ 
ware  developer  to  cultivate.  Do- While 
Jones  is  a  Department  of  Defense  engi¬ 
neer,  like  many  who  push  bits  for  a 
living.  One  speaker  at  SD  ’90,  William 
Roetzheim,  speculated  that  half  the  soft¬ 
ware  engineers  in  America  were  now 
or  would  be  at  some  time  in  the  future 
writing  to  DoD  specs.  Well.  I  don’t 
relish  the  thought  of  anyone  losing  his 
or  her  job,  but  I  am  skeptical.  This 
would  not  seem  to  be  the  best  time  to 
begin  learning  Ada. 

The  Big  Challenge  of  Programming 
in  the  Large 

“Stop  talking  of  war  cause  we’ve  heard 
it  all  before.  Why  don  ’tyou  go  out  there 
and  do  something  useful?’’ 

—  Sinead  O’Connor 


120 


The  image:  The  development  team  as 
bureaucracy,  ideas  trampled  under  po¬ 
litical  arguments,  progress  held  up  by 
mandatory  progress  reports,  brilliant 
developers  brought  down  to  the  level 
of  their  feeblest  teammates. 

The  reality:  The  same  thing,  all  too 
often.  There  appear  to  be  excellent 
reasons  to  fear  and  to  loathe  the  devel- 

Knowledge,  skills,  and 
insight  into  the  structure 
of  the  code  constitute 
the  best  possible 
debugger 


opment  team,  and  to  long  for  the  free¬ 
dom  to  just  write  the  damn  thing.  We 
all  know  the  stories  of  the  lone  pro¬ 
grammers  who  created  masterpieces. 
It  may  be  unrealistic  to  think  that  large 
software  projects  can  be  done  any  other 
way  than  through  development  teams, 
but  it  can  be  an  inviting  fantasy. 

And  yet,  there  are  the  stories  of  the 
team  that  worked.  And  most  have  even 
experienced  that  golden  time,  when 
the  team  fed  off  each  others’  talents 
and  the  result  was  a  collaboration  none 
of  the  participants  could  have  done 
alone,  and  that  all  were  proud  of.  OK, 
maybe  it  was  only  the  Pringles  can 
sculpture  that  we  built  on  the  Dean’s 
front  porch  when  we  were  freshmen, 
but  when  it  comes  to  that  sense  of 
shared  ownership  of  the  work,  is  build¬ 
ing  Pringles  can  towers  any  different 
from  writing  for  Presentation  Manager? 

What's  The  Secret? 

The  toughest  problems  usually  turn  out 
to  be  the  ones  involving  other  people. 
What  we  suspect  seems  to  be  true: 
Group  dynamics  may  be  the  most  im¬ 
portant  factor  in  software  development 
group  success.  As  Richard  Cohen,  speak¬ 
ing  at  SD  ’90,  said  “software  develop¬ 
ment  productivity  is  more  strongly  af¬ 
fected  by  people-  and  team-related  is¬ 
sues  than  [by]  any  other  variable  under 
the  management’s  control.” 

And  teams  are  increasingly  going  to 
be  where  it’s  at.  Programming  in  the 
large  is  —  err  —  getting  bigger.  Ken  Orr 
maintains  that  coding  skill  grows  less 
and  less  important  as  the  project  gets 
bigger.  “For  people  trained  in  good 
software  engineering  approaches,  writ¬ 
ing  individual  programs  that  aren’t  very 
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large  or  complex  is  not  a  critical  skill. 
On  the  other  hand,  the  planning,  archi¬ 
tecture,  requirements,  and  design  of  large 
suites  of  data  files  and  programs  (pro¬ 
gramming  in  the  large)  are  critical  skills 
[and]  will  become  more  so.  The  need 
for  software  engineers  will  remain  acute, 
but  increasingly  these  people  will  be 
writing  systems,  not  programs.” 

If  programming  in  the  large  is  the 
task  of  the  future,  team  programming 
is  the  paradigm  of  the  future.  Cohen 
nailed  down  what  may  be  the  essence 
of  how  successful  teamwork  feels:  “A 
real  team,”  he  said,  “is  one  in  which 
the  group  feels  common  ownership  of 
the  problem  and  its  solution.”  Many 
speakers  at  SD  ’90  talked  about  prob¬ 
lems  involved  in  team  programming, 
managing  software  engineering  projects, 
programming  in  the  large.  I  didn’t  catch 
all  their  talks,  but  after  the  conference 
I  sifted  through  the  proceedings  and 
my  notes,  and  found  that  many  of  them 
dealt  with  the  search  for  ways  to  achieve 
that  sense  of  common  ownership  of 
the  work. 

It’s  an  important  search.  Changes  are 
afoot,  SD  ’90  speaker  Tim  Twinam  says, 
and  the  customer  may  well  start  calling 
more  of  the  shots.  The  free  ride  of  the 
Trappist  technician  may  not  end  this 
year,  but  there  is  an  inherent  instability 
that  will  some  day  shake  out. 

Vern  Crandall  and  Larry  Constantine 
have  given  some  thought  to  the  group 
structures  conducive  to  good  teamwork. 
Crandall,  who  worked  at  Novell,  claims 
that  fresh  thinking  is  required  in  this 
area  because  most  of  the  old  answers, 
the  software  methodologies,  including 
Orr’s  data-structured  system  develop¬ 
ment  (DSSD),  were  developed  for  MIS 
development  work,  not  for  commer¬ 
cial  software  development.  “We  need 
a  product-oriented  approach,”  he  said. 

He  lists  some  of  the  issues  that  are 
unique  to  or  more  important  in  com¬ 
mercial  software  development  than  in 
MIS: 

•  Ill-defined  users  (you  can’t  walk  down 
the  hall  and  look  over  their  shoulders 
to  see  what  they’re  doing  wrong); 

•  Programming  to  a  moving  target  (the 
market  changes  during  the  develop¬ 
ment  process); 

•  Multiple,  complex  models  (the  batch 
mode  of  early  MIS  is  history;  today  a 
commercial  product  may  have  aspects 
of  several  models,  including  real¬ 
time  operating  system,  embedded  sys¬ 
tem,  control  software,  distributed 
processing,  communications,  WAN, 
LAN,  device  driver,  and  database); 

•  Multiple  industry  standards  and  plat¬ 
forms; 

•  Many  quality  issues  (reliability,  instal- 


lability,  configurability,  serviceability, 
usability,  interoperability,  perfor¬ 
mance,  security,  recoverability,  and 
migration);  and  difficulties  in  customer 
education  and  support. 

At  least  six  groups  of  people  must  all 
work  together  well  to  make  the  project 
come  off:  Marketing,  software  devel¬ 
opment,  software  testing,  software  main¬ 
tenance,  documentation,  and  human 
factors.  This  is  a  complex,  interrelated 
system  of  individuals  with  different  skills 
and  interests,  all  pushing  to  meet  a 
common  deadline  that  is  invariably  too 


tight.  Crandall  claims  that  flat  and  net¬ 
work  management  structures  don’t  work 
in  such  an  environment.  He  points  out, 
furthermore,  that  software  developers 
are  creative  people  and  that  rules,  regu¬ 
lations,  and  restrictions  need  to  be  kept 
to  a  minimum  to  avoid  stifling  their 
creativity.  He  hails  the  benefits  of  con¬ 
sensus  management  in  maintaining  the 
flexibility  needed  to  let  creative  people 
solve  problems  together.  But  the  flexi¬ 
bility  and  creativity  can  cause  the  de¬ 
velopers  to  get  off  track,  so  a  lot  of 
supervision  is  necessary,  as  well  as  a 
lot  of  encouragement  and  direction. 
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He  thinks  that  a  hierarchical  structure 
and  an  emphasis  on  accountability,  chal¬ 
lenge,  and  expectation  is  ideal. 

How  do  you  achieve  this?  Crandall 
has  some  suggestions:  No  individual 
team  should  be  larger  than  six  people. 
Products  should  be  staggered,  not  se¬ 
quentially  released.  Testing  and  main¬ 
tenance  are  skills;  hire  testing  and  main¬ 
tenance  engineers,  not  testers,  and  pay 

People  do  care  about 
quality  and  will  work 
harder  and  better  when 
they  feel  they  are 
working  on  a  product 
they  can  take  pride  in 


them  as  much  as  the  development  en¬ 
gineers.  Most  of  the  existing  models  for 
a  product  life  cycle  are  too  long;  you 
need  to  run  in  parallel  as  much  as 
possible.  In  particular,  software  devel¬ 
opment,  testing,  documentation,  and 
human  factors  (such  as  screen  design) 
must  run  in  parallel.  This  demands  a 
lot  of  communication  and  a  lot  of  free¬ 
dom  of  movement,  and  that  demands 
careful  structuring  of  the  teams. 

Larry  Constantine  is  a  pioneer  in  the 
development  of  structured  program¬ 
ming  and  structured  design.  He  gave 
three  talks  at  SD  ’90,  and  in  one  of  them 
defined  what  he  calls  the  “structured 
open  team.”  It’s  apparently  what  Cran¬ 
dall  is  describing.  “The  structured  open 
team  uses  formal  structure  to  increase 
internal  flexibility  and  adaptability  while 
maintaining  simple,  external  interfaces 
and  behavior.  Internally,  it  is  structured 
to  function  as  a  tight-knit,  closely  inte¬ 
grated  team  of  professional  equals  with 
clear  differentiation  of  functions  only 
as  necessary  for  effective  functioning.” 
One  of  the  key  aspects  of  the  struc¬ 
tured  open  team  is  the  default  assign¬ 
ment  of  responsibility.  Responsibilities 
can  be  shifted  around  as  people’s  skills 
and  knowledge  and  interests  (and  the 
changing  demands  of  the  job)  require, 
but  there  is  always  a  default  assign¬ 
ment  of  responsibilities  to  ensure  that 
nothing  falls  through  the  cracks. 

One  of  the  key  steps  in  developing 
a  software  product  is  testing.  Testing 
is  naturally  more  complex  in  multipro¬ 
grammer  projects,  but  Crandall  turns 


up  a  surprising  fact:  Few  schools  offer 
any  training  in  testing.  Roetzheim, 
though,  pointed  out  that  testing  is  an 
important  element  of  DoD  specs.  Maybe 
more  programmers  will  be  using  DoD 
specs  than  I  speculated  earlier.  Some 
companies  today  write  to  DoD  specs 
in  certain  circumstances  even  when  not 
doing  Defense  work. 

But  the  most  compelling  point  to 
come  from  these  talks  is  that  it  is  the 
human  issues  that  are  critical.  Cohen 
listed  some  of  the  human  traits  that  any 
software  development  team  must  deal 
with: 

•  People  make  mistakes 

•  People  are  often  blind  to  their  own 
errors 

•  People  misunderstand  each  other 

•  People  fixate 

•  People  get  overwhelmed  by  too  many 
details 

•  People  identify  with  their  work 

•  People  care  about  quality 

The  last  point  is  a  particularly  good 
one  for  managers  to  keep  in  mind: 
People  do  care  about  quality  and  will 
work  harder  and  better  when  they  feel 
they  are  working  on  a  product  they  can 
take  pride  in. 

It  was  P.J.  Plauger  who  sounded  the 
contrarian  note.  There  is  always  dan¬ 
ger  in  accepting  the  common  view  un¬ 
critically,  and  there  seems  to  be  some 
sort  of  common  view  of  good  software 
management  emerging  (which  is  not 
to  say  that  good  software  management 
is  emerging).  Plauger  offered,  for  the 
stimulation  of  software  management 
thinking,  his  contrarian  list  of  software 
management  heresies: 

•  Every  software  project  must  be  just 
slightly  out  of  control 

•  Your  goal  as  a  manager  is  to  make 
software  projects  boring 

•  Your  obligation  to  your  programmers 
is  to  answer  their  telephone  calls 

•  Your  indispensable  programmers  are 
your  greatest  liability 

•  Teaching  BAL  programmers  C++  is  a 
waste  of  time 

•  Staying  within  budget  is  more  impor¬ 
tant  than  making  a  profit 

•  Writing  software  must  be  fun,  but  not 
too  much  fun 

Plauger  justifies  these  heresies  convinc¬ 
ingly,  but  I  think  they  are  more  useful 
if  you  are  allowed  to  supply  your  own 
explanations. 

DDJ 
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(continued  from  page  15S) 

HCR/C++,  Version  2.2,  is  the  first  up¬ 
grade  on  this  C++  compiler  from  HCR 
Corporation.  HCR/C++  operates  on 
most  386  and  486  Unix  systems.  This 
version  includes  class  libraries  that  con¬ 
tain  a  comprehensive  set  of  predefined 
objects  that  are  compatible  with  the 
reusable  object  capabilities  of  C++ .  HCR/ 
C++  comes  with  an  enhanced  release 
of  dbXtra,  the  window-oriented  debug¬ 
ger  compatible  with  Berkeley’s  DBX. 

HCR/C++  2.2  includes  the  set  of  class 
libraries  defined  by  AT&T  and  those 
in  HCR/C++  2.1,  as  well  as  the  NIH 
(National  Institute  of  Health)  libraries, 
which  provide  classes  for  strings,  linked 
lists,  date  and  time  conversions,  in¬ 
dexed  arrays,  hash  tables,  regular  ex¬ 
pressions,  and  vector  operations.  The 
Interviews  libraries  that  were  devel¬ 
oped  at  Stanford  University  and  pro¬ 
vide  an  interface  to  X  Windows  are 
also  part  of  the  package.  The  product 
should  be  available  by  now,  and  retails 
for  $995.  Version  2.0  customers  can 
upgrade  for  $99.  Reader  service  no.  23. 
HCR  Corporation 
130  Bloor  St.  West,  10th  Floor 
Toronto,  Ont.  Canada  M5S  1N5 
416-922-1937 

The  bStrings  Library  for  C,  which  adds 
dynamic  string-handling  capabilities  to 
the  C  language,  is  available  from  KBM 
Communications.  The  bStrings  Library 
provides  dynamic  strings  without  frag¬ 
menting  memory.  Over  130  string  ma¬ 
nipulation  routines  are  provided,  which 
duplicate  most  every  string'  function 
available  in  Basic,  as  well  as  some  not 
found  in  that  language.  The  library  sup¬ 
ports  functions  that  cut,  copy,  paste, 
clear,  and  overwrite  whole  strings  or 
sections  of  strings,  and  will  work  with 
most  screen  management  packages. 

This  library  is  available  for  Borland’s 
Turbo  C  2.0,  Microsoft  C  5.0/5. 1  and 
QuickC  2.0.  Both  versions  are  provided 
with  each  order,  and  come  with  a  30 
day  money-back  guarantee.  The  pro¬ 
duct  sells  for  $89.95.  Reader  service 
no.  36. 

KBM  Communications,  Inc. 

2401  Lake  Park  Dr.,  Ste.  160 
Atlanta,  GA  30080 
800-227-0303 

A  QuickBasic  file  indexing  program, 
Index  Manager,  has  been  released  by 
CDP  Consultants.  This  product  sup¬ 
posedly  gives  programmers  the  ability 
to  create  B+  tree  files  indexed  within 
their  QuickBasic  programs.  It  allows 
random  file  access  by  full  key,  brows¬ 
ing  through  files  by  partial  key,  or  sort¬ 
ing  forward  or  backward.  One  external 
subroutine  performs  all  of  Index  Man¬ 


ager’s  functions,  and  the  programmer 
still  retains  full  control  over  all  data 
files,  as  only  indexes  are  managed. 

Indexes  are  created  with  a  prefix  B+ 
tree.  The  program  is  written  in  assem¬ 
bler  language,  and  utilizes  a  large  cache 
buffer  for  keeping  important  index  re¬ 
cords  in  memory.  A  demo  version  can 
be  downloaded  on  CompuServe  (GO 
MSSYS)  on  data  library  1  or  2,  called 
INDEXM.ARC,  and  GEnie  (M  505)  on 
data  library  10,  file  828.  The  program 
costs  $59-  Reader  service  no.  25. 

CDP  Consultants 
1700  Circo  del  Cielo  Dr. 

El  Cajon,  CA  92020 
619-  440-  6482 

New  run-time  tools  are  now  available 
from  Gold  Hill  Computers  for  its  de¬ 
velopment  environments  GoldWorks  II 
and  GCLISP  Developer  3.1.  The  com¬ 
pany  claims  that  these  products  will 
produce  applications  that  can  be  in¬ 
voked  directly  from  DOS  or  Microsoft 
Windows/286,  that  they  will  load  as 
much  as  five  times  faster  than  applica¬ 
tions  loaded  under  the  development 
environments,  and  that  they  will  re¬ 
quire  much  less  memory. 

GCLISP  Runtime  supports  the  deliv¬ 
ery  of  GCLISP  Developer  3-1  applica¬ 
tions.  The  Lisp  run-time  configuration 
requires  1  Mbyte  of  extended  memory, 
and  so  can  deliver  applications  with 
less  than  2  Mbytes  of  memory. 
Goldworks  II/PC  Runtime  configura¬ 
tion  requires  2  Mbytes  of  extended  mem¬ 
ory,  with  4  Mbytes  memory  targeted 
for  end-user  machines,  and  is  integrated 
with  external  programs  such  as  Lotus 
1-2-3,  dBase  III,  and  C.  Gold  Hill’s  Starter- 
Pak  is  $1000  for  GCLISP  3.1  and  $1500 
for  Goldworks  II/PC.  Reader  service 
no.  27. 

Gold  Hill  Computers,  Inc. 

25  Landsdowne  St. 

Cambridge,  MA  02139 
617-621-3300 
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CSORT:  A  Saga  of 
a  Sort 


Those  of  you  with  mainframe  ex¬ 
perience  know  that  a  common 
and  indispensable  utility  program 
in  that  environment  is  the  file 
sort  program.  Many  batch  applications 
involve  the  generation  of  reports  taken 
from  data  files  that  you  maintain  in  se¬ 
quences  other  than  the  sequence  needed 
for  the  report  at  hand.  I  remember  the 
two-  and  three-way  tape  sorts  on  the 
IBM  1401  from  as  far  back  as  1961.  It 
would  have  been  unthinkable  to  try  to 
design  a  system  without  one. 

The  Mainframe  Tape  Sort 

Here’s  how  such  a  sort  works  in  the 
typical  tape-drive  configuration  of  yore. 
You  need  at  least  four  tape  drives  to 
run  a  two-way  sort.  The  unsorted  file 
starts  out  on  the  first  tape  drive,  and  the 
other  three  have  scratch  reels  of  tape. 
A  file  of  parameters  (usually  on  a  con¬ 
trol  card)  tells  the  sort  program  the  size 
of  the  file’s  records  and  the  location, 
length,  and  sequence  (ascending  or  de¬ 
scending)  of  each  of  the  fields  to  be 
sorted. 

Pass  One,  the  Input  Pass  —  The 

sort  program  reads  as  many  records 
into  memory  as  the  CPU  can  hold  and 
sorts  them  in  an  array.  Then  it  writes 
the  sorted  block  of  records  to  the  third 
tape  drive.  Next,  it  reads  and  sorts  an¬ 
other  block  of  records  and  writes  that 


Al  Stevens 


block  to  the  fourth  drive,  then  the  next 
block  to  the  third,  and  so  on  until  all 
the  input  records  have  been  read.  Drives 
3  and  4  now  each  contain  multiple 
blocks  of  individually  sorted  records, 
and  this  is  the  end  of  the  first  pass. 

During  the  first  pass,  the  block  size 
is  restricted  to  the  amount  of  memory 
that  is  available.  Block  sizes  double 
during  subsequent  passes  because  each 


block  is  in  sequence,  and  the  program 
reads  them  a  record  at  a  time  to  per¬ 
form  the  merge. 

Pass  Two,  the  Merge-down  Pass  — 

The  computer  operator  replaces  the 
input  tape  on  drive  1  with  a  fourth 
scratch  tape,  and  the  sort  program 
merges  the  first  block  from  drive  3  with 
the  first  block  from  drive  4,  writing  the 
merged  block  onto  drive  1.  Then  it 
would  merge  the  next  blocks  from 
drives  3  and  4  onto  drive  2.  This  flip- 
flop  continues  until  all  the  blocks  from 
drives  3  and  4  are  merged  into  drives 
1  and  2,  which  together  now  contain 
half  as  many  blocks  as  3  and  4.  (The 
old-timers  among  my  readers  are  be¬ 
ginning  to  get  bored.) 

Pass  Three,  the  Output  Pass  — 
The  merges  continue  back  and  forth 
with  each  pass  reducing  the  number 
of  ordered  blocks  by  half  and  doubling 
the  size  of  each  block  until  at  the  final 
pass  there  is  only  one  block  on  either 
drive  1  or  3,  and  this  tape  contains  the 
sorted  file,  which  can  be  read  by  the 
application. 

Sordid  Data  on  Micros 

When  I  began  working  with  micro¬ 
computers  in  the  mid-seventies  I  looked 
for  the  standard  sort  utility  program 
that  I  thought  would  come  with  oper¬ 
ating  systems,  and  I  found  none.  The 
first  significant  application  I  wrote  for 
an  IMSAI  8080  needed  file  sorting,  and 
a  search  turned  up  a  CP/M  program 
called  “QSORT,”  but  I  was  surprised 
to  learn  that  it  was  difficult  to  find 
what  had  always  been  an  indispensa¬ 
ble  utility  program. 

With  the  PC  and  MS-DOS  came  the 
SORT  filter  program,  but  it  has  three 
serious  limitations:  It  can  only  sort  as 
many  records  as  will  fit  into  64K,  it  can 
sort  only  one  field  of  the  file’s  records, 
and,  being  a  filter,  it  works  only  with 
text  files. 


The  In-line  Sort 

So  much  for  the  file  sort  utility  pro¬ 
gram.  Now  let’s  consider  the  in-line 
sort  feature.  Anyone  who  has  pro¬ 
grammed  in  many  computer  languages 
has  accumulated  some  favorite  features 
about  each  one.  The  ideal  personal 
language  would  have  all  those  features 
wrapped  into  one.  Of  course,  when 
you  try  to  build  a  language  with  every¬ 
one’s  favorite  features,  you  get  a  com¬ 
mittee-designed  language  —  you  get 
ADA,  perhaps.  The  perfect  personal 
language  would  be  so  extensible  that 
each  of  us  could  design  his  own  syntax 
and  data  types,  plugging  in  the  features 
we  treasure  and  leaving  out  the  ones 
we  do  not.  The  flaw  in  that  approach 
is  that  no  one  could  read  anyone  else’s 
code,  and  so,  instead  of  each  of  us  build¬ 
ing  a  personal  ideal  language,  we  ebb 
to  the  committee  approach,  standards 
emerge,  and  we  strive  to  conform. 

As  a  full-time  C  programmer  and 
writer,  I  often  think  of  language  fea¬ 
tures  in  terms  of  the  features  I  liked 
about  languages  past  that  C  does  not 
have.  For  example,  the  string  functions 
of  Basic  are  missing  in  C.  Cobol's  MOVE 
CORRESPONDING  would  be  handy  in 
C  where  the  C  structure  assignment 
would  assign  only  those  members  that 
have  the  same  names.  You  can  add 
both  of  these  features  to  C  by  building 
appropriate  C++  classes  if  you  are  us¬ 
ing  the  C++  extensions  to  C,  and  so  the 
dubious  realm  of  the  customized  lan¬ 
guage  looms  again  in  the  near  future. 

There  is  one  feature  I  liked  about 
Cobol  that  you  can  build  in  traditional 
C  without  extending  the  language  other 
than  with  a  few  functions.  That  feature 
is  the  SORT  verb  and  it  is  relevant  to 
this  month’s  rambling. 

A  Cobol  program  can  pass  records 
to  the  SORT  verb  one  at  time  and  then 
later  retrieve  those  records  in  the  sorted 
sequence.  There  are  several  advantages 
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to  this  technique.  One  is  that  the  pro¬ 
gram  does  not  need  to  prepare  an  un¬ 
sorted  file,  exit  to  a  sort  utility  program, 
and  then  execute  a  third  program  to 
process  the  sorted  file.  You  can  form 
each  unsorted  record  from  one  or  more 
sources  just  prior  to  sending  it  off  to 
be  sorted,  and  you  can  transform  the 
sorted  records  into  another  format  be¬ 
fore  doing  anything  with  them.  No  in¬ 
termediate  file  of  uniquely  formatted 
records  is  involved. 

The  C  qsort  function  is  similar  to  this 
approach  except  that  it  sorts  an  in¬ 
memory  array,  and  so  all  your  data 
records  must  fit  into  memory.  A  true 


in-line  sort  will  accept  as  many  records, 
one  at  a  time,  as  you  want  to  give  it, 
and  will  return  those  records  to  you, 
one  at  a  time,  in  sorted  order. 

So  now  we  have  defined  two  re¬ 
quirements  missing  from  the  C  language 
and  the  microprocessor  operating  sys¬ 
tem  environment.  Why,  after  ten  solid 
years  of  micro  use,  are  these  features 
not  standard?  Obviously,  they  are  not 
widely  needed  for  some  reason,  and 
that  reason  is,  I  guess,  that  the  per¬ 
sonal,  inexpensive  nature  of  the  PC  has 
redefined  the  way  we  design  systems. 
Most  PC  programs  today  are  interac¬ 
tive.  If  they  involve  multiple  sequences 


of  data  files,  they  use  indexed  database 
managers  or  higher-level  DBMS  lan¬ 
guages  that  deal  with  sorting  in  their 
own  ways.  OK,  so  most  of  the  time  we 
do  not  need  a  sort  program  or  an  in¬ 
line  sort.  But  what  about  the  few  times 
when  we  do?  Nothing  else  will  do. 

About  five  years  ago,  I  tackled  this 
problem  by  writing  a  C  language  in¬ 
line  sort  function  for  some  programs 
for  a  video  tape  store.  Later  I  used  it  as 
the  sort  engine  for  a  stand-alone  sort 
program  that  sorts  disk  files.  I  used 
pre-ANSI  Aztec  C  for  the  IBM-PC  and 
published  the  code  in  a  book  (C  Devel¬ 
opment  Tools  for  the  IBM  PC,  Brady 
Books)  in  1986.  Since  then  I  have  reused 
that  program  many  times  in  circum¬ 
stances  where  I  might  have  chosen  a 
more  accessible  but  less  appropriate 
solution  had  I  not  already  had  this  little 
sort  program.  Now  that  the  ANSI  stan¬ 
dard  definition  of  C  is  in  place,  it’s  time 
to  update  that  program,  so  this  month 
we  promote  it  to  the  standard  and  pub¬ 
lish  it  here. 

CSORT 

What  follows  is  CSORT,  a  sorting  facil¬ 
ity  that  you  can  use  from  within  your 
programs  or  from  the  command  line. 
Although  I  developed  it  to  use  in  CP/M 
systems  and  later  in  MS-DOS,  it  is  not 
wired  to  either  of  those  environments 
and  should  easily  port  to  another  plat¬ 
form  where  a  standard  C  compiler  is 
available. 

The  CSORT  project  has  two  parts, 
the  in-line  sort  and  the  file  sort  pro¬ 
gram.  To  use  the  in-line  sort  in  a  C 
program,  you  describe  the  characteris¬ 
tics  of  the  records  to  be  sorted  and 
send  them,  one  at  a  time,  off  to  the  sort 
process.  After  you  have  sent  the  last  of 
the  records,  you  send  a  NULL  and  go 
about  your  business.  When  you  are 
ready  for  the  records  in  the  sorted  se¬ 
quence,  you  call  the  sort  program  and 
it  returns  the  records,  one  for  each  call. 
After  it  has  returned  the  last  of  the 
sorted  records,  it  returns  a  NULL.  Your 
program  is  essentially  the  polar  ends 
of  a  three-phase  pipe. 

You  and  CSORT  pass  records  back 
and  forth  with  pointers.  CSORT  makes 
a  copy  of  the  record  you  pass  it,  so  you 
can  safely  reuse  the  space  the  record 
occupied.  CSORT  expects  you  to  do 
the  same  because  it  might  reuse  the 
record  space  that  is  pointed  to  to  be  a 
previous  pointer  it  returned. 

CSORT  requires  that  you  sort  fixed- 
length  records,  but  the  records  them¬ 
selves  do  not  need  to  be  in  text  format. 
The  sort  comparison  uses  the  strnicmp 
function  to  compare  fields,  so  they  do 
not  need  to  be  null-terminated. 
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(continued  from  page  128) 

The  CSORT  API 

Following  is  the  application  program 
interface  for  CSORT.  Listing  One,  page 
144,  is  CSORT.H,  which  contains  sev¬ 
eral  control  values  for  the  sort.  The 
NOFLDS  global  value  specifies  the  maxi¬ 
mum  number  of  fields  that  can  be  in¬ 
volved  in  the  sort  of  the  record.  The 
MOSTMEM  and  LEASTMEM  values  con¬ 
trol  the  appropriation  of  a  buffer  from 
the  heap  for  sorting.  MOSTMEM  is  the 
amount  you  try  for,  and  LEASTMEM  is 
the  least  amount  you  will  accept.  I  have 
them  set  to  work  within  a  small-model 
program  on  the  PC. 


Here  are  the  prototypes  and  descrip¬ 
tions  of  the  CSORT  API  functions. 

int  imt  sort( struct  s  _prm  *prms);  To 

sort  records,  you  must  describe  them. 
The  5 _prm  structure  contains  the  defi¬ 
nition  of  the  records  to  be  sorted.  It  is 
defined  in  CSORT.H.  You  will  declare 
the  structure  and  initialize  it  as  follows. 
Assign  the  record  length  to  the  rc_len 
member.  The  s  Jld  array  of  substruc¬ 
tures  will  contain  entries  for  each  of 
the  fields  to  be  sorted.  The  s_fld.f_  pos 
member  contains  the  record  position 
for  the  field.  This  value  is  relative  to 
one.  If  there  are  fewer  than  NOFLDS 


fields,  the  terminal  entry  in  this  array 
will  contain  a  zero  value  for  this  mem¬ 
ber.  The  s_fldf_  len  member  is  the 
length  of  the  field.  The  s_fld.ad  mem¬ 
ber  is  the  character  “a”  if  the  field  is  to 
be  collated  in  ascending  sequence  and 
“d”  if  it  is  to  be  collated  in  descending 
sequence.  The  first  field  in  the  array  is 
the  major  sort  field;  the  last  is  the  mi¬ 
nor;  all  others  are  intermediate.  So,  if 
you  need  records  in,  for  example,  divi¬ 
sion  number,  department  number,  and 
employee  number  sequence,  you  will 
define  the  fields  in  that  order  in  the 
array.  With  the  array  properly  initial¬ 
ized,  call  the  init_sort  function.  If  the 
sort  may  proceed  —  if  enough  mem¬ 
ory  is  available  —  the  function  returns 
zero.  Otherwise  it  returns  -1 . 
void  sort(char  *rcd);  With  the  sort 
program  properly  initialized  through 
init_sort ,  you  may  send  records  to  be 
sorted  by  calling  the  sort  function  once 
for  each  record.  Pass  a  pointer  to  the 
record,  and  the  sort  function  will  make 
a  copy  of  the  record.  After  you  have 
passed  the  last  record,  pass  a  NULL 
pointer.  This  tells  the  sort  function  to 
finish  the  sort  and  prepare  to  return 
sorted  records. 

char  *sort _op(void);  To  retrieve  sor¬ 
ted  records,  call  the  sort_op  function. 
Each  call  to  it  will  return  a  pointer  to 
the  next  record  in  the  sorted  sequence. 
After  the  last  record  comes  back,  the 
sort_op  returns  a  NULL  pointer. 
void  sort  stats(void);  This  function 
displays  some  of  the  values  used  in  the 
sort  function. 

The  FILESORT  Program 

Listing  Two,  page  144,  is  FILESORT.C, 
a  program  that  uses  the  CSORT  API  to 
implement  a  stand-alone  file  sort  pro¬ 
gram.  You  run  it  by  entering  the  file¬ 
name,  record  length,  and  field  parame¬ 
ters  on  the  command  line.  It  uses  the 
API  in  the  manner  just  described. 

CSORT  Internals 

Listing  Three,  page  144,  is  CSORT.C, 
which  contains  the  in-line  sort  func¬ 
tions.  The  first  function  to  discuss  is 
init_sort,  which  you  call  to  initiate  sort¬ 
ing.  It  calls  appr__mem  to  allocate  a 
block  of  memory  in  which  to  sort,  in¬ 
itializes  the  sorting  parameters,  and  re¬ 
turns. 

The  sort  function  accepts  records  to 
sort  from  the  calling  application.  At 
first  it  simply  copies  them  into  the  buffer, 
one  after  the  other.  When  the  buffer  is 
full,  the  sort  function  calls  the  standard 
qsort  function  to  sort  the  records  in  the 
buffer.  This  becomes  a  block  of  sorted 
records,  also  called  here  a  “sequence.” 
The  dumpbuff  function  writes  them  to 
the  sort  work  file.  CSORT  uses  only 
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(continued  from  page  130) 
one  sort  work  file,  unlike  the  tape  sorts 
we  discussed  earlier.  Because  this  pro¬ 
gram  uses  disk  files,  and.  because  di¬ 
rect  record  addressing  is  possible,  we 
do  not  need  to  maintain  multiple,  serial 
devices  for  the  blocks  of  sorted  records 
after  the  fashion  of  a  streamer  tape 
device. 

When  the  calling  application  sends 
a  NULL  pointer  to  the  sort  function,  it 
sorts  the  final  sequence,  writes  it  to  the 
work  file,  and  calls  prepjmerge  to  pre¬ 
pare  for  when  the  caller  wants  sorted 
records.  The  merge  divides  the  sort 
work  buffer  into  many  miniature  buff¬ 
ers,  one  for  each  sequence  that  was 
generated  by  the  sort  function.  These 
buffers  contain  two  or,  usually,  more 
records.  If  and  while  the  number  of 
sequences  is  high  enough  to  prevent 
the  buffer  from  being  segmented  this 
way,  prep_merge  uses  the  merge  func¬ 
tion  to  merge  groups  of  two  sequences 
into  one,  halving  the  number  of  se¬ 
quences  and  doubling  their  sizes. 

When  the  number  of  sequences  is 
low  enough  that  each  one  can  contrib¬ 
ute  at  least  two  records  in  the  sort 
buffer,  the  merge  and  prep_merge  func¬ 
tions  are  done. 

The  calling  application  calls  sort_op 
to  get  sorted  records.  The  sort_op  func¬ 


tion  looks  at  the  first  record  in  each 
buffer  segment  to  find  the  lowest  rec¬ 
ord.  It  bumps  that  segment’s  record 
pointer  and  returns  a  pointer  to  the 
record  it  found.  When  it  exhausts  a 
buffer  segment,  it  reads  more  records 
from  the  associated  sequence  on  the 
sort  work  file.  When  all  the  segments 
are  empty,  the  application  has  read  the 
last  sorted  record,  and  the  sort  pro¬ 
gram  signals  that  it  is  done  by  returning 
a  NULL  pointer. 

TopSpeed  C 

Last  year  I  reported  that  I  had  seen  a 
demo  of  the  announced  TopSpeed  C 
compiler  from  Jensen  &  Partners  Inter¬ 
national.  The  product  is  shipping  now, 
and  is  a  full-featured  ANSI-conforming 
compiler  with  integrated  editor,  com¬ 
piler,  linker,  and  debugger.  I  used  it  to 
upgrade  CSORT  to  the  ANSI  specifica¬ 
tion  and  can  offer  these  first  impres¬ 
sions.  Be  advised  that  I  have  not  yet 
used  TSC  to  build  a  significant  system 
from  scratch,  so  these  judgments  are 
preliminary.  I  think  you  will  like  this 
product.  After  reading  and  following 
the  installation  procedures,  I  used  the 
books  only  once  during  the  project, 
and  that  was  to  learn  the  format  for  the 
MAKE  project  file.  Everything  else  is 
neatly  supported  with  comprehensive 


help  windows  and  intuitive  menus. 

TSC  has  a  number  of  features  that  I 
haven’t  used  yet  but  surely  will.  They 
have  built  a  DOS  equivalent  of  the 
OS/2  dynamic  link  library  (DLL).  You 
can  build  programs  that  link  to  their 
libraries  at  run  time.  There  is  a  post¬ 
mortem  debugger,  an  assembler  and 
disassembler,  a  program  profiler,  and 
support  for  DOS  Windows  and  OS/2 
Presentation  Manager  program  devel¬ 
opment. 

TSC  has  a  few  things  I’d  change. 
Their  version  of  the  interrupt  function 
type  has  a  severe  disability.  You  can¬ 
not  call  an  interrupt  function  directly 
or  through  a  function  pointer.  This  pre¬ 
vents  you  from  chaining  intercepted 
interrupts  and  renders  TSC  ineffectual 
as  a  TSR  development  compiler  —  un¬ 
less  you  want  to  compensate  by  using 
assembly  language. 

Although  TSC  has  the  _AX,  _BX,  etc. 
pseudoregisters  of  Turbo  C,  they  do 
not  support  _FLAGS,  which  makes  their 
use  in  interrupt  service  routine  pro¬ 
gramming  even  more  difficult. 

The  tables  of  contents  and  indexes 
in  most  of  the  documents  do  not  agree 
with  the  actual  page  numbers.  This  is 
an  unacceptable  lapse  in  quality  con¬ 
trol  for  any  documentation  effort.  I  for¬ 
give  that  lapse  only  because  the  on- 
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line  documentation  is  so  good. 

TSC  tends  to  leave  my  cursor  other 
than  the  way  it  found  it,  and  it  leaves 
all  manner  of  what  appears  to  be  tem¬ 
porary  work  files  scattered  about  my 
source  directory.  These  quirks  are  an¬ 
noying  at  best. 

One  last  gripe,  then  I’ll  relax.  I  re¬ 
joiced  when  I  saw  the  WATCH  utility. 
It  is  a  really  neat  TSR,  tossed  in  for 
good  measure,  that  you  can  use  to 
monitor  the  calls  your  program  makes 
to  DOS,  an  essential  tool  for  systems 
programmers.  I  do  a  lot  of  program¬ 
ming  in  the  Novell  NetWare  local  area 
network  environment,  and  NetWare  API 
calls  are  supersets  of  the  DOS  INT  0  x 
21.  To  my  dismay,  I  learned  that  WATCH 
only  watches  calls  that  you  select  from 
its  list  of  known  DOS  calls,  and  there 
seems  to  be  no  way  to  tell  it  to  watch 
the  Novell  superset  list.  Rats.  Another 
idea  well  conceived,  poorly  built. 

If  it  seems  that  I  am  overly  critical  it 
is  because  these  are  the  things  I  found 
that  I  think  you  should  know  about. 
There  may  be  others,  but,  as  I  said,  my 
use  of  TSC  has  been  limited  so  far.  All 
that  aside,  I  like  the  product  and  do 
not  hesitate  to  recommend  it.  It  is  in 
great  shape  for  the  first  version  of  any 
software  product  and  will  surely  im¬ 
prove  with  newer  versions.  The  PC 
programmer  has  a  dilemma.  There  are 
several  excellent  compilers  to  choose 
from.  By  now,  there  will  have  been 
benchmarks  and  reviews  and,  I  am  sure, 
you  still  will  not  know  what  to  do. 

(The  title  of  this  month’s  column  is 
a  paraphrase  of  that  of  the  Bill  Mauldin 
book,  A  Sort  of  a  Saga,  His  book  has 
nothing  to  do  with  C  or  programming, 
but  Mauldin’s  cartoons  and  writings  and 
that  book  in  particular  are  timeless  and 
were  major  influences  in  my  young  life.) 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  144.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  10. 
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Yes,  Virginia,  There 
Is  a  Xerox! 


I  damned  near  choked  on  my 
Cheerios  the  morning  the  Mercury 
News  announced  that  Xerox  was 
suing  Apple  over  the  Macintosh  UI 
copyrights.  Land  o’  Goshen!  There  is  a 
Xerox  after  all!  I  had  just  about  given 
up  hope. 

I  have  reason  to  feel  specially  about 
this  whole  situation.  I  spent  ten  years 
at  Xerox  (1974  -  1984)  when  much  of 
their  seminal  research  into  user  interface 
concepts  took  place.  I  was  not  directly 
involved  with  that  research,  but  I  spoke 
regularly  with  PARC  people  who  were. 

I  played  with  Smalltalk  on  the  Alto  pro¬ 
totype  workstation,  and  I  was  one  of 
the  very  first  in  Xerox  MIS/DP  trained 
on  the  Star  workstation  in  early  1981. 
Unfortunately,  I  was  one  of  the  very 
few  who  ever  saw  the  Star,  much  less 
worked  on  it.  Had  the  Star  caught  on, 
Apple’s  suit  against  Microsoft  would 
have  been  laughed  out  of  court. 

The  Apple  vs.  Xerox  Equation 

For  those  of  you  who  have  been  living 
in  a  Dewar’s  flask  since  1985,  let  me 
recap:  Last  year  Apple  sued  Microsoft 
and  Hewlett  Packard,  claiming  that  Mi¬ 
crosoft  Windows  2.0  and  HP  New  Wave 
violated  Apple’s  visual  copyrights  on 
the  Macintosh  user  interface.  Earlier 
this  year,  parts  of  the  suit  concerning 
contractual  technicalities  were  dismissed 
by  the  judge,  leaving  only  the  very 
large  question  of  whether  Windows 
2.0  and  New  Wave  indeed  infringed 
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on  the  Macintosh  visual  copyright. 

Now  Xerox,  in  its  suit,  claims  that 
Apple  appropriated  the  visual  copy¬ 
rights  expressed  in  the  Star  worksta¬ 
tion  before  the  Macintosh  was  born, 
and  that  Xerox,  as  owner  of  said  copy¬ 
rights,  is  due  royalties  from  the  use  of 
its  interface. 

There  is  a  wonderful  word  to  apply 
here,  as  ancient  and  ineluctable  as  fate 


itself:  Checkmate.  No  matter  which  way 
Apple  moves,  it  loses.  Why?  Because 
if  Windows  2.0  infringes  on  the  Macin¬ 
tosh,  then  the  Macintosh  infringes  on 
the  Star.  I  had  to  laugh  at  Apple’s  im¬ 
mediate  protest  that  it  was  protecting 
its  expression  of  the  ideas  pioneered 
by  Xerox,  and  not  the  ideas  themselves. 
Any  three-legged  salamander  blind  in 
one  eye  could  tell  you  that  Windows 
2.0  and  the  Macintosh  Ul  are  not  iden¬ 
tical  expressions,  but  instead  are  sepa¬ 
rate  expressions  of  a  common  philoso¬ 
phy  of  user  interaction.  And  if  the  simi¬ 
larities  of  expression  between  Windows 
2.0  and  the  Mac  are  close  enough  to 
infringe  on  the  Mac,  then  the  Mac  is 
similar  enough  to  the  Star  to  infringe 
upon  the  Star.  Poof!  Apple  loses  its 
claims  of  ownership. 

It  gets  better.  If  Apple  changes  its 
mind  and  withdraws  its  Windows  suit, 
Microsoft  and  HP  have  excellent 
grounds  to  complain  that  Apple  brought 
the  suit  merely  to  stifle  competition, 
leaving  it  open  to  prosecution  under 
antitrust  laws. 

Couldn’t  happen  to  a  nicer  bunch 
of  guys,  eh? 

Many  people  are  saying  that  Xerox 
can’t  win  its  suit  against  Apple  (or  any¬ 
one  else),  because  it  waited  far  too 
long  to  bring  the  suit  to  begin  with. 
This  is  true,  but  it  may  not  matter.  The 
scrutiny  that  Xerox  will  bring  to  bear 
on  the  whole  question  of  who  authored 
what  and  when  will  finally  lay  to  rest 
the  pernicious  lie  that  Apple  has  some 
kind  of  ownership  of  anything  with  pull¬ 
down  menus  and  overlapping  windows. 

Most  people  haven’t  seen  the  Star, 
so  public  opinion  hasn’t  really  gone 
up  against  Apple.  I  was  there,  how¬ 
ever,  when  it  happened,  and  I  don’t  lie 
about  these  things:  The  Xerox  Star  is 
closer  to  the  Mac  than  Windows  is. 
That’s  the  golden  equation  whose  so¬ 
lution  will,  with  luck,  put  windowing 
environments  in  the  public  domain  and 
end  this  damned  foolishness  now  and 
forever. 


Thinking  About  Object  Design 

Just  because  you  can  swing  a  hammer 
doesn’t  mean  you  can  design  a  house. 
That’s  the  message  that  seems  to  be 
emerging  from  our  first  year  as  Object 
Pascal  programmers.  People  are  catch¬ 
ing  on  to  the  syntactic  nuances  of  object- 
oriented  programming.  Creating  objects 
and  methods  is  no  longer  quite  the 
mystery  it  was  in  1989.  What  does  seem 
to  be  a  mystery  is  the  big  picture  of  it 
all,  containing  sizeable  questions  like, 
“What  should  be  an  object?  How  do 
you  divide  your  application  into  ob¬ 
jects,  and  how  do  you  apportion  func¬ 
tionality  to  the  objects  in  an  object  hier¬ 
archy?”  This  is  the  old  architecture  vs. 
carpentry  duality  made  new  again  by 
the  appearance  of  mass-market  OOP 
languages.  So  put  down  that  hammer 
for  a  bit,  and  let’s  talk  about  larger 
issues. 

What  Should  be  an  Object? 

Just  after  Turbo  Pascal  5.5  and  Quick 
Pascal  appeared  last  May  (almost  si¬ 
multaneously)  people  predictably  be¬ 
gan  jumping  on  the  OOP  concept  and 
taking  it  to  absurd  lengths,  just  for  the 
exhilarating  fun  of  it  all.  I  recall  hearing 
about  guys  who  were  creating  objects 
out  of  ASCII  characters,  or  even  inte¬ 
gers,  because  it  seemed  like  the  politi¬ 
cally  correct  thing  to  do  at  the  time. 

As  the  vanguard  soon  discovered, 
making  Pascal  integers  and  characters 
into  objects  bought  them  almost  noth¬ 
ing,  and  cost  like  hell.  The  first  lesson 
we  learned  about  OOP  melted  into 
conventional  wisdom  in  record  time: 
Atoms  are  atoms  for  a  reason.  Objects 
are  a  means  of  organizing  complexity. 
Don’t  go  looking  for  complexity  where 
there  isn’t  any.  Molecules  have  to  be 
made  out  of  something. 

My  own  rule  of  thumb  comes  down 
to  this:  Don’t  make  objects  out  of  any¬ 
thing  that  the  compiler  special-cases. 
This  includes  all  fundamental  types  such 
as  Boolean,  Char,  all  numerics,  and 
strings.  In  a  language  like  Modula-2 
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where  strings  have  no  special  status  to 
the  compiler,  a  string  object  might  make 
sense.  Certainly  a  long  string  type  (in 
which  you  can  keep  more  than  255 
characters)  is  a  prime  candidate  for 
objecthood.  Strings,  however,  have  spe¬ 
cial  privileges  with  respect  to  text  files, 
Readln  and  Writeln,  and  a  whole  slew 
of  built-in  string-handling  routines.  Fur¬ 
thermore,  strings  may  be  returned  as 
function  results,  a  capability  I  would 
be  extremely  reluctant  to  give  up.  En¬ 
casing  a  Pascal  string  within  an  object 
wrapper  actually  adds  complexity  to 
an  application,  and  that’s  not  how  the 
game  is  supposed  to  be  played. 

An  Exercise  in  Modeling  Reality 

When  I  wrote  the  tutorials  in  the  Turbo 
Pascal  5  5  OOP  Guide,  this  sort  of  ques¬ 
tion  hadn’t  occurred  to  me,  as  I  was 
nearly  as  new  to  Object  Pascal  as  the 
rest  of  the  PC  world  and  was  running 
but  a  step  and  a  half  ahead  of  the 
Comprehension  Wolves  through  the 
whole  project.  What  I  knew  of  objects 
came  to  me  from  Smalltalk,  in  which 
everything  is  an  object,  not  excluding 
atomic  particles  such  as  characters  and 
integers.  But  my  Smalltalk  experience 
kept  me  in  good  stead  when  I  had  to 
confront  questions  from  readers  like, 


“How  should  I  divide  an  application 
up  into  objects?”  and,  “How  do  I  de¬ 
fine  the  boundaries  between  objects?” 
There’s  no  easy  answer  this  time,  but 
I’ve  worked  with  a  principle  that  I  con¬ 
sider  very  effective:  Whenever  possi¬ 
ble,  reflect  in  your  objects  the  divisions 
and  relationships  seen  in  reality.  In  other 
words,  make  your  OOP  programs  simu¬ 
lations  even  when  they’re  not  really 
simulations. 

There  I  go  again,  getting  Eastern  on 
you.  Time  to  Get  Real. 

Artifacts,  Not  Actions 

Objects  were  originally  conceived  by 
Simula’s  architects  as  models  of  ele¬ 
ments  of  reality.  Reality  is  not  soup. 
Reality  is  lumpy,  and  the  lumps,  seen 
apart,  are  identifiable  things  with  iden¬ 
tifiable  functions.  A  lamp  is  a  thing  that 
emits  light  when  you  hit  its  buttons 
correctly.  A  carpet  keeps  the  oak  floors 
from  getting  scraped.  Your  Peter  Nor¬ 
ton  mug  is  a  mechanism  that  cooper¬ 
ates  with  gravity  to  keep  your  coffee 
out  of  your  lap.  Every  lump  in  reality 
has  a  name  and  a  job,  though  the  ne¬ 
cessity  of  some,  like  city  planners  and 
the  rock  band  Metallica,  is  seriously 
open  to  question. 

All  of  this  is  second  nature  to  anyone 


who  has  survived  his  or  her  Terrible 
Twos,  but  I  remind  you  of  the  nature 
of  reality  because  I  want  you  to  apply 
it  to  the  way  you  arrange  the  concept 
of  a  program  in  your  mind.  Too  many 
programmers  make  their  programs  like 
you’d  make  soup,  by  tossing  in  a  pinch 
of  this  and  half  a  cup  of  that  and  stir¬ 
ring  it  around  until  it  becomes  rela¬ 
tively  uniform  in  color  and  texture  and 
ceases  to  be  lethal. 

Because  programming  has  always 
been  an  action-oriented  process,  pro¬ 
grammers  often  begin  by  asking  what 
steps  constitute  the  larger  action  of  the 
program.  If  you  have  gotten  to  this 
point,  the  cooking  has  already  begun, 
and  you’re  halfway  to  soup  already. 
Never  forget  this:  A  program  is  not  an 
action.  A  program  is  an  artifact.  Once 
you  throw  the  artifact  into  your  con¬ 
ceptual  duck-press  and  squeeze  it  down 
to  a  statement  of  action,  you’ve  lost  a 
great  deal  of  valuable  information  about 
the  idea  of  the  program.  To  recap  in  a 
slightly  different  way:  A  statement  of 
what  a  program  does  is  far  less  useful 
than  a  statement  of  what  the  program 
is.  The  best  example  has  been  staring 
you  in  the  face  for  years.  Tell  me  first 
what  a  spreadsheet  program  does,  and 
then  when  you’ve  given  up  on  that, 
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tell  me  what  a  spreadsheet  is.  A  spread¬ 
sheet  does  a  whole  host  of  things,  but 
what  a  spreadsheet  is  is  a  model  of  the 
classic  accountant’s  paper  ledger  sheet. 
By  now,  the  lights  should  be  coming  on. 

Collecting  Stamps 

Seeing  artifacts  where  you  used  to  see 
actions  is  perhaps  the  most  important 
skill  to  be  learned  in  picking  up  OOP. 
Let’s  practice  a  little  by  identifying  a 
program  artifact  and  giving  it  reality  as 
an  object. 

The  artifact  in  question  is  the  hum¬ 
ble  moment,  the  point  in  time  at  which 
something  happens.  In  certain  kinds 
of  programming,  particularly  business 
or  financial  programming,  the  time  and 
date  when  a  transaction  happens  can 
be  almost  as  important  as  the  transac¬ 
tion  itself. 

You’ve  seen  evidence  of  a  moment 
in  every  DOS  directory  listing:  The  date 
and  time  when  the  file  was  last  modi¬ 
fied.  Every  directory  entry  on  a  DOS 
disk  has  a  time  stamp  and  a  date  stamp, 
which  are  sometimes  lumped  together 
and  simply  called  the  time  stamp. 

That’s  your  artifact.  To  avoid  confu¬ 
sion  between  its  time  and  date  compo¬ 
nents,  (because  it  incorporates  both)  I 
call  it  a  “when  stamp.”  Any  time  you 
need  to  retain  an  expression  of  the 
moment  that  something  happened  in 
your  program,  you  can  create  a  when 
stamp  object  for  it. 

Objects  embody  both  data  (the  ob¬ 
ject’s  “state”)  and  the  actions  necessary 
to  manipulate  that  data.  The  data  in  a 
when  stamp  is  straightforward:  Some 
single,  unambiguous  expression  of  both 
clock  time  and  calendar  date. 

DOS  has  such  an  expression  in  its 
directory  time  and  date  stamps.  It  makes 
sense  to  use  what  DOS  uses,  (espe¬ 
cially  when  DOS  can  be  made  to  do 
some  of  our  work  for  us)  so  let’s  agree 
to  keep  our  when  stamp  as  DOS-com¬ 
patible  as  possible.  The  DOS  time  stamp 
and  date  stamp  are  both  1 6-bit  words, 
so  we  can  combine  them  into  a  single 
32-bit  type  in  Object  Pascal.  The  obvi¬ 
ous  candidate  is  Longlnt,  the  32-bit 
long  integer  type. 

Having  the  when  stamp  stored  in  a 
single  numeric  type  carries  the  side 
benefit  that  two  when  stamps  can  be 
compared  for  time  priority  just  by  com¬ 
paring  with  the  numeric  greater  than 
and  less  than  operators. 

Time  values  are  never  negative,  so 
you  might  begin  to  worry  about  the 
sign  bit  in  a  long  integer,  which  is  a 
signed  type.  As  it  happens,  you  will 
have  to  worry,  but  not  for  a  very  long 
time.  (More  on  this  later — nonethe¬ 
less,  I  still  wish  that  Pascal  had  a  Long- 
Word  type.') 


Once  we  get  the  expression  of  time 
and  date,  we’ll  need  methods  to  ma¬ 
nipulate  it.  But  before  you  start  think¬ 
ing  about  methods,  get  your  data  and 
its  representation  in  order. 

Encoding  Time  and  Date,  DOS-style 

Understanding  how  our  When  object 
works  depends  heavily  on  knowing 
how  DOS  encodes  its  time  and  date 
stamps  in  their  16-bit  words. 

If  we  used  neat  decimal  star  dates  like 
Captain  Kirk,  we’d  be  better  off,  but  alas, 
a  date  is  a  set  of  three  separate  numeric 
quantities:  Year,  an  ascending  value 
that  never  repeats,  month,  a  value  that 
repeats  regularly  through  a  cycle  of  12, 
and  day,  a  value  that  repeats  through 
a  cycle  of  28,  29,  30,  or  31.  This  makes 
date  arithmetic  ugly  unless  the  date  is 
encoded  as  a  single  numeric  value. 
The  means  is  this:  Express  year,  month, 
and  date  as  binary  quantities,  then  line 
them  up  in  a  single  16-bit  word  such 
that  the  year  portion  occupies  the  high- 
est-order  bits,  the  month  portion  occu¬ 
pies  the  next-highest  order  bits,  and 
the  day  portion  occupies  the  lowest- 
order  bits.  Done  this  way,  two  date 
stamps  with  different  years  will  always 
compare  correctly  regardless  of  month 
or  date;  two  stamps  with  identical  years 
will  always  compare  correctly  on  the 
basis  of  month,  regardless  of  date,  and 
so  on.  Which  bits  relate  to  year,  month, 
and  date  is  shown  in  Figure  1. 

Note  that  the  year  is  encoded  in  a 
peculiar  (and  I  think  unfortunate)  way: 
As  an  offset  from  the  year  1980.  1980  is 
thus  year  0,  1981  year  1,  and  so  on.  This 
allows  the  year  to  be  encoded  in  only  a 
few  bits,  leaving  plenty  of  room  for  the 
month  and  day  in  a  16-bit  word.  The 
downside  is  that  you  can’t  encode  your 


Figure  1:  The  DOS  date  stamp  format 


birthday  as  a  time  stamp,  since  you 
were  probably  born  considerably  prior 
to  1980.  (I  was,  and  have  the  hairline 
to  prove  it.)  Seriously,  this  limits  the  use 
of  when  stamps  to  things  that  occur  in 
true  calendar  time  while  the  computer 
is  in  use,  and  not  to  encode  events  that 
happened  long  ago.  I  was  a  little  con¬ 
cerned  about  the  use  of  a  signed  type 
to  hold  the  when  stamp.  At  some  point, 
the  bit  encoding  of  the  time  and  date 
will  set  the  high  bit  in  the  long  integer, 
turning  the  value  negative  in  the  eyes 
of  the  run-time  library.  This  blows  any 
possibility  of  valid  comparisons  out  the 
window,  because  a  later  value  that  is 
negative  will  be  seen  as  less  (and  hence 
earlier)  than  any  positive  stamp.  How¬ 
ever,  when  I  did  the  math  I  found  that 
the  stamp  does  not  turn  negative  until 
December  31,  2043,  by  which  time  I 
will  either  be  dead  or  perfecting  zero-G 
lovemaking  techniques  out  past  the  or¬ 
bit  of  Mars. 

1 7  Pounds  of  Kitty  Litter  in  a 
1 6-pound  Bag 

The  DOS  time  stamp  presents  a  prob¬ 
lem.  No  matter  how  you  encode  the 
hours,  minutes,  and  seconds  (and  for¬ 
get  hundredths  here)  you  end  up  with 
a  minimum  of  17  bits:  Six  for  minutes 
(0  -  59);  six  for  seconds  (0  -  59),  and 
five  for  hours  (0  -  23). 

You  can  usually  cram  17  pounds  of 
kitty  litter  into  a  1 6-pound  bag  by  shak¬ 
ing  things  around  a  little.  Not  so  in  the 
bit  game  —  we  pack  ’em  tight.  Some¬ 
thing  has  to  give  a  little,  so  what  we 
do  is  ignore  every  other  second.  This 
cuts  the  number  of  bits  required  to 
encode  seconds  to  five,  and  16  bits  will 
suddenly  hold  the  stamp.  See  Figure  2. 

Note  the  way  the  stamp  is  encoded 
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Hours  (0-23)  Minutes  (0-59)  '  Seconds  (0-59  DIV  2) 

TimeStamp  :=  (Hours  SHL  1 1)  OR  (Minutes  SHL  5)  OR  (Seconds  SHR  1); 


Figure  2:  The  DOS  time  stamp  format 
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(continued  from  page  138) 
in  the  figure:  Whereas  the  hours  and 
minutes  values  are  shifted  left  to  move 
them  toward  the  high  end  of  the  word, 
the  seconds  value  is  shifted  right  by 
one  bit,  which  bumps  that  bit  off  into 
Peoria  and  out  of  our  hair.  Truncating 
the  seconds  by  half  means  that  two 
events  occurring  less  than  two  seconds 
apart  will  probably  resolve  to  identical 
time  stamps,  depending  on  their  syn¬ 
chronization  with  the  system  clock.  You 
have  to  keep  this  in  mind  and  avoid 
designing  time  stamps  encoded  this 
way  into  applications  where  stampable 
events  happen  in  quick  succession.  Note 
also  that  your  seconds  value  will  al¬ 
ways  be  an  even  number,  because  the 
1  bit  that  can  make  it  odd  is  not  stored 
in  the  stamp. 

To  Represent  or  Calculate? 

At  the  heart  of  it,  then,  a  When  object 
consists  of  a  long  integer  time/date 
stamp  encoded  as  explained  earlier.  If 
you  only  needed  to  compare  two  stamps 
for  time  order,  this  would  be  enough. 
However,  you  may  need  to  access  the 
seconds  value  separately,  or  the  hours 
or  months,  and  you  may  want  to  dis¬ 
play  time  or  date  or  both  in  some  gen¬ 
erally  understood  ASCII  form.  There 
are  two  ways  to  do  this: 

•  Add  separate  fields  to  the  object  to 
contain  distinct  hours,  minutes,  and 
seconds;  and  years,  months,  and  days. 
Then  recalculate  and  update  those  fields 
any  time  the  stamp  itself  changes. 

•  Leave  the  time/date  stamp  as  the  sole 
data  field  in  the  object,  and  calculate 
any  component  value  whenever  a  user 
of  the  object  requests  it. 

The  first  option  buys  speed  at  the  ex¬ 
pense  of  space,  and  the  second  buys 
space  at  the  expense  of  speed.  Which 
do  you  use?  Well,  do  you  need  more 
speed  or  space? 

I’m  not  just  being  glib  here.  There’s 
no  single  answer.  You  as  the  object’s 
designer  have  to  keep  track  of  your 
own  particular  needs.  I  tend  to  write 
small  programs,  and  I  like  fast  ones, 
so  my  own  first  impulse  is  to  throw 
memory  at  problems  to  make  them 
faster.  This  is  the  design  choice  I  made 
in  implementing  the  When  object,  as 
shown  in  Listing  One,  page  150. 

The  When  object  has  as  its  central 
data  item  the  WhenStamp  long  integer 
field.  It  also  has  separate  fields  for  year, 
month,  day,  day  of  week,  hours,  min¬ 
utes,  and  seconds.  I  added  an  ASCII 
representation  of  time  identical  to  that 
used  in  the  DOS  DIR  command,  as 
well  as  two  ASCII  date  representations: 
One  in  the  form  yy/mm/dd,  and  the 
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other  in  the  form  “Thursday,  June  29, 
1989.”  This  adds  94  bytes  to  the  size 
of  the  object,  but  I  did  it  with  eyes 
open  and  decided  that  the  benefits  were 
worth  the  cost.  There  was  one  excep¬ 
tion.  I  chose  not  to  provide  a  separate 
16-bit  time  and  date  stamp,  as  I  had 
originally  considered  doing,  because 
returning  one  half  or  the  other  of  a 
long  integer  can  be  done  without  any 
significant  calculation  overhead,  just  by 
typecasting.  Notice  the  definition  of 
WhenUnion ,  private  to  the  unit: 

WhenUnion  = 

RECORD 

TimePart :  Word; 

DatePart :  Word; 

END; 

WhenUnion  is  the  same  size  as  Long- 
Int ,  so  you  can  use  a  value  typecast  to 
access  either  the  time  or  date  portion 
of  the  combined  time/date  stamp: 

TimeStamp  := 

WhenUnion(WhenStamp).TimePart; 

It’s  that  easy,  and  saves  you  4  bytes  of 
memory  at  the  cost  of  no  calculation 
at  all.  I  like  that  sort  of  deal  —  kind  of 
like  insider  trading  in  Silicon  Valley. 

Choosing  Your  Methods 

Once  you’ve  decided  what  your  object 
is,  you  can  begin  working  out  what  it 
does;  that  is,  design  its  suite  of  meth¬ 
ods.  I  wanted  my  when  stamp  object 
to  be  easily  updated,  so  I  provided 
numerous  methods  for  changing  the 
value  of  the  WhenStamp  field.  All  the 
methods  beginning  with  Put  change 
the  value  of  WhenStamp ,  and  all  the 
methods  beginning  with  Get  return 
some  value  from  the  object.  This  is  a 
good  naming  convention  when  design¬ 
ing  objects,  and  I  recommend  it.  The 
PutNow  method  is  simple  but  extremely 
useful:  It  reads  the  current  value  of  the 
PC’s  clock/calfendar  and  applies  the  cur¬ 
rent  time  and  date  to  the  when  stamp. 
The  other  Put  methods  alter  the  value 
of  the  when  stamp  by  providing  a  new 
value  for  either  the  whole  stamp 
( PutWhenStamp )  or  some  component 
value  of  the  stamp,  such  as  year,  month, 
or  hours.  How  many  such  methods 
you  build  into  an  object  depends  on 
how  you  intend  to  use  the  object.  My 
recommendation  is  to  build  more  into 
the  object  than  you  may  need,  and 
reexamine  the  design  some  time  down 
the  road.  You  can  always  strip  out  what 
you  haven’t  used  .  .  .  but  you  never 
know  when  some  flash  of  insight  will 
allow  you  to  find  a  use  for  a  method 
that  you  hadn’t  imagined  when  you 
originally  wrote  it! 
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The  Encapsulation  Question 

The  “pure”  object-oriented  languages 
such  as  Smalltalk  and  Actor  both  allow 
and  enforce  total  encapsulation  of  an 
object’s  data.  You  cannot  directly  refer¬ 
ence  an  object’s  data  from  outside  the 
object  or  its  descendants.  Object  Pascal 
allows  total  encapsulation,  in  that  you 
can  voluntarily  provide  a  separate 
method  to  return  the  value  of  each 
field  in  the  object.  Nothing  enforces 
this,  however  —  you  can  reference  any 
field  in  any  object  from  anywhere  in 
your  program.  Purists  will  say,  “So 
what?”  Give  ’em  the  methods  anyway, 


and  say  hands  off  the  data.  Such  hard- 
nosedness  gives  you  the  considerable 
benefit  of  being  able  to  change  the 
actual  representation  of  the  data  within 
an  object  without  breaking  the  code 
that  uses  the  object.  For  example,  if  I 
forbade  direct  references  to  the  data 
inside  When ,  I  could  come  up  with 
my  own  time  stamp  format  that  was 
truly  universal  and  did  not  ignore  the 
existence  of  years  prior  to  1980  as  well 
as  every  other  tick  of  the  clock. 

If  you  needed  to  provide  stamps  for 
old  financial  records,  birthdays,  and 
such  (as  in  a  life  insurance  application) 


you’d  be  far  better  off  going  this  route. 
My  own  need  for  time  stamps,  how¬ 
ever,  was  limited  to  stamping  transac¬ 
tions  occurring  at  the  current  moment, 
so  I  made  the  decision  not  to  add  the 
additional  level  of  complication  to 
When.  I  also  wanted  to  retain  full  com¬ 
patibility  with  the  DOS  directory  time 
and  date  stamps,  and  the  easiest  way 
to  do  that  is  simply  to  represent  the 
time  and  date  the  same  way  DOS  does. 
Given  these  assumptions,  I  created 
When  to  allow  direct  read  access  to  all 
the  data  fields. 

Note  that  I  said  read.  Writing  directly 
to  the  fields  is  not  a  good  idea,  because 
all  the  fields  but  WhenStamp  are  actu¬ 
ally  component  values  of  WhenStamp, 
and  if  you  were  to  change  the  Month 
field  without  changing  WhenStamp,  the 
two  would  be  “out  of  sync.”  The  Put 
methods  were  designed  so  that  chang¬ 
ing  any  part  of  the  time  stamp  recalcu¬ 
lates  all  component  values  relating  to 
that  part  of  the  time  stamp.  For  example, 
changing  the  date  half  of  the  when  stamp 
recalculates  the  Year,  Month,  Day,  Day - 
OfWeek,  DateString,  and  LongDateString 
fields,  without  affecting  Hours,  Minutes, 
Seconds,  or  TimeString. 

You  need  to  be  aware  of  such  de¬ 
pendencies  when  deciding  how  to  allow 
updating  of  an  object’s  data.  Calculating 
component  values  from  a  master  field 
such  as  WhenStamp  whenever  they  are 
needed  avoids  problems  like  this,  if  you 
can  tolerate  the  loss  of  performance. 

Private  Parts 

For  reasons  unknown,  many  newcom¬ 
ers  to  OOP  get  the  notion  in  their  nog¬ 
gins  that  all  of  an  object’s  processing 
must  be  confined  to  its  methods,  and 
that  while  methods  can  call  one  an¬ 
other,  methods  somehow  cannot  call 
other  procedures  and  functions  unre¬ 
lated  to  the  object.  Not  true!  A  method 
can  call  any  routine  within  its  scope, 
just  as  any  nonmethod  procedure  or 
function  can.  Furthermore,  there  is  no 
way  to  declare  a  “private”  method  in 
Object  Pascal.  A  private  method  would 
be  one  that  could  be  called  by  other 
methods  within  the  object,  but  that 
could  not  be  accessed  from  outside  the 
object.  If  there  is  any  private  process¬ 
ing  to  be  done  by  an  object,  you  can 
do  what  I’ve  done  with  When  and  place 
the  object  definition  in  a  unit  —  with 
private  procedures  and  functions  fully 
declared  and  defined  within  the  im¬ 
plementation  section.  Such  procedures 
and  functions  may  be  called  by  the 
object’s  methods  but  are  not  available 
to  anyone  outside  the  unit  itself.  Simi¬ 
larly,  the  MonthTags  and  DayTags  con¬ 
stants  exist  for  the  convenience  of  the 
object  and  are  not  needed  by  users  of 
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the  object,  so  I’ve  declared  them  pri¬ 
vately,  within  the  implementation  sec¬ 
tion.  Ditto  with  WhenUnion.  As  long 
as  you  provide  functions  to  return  sepa¬ 
rate  16-bit  values  for  the  time  stamp 
and  date  stamp  portions  of  the  when 
stamp  (as  I  did  with  GetTimeStamp  and 
GetDateStamp),  there’s  no  need  to  give 
the  user  the  WhenUnion  definition.  Half 
the  battle  of  programming  is  masking 
complexity,  so  keep  an  object’s  private 
parts  under  a  bushel  basket  where  they 
won’t  be  stepped  on  or  misused  by  the 
ignorant  and  the  unwary. 

One  of  the  private  routines  is  a  day-of- 
the-week  calculator  using  an  algorithm 
called  “Zeller’s  Congruence.”  I’ve  had 
this  routine  in  my  files  for  so  long  I  no 
longer  remember  who  coded  it  up  and 
gave  it  to  me,  and  I  categorically  do 
not  understand  how  it  works  .  .  .  but  it 
does  work. 

Homework  Assignments 

That’s  how  1  went  about  designing  a 
very  simple  object.  To  make  sure  it 
sinks  in,  do  the  following  things  for 
practice: 

•  Recode  the  When  object  such  that  the 
only  data  field  is  the  long  integer  When- 
Stamp,  with  all  other  component  values 
and  alternate  representations  calculated 
as  they  are  needed,  by  new  Get  meth¬ 
ods.  This  shouldn’t  involve  much  new 
code  at  all,  but  will  involve  moving 
existing  code  around  a  lot.  While  you’re 
at  it,  you  might  add  a  simple  function 
to  return  the  full  long  integer  value  of 
WbenStamp,  giving  you  total  encapsu¬ 
lation.  You  might  like  this  more  com¬ 
pact  version  of  When  more  than  mine. 
So  be  it.  I’m  not  you.  (And  I  suspect 
we  both  should  be  glad.  .  .  .) 

•  Write  new  methods  to  add  or  sub¬ 
tract  specific  values  from  the  when 
stamp.  You  might  want  to  create  a  when 
stamp  containing  a  value  exactly  30 
days  from  right  now,  and  then  monitor 
that  stamp  over  the  coming  month  to 
ensure  that  something  necessary  hap¬ 
pens  at  that  moment.  This  requires  a 
way  of  adding  30  days  to  the  long 
integer  WbenStamp  value.  It’s  fairly  easy 
...  do  it! 

Object  Design  Recap 

To  summarize: 

An  object  is  an  artifact,  not  an  action. 
Look  at  the  way  the  universe  is  broken 
down  into  components,  and  learn  to 
think  of  your  programs  as  built  of  com¬ 
ponent  parts  in  much  that  same  way. 

Once  you’ve  identified  such  a  soft¬ 
ware  artifact,  decide  how  to  represent 
its  data  first.  Only  once  you  have  the 
data  design  down  should  you  begin  to 
ponder  what  methods  it  needs  to  serve 


that  data.  Remember,  Data  is  Boss  in 
object  land. 

It’s  possible  and  often  desirable  to 
disallow  any  direct  access  to  an  ob¬ 
ject’s  data.  This  frees  you  to  change  the 
way  the  data  is  stored  within  the  object 
without  breaking  code  that  uses  the 
object.  Remember,  however,  that  this 
can  add  significant  performance  handi¬ 
caps  to  code  that  uses  your  objects. 
Keep  the  tradeoffs  in  mind,  but  (as  the 
cricket  kept  saying)  always  let  your 
conscience  be  your  guide. 

Also  remember  that  this  is  just  a  first 
lesson.  We  haven’t  even  begun  to  ad¬ 
dress  the  issues  presented  by  inheri¬ 
tance  or,  lord  knows,  polymorphism. 
All  in  good  time. 

Have  You  Seen  this  Book? 

Maybe  you  all  can  help  me  out  a  little. 
My  newest  book,  Assembly  Language 
From  Square  One ,  (Scott,  Foresman  & 
Company)  has  been  off  the  presses  for 
some  time,  and  I  have  yet  to  see  it  in 
any  store.  If  you  have  seen  it  any¬ 
where,  drop  me  a  postcard  at  DDJ  and 
tell  me  what  store  is  carrying  it.  The 
computer  book  distribution  system 
seems  to  be  breaking  down  in  recent 
months,  much  as  it  did  in  1984.  Huge 
numbers  of  titles,  most  fit  only  to  hang 
in  a  Tennessee  outhouse,  have  been 
pouring  into  the  retail  channel  lately, 
and  it’s  gotten  me  (and  some  other 
well-known  authors)  more  than  a  little 
worried.  We  may  not  be  able  to  change 
the  system,  but  we’d  at  very  least  like 
to  know  what  books  are  going  where. 

Thanks. 

Write  to  Jeff Duntemann  on  MCI  Mail 
as  JDuntemann,  or  on  CompuServe  to 
ID  76117,1426. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  150.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  11. 
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C  PROGRAMMING 


Listing  One  (Text  begins  on  page  127.) 

/*  - csort.h - */ 


f close (fpout) ; 
sort_stats  () ; 
free (buf ) ; 


♦define  NOFLDS  5  /*  maximum  number  of  fields  to  sort 

♦define  MOSTMEM  50000U  /*  most  memory  for  sort  buffer 

♦define  LEASTMEM  10240  /*  least  memory  for  sort  buffer 


struct  s_prm  {  /* 

int  rc_len;  /* 

struct  { 

int  f_pos;  /* 

int  f_len;  /* 

char  ad;  /* 

}  s_fld  [NOFLDS];  /* 

} ; 


sort  parameters  */ 
record  length  */ 

1st  position  of  field  (rel  1)  */ 
length  of  field  */ 
a  =  ascending;  d  =  descending  */ 
one  per  field  */ 


static  void  usage (void) 

{ 

printf ("\nusage:  filesort  fname  len  (pos  length  ad — }"); 
exit  (1) ; 


End  Listing  Two 


Listing  Three 


struct  bp  { 
char  *rc; 
int  rbuf; 
int  rdsk; 


/*  one  for  each  sequence  in  merge  buffer  */ 
/*  ->  record  in  merge  buffer  */ 
/*  records  left  in  buffer  this  sequence  */ 
/*  records  left  on  disk  this  sequence  */ 


int  init_sort (struct  s_prm  *prms);  /* 
void  sort (char  *rcd) ;  /* 
char  *sort_op(void) ;  /* 
void  sort_stats (void) ;  /* 


Initialize  the  sort  */ 

Pass  records  to  Sort  */ 

Retrieve  sorted  records*/ 

Display  sort  statistics*/ 

End  listing  One 


Listing  Two 

/*  - filesort. c -  */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦include  "csort.h" 

/*  sort  a  file: 

*  command  line:  filesort  filename  length  { f 1 ,  11,  azl,  ...) 

*  filename  is  the  name  of  the  input  file 

*  length  is  the  length  of  a  record 

*  for  each  field: 

*  fl  is  the  field  position  relative  to  1 

*  11  is  the  field  lengths 

*  azl  =  A  =  ascending,  D  =  descending 


static  struct  s_prm  sp; 
static  void  usage (void); 

void  main (int  argc,  char  *argv[]) 

{ 

int  i,  fct  =  0; 

FILE  *fpin,  *fpout; 

char  *buf; 

char  filename [ 64 ] ; 

/* - get  the  file  name  from  the  command  line - */ 

if  (argc--  >  1) 

strcpy (filename,  argv++(l]); 

else 

usage ( ) ; 

/*  -  get  the  record  length  from  the  command  line  -  */ 

if  (argc--  >  1) 

sp.rc_len  =  atoi (argv++ [1] ) ; 

else 

usage  ( ) ; 

/*  -  get  field  definitions  from  the  command  line  -  */ 

do  ( 

if  (argc  <  4) 
usage  () ; 

sp.s_fld[fct] .f_pos  =  atoi (argv++[l] ) ; 
sp.s_fld[fct] .f_len  =  atoi(argv++[lj); 
sp.s_fld[fct] .ad  =  *argv++[l]; 
argc  -=  3; 
fct++; 

}  while  (argc  >1); 

printf ("\nFile:  %s,  length",  filename,  sp.rc_len); 
for  (i  =0;  i  <  fct;  i++) 

printf ("\nField  %d:  position  %d,  length  %d,  %s", 
i+1, 

sp.s_fld(i] .f_pos, 
sp.s_fld[ij .f_len, 
sp. s_f Id [ i ] .ad  ==  'd'  ? 

"descending"  :  "ascending"); 

if  ( ( fpin  =  fopen (filename,  "rb"))  ==  NULL)  { 
printf ("\nlnput  file  not  found"); 
exit  (1)  ; 

) 

if  ((buf  =  malloc (sp. rc_len) )  ==  NULL 
init_sort  (&s£>)  ==  -1)  { 

printf ("\nlnsufficient  memory  to  sort"); 
exit (1) ; 

} 

/* - sort  the  input  records - */ 

while  (fread(buf,  sp.rc_len,  1,  fpin)  ==  1) 
sort (buf) ; 
sort (NULL) ; 
fclose (fpin) ; 

/*  -  retrieve  the  sorted  output  records  -  */ 

fpout  =  fopen ("SORTED.DAT",  "wb"); 
while  ((buf  =  sort_op())  !=  NULL) 

f write (buf,  sp.rc_len,  1,  fpout); 


/* - csort.c - */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦include  "csort.h" 


static  struct  s_prm  *sp;  /*  structure  of  sort  parameters  */ 
static  unsigned  totrcd;  /*  total  records  sorted  */ 
static  int  no_seq;  /*  counts  sequences  */ 
static  int  no_seql; 

static  unsigned  bspace;  /*  available  buffer  space  */ 
static  int  nrcds;  /*  ♦  of  records  in  sort  buffer  */ 
static  int  nrcdsl; 

static  char  *bf,  *bfl;  /*  points  to  sort  buffer  */ 
static  int  inbf;  /*  variable  records  in  sort  buffer  */ 
static  char  **sptr;  /*  ->  array  of  buffer  pointers  */ 
static  char  *init_sptr;  /*  pointer  to  appropriated  buffer  */ 
static  int  rcds_seq;  /*  reds  /  sequence  in  merge  buffer  */ 
static  FILE  *fpl,  *fp2;  /*  sort  work  file  fds  */ 
static  char  fdname[15);  /*  sort  work  name  */ 
static  char  f2name[15);  /*  sort  work  name  */ 


static  int  comp(char  **a,  char  **b); 
static  char  *appr_mem (unsigned  *h) ; 
static  FILE  *wopen(char  *name,  int  n) ; 
static  void  dumpbuff (void) ; 
static  void  merge (void); 
static  void  prep_merge (void) ; 

/* - initialize  sort  global  variables -  */ 

int  init_sort (struct  s  prm  *prms) 

{ 

sp  =  prms; 

if  ( (bf  =  appr_mem(&bspace) )  !=  NULL)  { 

nrcdsl  =  nrcds  =  bspace  /  (sp->rc_len  +  sizeof(char  *)); 

init_sptr  =  bf; 

sptr  =  (char  **)  bf; 

bf  +=  nrcds  *  sizeof(char  *); 

fpl  =  fp2  =  NULL; 

totrcd  =  no_seq  =  inbf  =  0; 

return  0; 

) 

else 

return  -1; 


/* - Function  to  accept  records  to  sort - */ 

void  sort (char  *s_rcd) 

{ 

if  (inbf  ==  nrcds)  {  /*  if  the  sort  buffer  is  full  */ 

qsort (init_sptr,  inbf, 

sizeof  (char  *),  comp) ; 

if  (s_rcd)  {  /*  if  there  are  more  records  to  sort  */ 

dumpbuff ();  /*  dump  the  buffer  to  a  sort  work  file*/ 
no_seq++;  /*  count  the  sorted  sequences  */ 

} 

} 

if  (s_rcd  ! =  NULL)  { 

/*  —  this  is  a  record  to  sort  —  */ 
totrcd++; 

/*  —  put  the  red  addr  in  the  pointer  array  —  */ 

*sptr  =  bf  +  inbf  *  sp->rc_len; 
inbf++; 

/*  —  move  the  red  to  the  buffer  —  */ 
memmove (*sptr,  s_rcd,  sp->rc_len); 

sptr++;  /*  point  to  next  array  entry  */ 

) 

else  {  /*  null  pointer  means  no  more  reds  */ 

if  (inbf)  (  /*  any  records  in  the  buffer?  */ 

qsort (init_sptr,  inbf, 

sizeof  (char  *),  comp) ; 

if  (no_seq)  /*  if  this  isn't  the  only  sequence*/ 

dumpbuff ();  /*  dump  the  buffer  to  a  work  file  */ 

no_seq++;  /*  count  the  sequence  */ 

) 

no_seql  =  noseq; 

if  (no_seq  >1)  /*  if  there  is  more  than  1  sequence  */ 

prep_merge () ;  /*  prepare  for  the  merge  */ 


/* - Prepare  for  the  merge -  */ 

static  void  prep_merge() 

{ 

int  i  ; 

struct  bp  *rr; 
unsigned  n_bfsz; 

memset (init_sptr,  '\0',  bspace); 

/* - merge  buffer  size - */ 


(continued  on  page  146) 
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Listing  Three  (Listing  continued,  text  begins  on  page  127.) 

n_bfsz  =  bspace  -  no_seq  *  sizeof (struct  bp); 

/* - #  rcds/seq  in  merge  buffer - */ 

rcds_seq  =  n_bfsz  /  no_seq  /  sp->rc_len; 
if  (rcds_seq  <  2)  { 

/*  -  more  sequence  blocks  than  will  fit  in  buffer, 

merge  down - */ 

fp2  =  wopen (f2name,  2);  /*  open  a  sort  work  file  */ 

while  (rcds_seq  <  2)  { 

FILE  *hd; 

merge ();  /*  binary  merge  */ 

hd  =  fpl;  /*  swap  fds  */ 

fpl  =  fp2; 
fp2  =  hd; 
nrcds  *=  2; 

/* - adjust  number  of  sequences - */ 

no_seq  =  (no_seq  +1)  /  2; 

n_bfsz  =  bspace  -  no_seq  *  sizeof (struct  bp); 
rcds_seq  =  n_bfsz  /  no_seq  /  sp->rc_len; 

) 

) 

bfl  =  init_sptr; 
rr  =  (struct  bp  *)  init_sptr; 
bfl  +=  no_seq  *  sizeof (struct  bp); 
bf  =  bfl; 

/*  fill  the  merge  buffer  with  records  from  all  sequences  */ 

for  (i  =  0;  i  <  no_seq;  i++)  { 

f seek (fpl,  (long)  i  *  ((long)  nrcds  *  sp->rc_len) , 

SEEK_SET) ; 

/* - read  them  all  at  once - */ 

f read (bfl,  rcds_seq  *  sp->rc_len,  1,  fpl); 
rr->rc  =  bfl; 

/*  —  the  last  seq  has  fewer  reds  than  the  rest  —  */ 
if  (i  ==  no_seq-l)  { 

if  (totred  %  nrcds  >  rcds_seq)  { 

rr->rbuf  =  rcds_seq; 

rr->rdsk  =  (totred  %  nrcds)  -  rcds_seq; 

} 

else  { 

rr->rbuf  =  totred  %  nrcds; 
rr->rdsk  =  0; 

} 

} 

else  { 

rr->rbuf  =  rcds_seq; 
rr->rdsk  =  nrcds  -  rcds_seq; 

} 

rr++; 

bfl  +=  rcds_seq  *  sp->rc_len; 

) 

} 


} 

/* - Dump  the  sort  buffer  to  the  work  file - */ 

static  void  dumpbuff() 

{ 

int  i; 

if  (fpl  ==  NULL) 

fpl  =  wopen (fdname,  1); 
sptr  =  (char  **)  init_sptr; 
for  (i  =  0;  i  <  inbf;  i++)  ( 

fwrite (* (sptr  +  i),  sp->rc_len,  1,  fpl); 

* (sptr  +  i)  =  0; 

) 

inbf  =  0; 

) 

/*  - Open  a  sort  work  file -  */ 

static  FILE  *wopen(char  *name,  int  n) 

{ 

FILE  *fp; 

strcpy(name,  "sortwork . 000" ) ; 
name [ st rlen (name)  -  1]  +=  n; 
if  ( (fp  -  fopen(name,  "wb+"))  ==  NULL)  { 
printf ("\nFile  error"); 
exit (1) ; 

) 

return  fp; 

} 

/* - Function  to  get  sorted  records - - - 

This  is  called  to  get  sorted  records  after  the  sort  is  done. 

It  returns  pointers  to  each  sorted  record. 

Each  call  to  it  returns  one  record. 

When  there  are  no  more  records,  it  returns  NULL.  -  */ 

char  *sort_op() 

{ 

int  j  =  0; 
int  nrd,  i,  k,  1; 
struct  bp  *rr; 
static  int  rl  =  0; 
char  *rtn; 
long  ad,  tr; 

sptr  =  (char  **)  init_sptr; 
if  (no_seq  <  2)  { 

/*  —  with  only  1  sequence,  no  merge  has  been  done  —  *7 
if  (rl  ==  totred)  { 
free (init_sptr)  ; 
fpl  =  fp2  =  NULL; 
rl  =  0; 
return  NULL; 

) 

return  *(sptr  +  rl++) ; 

) 


/* - Merge  the  work  file  down 

This  is  a  binary  merge  of  records  from  sequences 


in  fpl  into  fp2.  - */ 

static  void  merge () 

{ 

int  i; 

int  needy,  needx;  /*  true  =  need  a  red  from  (x/y)  */ 

int  xent,  yent;  /*  #  reds  left  each  sequence  */ 

int  x,  y;  /*  sequence  counters  */ 

long  adx,  ady;  /*  sequence  record  disk  addresses  */ 


/*  —  the  two  sets  of  sequences  are  x  and  y  -  */ 

fseek (fp2,  0L,  SEEK_SET) ; 
for  (i  =0;  i  <  no_seq;  i  +=  2)  { 

x  =  y  =  i; 
y++; 
yent  = 

y  =  no_seq  ?  0  :  y  ==  no_seq  -  1  ? 
totred  %  nrcds  :  nrcds; 
xent  =  y  ==  no_seq  ?  totred  %  nrcds  :  nrcds; 
adx  =  (long)  x  *  (long)  nrcds  *  sp->rc_len; 
ady  =  adx  +  (long)  nrcds  *  sp  ->rc_len; 
needy  =  needx  =  1; 
while  (xent  ! \  yent)  ( 

if  (needx  &&  xent)  (  /*  need  a  red  from  x?  */ 

fseek (fpl,  adx,  SEEK_SET) ; 
adx  +=  (long)  sp->rc_len; 
fread(init_sptr,  sp->rc_len,  1,  fpl); 
needx  =  0; 

} 

if  (needy  &&  yent)  {  /*  need  a  red  from  y?  */ 

fseek (fpl,  ady,  SEEK_SET) ; 
ady  +=  sp->rc_len; 

fread(init_sptr+sp->rc_len,  sp->rc_len,  1,  fpl); 
needy  =  0; 

) 

if  (xent  ! !  yent)  {  /*  if  anything  is  left  */ 

/*  -  compare  the  two  sequences  —  */ 

if  (lycnt  I!  (xent  && 

(comp(&init_sptr,  &init_sptr  +  sp->rc_len) ) 
<  0))  { 

/* - record  from  x  is  lower - */ 

fwrite (init_sptr,  sp->rc_len,  1,  fp2); 

— xent; 
needx  =  1; 

1 

else  if  (yent)  {  /*  record  from  y  is  lower  */ 

fwrite (init_sptr+sp->rc_len, 

sp->rc_len,  1,  fp2); 

— yent; 
needy  =  1; 

} 

} 

) 
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rr  =  (struct  bp  *)  init_sptr; 
for  (i  =  0;  i  <  no_seq;  i++) 

j  1=  (rr  +  i)->rbuf  I  (rr  +  i)->rdsk; 

/*  —  j  will  be  true  if  any  sequence  still  has  records  -  */ 

if  (!j)  { 

fclose(fpl);  /*  none  left  */ 

remove (fdname) ; 
if  <fp2)  { 

fclose (fp2) ; 
remove (f2name) ; 

} 

f ree (init_sptr) ; 
fpl  =  fp2  =  NULL; 
rl  =  0; 
return  NULL; 

} 

k  =  0; 

/*  —  find  the  sequence  in  the  merge  buffer 

with  the  lowest  record  -  */ 

for  (i  =  0;  i  <  no_seq;  i++) 

k  =  ((comp(  &(rr  +  k)->rc,  &(rr  +  i)->rc)  <  0)  ?  k  :  i); 

/*  —  k  is  an  integer  sequence  number  that  offsets  to  the 
sequence  with  the  lowest  record  -  */ 

(rr  +  k)->rbuf — ;  /*  decrement  the  red  counter  */ 

rtn  =  (rr  +  k)->rc;  /*  set  the  return  pointer  */ 

(rr  +  k)->rc  +=  sp->rc_len; 
if  ((rr  +  k)->rbuf  ==  0)  ( 

/* - the  sequence  got  empty - */ 

/*  —  so  get  some  more  if  there  are  any  —  */ 
rtn  =  bf  +  k  *  rcds_seq  *  sp->rc_len; 
memmove(rtn,  (rr  +  k)~>rc  -  sp->rc_len,  sp->rc_len) ; 

(rr  +  k)->rc  =  rtn  +  sp->rc_len; 
if  ((rr  +  k)->rdsk  !=  0)  ( 

1  =  ( (rcds_seq-l)  <  (rr+k) ->rdsk)  ? 

rcds_seq-l  :  (rr+k) ->rdsk; 
nrd  =  k  ==  no_seq  -  1  ?  totred  %  nreds  :  nreds; 
tr  =  (long)  ( (k  *  nreds  +  (nrd  -  (rr  +  k)->rdsk))); 
ad  =  tr  *  sp->rc_len; 
fseek (fpl,  ad,  SEEK_SET) ; 

fread(rtn  +  sp->rc_len,  1  *  sp->rc_len,  1,  fpl); 

(rr  +  k) ->rbuf  =  1; 

(rr  +  k)->rdsk  -=  1; 

} 

else 

memset((rr  +  k)->rc,  127,  sp->rc_len); 

) 

return  rtn; 


/* - Function  to  display  sort  stats - */ 

void  sort_stats() 

{ 

printf ("\n\n\nRecord  Length  =  %d", sp->rc_len) ; 
printf("\n%d  records  sorted", totred) ; 
printf ("\n%d  sequence", no_seql) ; 
if  (no_seql  !=  1) 
putchar (' s' ) ; 

printf ("\n%u  characters  of  sort  buffer",  bspace) ; 
printf ("\n%d  records  per  buffer\n\n",nrcdsl) ; 

1 

/*  -  appropriate  available  memory  -  */ 

static  char  *appr_mem (unsigned  *h) 

( 

char  *buff  =  NULL; 

‘h  =  (unsigned)  MOSTMEM  +  1024; 

while  (buff  ==  NULL  &&  *h  >  LEASTMEM)  { 

*h  -=  1024; 
buff  =  malloc (*h) ; 

) 

return  buff; 

) 

/*  -  compare  function  for  sorting,  merging  - 

static  int  comp (char  **a,  char  **b) 

{ 

int  i,  k; 

if  (**a  ==  127  : :  **b  ==  127) 

return  (int)  **a  -  (int)  **b; 
for  (i  =  0;  i  <  NOFLDS;  i++)  { 

if  ( sp->s_f Id [ i ) .f_pos  ==  0) 
break; 

if  ( (k  =  strnicmp( (*a) +sp->s_fld[i) .f_pos  -  1, 
(*b) +sp->s_fld(i j . f_pos  -  1, 
sp->rc_len) )  !=  0) 

return  ( sp->s_f Id ( i ] .ad  ==  'd')?-k:k; 

) 

return  0; 


*/ 


End  Listings 
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Listing  One  ( Text  begins  on  page  135.) 


i - ) 

{  TIMED ATE  } 

{  1 

{  A  Time-and-date  stamp  object  for  Turbo  Pascal  5.5  } 
{  ) 

{  by  Jeff  Duntemann  } 

{  Last  update  12/23/89  } 

{  } 

{  NOTE:  This  unit  should  be  good  until  December  31,  } 
{  2043,  when  the  long  integer  time/date  stamp  turns  } 
{  negative.  HOWEVER,  the  Zeller's  Congruence  } 

{  algorithm  shown  here  fails  at  the  end  of  the  20th  } 

{  century.  I  should  be  able  to  figure  out  the  fix  } 

{  by  then. . .  } 

I - } 


UNIT  TimeDate; 

INTERFACE 
USES  DOS; 

TYPE 

String9  =  STRING [9]; 

String20  =  STRING [20]; 

String50  =  STRING [50]; 

When  = 

OBJECT 

WhenStamp  :  Longlnt; 

TimeString  :  String9; 

Hours, Minutes, Seconds  :  Word; 

DateString  :  String20; 

LongDateString  :  String50; 

Year, Month, Day  :  Word; 

DayOfWeek  :  Integer; 

FUNCTION  C-etTimeStamp  :  Word; 

FUNCTION  GetDateStamp  :  Word; 

PROCEDURE  PutNow; 

PROCEDURE  PutWhenStamp (NewWhen 
PROCEDURE  PutTimeStamp (NewStamp  :  Word); 

PROCEDURE  PutDateStamp (NewStamp  :  Word); 

PROCEDURE  PutNewDate (NewYear, NewMonth, NewDay  :  Word); 
PROCEDURE  PutNewTime (NewHours, NewMinutes, NewSeconds  :  Word); 
END; 


IMPLEMENTATION 

{  Keep  in  mind  that  all  this  stuff  is  PRIVATE  to  the  unit!  ) 

CONST 

MonthTags  :  ARRAY  [1..12]  of  String9  = 

('January' , 'February' , 'March' , 'April' , 'May' , 'June' , 'July' , 

'August' , 'September' , 'October' , 'November' , 'December' ) ; 

DayTags  :  ARRAY  [0..6]  OF  String9  = 

( ' Sunday' , ' Monday' , ' Tuesday' , ' Wednesday' , 

' Thursday' , ' Friday' , ' Saturday' ) ; 

TYPE 

WhenUnion  = 

RECORD 

TimePart  :  Word; 

DatePart  :  Word; 

END; 

VAR 

Tempi  :  String50; 

Dummy  :  Word; 

f  Some  utility  routines  private  to  this  unit:  ) 

FUNCTION  CalcTimeStamp (Hours, Minutes, Seconds  :  Word)  :  Word; 

BEGIN 

CalcTimeStamp  :=  (Hours  SHL  11)  OR  (Minutes  SHL  5)  OR  (Seconds  SHR  1); 
END; 


FUNCTION  CalcDateStamp (Year, Month, Day  :  Word)  :  Word; 

BEGIN 

CalcDateStamp  :=  ((Year  -  1980)  SHL  9)  OR  (Month  SHL  5)  OR  Day; 
END; 


PROCEDURE  CalcTimeString (VAR  TimeString  :  String9; 

Hours, Minutes, Seconds  :  Word); 

VAR 

Tempi, Temp2  :  String9; 

AMPM  :  Char; 

I  :  Integer; 

BEGIN 

I  :=  Hours; 

IF  Hours  =  0  THEN  I  :=  12;  {  "0"  hours  =  12am  } 

IF  Hours  >  12  THEN  I  :=  Hours  -  12; 

IF  Hours  >  11  THEN  AMPM  :=  'p'  ELSE  AMPM  :=  'a'; 

Str (I :2, Tempi) ;  Str (Minutes, Temp2) ; 

IF  Length (Temp2)  <  2  THEN  Temp2  :=  '0'  +  Temp2; 
TimeString  :=  Tempi  +  ':'  +  Temp2  +  AMPM; 

END; 


PROCEDURE  CalcDateString (VAR  DateString  :  String20; 

Year, Month, Day  :  Word); 

BEGIN 

Str (Month, DateString) ; 


Str (Day, Tempi) ; 

DateString  :=  DateString  +  '/'  +  Tempi; 

Str (Year, Tempi) ; 

DateString  :=  DateString  +  '/'  +  Copy (Tempi, 3, 2) ; 
END; 


PROCEDURE  CalcLongDateString (VAR  LongdateString  :  String50; 

Year, Month, Date, DayOfWeek  :  Word); 

VAR 

Tempi  :  String9; 

BEGIN 

LongDateString  :=  DayTags [DayOfWeek]  +  ',  '; 

Str (Date, Tempi) ; 

LongDateString  :=  LongDateString  + 

MonthTags [Month]  +  '  '  +  Tempi  +  ',  '; 

Str (Year, Tempi) ; 

LongDateString  :=  LongDateString  +  Tempi; 

END; 


( - } 

{  This  calculates  a  day  of  the  week  figure,  where  0=Sunday,  l=Monday,  ) 
{  and  so  on,  given  the  year,  month,  and  day.  The  year  may  be  passed  ) 
{  as  either  "1989"  or  "89"  but  *not*  as  1980-relative,  or  "9".  Also  ) 
(  note  that  this  particular  algorithm  turns  into  a  pumpkin  in  2000.  ) 

{  BTW,  don't  ask  me  to  explain  how  this  crazy  thing  works.  I  haven't  ( 
(  the  foggiest  notion.  If  I  ever  meet  Mr.  Zeller,  I'll  ask  him.  ) 

, - , 

FUNCTION  CalcDayOfWeek (Year, Month, Day  :  Word)  :  Integer; 

VAR 

Century, Leftovers, Holder  :  Integer; 

BEGIN 

{  First  test  for  error  conditions  on  input  values:  } 

IF  (Year  <  0)  OR 

(Month  <  1)  OR  (Month  >  12)  OR 
(Day  <  1)  OR  (Day  >  31)  THEN 

CalcDayOfWeek  :=  -1  {  Return  -1  to  indicate  an  error  } 

ELSE 

{  Do  the  Zeller's  Congruence  calculation:  } 

BEGIN 

IF  Year  <  100  THEN  Inc (Year, 1900) ; 

Dec (Month, 2) ; 

IF  (Month  <  1)  OR  (Month  >  10)  THEN 
BEGIN 

Dec (Year, 1) ; 

Inc (Month, 12) ; 

END; 

Century  :=  Year  DIV  100; 

Leftovers  :=  Year  MOD  100; 

Holder  :=  (Trunc (Int (2 . 6  *  Month  -  0.2))  +  Day  + 

Leftovers  +  (Leftovers  DIV  4)  + 

(Century  DIV  4)  -  Century  -  Century)  MOD  7; 

IF  Holder  <  0  THEN 
Inc (Holder, 7) ; 

CalcDayOfWeek  :=  Holder; 

END; 

END; 


(  Method  implementations  for  type  When:  ) 


(  There  will  be  many  times  when  an  individual  date  or  time  stamp  will  } 
(  be  much  more  useful  than  a  combined  time/date  stamp.  These  simple  } 
{  functions  return  the  appropriate  half  of  the  combined  long  integer  } 
(  time/date  stamp  without  incurring  any  calculation  overhead.  It's  } 
(  done  with  a  simple  value  typecast:  ) 


FUNCTION  When.GetTimeStamp  :  Word; 

BEGIN 

GetTimeStamp  :=  WhenUnion (WhenStamp) .TimePart ; 
END; 


FUNCTION  When. GetDateStamp  :  Word; 

BEGIN 

GetDateStamp  :=  WhenUnion (WhenStamp) .DatePart; 
END; 


(  To  fill  a  When  record  with  the  current  time  and  date  as  maintained  ) 
!  by  the  system  clock,  execute  this  method:  ) 

( - , 

PROCEDURE  When. PutNow; 

BEGIN 

{  Get  current  clock  time.  Note  that  we  ignore  hundredths  figure:  } 
GetTime (Hours, Minutes, Seconds, Dummy) ; 

{  Calculate  a  new  time  stamp  and  update  object  fields:  } 

PutTimeStamp (CalcTimeStamp (Hours, Minutes, Seconds) ) ; 

GetDate (Year, Month, Day, Dummy) ;  {  Get  current  clock  date  } 

{  Calculate  a  new  date  stamp  and  update  object  fields:  } 

PutDateStamp (CalcDateStamp (Year, Month, Day) ) ; 

END; 


( - ) 

{  This  method  allows  us  to  apply  a  whole  long  integer  time/date  stamp  ) 
{  such  as  that  returned  by  the  DOS  unit's  GetFTime  procedure  to  the  ) 


{  Combined  time/date  stamp  ) 

{  i.e.,  "12:45a"  ) 

{  Seconds  is  always  even!  ) 

{  i.e.,  "06/29/89"  I 

{  i.e.,  "Thursday,  June  29,  1989"  } 

{  0=Sunday,  l=Monday,  etc.  ) 

(  Returns  DOS- format  time  stamp  ) 

{  Returns  DOS-format  date  dtamp  } 

:  Longlnt); 
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{  When  object.  The  object  divides  the  stamp  into  time  and  date  } 
{  portions  and  recalculates  all  other  fields  in  the  object.  } 
{ - » 


PROCEDURE  When.PutWhenStamp(NewWhen  :  Longlnt) ; 

BEGIN 

WhenStamp  :=  NewWhen; 

{  We've  actually  updated  the  stamp  proper,  but  we  use  the  two  } 
{  "put"  routines  for  time  and  date  to  generate  the  individual  } 
{  field  and  string  representation  forms  of  the  time  and  date.  } 
{  I  know  that  the  "put"  routines  also  update  the  long  integer  } 
{  stamp,  but  while  unnecessary  it  does  no  harm.  } 

PutTimeStamp (WhenUnion (WhenStamp) .TimePart) ; 

PutDateStamp (WhenUnion (WhenStamp) .DatePart) ; 

END; 


, - - - 1 

{  We  can  choose  to  update  only  the  time  stamp,  and  the  object  will  } 
{  recalculate  only  its  time-related  fields.  ) 


PROCEDURE  When. PutTimeStamp (NewStamp  :  Word); 

BEGIN 

WhenUnion (WhenStamp) .TimePart  ;=  NewStamp; 

{  The  time  stamp  is  actually  a  bitfield,  and  all  this  shifting  left  ) 
(  and  right  is  just  extracting  the  individual  fields  from  the  stamp:) 
Hours  :=  NewStamp  SHR  11; 

Minutes  :=  (NewStamp  SHR  5)  AND  $003F; 

Seconds  :=  (NewStamp  SHL  1)  AND  $001F; 

{  Derive  a  string  version  of  the  time:  } 

CalcTimeString (TimeString, Hours, Minutes, Seconds) ; 

END; 


{  Or,  we  can  choose  to  update  only  the  date  stamp,  and  the  object  } 


{  will  then  recalculate  only  its  date-related  fields.  ) 

i - > 


PROCEDURE  When. PutDateStamp (NewStamp  :  Word); 

BEGIN 

WhenUnion (WhenStamp) .DatePart  :=  NewStamp; 

{  Again,  the  date  stamp  is  a  bit  field  and  we  shift  the  values  out  } 
{  of  it:  ) 

Year  :=  (NewStamp  SHR  9)  +  1980; 

Month  :=  (NewStamp  SHR  5)  AND  $OOOF; 

Day  :=  NewStamp  AND  $00 IF; 

(  Calculate  the  day  of  the  week  value  using  Zeller's  Congruence:  ) 

DayOfWeek  :=  CalcDayOfWeek (Year, Month, Day) ; 

(  Calculate  the  short  string  version  of  the  date;  as  in  "06/29/89":  ) 
CalcDateString (DateString, Year , Month, Day) ; 

f  Calculate  a  long  version,  as  in  "Thursday,  June  29,  1989":  ) 
CalcLongDateSt ring (LongdateSt ring, Year , Month, Day, DayOfWeek) ; 

END; 


PROCEDURE  When . PutNewDate (NewYear , NewMonth, NewDay  :  Word); 

BEGIN 

{  The  "boss"  field  is  the  date  stamp.  Everything  else  is  figured  } 

{  from  the  stamp,  so  first  generate  a  new  date  stamp,  and  then  } 

{  (odd  as  it  may  seem)  regenerate  everything  else,  ‘including*  ) 

{  the  Year,  Month,  and  Day  fields:  } 

PutDateStamp (CalcDateStamp (NewYear, NewMonth, NewDay) ) ; 

(  Calculate  the  short  string  version  of  the  date;  as  in  "06/29/89":  } 
CalcDateString (DateString, Year , Month, Day) ; 

{  Calculate  a  long  version,  as  in  "Thursday,  June  29,  1989":  ) 
CalcLongDateSt ring (LongdateString, Year , Month, Day, DayOfWeek) ; 

END; 


PROCEDURE  When.PutNewTime (NewHours, NewMinutes, NewSeconds  :  Word); 
BEGIN 

{  The  "boss"  field  is  the  time  stamp.  Everything  else  is  figured  ) 
{  from  the  stamp,  so  first  generate  a  new  time  stamp,  and  then  ) 

(  (odd  as  it  may  seem)  regenerate  everything  else,  ‘including*  } 

(  the  Hours,  Minutes,  and  Seconds  fields:  ) 

PutTimeStamp (CalcTimeStamp (NewHours, NewMinutes, NewSeconds) ) ; 

(  Derive  the  string  version  of  the  time:  ) 

CalcTimeString (TimeString, Hours, Minutes, Seconds) ; 

END; 


End  Listing  One 

Listing  Two 

PROGRAM  TimeTest; 

USES  Crt , TimeDate ; 

VAR 

Now  :  When; 

BEGIN 

Write ('At  the  tone,  it  will  be  exactly  '); 

Delay (1000) ; 

Now.PutNow; 

Sound(lOOO);  Delay(lOO);  NoSound; 

WITH  Now  DO  Writeln (TimeString, 'm  on  ' ,  LongDateString, ' . ' ) ; 

Rea din 
END. 


End  Listings 


Dr.  Dobb 's  Journal,  April  1990 


OF  INTEREST 


Actor  2.0,  an  object-oriented  develop¬ 
ment  environment  for  Microsoft  Win¬ 
dows  applications,  has  been  announced 
by  The  Whitewater  Group.  Version 
2.0  boasts  an  automatic  object  swap¬ 
ping  system  that  swaps  static  objects 
and  code  out  to  disk,  which  allows 
developers  to  break  the  640K  barrier 
of  MS-DOS  and  create  applications  that 
are  larger  than  1  Mbyte  in  size.  It  does 
this  by  means  of  an  LRU  (least-recently 
used)  algorithm,  which  ages  unused 
objects  and  sends  the  old  ones  out  to 
disk. 

Actor  2.0  also  has  additional  object- 
oriented  features,  new  commands,  and 
improved  support  for  C.  Whitewater 
spokesman  Zack  Urlocker  told  DDJihzt 
“programmers  wanted  increased  com¬ 
patibility  with  C  so  we’ve  added  the 
ability  to  pass  C  structures  and  com¬ 
bine  primitives  in  C  and  assembly  lan¬ 
guage.  This  means  you  can  get  directly 
into  the  low-level  structure  of  objects.” 
2.0  runs  on  any  PC  or  PS/2  (or  compa¬ 
tibles)  under  Microsoft  Windows,  and 
requires  640K  of  memory,  a  hard  disk, 
a  graphics  card  of  any  resolution,  a 
mouse,  and  Microsoft  Windows  2.x  or 
later.  The  cost  is  $695,  but  registered 
users  of  previous  versions  can  upgrade 
for  $149.  Reader  service  no.  20. 

The  Whitewater  Group 
600  Davis  St. 

Evanston,  IL  60201 
708-328-3800 

Version  2.00  of  Top  Speed  Modula-2 
has  been  announced  byJPI  This  ver¬ 
sion  works  with  the  multilanguage  de¬ 
velopment  recently  released  with 
TopSpeed  C,  which  automatically  se¬ 
lects  the  appropriate  compiler  for  the 
source  file  it  needs  to  compile,  and 
includes  nine  editing  windows,  500K 
per  file,  and  a  hypertext  help  system. 
New  compiler  options  allow  interfac¬ 
ing  of  C  libraries  and  functions  with 
Modula-2  programs,  and  vice  versa.  The 
optimizing  code  generator  is  featured 
in  the  new  family  of  TopSpeed  lan¬ 
guages  (including  a  TopSpeed  Pascal, 


which  has  also  been  announced),  com¬ 
mon  to  all  the  languages. 

TopSpeed  Modula-2,  Version  2.00, 
has  multiple  memory  model  support, 
and  new  keywords  and  syntax  exten¬ 
sions  allow  object-oriented  program¬ 
ming.  A  new  keyword  CLASS  allows  a 
RECORD-like  structure  to  include  PRO¬ 
CEDURE  declarations,  hide  data,  spec¬ 
ify  inheritance  and  VIRTUAL  proce¬ 
dures.  And  syntax  extensions  allow  the 
name  of  a  variable  of  a  CLASS  type  to 
qualify  the  name  of  a  procedure. 

Included  now  in  all  TopSpeed  com¬ 
pilers  is  the  Visual  Interactive  Debug¬ 
ger  (VID),  which  is  a  multilanguage 
source-level  debugger  that  features  on¬ 
screen  display  of  all  breakpoint  traps, 
single-step  operation,  and  full  source 
code  inspection.  TopSpeed  Modula-2 
is  available  for  DOS  ($395  for  extended 
edition)  and  OS/2  ($495  for  extended 
edition).  Reader  service  no.  33. 

Jensen  &  Partners  International 
1101  San  Antonio  Rd.,  Ste.  301 
Mountain  View,  CA  94043 
415-967-3200 

A  software  development  tool  that  gives 
the  80386  processor  the  same  level  of 
protection  available  in  protected  oper¬ 
ating  systems  has  been  announced  by 
Nu-Mega.  Bounds-Checker  automati¬ 
cally  detects  out-of-bounds  accesses  by 
an  application  program,  using  the  sym¬ 
bolic  information  created  by  the  Micro¬ 
soft  C  5.X  and  6.0  compilers  to  show 
you  the  exact  source  line  causing  the 
out-of-bounds  access.  Nu-Mega  claims 
that  Bounds-Checker  cuts  steps  in  the 
development  process  and  eliminates 
the  need  to  debug,  and  that  it  prevents 
serious  side  effects  of  subtle  overwrites 
that  may  not  be  particularly  dangerous 
until  the  program  is  in  the  field. 

The  Bounds-Checker  provides  real¬ 
time  memory  protection,  differentiates 
between  code  and  data,  protects  pro¬ 
gram  code  and  all  memory  outside  your 
program,  and  prevents  the  system  soft¬ 
ware  from  corrupting  your  program  — 
it  can  determine  if  a  TSR  or  other  pro¬ 
gram  is  trouncing  your  program.  Sells 
for  $249.  Reader  service  no.  35. 
Nu-Mega  Technologies 
P.O.  Box  7607 
Nashua,  NH  03060-7607 
603-888-2386 

Borland  International  has  announced 
Version  2.0  of  its  Turbo  Debugger, 
which  includes  a  toolkit  that  features 
the  new  Turbo  Profiler.  The  profiler 
measures  where  in  your  program  time 
is  spent,  how  many  times  a  line  is  exe¬ 
cuted,  how  many  times  a  routine  is 
called  and  by  what,  and  which  files  are 
accessed  most  often  and  for  how  long. 


It  also  tracks  the  use  of  resources  such 
as  processor  time,  disk  access,  key¬ 
board  input,  printer  output,  and  inter¬ 
rupt  activity. 

The  Turbo  Profiler  graphically  dis¬ 
plays  where  your  program  is  spending 
its  time,  telling  you  which  parts  of  the 
program  are  used  most  often  and  may 
need  optimization  or  rewriting,  and 
which  parts  are  used  so  little  that  you 
needn’t  bother  tightening  them.  An  op¬ 
timizing  compiler  generates  code  for 
the  program  you  give  it. 

Multiple  overlapping  windows,  icons, 
mouse  support,  and  context-sensitive 
on-line  help  are  included  in  the  user 
interface.  The  Profiler  works  with  Turbo 
Pascal  5.0,  Turbo  C  2.0,  and  Turbo 
Assembler  1.0,  and  any  later  versions 
of  these  compilers.  Also  supports  Code¬ 
View  and  .MAP  file  debug  formats.  For 
IBM  PCs  and  compatibles  operating 
PC-DOS  (MS-DOS)  2.0  or  later.  Requires 
384K  (256K  for  Turbo  Assembler).  The 
toolkit  retails  for  $149-95.  Reader  ser¬ 
vice  no.  34. 

Borland  International 
1800  Green  Hills  Rd. 

Scotts  Valley,  CA  95066-0001 
408-438-8400 

Version  4.0  of  the  LALR  compiler  con¬ 
struction  toolkit  can  now  be  purchased 
from  IALR  Research.  The  toolkit  in¬ 
cludes  the  parser  generator,  LALR,  and 
a  scanner  generator,  DFA,  as  well  as 
various  source  code  modules,  such  as 
a  main  program,  a  screener,  parser  skele¬ 
ton,  and  scanner  skeleton.  DDJ  spoke 
with  the  developer,  Paul  Mann,  who 
said  that  the  LALR  compiler  is  “an  ad¬ 
vanced  compiler  construction  tool  that 
goes  beyond  YACC.  It  features  extended 
BNF  notation,  automatic  creation  of  ab¬ 
stract  syntax  trees,  and  a  high-speed 
scanner  generator.  It’s  well  suited  for 
developing  compilers,  translators,  and 
interpreters  for  computer  languages.” 

A  BNF  grammar  describes  the  state¬ 
ments  of  the  language  as  input  to  the 
LALR,  and  describes  the  symbols  as 
input  to  the  DFA.  The  LALR  parser  gen¬ 
erator  provides  automatic  error  recov¬ 
ery,  and  handles  large  grammars  such 
as  Fortran  and  Cobol.  The  company 
claims  that  the  DFA  scanner  generator 
produces  high-speed  deterministic  fi¬ 
nite  automatons  that  run  about  four 
times  faster  than  LEX  scanners.  The 
source  code  output  is  compatible  with 
Turbo  C,  Microsoft  C,  Watcom  C,  among 
others.  The  price  is  $495.  Reader  ser¬ 
vice  no.  26. 

LALR  Research 
1892  Burnt  Mill  Rd. 

Tustin,  CA  92680 
714-832-2274 

(continued  on  page  157) 
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(continued  from  page  152) 

BrainMaker  v2.0,  a  system  for  design¬ 
ing,  building,  training,  testing,  and  run¬ 
ning  neural  networks,  is  now  available 
from  California  Scientific  Software. 
The  company  claims  that  version  2.0 
is  a  major  enhancement,  and  has  such 
features  as  the  NetMaker,  which  is  a 
network  generation  and  data  manipu¬ 
lation  program  with  spread-sheet  style 
data  display  and  the  ability  to  perform 
arithmetic  operations  on  data.  In  addi¬ 
tion,  BrainMaker  now  reads  data  from 
Lotus,  dBase,  Quattro,  and  Excel  files; 
automatic  numeric  translation  allows 
the  display  of  large  numbers;  graphics 
post-processing  of  network  results  is 
supported;  and  it  includes  training  and 
running  algorithms  that  are  as  fast  as 
500,000  neural  connections  per  sec¬ 
ond.  Mark  Lawrence,  CSS  president, 
told  DDJ  that  “with  Release  1,  we  knew 
we  had  a  neat  technology,  and  that  our 
users  would  have  to  tell  us  what  it  was 
for.  They  told  us  it  was  mostly  for  fi¬ 
nancial  forecasting,  so  now  we’ve  gone 
back  and  written  it  like  it  should  have 
been.” 

This  upgrade  includes  the  Introduc¬ 
tion  to  Neural  Networks ,  an  overview 
of  the  history  and  research  of  neural 
networks,  and  a  user’s  guide  and  refer¬ 
ence  manual.  The  cost  is  $195,  $95  for 
registered  users.  Requires  a  PC,  PS/2, 
or  compatible.  Reader  service  no.  21. 
California  Scientific  Software 
160  E.  Montecito  Ave.,  #E 
Sierra  Madre,  CA  91024 
818-355-1094 

Macintosh  Allegro  Common  Lisp  (CL), 
v.  1.3,  an  extended  implementation  of 
Common  Lisp,  is  being  shipped  by  Ap¬ 
ple  Computer.  It  supports  all  the  fea¬ 
tures  described  in  the  Guy  Steele  text 
Common  Lisp:  The  Language.  The  Macin¬ 
tosh  Allegro  CL  can  be  used  to  develop 
stand-alone  Macintosh  applications  and 
to  port  applications  developed  on  other 
machines. 

User  interface  components  can  be 
modified  both  interactively  and  under 
program  control.  Events  are  caught  and 
dispatched  by  the  Lisp  run-time  kernel. 
Windows  are  accessible  as  high-level 
objects,  and  can  be  created  and  closed 
with  simple  Lisp  functions.  Menus  and 
dialog  boxes  are  implemented  as  ob¬ 
jects,  as  well.  Fred,  an  integrated  pro¬ 
grammable  editor,  combines  the  capa¬ 
bilities  of  Emacs  with  the  multiple- 
window,  mouse-based  editing  style  of 
the  Mac.  The  Stand-Alone  Application 
Generator  produces  ready-to-use  Mac 
applications,  which  require  a  “nominal 
fee”  license  to  distribute.  System  re¬ 
quirements  include  any  Mac  except  the 
51 2K,  a  second  800K  disk  drive,  and 
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Mac  System  Software,  Version  6.0.  It 
sells  for  $495.  Reader  service  no.  28. 
Apple  Computer,  Inc. 

20525  Mariani  Ave. 

Cupertino,  CA  95014 
408-996-1010 

MS-DOS  Kermit,  Version  3.0,  is  now 
available  from  the  Columbia  Univer¬ 
sity  Center  for  Computing  Activi¬ 
ties.  The  new  features  include  transfer 
of  text  files  in  international  character 
sets  via  a  new  Kermit  protocol  exten¬ 
sion;  emulation  of  the  DEC  VT320  ter¬ 
minal,  including  soft  function  keys  and 
support  for  a  wide  variety  of  interna¬ 
tional  character  sets  in  any  of  the  five 
standard  PC  code  pages;  and  sliding 
window  packet  protocols  for  improved 
file  transfer  performance  over  public 
data  networks  and  long  distance  satel¬ 
lite  connections. 

Version  3-0  also  has  expanded  sup¬ 
port  for  local  area  networks,  and  en¬ 
hanced  Tektronix  graphics  terminal  emu¬ 
lation  with  VT340  extensions.  Graph¬ 
ics  screens  may  be  saved  in  TIFF  5.0 
for  importation  into  such  applications 
as  WordPerfect,  Pagemaker,  and  Ven¬ 
tura  Publisher.  This  version  was  pre¬ 
pared  by  Joe  R.  Doupnik  of  Utah  State 
University  in  cooperation  with  Colum¬ 
bia  University.  Reader  service  no.  29. 
Kermit  Distribution,  Columbia  Univ. 
Center  for  Computing  Activities 
612  W.  115th  St. 

New  York,  NY  10025 
212-854-3703 

Stony  Brook  Professional  Modula-2,  Ver¬ 
sion  2.0,  is  now  available  from  Stony 
Brook  Software.  This  compiler  pack¬ 
age  includes  the  QuickMod  compiler 
and  an  optimizing  compiler;  develop¬ 
ment  support  for  DOS,  OS/2,  and  Mi¬ 
crosoft  Windows;  the  ability  to  inter¬ 
face  with  libraries  written  in  C  or  other 
languages;  the  Ml6  debugger;  an  ex¬ 
tensive  run-time  library;  built-in  multi¬ 
tasking;  and  the  Stony  Brook  linker. 

The  Stony  Brook  environment  gives 
you  control  over  source  file  placement, 
keystroke  macros,  the  ability  to  per¬ 
form  DOS  commands,  a  cross-refer¬ 
ence  of  module  dependencies,  inter¬ 
face  to  the  symbolic  debugger,  and  the 
ability  to  assemble  foreign  language 
modules.  QuickMod  complies  with 
Wirth’s  definition  of  Modula-2,  and  sup¬ 
ports  symbol  scoping  and  forward  ref¬ 
erence  capabilities  in  one  pass.  Added 
are  structured  constants,  array  sub¬ 
strings,  conditional  compilation,  type 
coercions,  and  set  types  containing  up 
to  65,536  bits.  The  whole  package  re¬ 
tails  for  $295;  the  source  code  for  the 
run-time  library  costs  $150.  Reader  ser¬ 
vice  no.  24. 
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Stony  Brook  Software 
187  E.  Wilbur  R.,  Ste.  9 
Thousand  Oaks,  CA  91360 
800-624-7487  (US) 

805-496-5837  (Calif,  and  International) 


Books  of  Interest 

NeuralSource,  The  Bibliographic  Guide 
to  Artificial  Neural  Networks,  by  Phillip 
Wasserman  and  Roberta  Oetzel,  is  avail¬ 
able  from  Van  Nostrand  Reinhold. 
This  bibliography  purports  to  be  the 
most  extensive  collection  of  research 
information  on  neural  nets.  Periodi¬ 
cals,  private  reports,  and  books  are  in¬ 
cluded.  Sells  for  $64.95.  ISBN  0-442- 
23776-6. 

Also  by  Wasserman  is  Neural  Com¬ 
puting,  Theory  and  Practice.  This  is 
an  introduction  to  artificial  neural  net¬ 
works  for  the  nonspecialist.  Assumes 
no  math  background  beyond  an  un¬ 
dergraduate  scientific  education.  Uses 
a  step-by-step  algorithmic  approach  to 
present  commonly  used  network  para¬ 
digms.  $36.95,  ISBN  0-442-20743-3. 
Reader  service  no.  30. 

Van  Nostrand  Reinhold 
P.O.  Box  668 
Florence,  KY  41022-0668 
606-525-6600 

Elements  of  Functional  Programming 
by  Chris  Reade  has  been  published  by 
Addison- Wesley.  Covers  the  concepts 
and  techniques  used  in  modern  func¬ 
tional  programming  languages,  as  well 
as  support  for  abstraction,  program¬ 
ming  with  lists,  new  types,  abstract  data 
types  and  modules,  lazy  and  eager  evalu¬ 
ation,  and  implementation  techniques. 
Hardback  edition  costs  $37.75,  ISBN 
0-201-12915-9-  Reader  service  no.  31. 
Addison- Wesley 
Reading,  MA  01867 
617-944-3700 

The  COSMIC  Software  Catalog  1990 
Edition  is  available  from  the  Univer¬ 
sity  of  Georgia.  It  is  a  comprehensive 
listing  of  program  abstracts  describing 
all  available  NASA  computer  programs. 
You  can  purchase  it  in  book  form  ($25), 
on  microcomputer  diskette  ($30),  on 
magnetic  tape  ($50),  or  on  microfiche 
($10).  The  catalog  cross-indexes  over 
1200  computer  programs,  in  areas  such 
as  aerodynamics,  reliability,  compos¬ 
ites,  heat  transfer,  artificial  intelligence, 
and  structural  analysis.  Reader  service, 
no.  32. 

COSMIC 

University  of  Georgia 
382  E.  Broad  St. 

Athens,  GA  30602 
404-542-4807 
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Junk  Customers 


S  W  A  I  N  E'  S  FLAMES 


2/11/90:  Investment  banking  firm  Drexel  Burnham  Lambert,  home  of  the  junk  bond 
phenomenon,  informs  its  employees  that  it  is  filing  for  bankruptcy. 

2/12/90:  My  cousin  Corbett  launches  his  program  for  software  developers  who  can’t 
afford  the  skyrocketing  costs  of  software  marketing:  Junk  Customers. 

Corbett  was  concerned  about  the  software  developer  who  can’t  afford  to  run  large  ads 
in  the  major  computer  magazines  and  can’t  afford  to  rent  lists  of  prospects.  Some 
magazines  and  some  lists  will  result  in  more  responses  and  purchases  than  others,  of 
course,  and  it  was  while  trying  to  come  up  with  a  new  measure  of  the  value  of  these 
sources  that  Corbett  hit  on  the  secret,  which  he  calls  “Junk  Customers.” 

He  took  his  inspiration  from  Mike  Milken,  the  Drexel  Burnham  Lambert  employee  who 
made  such  a  splash  with  junk  bonds.  Milken  noticed  that  there  were  a  lot  of  companies 
that  had  to  go  to  the  bank  when  they  wanted  money.  This  was  bad,  he  realized.  The 
companies  tried  issuing  bonds  to  get  investors  to  put  up  money,  but  investment  firms 
such  as  Drexel  et  al.  steered  investors  away  from  these  bonds,  labeling  them  “low  value.” 
This  meant  that  there  was  a  higher  probability  that  the  companies  would  fail  to  pay 
up  —  go  out  of  business  or  whatever  —  than  was  the  case  with  so-called  high-quality 
bonds.  The  companies  tried  to  make  their  bonds  appealing  by  increasing  the  yield  — what 
you  get  back  for  your  investment  —  and  Mike  Milken  saw  this  as  a  good  deal.  He  began 
helping  his  clients  to  buy  a  broad  selection  of  these  high-yield,  low-value  bonds,  starting 
what  became,  at  its  peak,  a  $200  billion  market. 

Corbett  has  come  up  with  a  similar  plan  for  software  marketing.  (The  plan  is  completely 
general,  but  his  loyalty  is  to  the  software  development  community.  He  wants  you  to  have 
it.)  He  defines  the  yield  of  a  source  of  prospects  —  a  list  of  names  or  a  page  of 
advertising  —  as  the  inverse  of  the  CPM  (ad  sales  jargon  for  “cost  per  thousand”).  Yield 
is  how  many  names  you  get  for  a  buck.  He  defines  the  value  of  a  source  as  how  well  the 
source  will  pull  —  how  likely  each  name  is  to  result  in  a  sale.  The  trick,  as  with  junk 
bonds,  is  to  develop  a  varied  portfolio  of  high-yield,  low-value  sources. 

Identifying  a  truly  low-value  source  is  tricky.  It  can’t  just  be  a  source  that  is  ill-suited  to 
your  needs;  such  a  source  might  be  able  to  get  a  lot  of  money  from  someone  else.  To 
ensure  that  the  yield  can  be  made  high  enough,  this  must  be  a  source  ill-suited  to  anyone’s 
needs,  a  publication  or  list  poorly  suited  to  any  commercial  advertising  or  name  rental 
purpose.  Then  there  is  another  problem  in  dealing  with  low-quality  sources:  You’ll  need 
a  lot  of  them.  The  low  quality  translates  into  few  responses  from  any  one  source,  and  the 
overhead  of  dealing  with  hundreds  of  such  companies  can  easily  eat  up  any  gains. 

Corbett  thinks  he  has  found  the  single  correct  answer  to  the  Junk  Customers  challenge, 
and  is  generously  allowing  me  to  pass  it  on  to  you:  Church  newsletters.  Every  community 
has  a  church,  every  church  has  a  newsletter,  and  every  church  belongs  to  some  large 
national  or  international  organization  capable  of  serving  as  a  central  clearing  house  for 
ad  sales  or  list  rental.  The  nonprofit  status  of  churches  and  their  general,  noncommercial 
slant  makes  a  church  newsletter  an  exceptionally  low-value  source,  Corbett  maintains. 

He  sees  an  intriguing  wrinkle  to  the  idea  of  church  newsletter  subscribers  as  prospects 
for  software  sales.  Current  wisdom  says  that  you  should  look  for  software  prospects 
among  owners  of  computers.  The  church  newsletter  subscribers  will  include  many  who 
do  not  own  a  computer,  apparently  nonprospects  almost  by  definition.  But  any  good 
marketer  knows  to  mistrust  such  self-fulfilling  predictions,  and  to  ask  the  positive  ques¬ 
tion,  why  would  this  person  want  my  product?  In  this  case,  the  answer  is  surprisingly 
obvious.  The  industry  has  been  doing  it  backwards! 

Consider:  It  is  much  easier  to  ease  a  potential  customer  into  a  new  product  category 
with  a  small  purchase  than  with  a  large  one.  One  of  the  reasons  many  people  cite  for  not 
buying  a  PC  is  that  they  don’t  know  how  to  justify  spending  over  a  thousand  dollars.  So 
they  buy  a  Nintendo  instead.  These  people  could  be  buying  your  CAD  package. 

Consider:  Anyone  who  has  ever  thought  about  buying  a  PC  has  heard  the  advice, 
“Decide  what  software  you  want  to  run,  and  then  buy  the  PC  that  runs  that  software.” 
You’ve  probably  given  that  advice,  but  did  you  listen  to  what  you  were  really  saying? 

Consider  this  pitch:  For  less  than  the  cost  of  a  Nintendo,  you  can  own  the  most  powerful 
CAD  package  in  the  known  universe.  Now  you,  too,  can  design  microprocessor  circuits, 
draft  plans  for  a  new  house  on  the  coast,  develop  a  new  art  form,  make  your  own  clothes. 
Required  Silicon  Graphics  IRIS  workstation  must  be  purchased  separately. 

Remember,  you  read  it  here  first. 


Michael  Sw'aine 
editor-at-large 
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GENERATION  SCAVENGING  16 

by  Frank  Jackson 

The  generation  scavenging  algorithm  is  an  efficient,  portable  garbage  collector  that  does 
not  require  special  hardware  support. 

DYNAMIC  LINK  LIBRARIES  FOR  DOS  30 

by  Gaty  Syck 

DLLs  provide  an  easy  way  to  run  large  programs  in  small  memory  spaces  and  Gary  shows 
how  you  can  add  DLL  facilities  to  DOS  programs. 

GETTING  A  HANDLE  ON  VIRTUAL  MEMORY  40 

by  Walter  Bright 

"Handle  pointers”  let  you  extend  available  memory  space  by  dynamically  allocating  data. 

Walter  discusses  handles  and  how  you  can  take  advantage  of  them. 

OBJECT  SWAPPING  48 

by  Jan  Bottorff  and  Jim  Bolland 

For  object-oriented  environments,  "object-swapping”  picks  up  where  virtual  memory 
systems  leave  off. 

A  MEMORY  CONTROLLER  58 

by  Robert  A.  Moeser 

Rob  presents  a  set  of  memory  management  routines  that  can  be  used  as  extensions  to  your 
library’s  malloc  and  free  routines. 

DEMYSTIFYING  16-BIT  VGA  70 

by  Michael  Abrash 

Michael  clears  up  misconceptions  about  16-bit  VGA  and  explains  why  programmers  need 
not  treat  8-  and  16-bit  VGAs  differently. 

EXAMINING  ROOM _ 

MULTIPROCESSING  WITH  SMALLTALK/V  82 

by  Kenneth  E.  Ayers 

Find  out  what’s  in  store  for  Ken  as  he  adds  multiprocessing  capabilities  to  Smalltalk/V,  using 
the  CX  Multiprocessing  Kit  to  build  a  simulated  supermarket. 

ENCAPSULATING  C++  BOOKS  1 50 

by  Andrew  Scbulman 

Books  on  C++  are  cropping  up  all  over  the  place  and  Andrew  has  read  a  lot  of  them.  Here 
are  a  few  of  his  favorites. 

PROGRAMMER'S  WORKBENCH _ 

ACCESSING  HARDWARE  FROM  80386  PROTECTED  MODE:  PART  I 

by  Stephen  Fried 

Stephen  kicks  off  a  two-part  discussion  of  the  80386  by  examining  topics  such  as  tiling,  the 
huge  model,  and  the  use  of  FAR  pointers  to  address  up  to  64  terabytes  of  memory. 
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PROGRAMMING  PARADIGMS 

by  Michael  Swaine 

Michael  copes  with  the  chaos  of  complex  systems. 

C  PROGRAMMING 

by  Al  Stevens 

While  many  programmers  are  wondering  about  moving  from  C  to  C++,  Al  takes  the  curious 
step  of  moving  from  C++  to  C. 

|  STRUCTURED  PROGRAMMING  141 

by  Jeff  Duntemann 

Jeff  poses  some  sharp  questions  about  cutting  edges,  explores  object  hierarchies,  and 
examines  the  Object  Professional  Library  from  Turbo  Power  Software. 


DEPARTMENTS _ 

EDITORIAL  6 

by  Jonathan  Erickson 

LETTERS  8 

by  you 

SWAINE’S  FLAMES . 160 

by  Michael  Swaine 

PROGRAMMER'S 
SERVICES _ 

ADVERTISER  INDEX . 152 

where  to  go  for  more  information 
on  products 

OF  INTEREST . 153 

compiled  by  Janna  Custer 

PROGRAMMER’S 
MARKETPLACE  154 


|  classified  ads 


NEXT  ISSUE _ 

Hot-links  can  make  for  sizzling  software, 
and  in  June  we’ll  be  tackling  hands-on 
hypertext  problems,  including  the  tools  for 
building  your  own  hypertext  help  system. 
We  ll  also  continue  our  examination  of  C++ 
and  go  deeper  into  the  80386’s  protected 
mode. 
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E  D  ITORIAL 


A  Little  Help 
From  Our 
Friends 


Depending  on  where  you  live,  you’ve  probably:  a.)  just  finished  shoveling  snow  for  the  last 
time  this  winter,  or  b.)  mowed  your  lawn  for  the  first  time  this  summer.  (Or  maybe,  c.)  you 
live  in  a  maintenance-free  condo  in  Florida  and  don’t  have  to  worry  about  shovels  or  lawn 
mowers.)  In  any  case,  January  1991  is  likely  the  farthest  thing  from  your  mind.  For  us,  magazine 
seasons  being  what  they  are,  1991  is  peeking  over  the  masthead  and  we  want  your  help  in  zeroing 
in  on  our  1991  Editorial  Calendar.  What  we’re  looking  for  is  a  list  of  general  topics  you’d  like 
covered  in  next  year’s  DDJ. 

We’re  trying  to  make  it  easy  on  you.  If  you’ll  turn  to  page  16  (home  of  Frank  Jackson’s  article 
“Generation  Scavenging”),  you’ll  find  a  tear-out  card  with  a  list  of  possible  topics.  We’d  like  you 
to  check-off  or  rank  in  order  of  preference  (1  being  most  preferred)  those  topics  of  greatest  interest. 
If  the  topic  you’re  particularly  interested  in  isn’t  on  the  list,  use  the  available  space  for  write-in 
candidates.  And,  as  a  matter  of  curiosity  (and  because  we  had  room  on  the  card),  tell  us  which 
article  DDJ  published  over  the  past  few  months  you  liked  the  best. 

Be  sure  to  include  your  name,  address,  and  phone  number,  tear  out  the  card,  and  drop  it  in  the 
mail.  It’s  already  addressed  and  stamped. 

We’re  also  trying  to  make  it  worth  your  while.  To  provide  some  incentive  for  your  mailing 
in  the  card,  we’ll  have  a  random  drawing  around  the  end  of  June.  If  your  card  is  drawn,  you’ll  get 
your  choice  of  whatever  developer’s  tools  are  available  on  the  following  list.  The  first  person 
selected  gets  to  pick  from  the  list,  then  the  second  person,  and  so  on,  right  on  down  the  roster. 
The  companies  listed  below  have  generously  donated  their  software  to  help  us  out,  and  by  the 
time  the  drawing  actually  takes  place  there  may  very  well  be  more  tools  available. 


Actor  2.0 —  Whitewater  Group 

Bounds-Checker —  Nu-Mega  Technologies 

dbVista  for  DOS —  Raima  Corp. 

DDJ  Bound  Volume  Set —  M&T  Books 

QRAM  and  MANIFEST —  Quarterdeck 
Office  Systems 

Formation  —  Aspen  Scientific 
Greenleaf  ComLib —  Greenleaf  Inc. 
HCR/C++ —  HCR  Corp. 

Instant-C —  Rational  Systems  Inc. 
Microsoft  C —  Microsoft  Corp. 

Microsoft  Basic —  Microsoft  Corp. 


PCX  Toolkit —  Genus  Microprogramming 

Smalltalk.  V/Mac — Digitalk  Inc. 

Smalltalk  V/286 — Digitalk  Inc. 

Stony  Brook  Modula-2 —  Stony  Brook  Software 

Think  C  4.0 —  Symantec  Corp. 

Think  Pascal  3-0 —  Symantec  Corp. 

TopSpeed  C  or  Modula-2 — Jensen  & 

Partners  Inti. 

Turbo  C —  Borland  Inti. 

TurboPower  Library—  TurboPower 
Watcom  C  or  Fortran  —  Watcom  Corp. 

Zortech  C++  —  Zortech  Corp. 


After  the  drawing,  we’ll  publish  a  complete  list  of  all  winners  and  the  software  you  selected.  You’re 
responsible  for  any  taxes  or  duties.  You  don’t  have  to  purchase  any  product  to  enter  the  drawing, 
nor  do  you  have  to  be  a  DDJ  subscriber.  You  do  have  to  fill  out  the  card,  however.  (M&T  Publishing 
and  Computer  Metrics  employees  aren’t  eligible.)  We’ll  also  publish  next  year’s  Editorial  Calendar 
and  give  you  plenty  of  time  to  start  thinking  about  and  writing  articles. 

I’m  happy  to  have  the  opportunity  to  share  these  tools  with  you  and  am  grateful  to  the  vendors 
who  helped  out.  More  than  that,  however,  I’m  looking  forward  to  seeing  what  topics  are  important 
to  you. 

Yes,  we’re  still  horsing  around . . .  It’s  now  official.  We  made  Dr.  Dobbs,  the  quarter  horse  I 
wrote  about  here  last  month,  our  honorary  mascot  after  he  won  his  first  race.  (Note  that  he’s  no 
longer  classified  as  a  “nag.”)  Earlier  this  racing  season,  the  good  Doctor  had  three  photo  finishes, 
all  ending  on  the  short  side  of  the  wire.  Last  Saturday’s  race,  however,  shaped  up  as  yet  another 
photo  finish,  but  this  time  with  Dr.  Dobbs  out  in  front  by  a  nose.  The  crowd,  if  not  the  DDJ  staff, 
went  wild. 


Jonathan  Erickson 
editor-in-chief 
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C++  and  the  386 

Dear  DDJ, 

As  one  of  what  I  would  imagine  is  a 
very  small  number  of  Intek  C++  users, 
I  read  with  interest  the  exchange  be¬ 
tween  Mac  Cutchins  of  Intek  and  A1 
Stevens  in  your  March  1990  “Letters” 
section.  When  I  first  received  the  Intek 
package  I  had  many  of  the  same  prob¬ 
lems  that  A1  did,  including  a  not  so 
amusing  little  bug  that  resulted  in  the 
compiler  only  working  every  second 
time.  Several  of  their  header  files  would 
not  compile  due  to  typos  and  bugs  of 
one  sort  or  another.  Intek  technical 
support  was  always  polite  but  rarely 
helpful  and  I  sometimes  got  the  im¬ 
pression  that  I  was  the  only  user  they 
had  actually  suckered  into  buying  the 
product.  To  be  fair  they  did  supply  an 
upgrade  when  I  complained  that  the 
old  version  of  the  PharLap  binder  they 
had  used  prevented  its  working  cor¬ 
rectly  with  the  VCPI  standard  and  hence 
precluded  the  use  of  QEMM  and 
DesqView.  I  was  also  notified  (by  tele¬ 
phone  no  less)  of  their  upgrade  to  2.0 
and  it  was  reasonably  priced  and  deliv¬ 
ered  promptly. 

I  was  eventually  able  to  contrive  the 
necessary  patches,  batch  files,  and  bug 
fixes  so  that  it  would  reliably  compile 
things  from  my  Brief  editor  and  I  could 
pretend  I  was  working  with  a  real  devel¬ 
opment  tool.  Still  one  might  ask  why 
bother  with  it  when  there  are  other 
alternatives. 

First  and  foremost  because  Intek  C++ 
is  the  only  product  which  will  support 
the  Meta  Ware  HiC  or  Watcom  compil¬ 
ers,  thus  it  is  the  only  way  to  produce 
code  for  386  protected  mode  programs 
running  under  DOS  extenders.  Also, 
as  Mac  Cutchins  points  out,  Intek’s  use 
of  386  protected  mode  means  you  are 
not  concerned  with  running  out  of  mem¬ 
ory  when  compiling  large  source  mod¬ 
ules.  The  large  and  numerous  header 
files  that  C++  encourages  can  quickly 
exhaust  the  memory  of  real  mode  com- 
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pilers  such  as  Zortech.  Many  of  my 
large  library  modules  would  have  to 
be  split  up  and  might  still  give  prob¬ 
lems  compiling  under  Zortech.  Finally 
and  unexpectedly,  the  translator  itself 
is  quite  robust  once  it  is  running.  It 
correctly  compiled  code  segments 
where  Zortech  1.2  version  gave  spuri¬ 
ous  errors.  The  2.0  version  of  Zortech 
seemed  more  robust  in  my  limited  test¬ 
ing  of  it,  but  could  not  compile  many 
of  my  files  due  to  the  memory  limita¬ 
tion  problem. 

I  am  the  only  one  in  our  shop  using 
C++  at  the  moment,  but  that  will  change 
in  the  near  future  and  I  dread  having 
to  invest  in  more  copies  of  the  Intek 
product.  With  each  new  issue  of  DDJ  I 
carefully  scan  all  the  adds  and  announce¬ 
ments  for  a  Turbo  C++  386  or  some¬ 
thing  similar.  The  OS/2  version  of 
Zortech  is  tempting,  but  I  need  to  use 
too  many  PharLap  programs  to  make 
that  feasible  just  yet.  When  all  is  said 
and  done  Intek  has  the  singular  advan¬ 
tage  of  being  the  only  product  available 
under  DOS  for  creating  really  large  C++ 
applications.  If  something  else  is  avail¬ 
able  I  would  love  to  know  about  it. 

Craig  Morris 

Calgary,  Alberta,  Canada 

DDJ  responds:  Thanks  for  your  insights, 
Craig.  Just  within  the  last  few  days, 
DDJ  contributing  editor  Andrew 
Schulman  started  an  in-depth  look  of 
C++  implementations  for  the 386,  begin¬ 
ning  with  Intek  C++  and  MicroWay’s 
NDP  C++.  We’re  looking  forward  to 
sharing  his  findings  sometime  in  the 
near  future. 

Trick  Trade-offs 

Dear  DDJ, 

This  message  is  in  regards  to  Tim  Pater¬ 
son’s  article  “Assembly  Language  Tricks 
of  the  Trade”  in  the  March  1990  DDJ. 

I’ve  always  enjoyed  reading  articles 
about  the  tricks  and  magic  that  other 
programmers  use.  If  we  assume  some 
things,  though,  we  can  do  your  Binary- 
To- ASCII  Conversion  one  better. 

If  we  assume  that  the  Cariy  and  Aux¬ 
iliary  Carry  are  clear,  then  a  binary  value 
in  the  range  00-0F  in  AL  can  be  con¬ 
verted  to  ASCII  by: 

daa  ;  00-09,  10-15 

add  A10F0H  ;  F0-F9  NC,  00-05  CY 
adc  al,040h  ;  30-39,  41-46  (’0’-’9\ 

’A’-’F’) 

Since  we  usually  want  to  convert  a 
BYTE  to  two  ASCII  characters,  this  is 
usually  preceded  by  masking  and/or 
shifting  some  other  value.  These  op¬ 
erations  will  clear  the  Carry  and  Auxil¬ 
iary  Carry,  so  everything’s  OK. 


Yet  another  trick:  You  mention  us¬ 
ing  the  AAM  and  AAD  instructions  for 
Binary/Decimal  Conversion.  There  is 
an  undocumented  “extension”  to  these 
instructions,  which  is  often  useful.  The 
opcodes  for  AAD  and  AAM  are: 

AAD  =  D5  0A 

AAM  =  D4  0A 

If  the  OAs  look  a  little  suspicious,  it’s 
because  they  are  the  divisors  used  in 
the  conversion.  The  instruction  se¬ 
quence  D4  10  is  equivalent  to  separat¬ 
ing  the  byte  in  AL  into  its  upper/lower 
nibbles  and  placing  the  upper  nibble 
into  the  lower  nibble  of  AH,  leaving 
just  the  lower  nibble  in  AL.  This  also 
happens  to  clear  the  Carry  and  Auxil¬ 
iary  Carry  flags.  Sooooo  . .  .  used  in  con¬ 
junction  with  the  Binary-to-ASCII  Con¬ 
version  code  above  will  result  in  an 
extremely  compact,  baitally  fast  Byte-to- 
Two-ASCII-Digits  Conversion.  Neat,  eh? 

Keith  Moore 

Fort  Worth,  Texas 

Tim  responds:  I  am  aware  of  the  tricks 
Keith  mentions.  However,  both  rely  on 
undocumented  features  of  the  8086 
family,  which  is  a  very  dangerous  prac¬ 
tice. 

The  only  instructions  which  are  docu¬ 
mented  to  affect  the  Auxiliary  Carry 
(AC)  flag  in  a  specific  way  are  arith¬ 
metic  instructions  (not  including  shifts). 
Masking  and  shifting  instructions  are 
documented  as  leaving  the  AC flag  un¬ 
defined.  Thus  it  is  very  unlikely  that  the 
state  of  the  AC  flag  will  be  known  when 
Keith ’s  instruction  is  executed,  and  the 
method  could  easily  fail. 

Testing  with  a  debugger  may  leave 
the  impression  that  masking,  for  exam¬ 
ple,  leaves  the  AC  flag  clear.  However, 
did  you  check  this  on  an  8088,  8086, 
286,  or  386?  What  about  the  33-MHz 
386,  which  uses  a  different  mask  set 
than  the  slower  versions?  Are  you  sure 
the  386SX,  486,  and  586  (which  no 
one  has  seen  yet)  all  work  that  way? 

The  same  thing  can  be  said  for  using 
variants  of  the  AAM  and  AAD  instruc¬ 
tions  to  multiply  or  divide  by  some¬ 
thing  other  than  ten.  Eleven  years  ago 
I  discovered  that  the  8086  used  the 
second  byte  of  those  instructions  as  an 
immediate  value.  But  does  a  486?  If  it 
does,  then  the  486 has  a  bug  — -  it  should 
perform  an  invalid  opcode  trap  if  the 
second  byte  is  not  OAH.  Or  else  Intel 
needs  to  document  that  it  works. 

There  are  too  many  different  proces¬ 
sors  in  the  family —  and  too  many  dif¬ 
ferent  manufacturers  —  to  consider  us¬ 
ing  undocumented  features.  Let’s  all 
play  by  the  rules. 

(continued  on  page  12) 
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But  Basic  Already  Does  That .  .  . 

Dear  DDJ, 

No  one  is  a  bigger  fan  of  Jeff  Dun- 
temann  than  I,  but  he  completely  missed 
the  boat  in  his  Modula-2  discussion 
{DDJ,  February  1990).  As  Jeff  went  over 
the  list  of  omissions  in  both  Pascal  and 
Modula-2, 1  kept  saying  to  myself,  “But 
QuickBASIC  already  does  that.’’  In  my 
opinion,  Microsoft  QuickBASIC  over¬ 
comes  all  of  the  shortcomings  of  both 
Pascal  and  Modula-2,  with  a  language 
that  is  both  fully  structured  and  incred¬ 
ibly  easy  to  use. 

For  example,  Jeff  laments  Pascal’s 
inability  to  view  a .  list  of  procedures, 
and  praises  that  feature  in  Modula-2. 
But  QuickBASIC  has  had  a  “View  Subs” 
menu  for  years.  He  then  compares  Pas¬ 
cal's  ability  to  use  a  varying  number 
and  type  of  parameters  for  built-in  state¬ 
ments,  as  opposed  to  Modula  with  its 
separate  WriteString,  Readlnt ,  and  so 
forth.  Again,  QuickBASIC  (and  even 
interpreted  BASIC!)  has  always  had  that 
capability.  Worse  still,  procedures  in 
either  language  cannot  accept  a  truly 
“open  ended”  array.  And  again,  Quick¬ 
BASIC  lets  you  pass  any  array  —  with 
any  number  of  dimensions  and  any 
range  of  upper  and  lower  bounds  — 
to  any  subroutine.  How  else  could  one 
write  a  usable  sort  routine?! 

I  won’t  belabor  the  remaining  list  of 
advantages  that  QuickBASIC  has  over 
the  “Wirth”  languages.  No,  I  won’t  dwell 
on  QuickBASIC’s  many  data  types,  auto¬ 
matic  support  for  a  coprocessor,  TRUE 
dynamic  strings,  world-coordinate  graph¬ 
ics,  or  its  ability  to  manage  an  entire 
project  without  requiring  all  of  the  files 
to  be  in  the  same  directory.  (Yeah, 
that’s  a  good  one  —  multiple  copies 
of  your  debugged  subroutines  scattered 
all  over  a  disk.)  And  I  won’t  even  bela¬ 
bor  QuickBASIC’s  outstanding  support 
for  fully  interrupt-drive  communications. 
Where  Jeff  is  bragging  about  a  100-line 
Comm  program  he  wrote  in  an  hour 
using  Modula-2,  I  maintain  the  same 
could  be  done  in,  say,  20  lines  in  ten 
minutes  using  QuickBASIC. 

Indeed,  if  any  language  is  the  right¬ 
ful  successor  to  “king”  Turbo  Pascal, 
surely  it  is  QuickBASIC. 

Ethan  Winer 

Stamford,  Connecticut 

Editor’s  note:  Ethan  is  president  of  Cres¬ 
cent  Software,  developers  of  QuickBA¬ 
SIC  add-on  tools. 

Forth-Coming 

Dear  DDJ, 

I  read  Martin  Tracy’s  article,  “Zen  Forth,” 
with  great  interest  {DDJ,  January  1990). 
As  a  Forth  programmer  myself,  I’m  in- 
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terested  in  Forth  systems  and  applica¬ 
tions.  I  even  wrote  a  Forth  system  for 
sale  (CorrectForth  —  I  published  it  as 
a  product  of  Correct  Software,  Inc.).  I 
have  a  number  of  comments  on  the 
implementation  and  what  looks  like 
bugs  in  the  source  code. 

First,  you  could  put  the  address  of 
colon  into  the  register  DI.  Then  colon 
looks  like  this: 

LABEL  COLON  BP  SPXGHGSI  PUSH 
BPSP  X  CHG  SI  POP  NEXT  C; 

(the  CFA  code  or  a  colon  definition  is 
DI  CALL).  The  result  is  a  system  about 
290  faster  than  a  JMP  colon  and  numer¬ 
ous  changes  to  the  source  code  (string 
operators,  FIND,  etc.).  The  changes  are 
minor  and  would  involve  saving  and 
restoring  DI.  Another  change  would 
be  to  use  register  ES  to  point  to  RAM, 
thus  increasing  the  amount  of  code 
space  and  data  space  available.  Only 
string  operations  would  be  affected  and 
would  involve  saving  and  restoring  ES. 
Then,  too,  you  could  describe  another 
register  to  hold  the  nest  to  top  of  stack 
value.  This  speeds  up  the  system  by 
10  percent  since  lots  of  Forth  words 
use  2  parameters.  The  system  as  pub¬ 
lished  in  DDJ  runs  the  Sieve  of  Eras- 
tothenes  benchmarks  in  46  seconds, 
but  the  new  improved  system  in  45 
second.  Time  counts  in  real-time  appli¬ 
cations! 


The  source  code  bugs  are  as  follows: 


Screen 

Page 

Bug(s) 

13 

98 

use  of  TRUE  (a  code 
defined  word)  in  = 

<,  U< 

14 

98 

same  as  above,  only 

for  0=,  0< 

37 

102 

use  of  SPO  in  depth 

The  reason  I’d  call  them  bugs  is  that 
I  don’t  think  the  metacompiler  Martin 
was  using  would  execute  works  de¬ 
fined  in  the  metacompiler’s  target  dic¬ 
tionary.  If  it  did,  I’d  think  twice  before 
I’d  use  such  a  “feature”  —  I  would  cross 
compile  into  a  processor  that  might 
not  execute  host  code  .  .  .  ! 

Overall,  this  system  sings  pretty  good. 
I  counted  on  that  —  Mr.  Tracy’s  been 
in  the  Forth  community  much  longer 
than  I  have.  The  choice  of  a  DCT  (di¬ 
rect  threaded  code)  implementation  of 
Forth  is  the  best  in  my  opinion  since  it 
has  the  best  tradeoff  of  size  vs.  speed. 
If  you  want  speed  and  don’t  care  about 
size,  go  for  STC  (subroutine  threaded 
code)  (like  Small  C  did).  If  you  want 
really  tight  code  (say  you  only  have 
4K  of  ROM),  go  for  TTC  (token  threaded 
code).  If  you  want  speed  and  just  have 
to  have  small  size,  go  for  DTC.  The 


high-level  words  run  at  an  acceptable 
speed  and  providing  you  chose  the 
proper  words  as  going  into  assembler 
(CODE  definitions  for  the  knowledge¬ 
able),  you'll  get  screaming  speed  at 
little  cost. 

Russell  McCale 

New  York,  New  York 

Martin  responds:  Thank  you  for  your 
interest  in  ZEN  Forth.  Iam  writing  this 
letter  to  answer  some  of  the  many  ques¬ 
tions  I  have  received. 

ZEN  is  a  personal  dialect  I  have  been 
developing  and  porting for  several  years . 
Most  recently,  I  have  been  using  it  to 
track  the  development  of  the  ANSI  X3J 14 
proposed  standard.  The  current  state 
of  the  standard  is  reflected  in  a  ivork- 
ing  document  called  BASIS.  The  BASIS 
changes  every  three  months. 

The  most  recent  BASIS  is  BASIS  10, 
and  I  have  written  ZEN1_10  to  match 
it.  ZEN1_10  means  Version  1,  release 
10.  I  have  posted  ZEN1_10  on  GENIE 
and  on  BIX,  and  will  continue  to  post 
new  versions  there. 

ZEN1_10  is  not  meant  to  be  a  devel¬ 
opment  system,  but  rather  a  simple  and 
efficient  Forth  dialect.  I  have  provided 
only  the  source  code,  for  your  study, 
and  an  executable  file  that  you  can 
use  to  load  a  text  file  to  test  a  program 
for  ANSI  compatibility. 

Yes,  you  are  missing  documentation, 
assembler,  metacompiler,  etc.  These  will 
not  be  written  until  the  draft  proposal 
dpANS  is  ready,  which  is  at  least  nine 
months  away.  The  current  release  was 
created  by  a  Forth -to-assembler-source 
translator.  The  next  release  will  prob¬ 
ably  be  written  in  Turbo  C  or  C++. 

More  on  Algorithm  Patenting 

Dear  DDJ, 

The  compression  algorithms  have  been 
in  my  conscious  path  for  a  search  to 
reduce  some  of  my  voluminous  writ¬ 
ings.  I  have  corresponded  with  you 
and  Mark  Nelson  about  this,  and  al¬ 
though  I  could  never  get  his  C  program 
to  run  with  “Let’s  C”  from  Mark  Wil¬ 
liams,  I  read  with  interest  what  some 
of  the  law  types  have  to  say  about  it. 

Having  been  in  the  chemical  field 
for  some  30  years,  I  have  come  across 
many  snafus  of  the  Patent  Office.  I 
leave  to  your  imagination  why  these 
snafus  occur;  not  in  the  least  is  the 
heavy  burden  of  research  of  prior  art 
before  patents  are  granted.  Many  times 
patents  were  granted  on  chemical  pro¬ 
cedures  or  compounds  that  were  in 
direct  conflict  with  prior  art.  These  were 
easy  to  deal  with.  Usually  showing  prior 
art  would  annul  the  patent  rights  right 
on  the  spot. 

(continued  on  page  14) 
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It  may  have  become  a  bit  more  diffi¬ 
cult  today,  since  our  society  is  the  most 
litigious  in  the  world  and  lawyers,  in 
and  out  of  government,  seem  to  thrive 
on  perpetuating  their  own  income  at 
the  expense  of  the  general  population. 
Lawyers  have  become  the  true  leeches 
of  this  society,  that  leech  wealth  from 
this  society.  I  am  not  surprised  that 
some  two-bit  lawyer  will  claim  the  LZW 
routine  to  be  patentable,  while  the  real 
inventors  lived  some  50  years  ago  and 
may  have  been  dead  for  a  while.  After 
all,  lawyers  have  to  make  money  too. 

Paul  A.  Elias 

Fountain  Hills,  Arizona 

Location  IS  Everything 

Dear  DDJ 

I’m  working  with  Softaid’s  hardware 
8088  emulator,  and  found  Mark  Nel¬ 
son’s  January  1990  article  (“Location  is 
Everything!”)  on  an  exe-to-hex  locate 
utility  useful  and  instructive.  However, 
I  had  to  move  the  STACK  segment  in 
his  START.ASM  file  in  front  of  the  other 
data  segments  to  make  the  locate  pro¬ 
gram  behave  correctly;  this  with 
Borland’s  TASM  1.0,  C  2.0,  and  TLINK 
2.0,  which  combination  I  assume  uses 
some  slight  unanticipated  variation  of 
the  5  million  sacred  ways  of  ordering 
segments  and  groups.  Without  this 
change,  the  stack  segment  would  up, 
in  a  test  file,  a  paragraph  after  the  rest 
of  the  data,  and  since  LOCATE  uses 
this  value  to  figure  out  where  all  the 
data  is,  it  wouldn’t  relocate  properly. 
(This  is  because  —  I  would  figure  but 
heaven  only  knows  —  the  exe  stack 
record  LOCATE  uses  was  actually  in 
fact  the  genuine  offset  of  the  stack,  not 
of  some  trifling  DGROUP,  no  matter 
what  START.ASM  says.) 

Once  over  that  minor  difficulty  I  was 
able,  using  various  C,  TASM,  and  TLINK 
debugging  options,  to  include  line  num¬ 
bers  and  globals  into  an  output  map 
file  which  the  Softaid  SLD  (source  level 
debugger)  program  and  utilities  could 
translate,  download,  and  more  or  less 
understand  —  that  is,  I  could  step  and 
breakpoint  in  source  (public  variables 
would-up  in  the  wrong  place,  but  I’m 
sure  a  little  more  hacking  could  fix 
that).  SLD  is  a  great  and  powerful  thing 
capable  of  much  more,  or  so  I  am  told, 
and  inasmuch  as  the  Softaid  system  is 
thousands  of  dollars,  we’re  spending 
a  few  hundred  more  for  a  sophisticated 
locator  program.  But  it’s  nice  to  have 
an  extra  emergency  tool,  and  using/ 
fiddling  Mr.  Nelson’s  program  was  just 
the  bit  of  8088-in-ROM  exercise  I  needed 
to  get  in  the  mood.  Thanks  for  the  help. 

J.G.  Owen 

Fort  Salonga,  New  York 


Round  and  Round 
We  Go  . . .  Maybe 

Dear  DDJ, 

Recently  I  had  the  chance  to  put  to  use 
the  parametric  circle  algorithm  described 
in  Robert  Zigon’s  article  in  the  January 
issue  of  DDJ  (“Parametric  Circles”). 
Shortly  thereafter,  I  came  across  Joseph 
M.  Hovanes  Jr.’s  letter  in  the  March 
issue,  citing  the  shortcomings  of  this 
algorithm  when  compared  to  Bresen- 
ham’s  algorithm. 

Although  Bresenham’s  algorithm  is 
more  efficient,  the  parametric  approach 
does  have  several  advantages.  First,  the 
eight-way  symmetry  that  Mr.  Hovanes 
mentions  can  be  applied  when  drawing 
a  parametric  circle,  too.  Second,  only 
floating-point  additions  and  multiplica¬ 
tions  (i.e.,  no  trig  functions)  are  per¬ 
formed  inside  the  loop.  If  your  computer 
has  a  floating-point  coprocessor,  the  exe¬ 
cution  time  is  within  the  same  order  of 
magnitude  as  integer  arithmetic. 

Lastly,  if  you  need  to  draw  only  part 
of  a  circle  (i.e.,  an  arbitrary  circular 
arc),  the  parametric  algorithm  can  be 
easily  adapted  to  start  and  stop  where 
you  please.  After  examining  Bresen¬ 
ham’s  algorithm  for  quite  a  while,  I’m 
pretty  sure  that  it  can  only  draw  a  com¬ 
plete  circle,  or  one  of  the  eight  sym¬ 
metric  sectors. 

Ben  White 

Mountain  View,  California 

It’s  All  in  the  Numbers 

Dear  DDJ, 

The  major  point  Michael  Swaine  makes 
in  his  November  1989  “Swaine’s  Flames” 
—  that  we  should  not  blindly  accept 
“numerical”  answers  is  well  taken.  Un¬ 
fortunately,  in  the  second  example  of 
incorrect  use  of  numeric  things,  I  be¬ 
lieve  he  is  in  error  and  John  Paulos  is 
correct.  In  my  15  years  hanging  around 
research  laboratories,  I  have  always  un¬ 
derstood  two  values  to  be  different  by 
“two  orders  of  magnitude”  to  mean 
different  by  a  factor  of  10  2,  not,  as  he 
claims,  by  10100.  If  this  were  the  case, 
the  term  would  not  come  up  very  often, 
since  10100  is  a  very  large  number  — 
about  equal  to  the  number  of  atoms  in 
the  universe. 

I  ran  across  a  better  example  of  in¬ 
correct  number  usage  in  an  IBM  ad. 
This  ad  states  that  the  footprint  of  their 
new  printer  (291  square  inches)  is  33 
percent  smaller  than  H.P.’s  LaserJet  (432 
square  inches).  Give  or  take  a  square 
inch,  this  is  correct.  However,  the  ad 
then  concludes  from  this  fact  “And  that 
gives  you  33  percent  more  usable  work¬ 
space.”  This  proclamation,  while  sound¬ 
ing  somehow  reasonable,  is  correct  for 
only  one  of  all  possible  workspaces. 

For  example,  my  computer/printer 


space  is  a  fairly  typical  80  x  32  inches 
(2560  square  inches).  If  I  had  a  Laser¬ 
Jet,  I  would  have  2560  -  432  =  2128 
square  inches  of  “usable”  workspace. 
(Is  a  printer  really  useless?)  If,  accord¬ 
ing  to  IBM,  I  purchase  their  product  to 
replace  the  LaserJet,  I  will  have  33  per¬ 
cent  more  workspace,  or  2128  x  1.33  = 
2830  square  inches  more  than  the  area 
of  my  table  with  no  printer  at  all.  Good 
deal,  it  saves  buying  a  bigger  desk! 

In  fact,  if  each  time  I  buy  an  IBM 
printer,  I  get  33  percent  more  work¬ 
space,  the  purchase  of  118  of  them 
should  give  me  control  of  the  entire 
surface  of  the  earth.  However,  if  I  need 
still  more  room,  even  if  I  only  purchase 
one  a  day,  inside  of  a  year  I  can  have 
the  lateral  dimensions  of  my  workspace 
increasing  at  an  average  speed  greater 
than  light.  But  that,  as  we  know,  would 
be  ridiculous. 

Of  course,  in  my  example,  what  really 
happens  is  that  after  the  purchase  of 
an  IBM  laser  printer,  I  would  have  2560  - 
291  =  2269  square  inches  of  workspace; 
2269/2128  =  =>  7  percent  more  than 
before.  This  is  of  some  benefit,  of  course, 
but  it  doesn’t  sound  very  impressive  — 
and  the  point  of  using  numbers  at  all 
is  to  impress  people  —  right? 

Jeffry  Stetson 

Villigen,  Switzerland 

I  Fought  the  Law  But  I  Won 

Dear  DDJ, 

I  was  a  little  bit  surprised  by  Dun- 
temann’s  One  Law  of  Portability  (DDJ 
March  1990):  That  it's  virtually  impossi¬ 
ble  to  take  source  code  for  an  on-line 
program  and  recompile  it  on  an  en¬ 
tirely  different  computer  with  little  if 
any  modifications. 

Actually,  I  know  that  it  can  be  done, 
since  I’ve  done  exactly  that  by  switch¬ 
ing  Ryan  McFarland  Cobol  code  be¬ 
tween  an  IBM  PC  compatible  and  a 
minicomputer  running  Unix.  And  come 
to  think  of  it,  why  can’t  any  higher- 
level  language  include  verbs  which 
mean  “display  this  on  the  user’s  screen” 
and  “place  user’s  keyboard  input  into 
this  memory  location,”  regardless  of 
whether  the  code  is  compiled  and  exe¬ 
cuted  on  a  PC,  VAX,  or  3090? 

Jacob  Stein 

Monsey,  New  York 

DDJ 

We  welcome  your  comments  (and  sug¬ 
gestions).  Mail  your  letters  (include  disk 
if  your  letter  is  lengthy  or  contains  code) 
to  DDJ,  501  Galveston  Dr.,  Redwood 
City,  CA  94063,  or  send  them  electroni¬ 
cally  to  CompuServe  76704,50  or  via 
MCI  Mail,  c/o  DDJ .  Please  include  your 
name,  city,  and  state.  We  reserve  the 
right  to  edit  letters. 
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An  efficient,  unobtrusive,  portable  garbage  collector 


Frank  Jackson 


Nobody  likes  to  take  out  the  trash,  and  programmers 
are  no  exception.  Wouldn’t  it  be  nice  if  someone 
else  would  gather  up  all  the  garbage  that  we  create 
and  dispose  of  it  for  us?  It  should  come  as  a 
welcome  relief,  then,  to  discover  that  the  run-time 
systems  of  programming  languages  such  as  Lisp,  Smalltalk, 
and  Prolog  generally  provide  facilities  that  do  exactly  that. 
With  the  advent  of  powerful  computer  workstations,  auto¬ 
matic  garbage  collection  has  become  an  important  compo¬ 
nent  of  many  modern  interactive  programming  environ¬ 
ments  as  well  as  the  applications  that  are  built  using  such 
environments. 

Although  traditional  programming  languages  such  as  C, 
Fortran,  and  Pascal  do  not  require  the  programmer  to  ex¬ 
pend  any  effort  managing  the  memory  occupied  by  either 
the  data  that  is  allocated  on  the  system’s  run-time  stack  or 
the  data  that  is  statically  allocated  on  the  system’s  heap,  they 
do  require  the  programmer  to  manage  any  data  that  is 
dynamically  allocated  on  the  heap.  Programmers  that  use 
such  languages  are  forced  to  litter  their  programs  with 
explicit  free  statements  if  they  wish  to  recycle  the  storage 
consumed  by  heap-allocated  data  that  is  no  longer  useful. 
By  having  the  language’s  run-time  system  collect  such  gar¬ 
bage  automatically,  a  certain  class  of  well-known  bugs  is 
eliminated.  For  example,  storage  leaks  cannot  occur  in  such 
a  system,  so  valuable  memory  is  not  wasted  if  the  program¬ 
mer  neglects  to  free  data  that  is  no  longer  accessible.  Even 
more  important,  data  cannot  be  prematurely  freed,  avoiding 
the  chaos  that  can  result  when  an  application  tries  to  access 
data  that  was  mistakenly  recycled.  Finally,  the  programmer 
is  relieved  of  the  burden  of  having  to  explicitly  manage  the 
heap,  which  saves  development  time  and  results  in  less 
complex  code. 


Frank  is  a  member  of  the  technical  staff  at  ParcPlace 
Systems  and  has  spent  much  of  his  time  there  designing, 
building,  and  evaluating  various  forms  of  automatic  mem¬ 
ory  management.  He  can  be  reached  at  ParcPlace  Systems, 
1550  Plymouth  St.,  Mountain  View,  CA  94043- 


Given  these  benefits,  you  might  expect  heap-based  gar¬ 
bage  collection  to  be  an  integral  component  of  most  present 
day  language  implementations.  This  is  not  the  case,  how¬ 
ever.  Most  traditional  programming  languages  were  not 
designed  with  garbage  collection  in  mind,  and  it  is  generally 
difficult  to  retrofit  existing  language  implementations  with 
an  automatic  garbage  collector.  Further,  there  are  a  number 
of  serious  drawbacks  to  the  classical  garbage  collection 
algorithms.  These  drawbacks  include: 

•  Distracting  pauses  when  performing  a  garbage  collection 

•  Failure  to  reclaim  certain  types  of  garbage 

•  High  overhead  in  space  and  time 

These  drawbacks  become  even  more  apparent  when  the 
algorithms  are  deployed  in  modern  interactive  environ¬ 
ments,  given  the  stringent  response-time  requirements  of 
these  environments. 

Significant  progress  has  been  made  in  the  past  decade, 
however,  and  new  garbage  collection  techniques  have  been 
developed  that  all  but  eliminate  the  above  drawbacks.  One 
of  these  techniques  —  generation  scavenging  —  not  only 
addresses  each  of  the  problems  just  listed,  but  it  requires 
no  hardware  support,  making  it  portable  across  a  wide 
variety  of  personal  computers  and  engineering  worksta¬ 
tions.  In  this  article,  I’ll  discuss  some  of  the  historical  events 
that  led  to  the  development  of  the  original  generation¬ 
scavenging  algorithm.  In  addition,  I’ll  describe  some  of  the 
more  recent  refinements  that  significantly  enhance  the  per¬ 
formance  of  the  basic  generation  scavenger.  In  particular, 
the  scavenging  algorithm  described  later  can  be  tuned  so 
that  the  average  pause  time  and  the  total  overhead  for 
collecting  garbage  can  be  reduced  to  an  acceptably  low 
level. 

Classical  Garbage  Collection  Algorithms 

Automatic  garbage  collection  has  roughly  a  30-year  history, 
starting  with  the  near  simultaneous  invention  of  the  two 
classical  approaches  to  garbage  collection  from  which  most 
modern  collection  schemes  are  derived,  namely  the  mark-and- 
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sweep  collection  algorithm  and  the  reference-counting  al¬ 
gorithm.  In  I960,  Collins2  introduced  the  notion  of  using 
reference  counts  to  determine  if  a  piece  of  data  could  be 
safely  reclaimed.  Each  piece  of  data,  which  I  shall  refer  to 
hereafter  as  an  object,  has  associated  with  it  a  count  of  the 
number  of  other  objects  that  reference  it.  When  this  cpunt 
drops  to  zero,  the  object  can  be  reclaimed  automatically  by 
the  run-time  system. 

The  primary  advantage  of  the  reference-counting  ap¬ 
proach  is  that  the  pauses  required  for  such  reclamations  are 
generally  imperceptible  to  the  user,  because  these  object 
reclamations  can  easily  be  distributed  across  the  computa¬ 
tion.  In  addition,  the  space  occupied  by  the  garbage  objects 
can  be  recycled  immediately,  thereby  reducing  the  total  amount 
of  memory  required  to  complete  a  given  computation,  al¬ 
though  this  space  advantage  is  reduced  somewhat  by  the 
storage  required  to  hold  the  per-object  reference  counts. 

There  are  some  significant  disadvantages  to  the  reference¬ 
counting  approach,  however.  Most  importantly,  it  can’t  re¬ 
claim  circular  garbage,  because  any  object  that  is  indirectly 
self-referential  will  never  have  a  reference  count  of  zero, 
even  if  the  object  is  no  longer  accessible  to  those  objects 
that  are  still  involved  in  the  computation.  In  addition,  spe¬ 
cial  provisions  have  to  be  made  to  reclaim  those  objects 
whose  reference-count  fields  have  overflowed.  Accordingly, 
most  systems  that  employ  reference  counting  attempt  to 
prevent  these  storage  leaks  by  either  providing  a  backup 
garbage  collection  system  that  utilizes  a  different  collection 


algorithm  or  by  incurring  the  expence  of  additional  recur¬ 
sive  scanning. 

Reference  counting  also  has  high  overhead  because  each 
store  requires  the  run-time  system  to  decrement  the  refer¬ 
ence  count  of  the  object  whose  reference  is  being  overwrit¬ 
ten  and  to  increment  the  reference  count  of  the  object 
whose  reference  is  being  stored.  In  addition,  when  an 
object’s  reference  count  drops  to  zero,  the  run-time  system 
has  to  decrement  the  reference  count  of  every  object  pointed 
to  by  the  dying  object,  possibly  causing  the  reference  counts 
of  these  objects  to  drop  to  zero,  forcing  the  system  to 
decrement  the  reference  counts  of  still  more  objects.  Finally, 
additional  overhead  is  engendered  by  the  necessity  of  recy¬ 
cling  the  storage  occupied  by  these  dead  objects  in  order 
to  avoid  running  short  of  memory. 

Subsequent  refinements  to  the  basic  reference-counting 
algorithm  by  Deutsch  and  Bobrow4  in  1976  have  succeeded 
in  reducing  the  total  temporal  overhead  to  approximately 
ten  percent,  which  is  still  a  relatively  high  price  to  pay. 
Consequently,  reference  counting  is  no  longer  widely  used 
in  commercially  available  language  implementations.  The 
fact  that  reference  counting  permits  object  reclamation  based 
strictly  on  local  information,  however,  has  made  it  relevant 
to  systems  that  must  operate  in  a  distributed  computing 
environment. 

The  other  classical  garbage  collection  technique,  also 
proposed  in  I960,  is  McCarthy’s7  mark-and-sweep  algo¬ 
rithm.  Unlike  reference  counting,  which  uses  local  informa- 
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tion  to  make  its  decisions,  the  mark-and-sweep  algorithm 
relies  on  a  global  traversal  of  all  live  objects  to  decide  which 
objects  can  be  reclaimed.  The  basic  mark-and-sweep  algo¬ 
rithm  works  as  follows: 

1.  Mark  all  objects  reachable  from  the  system’s  roots  as 
being  live  objects. 

2.  Sweep  memory,  unmarking  live  objects  and  reclaiming 
dead  objects,  possibly  performing  a  simultaneous  or 
subsequent  memory  compaction. 

Although  the  mark-and-sweep  algorithm  does  reclaim 
circular  garbage,  it,  too,  has  serious  drawbacks: 
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•  High  overhead,  because  the  system  has  to  reference  both 
live  and  dead  objects  during  each  garbage  collection. 

•  Lengthy,  potentially  disruptive  pauses  that  are  propor¬ 
tional  to  the  amount  of  memory  that  is  currently  allocated. 

Generation  scavenging  has  proven 
to  be  an  efficient,  unobtrusive 
technique  for  reclaiming  storage 
among  an  object  population  where 
deaths  outnumber  survivors 


In  a  virtual  memory  system,  these  pauses  can  be  exacer¬ 
bated  by  the  paging  overhead  required  to  touch  each  object 
in  the  entire  system.  The  mark  phase  can  cause  especially 
bad  paging  behavior,  because  it  typically  exhibits  what  is 
essentially  random  page-referencing  behavior. 

Modern  Garbage  Collection  Algorithms 

The  high  cost  in  time  associated  with  the  classical  garbage 
collection  algorithms  was  reduced  somewhat  by  the  devel¬ 
opment  of  the  copying  garbage  collectors,  such  as  that 
described  in  1969  by  Fenichel  and  Yochelson/  In  its  sim¬ 
plest  form,  a  copying  collector  works  in  the  following  man¬ 
ner:  The  data  heap  is  divided  into  two  semispaces,  and 
object  allocations  are  restricted  to  a  single  semispace.  When 
that  semispace  fills  up,  the  computation  is  paused,  and  the 
garbage  collector  then  traces  the  system’s  roots,  copying  all 
live  objects  to  the  other  semispace.  Once  all  of  the  live 
objects  have  been  copied,  the  computation  can  continue 
with  new  objects  being  allocated  in  the  same  semispace  as 
the  live  objects. 

Such  a  collector  is  potentially  faster  than  the  traditional 
mark-and-sweep  collector  because  it  touches  only  live  ob¬ 
jects,  making  its  pause  time  proportional  to  the  total  size  of 
the  live  objects  rather  than  the  size  of  allocated  memory. 
Dead  objects  are  reclaimed  by  virtue  of  the  fact  that  they  are 
not  copied  to  the  other  semispace.  The  problem  with  this 
approach  is  twofold:  First,  dividing  the  heap  into  semis¬ 
paces  wastes  space  because  the  computation  can  utilize 
only  half  of  the  heap  at  any  given  time,  and,  second,  the 
pauses  required  to  copy  all  of  the  live  objects  can  still  be 
quite  lengthy. 

To  eliminate  the  disruptive  pauses  caused  by  this  sort  of 
stop-and-copy  collector,  Baker1  proposed  an  incremental 
copying  collector  in  1978.  In  this  approach,  the  act  of 
copying  live  objects  from  one  semispace  to  the  other  was 
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interleaved  with  the  actual  computation.  This  algorithm 
imposed  some  additional  forms  of  overhead  on  the  compu¬ 
tation,  however,  including  the  need  for  the  computation  to 
monitor  every  read  and  write  to  the  heap  in  order  to  cor¬ 
rectly  follow  the  forwarding  pointers  that  were  placed  at  an 
object’s  old  address  when  it  was  copied  to  the  other  semis¬ 
pace.  This  additional  overhead  was  typically  overcome  by 
using  hardware  support,  such  as  that  available  on  the  MIT 
Lisp  machines.  Even  so,  the  Baker  collector  was  just  as 
spatially  inefficient  as  the  other  copying  collectors,  because 
it  also  divided  the  heap  into  a  pair  of  semispaces.  In  addi¬ 
tion,  the  total  time  required  to  copy  all  of  the  live  objects 
with  each  collection  was  still  unreasonably  long. 

Generation-Based  Garbage  Collectors 

To  alleviate  the  problems  associated  with  these  early  copy¬ 
ing  collectors,  language  implementors  began  to  exploit  the 
empirical  properties  of  data.  Researchers  observed  that  young 
objects  tended  to  die  while  still  young,  whereas  older  ob¬ 
jects  were  more  likely  to  live  on  indefinitely.  It  made  sense, 
then,  to  devote  more  effort  to  collecting  young  objects, 
where  the  return  on  the  system’s  copying  investment  was 
likely  to  be  high,  instead  of  repeatedly  copying  older  objects 
that  simply  refused  to  die. 

To  make  such  an  approach  possible,  Lieberman  and 
Hewitt6  proposed  in  1983  that  objects  be  segregated  into 
multiple  generations,  with  each  generation  containing  ob¬ 
jects  of  roughly  the  same  age.  In  addition,  they  proposed 
that  the  system  be  designed  so  that  each  generation  could 
be  colleted  independently.  Younger  generations  could  then 
be  collected  more  often,  generally  using  some  sort  of  copy¬ 
ing  algorithm.  If  an  object  survived  enough  collections,  then 
it  would  be  promoted  to  an  older  generation,  where  it 
would  be  collected  with  less  frequency.  This  approach 
saved  time  because  there  were  fewer  objects  to  copy  in  the 
young  generations,  given  the  high  mortality  rate  of  young 
objects;  it  also  saved  space  because  in  principle  the  system 
needed  to  maintain  only  enough  free  space  at  any  given 
time  to  copy  the  live  objects  in  a  single  generation  rather 
than  enough  free  space  to  copy  all  of  the  objects  in  the 
entire  system. 

The  feasibility  of  the  generation-based  approach  depended 
in  part  on  the  speed  with  which  the  garbage  collector  could 
identify  the  live  objects  in  a  given  generation.  Consequently, 
the  implementors  of  the  generation-based  systems  devel¬ 
oped  various  methods  for  keeping  track  of  the  roots  for 
each  generation.  This  task  was  typically  simplified  by  keep¬ 
ing  track  only  of  the  objects  in  older  generations  that  pointed 
directly  to  objects  in  the  younger  generations,  and  being 
careful  to  collect  all  of  the  younger  generations  when  col¬ 
lecting  an  older  generation.  Nevertheless,  the  task  of  keep¬ 
ing  track  of  each  generation’s  roots  added  additional  over¬ 
head  to  the  computation.  For  example,  each  store  into  the 
heap  had  to  be  monitored  to  see  if  it  created  the  sort  of 
intergenerational  reference  that  increased  the  number  of 
roots  for  a  given  generation.  However,  the  overhead  re¬ 
quired  to  monitor  each  store  in  such  a  manner  was  generally 
less  than  the  store  overhead  required  by  the  reference¬ 
counting  approach.  At  any  rate,  the  generation-based  ap¬ 
proach  allows  the  language  implementor  to  stake  out  an 
intermediate  position  between  those  taken  by  the  reference¬ 
counting  approach,  which  relies  solely  on  local  knowledge 
to  reclaim  garbage,  and  the  mark-and-sweep  approach, 
which  has  to  traverse  the  entire  system  to  reclaim  garbage. 

Even  more  overhead  is  incurred  by  those  generation- 
based  systems  that  reclaim  garbage  incrementally  (as  noted 
in  the  discussion  of  the  Baker1  algorithm).  Such  systems, 
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most  notably  Moon’s8  ephemeral  garbage  collector  for  Lisp, 
generally  hide  much  of  this  overhead  by  taking  advantage 
of  the  hardware  support  provided  by  modern  Lisp  ma¬ 
chines.  Such  systems  are  still  in  use  today,  and  the  language 
implementors  on  these  machines  continue  to  find  ways  to 
further  utilize  these  hardware  capabilities  (for  example, 
Courts3  has  described  a  way  to  reduce  page  faults  by  dy¬ 
namically  improving  the  locality  of  reference  of  those  ob¬ 
jects  housed  on  the  heap). 

Generation  Scavenging 

Many  language  implementors,  however,  especially  those 
developing  third-party  software  that  must  be  deployed  on 
a  variety  of  hardware  platforms  and  operating  systems,  can’t 
count  on  having  any  hardware  support  for  garbage  collec¬ 
tion  at  their  disposal.  Without  hardware  support,  it  is  quite 
difficult  to  implement  an  efficient  incremental  garbage  col¬ 
lector,  primarily  because  of  the  extra  overhead  required  to 
follow  forwarding  pointers  when  reading  and  writing  to  the 
heap.  The  generation-scavenging  algorithm  was  developed 
to  provide  language  implementors  with  a  garbage  collector 
that,  like  the  incremental  collectors,  was  unobtrusive  but, 
unlike  the  incremental  collectors,  did  not  require  hardware 
support  in  order  to  be  reasonably  efficient. 

The  basic  algorithm,  as  described  by  Ungar10  in  1984, 
requires  that  the  heap  be  divided  into  two  spaces  —  old- 
space  and  newspace.  oldspace  is  generally  much  larger  than 
newspace ,  because  oldspace  is  used  as  the  repository  for 
objects  that  are  considered  permanent.  As  such,  oldspace  is 
collected  infrequently,  typically  by  using  a  global  mark-and- 
sweep  collector.  Instead,  most  reclamation  attempts  are 
focused  on  the  objects  in  newspace.  In  Ungar’s10  original 
algorithm,  newspace  is  divided  into  three  zones  —  a  crea¬ 
tion  zone  and  two  survivor  zones.  New  objects  are  allocated 
in  the  creation  zone.  Whenever  the  creation  zone  fills  up, 


Figure  1:  Nepotism 


the  computation  is  halted,  and  the  scavenging  mechanism 
copies  all  live  objects  in  the  creation  zone  to  one  of  the 
survivor  zones.  A  forwarding  pointer  is  left  behind  for  each 
object  that  is  copied,  and  any  other  objects  that  reference 
the  old  location  of  a  copied  object  will  have  these  references 
updated  when  the  scavenger  scans  them  in  its  search  for 
additional  survivors.  Once  the  scavenge  is  complete,  the 
creation  zone  will  be  empty  and  can  be  reused.  Subsequent 
scavenges  will  continue  to  copy  those  live  objects  that  can 
be  found  in  the  creation  space  and  the  occupied  survivor 
zone  to  the  empty  survivor  zone.  In  this  scheme,  then, 
objects  are  born  in  the  creation  zone  and  thereafter  bounce 
back  and  forth  between  the  two  survivor  zones  until  they 
are  deemed  old  enough  to  be  promoted  to  oldspace.  Un¬ 
gar11  refers  to  this  process  of  promoting  an  object  to  old¬ 
space  as  “tenuring.” 

Because  generation  scavenging  is  a  stop-and-copy  algo¬ 
rithm,  as  opposed  to  being  incremental,  there  is  no  need  for 
special  hardware  to  follow  forwarding  pointers,  because  all 
references  to  these  forwarding  pointers  are  automatically 
updated  during  the  scavenge.  Like  the  other  generation- 
based  algorithms,  however,  the  system  must  maintain  a  list 
of  roots  for  newspace.  It  must  keep  a  list  of  those  objects  in 
oldspace  that  contain  references  to  objects  in  newspace. 
Maintaining  this  list  imposes  some  extra  overhead  on  every 
store  into  the  heap.  Even  without  special  purpose  hardware, 
however,  this  overhead  doesn’t  appear  to  be  onerous  for 
the  following  empirical  reasons: 

•  Stores  occur  much  less  frequently  than  fetches. 

•  Very  few  oldspace  objects  point  to  objects  in  newspace , 

so  the  list  of  roots  is  generally  small. 

•  The  vast  majority  of  stores  (that  is,  the  stores  into  those 

objects  housed  in  newspace)  can  be  ignored  on  the  basis 

of  a  single  boundary  check. 

In  addition,  the  system  must  be  able  to  discern  the  age  of 
an  object  so  that  the  scavenger  can  decide  when  the  object 
should  be  tenured  to  oldspace.  In  Ungar’s10  initial  implemen¬ 
tation,  each  object  had  an  age  field  that  the  scavenger 
incremented  periodically.  As  we  shall  see  shortly,  the  re¬ 
quirement  that  the  system  keeps  track  of  each  object’s  age 
need  not  impose  any  additional  storage  overhead.  Genera¬ 
tion  scavenging,  then,  can  be  viewed  as  a  two-generation 
system,  where  oldspace  and  newspace  are  the  two  genera¬ 
tions,  or  a  multi-generation  system  with  objects  of  different 
generations  (that  is,  different  ages)  being  housed  together 
in  newspace. 

Because  the  generation-scavenging  algorithm  was  first 
published,  many  variations  have  been  both  proposed  and 
implemented.  In  some  systems,  newspace  is  composed  of 
two  zones  instead  of  three.  Other  implementations  allow 
the  scavenger  to  scavenge  multiple  spaces  instead  of  re¬ 
stricting  its  purview  to  a  single  space.  These  spaces  are 
sometimes  arranged  as  pairs  of  semispaces  and  sometimes 
as  a  bucket  brigade  of  consecutive  spaces  through  which 
the  surviving  objects  are  promoted.  Some  systems  eliminate 
the  need  for  an  age  field  by  spatially  segregating  objects  of 
the  same  age.  (See  Wilson  and  Moher13  for  an  example  of  a 
system  that  obviates  the  need  for  an  age  field  by  organizing 
its  spaces  into  a  bucket  brigade.)  Finally,  various  schemes 
have  been  proposed  for  efficiently  identifying  the  roots  of 
newspace.  Shaw,9  for  example,  recently  suggested  combin¬ 
ing  the  store  check  with  the  virtual  memory  mechanism  that 
marks  hardware  pages  as  being  dirty  and  then  scanning 
these  dirty  pages  for  actual  roots  at  scavenge  time. 

Tenure  Policies 

One  of  the  key  decisions  that  a  generation  scavenger  must 
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make  is  when  to  tenure  an  object  to  oldspace.  Early  scaven¬ 
gers  generally  employed  a  simple  fixed-age  tenure  thresh¬ 
old:  They  tenured  any  object  that  had  survived  for  a  fixed 
amount  of  time  or  a  fixed  number  of  scavenges.  Studies 
conducted  by  myself  and  Ungar12  show  that  such  tenure 
policies  are  not  particularly  effective  in  minimizing  the  amount 
of  tenured  garbage  (that  is,  objects  that  die  after  being 

By  having  the  language’s  run-time 
system  collect  garbage  automatically, 
a  certain  class  of  well-known  hugs 
is  eliminated 


tenured)  or  in  controlling  the  length  of  the  pauses  required 
to  perform  the  scavenge.  Different  applications  cause  ob¬ 
jects  to  survive  for  different  amounts  of  time,  so  no  single 
tenure  threshold  will  perform  optimally  in  all  circumstances. 
If  the  tenure  threshold  is  set  too  young,  then  oldspace  will 
be  flooded  with  objects  that  die  shortly  thereafter.  (This 
problem  will  be  further  exacerbated  by  the  effects  of  nepo¬ 
tism.  See  Figure  1.)  And  if  the  tenure  threshold  is  set  too  high, 
then  the  scavenge  pauses  can  easily  become  disruptive. 

Both  of  the  above  problems  can  be  solved  by  employing 
a  tenure  policy  that  modifies  its  tenure  threshold  dynami¬ 
cally  according  to  the  demographics  of  the  object  popula¬ 


tion  currently  housed  in  newspace.  I  will  now  describe  how 
one  might  go  about  designing  such  a  tenure  policy.  Because 
stop-and-copy  collectors  traditionally  have  problems  with 
distracting  pauses,  it  is  important  to  provide  the  scavenger 
with  the  means  to  control  the  length  of  its  pauses.  Assuming 
that  we  have  determined  the  maximum  pause  time  that  the 
scavenger  can  be  permitted  to  take  without  being  consid¬ 
ered  disruptive,  we  need  to  measure  how  many  bytes  of 
surviving  objects  the  scavenger  can  copy  in  that  amount  of 
time.  The  scavenger  can  then  control  the  length  of  its  pauses 
by  using  this  number  as  a  watermark  in  the  survivor  zones. 
If  the  aggregate  size  of  the  objects  in  the  survivor  zone  is 
less  than  this  watermark,  then  the  scavenger  doesn’t  need 
to  tenure  any  objects  during  the  upcoming  scavenge,  be¬ 
cause  the  pause  required  to  scavenge  these  survivors  will 
probably  be  acceptably  brief.  If,  however,  the  size  of  these 
survivors  actually  exceeds  this  watermark,  then  the  scaven¬ 
ger  should  tenure  some  objects  during  the  next  scavenge 
to  keep  the  pause  times  from  becoming  disruptive. 

Because  the  scavenger  tenures  objects  to  keep  the  dura¬ 
tion  of  its  pauses  under  control,  we  need  to  provide  it  with 
the  means  to  minimize  the  amount  of  the  tenured  garbage 
that  it  creates.  Rather  than  tenure  objects  randomly,  which 
could  result  in  young  objects  that  are  unworthy  of  promo¬ 
tion  being  tenured,  the  scavenger  uses  demographic  infor¬ 
mation  to  select  a  tenure  threshold  that  will  result  in  the 
desired  amount  of  the  oldest  objects  in  newspace  being 
tenured.  The  necessary  demographic  information  can  be 
kept  in  a  table  indexed  by  age  that  contains  the  number  of 
data  bytes  in  newspace  for  each  age.  This  table  can  either 

(continued  on  page  26) 
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be  maintained  by  the  scavenger  as  a  matter  of  course,  or  it 
can  be  created  on-the-fly  by  a  quick  scan  of  the  occupied 
survivor  zone.  By  scanning  this  table  backwards,  the  scav¬ 
enger  can  then  set  the  appropriate  tenure  threshold  for  the 
ensuing  scavenge.  These  measures  permit  the  scavenger  to 
tenure  the  minimal  amount  of  objects  that  have  the  highest 
likelihood  of  surviving  (see  Figure  2). 

Thus  far,  we’ve  described  a  scavenger  that  can  easily  be 
made  nondisruptive,  even  in  the  face  of  the  varying  object 
demographics,  but  what  about  the  total  scavenging  over¬ 
head?  Given  a  maximal  acceptable  pause  time  of,  say,  100 
milliseconds,  we  can  drive  the  total  scavenge  overhead 
reasonably  low  by  sizing  the  creation  zone  appropriately 
(assuming  that  the  overhead  required  to  perform  the  store 
checks  is  as  low  as  recent  studies  seem  to  suggest).  That  is, 
if  we  were  to  size  the  creation  zone  such  that  it  filled  up 
once  per  second  (and,  hence,  a  scavenge  was  performed 
every  second  or  so),  then  the  total  overhead  for  scavenging 
would  be  around  ten  percent.  If,  however,  we  sized  the 
creation  zone  so  that  it  filled  up  every  three  to  four  seconds, 
then  the  scavenge  overhead  would  be  less  than  three  percent. 

Thus,  the  generation  scavenger  described  can  easily  be 
tuned  in  two  respects:  The  average  pause  time  required  to 
perform  a  scavenge  and  the  total  scavenge  overhead  can  be 
controlled  by  setting  the  watermark  in  survivor  space  and  the 
size  of  the  creation  zone,  respectively.  Of  course,  the  cost  for 
reducing  both  pause  times  and  scavenge  overhead  is  paid  in 
memory,  in  terms  of  both  the  memory  required  to  size  the 
creation  zone  appropriately  and  the  space  taken  up  by  ten¬ 
ured  garbage  resulting  from  the  need  to  keep  the  total  size 
of  the  scavenge  survivors  less  than  the  survivor  zone  water¬ 
mark.  For  example,  current  Smalltalk  implementations  on 
stock  hardware  that  utilize  this  particular  type  of  scavenger 
typically  have  survivor  zone  watermarks  that  vary  between 
50K  and  120K,  resulting  in  worst  case  pause  times  of  100 
milliseconds,  and  creation  zones  between  400K  and  800K, 


Max  pause  time  watermark 

Surviving  new  objects  <  max 
=>  tenure  threshold  <-co 


New  object  area 


After  scavenge  n,  the  amount 
of  surviving  new  object  data  is 
less  than  the  limit  imposed  by 
the  maximum  acceptable  pause 
time.  The  tenure  threshold  is  set 
to  infinity  so  that  the  next 
scavenge  will  not  tenure  any 
objects. 


New  object  area  Tenure  threshold  <=-  2 


After  scavenge  n+1,  the 
amount  of  surviving  new  object 
data  exceeds  the  limit  by  100 
bytes.  The  age  table  indicates 
that  the  tenure  threshold  must 
be  set  to  2  in  order  to  tenure 
at  least  1 00  bytes. 
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170  bytes  tenured 


After  scavenge  n+2,  170  bytes 
have  been  tenured.  The  amount 
of  surviving  new  object  data  is 
again  less  than  the  limit 
imposed  by  the  maximum 
acceptable  pause  time. 

The  tenure  threshold  is  set  to 
infinity  so  that  the  next 
scavenge  will  not  tenure  any 
objects. 


Figure  2:  Demographic  feedback-mediated  tenuring 
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resulting  in  a  scavenge  overhead  of  less  than  three  percent. 

Because  it  requires  neither  hardware  assistance  nor  any 
operating  system’s  software,  this  scavenger  has  been  suc¬ 
cessfully  deployed  as  a  component  of  Objectworks  for  Smalltalk- 
80  fielded  by  ParcPlace  Systems.  This  particular  implementa¬ 
tion,  coded  entirely  in  C,  has  been  ported  to  a  wide  variety 
of  personal  workstations,  including  the  Apple  Macintosh 
family,  most  386-based  DOS  PCs,  and  the  workstations  sold 
by  Sun,  Digital  Equipment,  and  Hewlett-Packard. 

Trouble  in  Paradise 

Generation  scavenging  is  not  without  its  shortcomings,  how¬ 
ever.  Certain  space-consumptive  programs  may  produce  so 
many  live  objects  that  their  sheer  volume  simply  over¬ 
whelms  the  capacity  of  the  newspace  architecture  described 
earlier.  These  programs  typically  produce  substantial  amounts 
of  tenured  garbage  that  can  result  in  wasted  memory,  poor 
paging  behavior,  and  lengthy  interruptions  required  to  re¬ 
claim  this  garbage.  These  problems  can  be  mitigated  some¬ 
what  by  utilizing  several  large  additional  generations,  but 
not  without  incurring  noticeable  pauses  when  these  addi¬ 
tional  generations  are  scavenged  with  the  current  genera¬ 
tion  of  stop-and-copy  algorithms.  Finding  an  efficient  way 
to  collect  these  additional  generations  without  perceptible 
pauses  on  stock  hardware  will  require  further  research. 

Furthermore,  real-time  programs  frequently  require  drastically 
shorter  scavenge  pauses  than  normal  interactive  programs. 
The  measures  required  to  reduce  these  pauses  can  also  result 
in  a  significant  increase  in  the  amount  of  tenured  garbage. 


Conclusions 

Generation  scavenging  has  proven  to  be  an  efficient,  unob¬ 
trusive  technique  for  reclaiming  storage  among  an  object 
population  where  deaths  outnumber  survivors.  In  addition, 
it  has  proven  to  be  popular  among  language  implementors. 
For  example,  all  of  the  commercially  available  Smalltalk 
implementations  use  variants  of  generation  scavenging  as 
their  primary  reclamation  systems.  This  popularity  can  be 
attributed  both  to  the  algorithm’s  simplicity  and  to  the  fact 
that  it  requires  no  special  hardware  support.  Finally,  I  ex¬ 
pect  future  developments  in  the  area  of  generation-based 
garbage  collection  to  proceed  along  the  following  lines: 

•  Addressing  the  problems  posed  by  programs  that  produce 
massive  quantities  of  intermediate-lived  objects. 

•  Finding  ways  to  reduce  the  number  of  page  faults  in 
programs  that  utilize  virtual  memory. 

•  Searching  for  more  efficient  methods  of  keeping  track  of 
the  roots  to  a  given  generation. 

•  Experimentation  with  alternate  tenure  policies. 
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Dynamic  Link 
Libraries  For  DOS 

Running  large  programs  in  small  memory  space 

Gary  Syck 


With  the  average  size  of  avail¬ 
able  memory  increasing,  the 
average  size  of  applications 
that  use  that  memory  also 
grows,  as  programmers 
come  up  with  new  ways  to  put  all  that 
memory  to  use.  The  real  challenge  is 
to  shoehorn  the  great  ideas  for  tomor¬ 
row’s  programs  into  the  limited  mem¬ 
ory  of  today’s  computers.  At  some  point 
you  just  can’t  shrink  programs  without 
leaving  out  attractive  features.  Of  course, 
you  can  try  to  convince  users  that  they 
don’t  need  their  favorite  features,  but 
a  better  strategy  is  to  come  up  with 
some  kind  of  memory  management  that 
lets  you  move  portions  of  the  program 
and  data  in  and  out  of  memory  as 
required. 

Most  PC  programming  systems  pro¬ 
vide  some  way  to  do  overlays,  which 
are  portions  of  a  program  that  load  into 
the  same  area  of  memory.  When  a  rou¬ 
tine  is  required,  that  routine  gets  loaded 
into  the  overlay  area,  replacing  what¬ 
ever  code  or  data  is  already  there. 

Things  get  complicated  when  the  rou¬ 
tine  in  the  overlay  area  requires  a  rou¬ 
tine  that  is  in  another  overlay.  In  this 
case,  the  calling  routine  will  be  swapped 
out.  This  causes  problems  when  the 
called  routine  returns  and  finds  some¬ 
thing  else  where  the  calling  routine 
used  to  be. 


Gary  is  an  independent  consultant  and 
can  be  reached  at  12032  100th  Ave. 
N.E.,  *D203,  Kirkland,  WA  98034. 


To  prevent  this  problem  when  lay¬ 
ing  out  the  overlay  areas  for  a  program, 
you  must  consider  what  routines  are 
called  from  where.  Figure  1  shows  a 
typical  memory  map  for  a  program  that 
uses  overlays. 

Enter  Dynamic  Link  Libraries 

Dynamic  link  libraries  (DLLs),  which 
were  introduced  with  Windows  and 
OS/2,  move  the  task  of  linking  in  code 
from  the  end  of  the  compile/link  step 
to  when  the  program  is  actually  run¬ 
ning.  Run-time  linking  lets  the  linker 
put  an  object  file  anywhere  in  available 
memory.  If  there  is  no  memory  avail¬ 
able,  the  linker  can  find  an  object  file 


that  is  not  being  used  and  replace  it 
with  the  file  it  needs  to  load.  But  to 
take  advantage  of  DLLs,  you  must  use 
an  operating  system  that  supports  them, 
such  as  Windows  or  OS/2.  (It  is  ironic 
that  to  make  use  of  a  system  that  makes 
large  programs  run  in  small  memory 
spaces,  you  must  use  an  operating  sys¬ 
tem  that  requires  several  megabytes  of 
RAM  to  work.) 

The  routines  presented  in  this  article 
show  how  to  make  a  run-time  linker/ 
loader  that  uses  about  5K  of  code.  This 
is  the  heart  of  a  DLL  system.  At  the  end 
of  the  article  are  some  comments  on 
how  this  can  be  expanded  into  a  full 
DLL  system. 
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(continued  from  page  30) 

The  key  to  understanding  what  is 
going  on  is  to  remember  that  a  DLL 
loader  is  simply  a  linker  that  works  at 
run  time,  combined  with  a  program 
loader.  A  conventional  linker  combines 
all  of  the  object  files  for  a  program  into 
a  single  file  and  fixes  all  of  the  memory 
references  to  point  to  locations  in  the 
file.  The  loader  puts  the  file  in  memory, 
adds  the  address  where  the  file  was 
loaded  to  the  memory  addresses,  sets 
up  the  segment  registers,  and  jumps  to 
the  start  address  of  the  program. 

I  made  some  assumptions  in  order 
to  simplify  the  process  of  linking  and 
loading  object  files.  The  basic  assump¬ 
tion  is  that  the  object  file  was  created 
by  Microsoft  C  5. 1 ,  using  the  large  mem¬ 
ory  model.  This  choice  of  language 
and  memory  model  means  that  the 
linker  loader  will  always  deal  with  the 
same  arrangement  of  segments. 

There  are  three  major  pieces  to  this 
program.  The  first  piece,  GETDATA.C 
(Listing  One,  page  104),  loads  all  of  the 
global  data  and  creates  the  master  sym¬ 
bol  table.  The  second,  STUB. ASM  (List¬ 
ing  Two,  page  104),  is  the  calling  mecha¬ 
nism  for  functions.  LINKER. C  (Listing 
Three,  page  105)  is  the  linker  itself. 
Finally,  the  file  DLL.C  (Listing  Four, 
page  108)  ties  them  all  together. 

Loading  Global  Data 

Global  data  is  a  bit  of  a  problem  for  the 
run-time  linker.  All  global  data  must 
be  defined  before  it  can  be  referenced. 
With  conventional  linkers  this  is  not  a 
problem  because  the  linker  reads  all 
of  the  object  files  before  doing  any 
fix-ups.  The  run-time  linker  looks  at 
one  module  at  a  time,  so  modules  that 
define  data  must  be  loaded  before  mod¬ 
ules  that  use  the  data. 

Another  problem  with  global  data 
occurs  when  the  linker  wants  to  re¬ 


move  a  module  from  memory.  Ideally, 
it  should  also  remove  any  static  data 
for  that  module.  There  is,  unfortunately, 
no  way  to  tell  the  difference  between 
static  data  and  initialized  global  data. 

The  solution  to  these  problems  is  to 
require  all  global  data  to  be  defined  in 
a  single  object  file.  Loading  this  object 
file  first  insures  that  global  data  will  be 
ready  when  it  is  needed.  Any  global 
data  that  is  not  in  this  file  is  assumed 
to  be  static  data  associated  with  the 
module  being  loaded.  The  file  used  in 
this  sample  program  is  named 
GBLDATA.OBJ,  which  is  a  standard  ob¬ 
ject  file  that  is  created  by  compiling  the 
C  source  file,  GBLDATA.C  (Listing  Five, 
page  108),  which  contains  global  data 
definitions.  Listing  Six  (page  109)  is  the 
file  MAIN.C  from  which  MAIN. OBJ  is 
created;  Listing  Seven  (page  109)  is 
DLL.H,  the  header  file. 

The  function  GetData  in  GETDATA.C 
reads  GBLDATA.OBJ  and  extracts  the 
data  information  in  it.  The  function  be¬ 
gins  by  opening  the  object  file.  Next,  a 
loop  reads  each  object  record  from  the 
object  file.  In  the  loop  is  a  switch  state¬ 
ment  that  does  different  things  to  dif¬ 
ferent  record  types.  When  the  loop  is 
finished,  the  linker  closes  the  file  and 
allocates  space  for  the  last  group  of 
uninitialized  data  variables. 

Two  types  of  variables  can  be  ex¬ 
pected  in  GBLDATA.OBJ.  The  first  type 
is  initialized  data.  In  this  implementa¬ 
tion  all  initialized  data  goes  in  the  near 
data  segment  in  the  DataSpace  array 
defined  in  STUB. ASM. 

The  PUBDEF  record  in  the  object  file 
contains  all  of  the  names  of  the  initial¬ 
ized  data  variables.  This  information, 
along  with  the  size  and  location  of  the 
data,  is  copied  into  the  Syms  table.  The 
data  that  initializes  the  variables  is  in 
the  LEDATA  records. 

The  second  type  of  variable  is  the 
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(continued  from  page  32) 
uninitialized  data.  The  names  of  unini¬ 
tialized  variables  can  be  found  in 
COMDEF  records.  The  COMDEF  rec¬ 
ord  contains  the  name,  number  of  ele¬ 
ments,  and  size  of  an  element  for  a 
variable.  This  information  is  copied  into 
the  Syms  table.  To  reduce  the  number 
of  allocations  required,  no  allocation 

The  routines  presented 
in  this  article  show  how 
to  make  a  run-time 
linker/loader  that  uses 
about  5K  of  code 


is  made  until  there  is  at  least  32K  of 
data  to  allocate.  The  function  Allo- 
cateSyms  does  the  allocation  and  puts 
the  appropriate  addresses  into  the  Syms 
table  entries  for  the  symbols  affected. 
A  final  allocation  must  be  done  when 
there  are  no  more  records  to  pick  up 
the  last  group  of  variables. 

Calling  Functions 

When  GetData  has  loaded  all  the  global 
data,  the  main  routine  moves  on  to 
functions.  Function  information  is  kept 
in  a  table  called  “FuncLst.”  Library  func¬ 
tions  must  be  placed  in  the  table  ex¬ 
plicitly  (unless  you  have  the  object  files 
for  the  library  available).  The  library 
functions  will  be  linked  to  the  main 
program  by  the  conventional  linker. 
In  this  example  the  library  function 
printfwiW  be  used,  so  it  must  be  placed 
in  the  table. 

All  other  functions  will  be  loaded 
by  the  run-time  linker.  Before  it  can 
be  loaded,  a  function  must  have  an 
entry  in  the  FuncLst  table.  The  entry 
contains  the  name  of  the  function,  the 
location  of  the  function  (or  NULL  if  the 
function  is  not  loaded,  yet),  a  flag  that 
tells  if  the  function  is  unloadable,  and 
a  copy  of  the  stub  routine.  The  entry 
after  all  of  the  library  routines  is  for  the 
first  function  in  the  program.  Note  that 
the  address  of  the  function  is  NULL. 
This  indicates  that  the  function  has  not 
been  loaded  yet.  To  start  the  program 
the  stub  routine  for  this  function  is 
called. 

The  stub  routine  is  a  copy  of  the 
function  Stub  in  STUB.  ASM.  Each  copy 
is  modified  so  that  it  knows  what  func¬ 
tion  it  goes  with.  The  stub  routine  will 
be  called  instead  of  the  related  func¬ 
tion.  The  job  of  the  stub  routine  is  to 
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(continued  from  page  34) 
determine  if  the  function  is  in  memory 
(by  the  value  of  the  address  in  FuncLst) 
and  load  it  if  it  is  not.  In  a  system  that 
swaps  functions  in  and  out  of  memory, 
the  stub  routine  would  also  set  flags 
indicating  that  the  function  is  in  use  or 
not.  Once  the  function  has  been  loaded, 
the  stub  routine  jumps  to  the  function. 

Linking  Modules 

When  the  function  is  not  in  memory, 


the  stub  routine  calls  the  linker.  The 
first  step  is  to  find  the  file.  The  name 
of  the  file  is  extracted  from  the  name 
of  the  function.  If  there  is  only  one  file, 
the  name  of  the  function  must  match 
the  name  of  the  file.  If  there  are  several 
functions,  they  each  begin  with  the 
name  of  the  file,  followed  by  an  under¬ 
score,  then  the  function  name. 

The  logic  for  loading  the  file  into 
memory  is  similar  to  that  used  for  load¬ 
ing  GBLDATA.OBJ.  The  difference  is 


that  there  are  a  few  more  records  to 
deal  with.  The  first  new  record  is  the 
EXTDEF  record.  This  record  contains 
the  external  symbols  used  by  the  mod¬ 
ule.  If  the  external  symbol  is  in  Syms, 
then  it  is  a  data  reference;  otherwise,  it 
is  another  function,  and  an  entry  is 
made  in  FuncLst.  Each  external  item  is 
put  in  a  table  called  “ExtSyms.”  This 
table  maps  the  symbol  number  used 
in  this  file  to  the  symbol  numbers  used 
in  Syms  and  FuncLst. 


Compiler  Supported  DLLs  for  DOS 

Andrew  Schulman 


The  main  executable  for  Jensen  & 
Partners  International’s  (JPI)  new 
TopSpeed  C  development  environ¬ 
ment,  TS.EXE,  is  only  7K  bytes  in  size. 
TSC.EXE,  the  command-line  version 
of  the  C  compiler,  is  also  only  7K.  The 
only  .OVL  (overlay)  file  is  38K.  So 
where’s  the  code? 

Regrettably,  JPI  has  not  returned 
us  to  the  days  of  Turbo  Pascal  3-0, 
when  a  blazingly  fast  compiler  and 
full-screen  text  editor  fit  in  under  40K. 
Instead,  most  of  the  JPI  environment 
is  contained  in  files  such  as  TS- 
MAIN.DLL,  TSLINK.DLL,  TSMAKE. 
DLL,  and  TSASM.DLL. 

Microsoft’s  EXEHDR  utility  (included 
with  the  Windows  and  OS/2  software 
development  kits)  reveals  that  these 
are  “true”  segmented-executable  dy¬ 
namic-link  libraries  (DLLs).  The  entry 
points  have  names  such  as  STR$CARD- 
TOSTR  and  WINDOWS$PUTONTOP, 
corresponding  to  functions  from  JPI’s 
Modula-2  compiler  (for  example,  Win¬ 
dows.  PutOnTopC )).  This  C  compiler 
and  development  system  has,  with 
the  exception  of  library  functions  such 
as  print/C ),  been  written  not  in  C,  but 
in  Modula-2. 

JPI’s  use  of  DLLs  for  DOS  makes 
sense  for  a  number  of  reasons: 

•  Because  the  TopSpeed  development 
environment  is  comprised  of  individ¬ 
ual  programs,  and  because  these  pro¬ 
grams  have  many  subroutines  in  com¬ 
mon,  why  copy  the  subroutine  from 
.LIB  into  each  executable?  Instead,  all 
programs  share  a  single  copy  of  a 

Andrew  Schulman  is  a  contributing 
editor  to  Dr.  Dobb’s  Journal  and  is  a 
co-author  of  the  book,  Extending  DOS 
(Addison-Wesley,  1990). 


subroutine,  which  stays  in  a  DLL.  The 
programs  are  clients  of  the  DLL.  Da¬ 
tabase  programmers  have  always 
known  that  it  is  evil  to  maintain  mul¬ 
tiple  copies  of  the  same  piece  of  data. 
So  why  is  it  okay  to  have  multiple 
copies  of  the  same  piece  of  code? 

•  DLLs  don’t  just  provide  code  sharing 
on  disk  (which  is  a  capability  also 
offered  by  non-DLL  systems  such  as 
PocketSoft’s  .RTLink).  Another  benefit 
is  reduced  memory  consumption:  In 
JPI’s  implementation  of  DOS  DLLs,  as 
a  DLL  is  loaded  into  memory,  least- 
recently-used  DLLs  may  be  unloaded. 
All  of  this  takes  place  without  the  knowl¬ 
edge  of  the  programmer.  Thus,  JPI’s 
DOS  DLLs  act  as  transparent  overlays. 

•  For  JPI,  a  key  reason  to  use  DLLs  is 
that  they  facilitate  plugging  new  pro¬ 
gramming  languages  into  TS,  which 
is  a  language-independent  develop¬ 
ment  environment.  To  add  a  new  lan¬ 
guage,  simply  install  some  DLLs  and 
some  header  files.  In  addition  to  C, 
8088  assembler,  and  Modula-2,  JPI 
plans  to  add  C++  and  Ada.  Only  time 
will  tell  what  success  JPI  has  with  this 
ambitious  plan. 

•  One  consideration  is  portability  be¬ 
tween  OS/2  and  MS-DOS.  The  OS/2 
versions  of  JPI’s  compilers  use  the 
DLL  mechanism  provided  by  OS/2. 
The  much  smaller  MS-DOS  operating 
system  does  not  provide  DLLs,  but 
clever  programmers  have  found  that, 
what  MS-DOS  does  not  provide,  it 
also  does  not  prevent.  Because  the 
DOS  version  of  the  TopSpeed  com¬ 
piler  runs  in  real  mode,  JPI  could  not 
use  the  Intel  “segment  not  present” 
exception  (INT  OB),  which  aids  dy¬ 
namic  linking  in  protected  mode. 
While  OS/2  supports  DLLs,  DOS 
merely  allows  them. 


Purchasers  of  the  TopSpeed  C  Ex¬ 
tended  Edition  (which  costs  $200  more 
than  the  Standard  Edition)  get  to  use 
the  same  DOS  DLL  technology  in  their 
own  programs.  The  Extended  Edition 
includes  complete  source  code  for 
JPI’s  implementation  of  DOS  DLLs. 

In  contrast  to  the  Microsoft  tools, 
no  .DEF  file  is  required  to  make  a  DLL 
in  the  JPI  environment.  Instead,  you 
place  a  directive  such  as  “make  DOS 
DLL,”  “make  OS2  DLL,”  or  “make  WIN 
DLL”  (for  Microsoft  Windows)  in  a 
project  file.  To  use  DLLs  in  an  MS- 
DOS  program,  you  use  the  directive 
“make  DynaEXE.” 

Analogous  to  the  LIBPATH  state¬ 
ment  in  an  OS/2  CONFIG.SYS  file, 
when  using  JPI  DLLs  under  MS-DOS, 
you  need  to  set  a  LIBPATH  DOS  envi¬ 
ronment  variable. 

JPI  appears  to  have  given  far  greater 
thought  than  Microsoft  to  issues  of  C 
language  support  for  dynamic  link¬ 
ing  and  multi-threaded  programming. 
For  example,  the  JPI  license  agree¬ 
ment  contains  a  well  thought-out  state¬ 
ment  regarding  distribution  of  DLLs. 
Similarly,  each  function  in  JPI’s  Li¬ 
brary  Reference  manual  contains  a 
discussion  of  “Multi-thread  considera¬ 
tions."  This  is  connected  with  dynamic 
linking,  because  all  DLLs,  and  all  pro¬ 
grams  that  call  DLLs,  must  use  JPI’s 
“MThread”  model. 

It  was  said  earlier  that  JPI’s  DOS 
DLLs  are  like  transparent  overlays. 
When  a  feature  is  said  to  be  transpar¬ 
ent,  it  generally  means  that  (to  the 
programmer)  it  looks  like  the  feature 
isn’t  there.  However,  transparency  isn’t 
always  useful.  In  the  case  of  dynamic 
linking,  sometimes  the  programmer 
needs  explicit  control  over  this  pro¬ 
cess  (see  my  article  “Linking  While 
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The  other  new  record  is  the  FIXUP. 
These  records  are  used  to  put  the  ad¬ 
dresses  of  functions  and  data  into  the 
code  in  the  module.  Each  fix-up  refers 
to  an  item  in  Syms  or  FuncLst  (via 
ExtSyms).  The  fix-up  code  looks  up 
the  address  required  and  places  it  in 
the  code  at  the  location  specified. 

Two  of  the  record  types  used  in 
GBLDATA.OBJ  have  a  slightly  different 
purpose  in  the  linker.  The  first  is  the 
PUBDEF  record.  The  only  public  sym- 


the  Program  is  Running,”  DDJ ,  No¬ 
vember  1989).  Unfortunately,  JPI’s 
DOS  implementation  currently  does 
not  provide  any  way  to  dynamically 
link  under  explicit  program  control, 
in  that  there  is  no  DOS  equivalent  to 
the  OS/2  functions  DosLoadModuleC ) 
and  DosGetProcAddr(  ).  In  another 
sense,  though,  JPI’s  implementation 
of  DOS  DLLs  is  currently  not  trans¬ 
parent  enough:  You  will  notice  a  per¬ 
formance  penalty.  In  one  test,  a  pro¬ 
gram  that  called  code  in  a  DLL  took 
four  times  as  long  to  run  as  the  fatter 
“stand-alone”  version  that  didn’t  use 
DLLs.  However,  JPI  claims  this  was  a 
worst-case  example,  and  that  typical 
DLL  use  presents  only  a  10-15  per¬ 
cent  performance  penalty. 

JPI  is  not  alone  in  bringing  DLLs  to 
DOS :  Several  other  companies  are  work¬ 
ing  towards  the  same  goal.  First  and 
foremost  a  Modula-2  company,  JPI, 
like  other  Modula-2  companies  such 
as  Stony  Brook,  is  also  working  to 
ensure  that  multi-threaded  program¬ 
ming  is  portable  between  OS/2  and 
MS-DOS  (multiprocessing  is  a  funda¬ 
mental  part  of  the  Modula-2  program¬ 
ming  language).  By  making  DLLs  and 
multi-threaded  programming  available 
to  MS-DOS  C  programmers,  JPI  is  help¬ 
ing  to  bridge  the  gap  between  MS- 
DOS  and  OS/2. 

This  is  part  of  a  general  trend  to¬ 
ward  making  OS/2  features  available 
under  MS-DOS.  Protected-mode  DOS 
extenders  are  another  example  of  this 
trend:  They  provide  a  large  address 
space,  virtual  memory,  and  protected 
mode,  while  still  holding  onto  the 
venerable  MS-DOS  operating  system. 
This,  like  the  goal  of  dynamic  linking 
under  MS-DOS,  in  turn  reflects  the 
human  instinct  to  “have  your  cake 
and  eat  it  too.” 
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bols  in  these  files  should  be  function 
names.  The  PUBLIC  record  is  the  only 
place  to  get  the  offsets  of  the  functions 
in  this  module.  This  information  will 
be  copied  into  FuncLst  when  the  code 
for  the  function  is  loaded. 

The  other  record  that  is  different  is 
the  LEDATA  record.  In  these  files  the 
LEDATA  record  contains  either  initial¬ 
ized  data  or  code.  The  segment  field  is 

DLLs  move  the 
task  of  linking 
in  code  from 
the  end  of  the  compile/ 
link  step  to  when  the 
program  is  actually 
running 


used  to  tell  the  difference.  Segments 
are  referred  to  by  number  in  LEDATA 
records.  The  number  points  to  a  name 
in  the  SEGDEF  record.  Because  Micro¬ 
soft  C  always  uses  the  same  segments, 
the  numbers  don’t  change  —  so  the 
SEGDEF  record  does  not  have  to  be 
used.  LEDATA  records  for  segment  2 
are  string  literals;  segment  3,  constants; 
and  segment  1,  code. 

The  string  literals  and  constants  are 
placed  in  the  data  segment.  The  vari¬ 
ables  DataSize  and  LocalSize  are  the 
start  of  the  local  data  and  the  size  of  the 
local  data.  These  variables  can  be  used 
to  remove  the  local  data  from  memory 
when  the  function  gets  swapped  out. 

The  linker  allocates  space  for  all  of 
the  code  segment  LEDATA  records 
found.  Once  the  space  is  allocated,  the 
address  of  the  space  and  the  offset 
from  the  PUBDEF  record  are  combined 
to  make  the  address  of  the  function. 
This  information  is  then  placed  in  the 
FuncLst  table  for  use  by  that  function’s 
stub  routine. 

When  there  are  no  more  records,  the 
linker  closes  the  object  file  and  up¬ 
dates  the  DataSize  pointer.  The  linker 
returns  control  to  the  stub  routine.  The 
stub  routine  jumps  to  the  function.  It 
jumps  instead  of  calling  the  function  so 
that  the  stack  will  not  contain  an  extra 
return  address.  In  a  fully  functioning 
DLL  system  the  stub  routine  would  pop 
the  return  address  off  the  stack  and 
then  call  the  function.  When  the  func¬ 
tion  returned,  the  stub  routine  could 
adjust  any  flags  required  and  return  to 
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the  address  it  popped  off  the  stack. 

Summary 

DLLs  provide  an  easy-to-use,  flexible 
system  for  running  large  programs  in 
small  memory  spaces.  If  history  is  any 
guide,  then  there  will  always  be  a  need 
for  this  kind  of  technique.  The  implemen¬ 
tation  of  a  DLL  system  is  not  very  com¬ 
plex.  You  do  not  need  to  have  a  so¬ 
phisticated  operating  system  to  imple¬ 
ment  one. 

The  program  presented  here  does 
the  hard  part  —  linking  the  functions. 
To  make  it  a  complete  DLL  system  you 
need  a  memory  management  system 
that  keeps  track  of  which  functions  are 
active  and  which  can  be  removed  from 
memory. 

The  program  assumes  that  everything 
is  correct.  It  will  crash  if  there  are  unde¬ 
fined  symbols  or  missing  object  files. 
This  could  be  corrected  with  a  prepro¬ 
cessor  that  verifies  that  all  of  the  pieces 
are  correct.  This  preprocessor  could 
also  put  the  object  files  in  a  single  file 
for  easier  control. 

Using  DLLs  can  change  the  way  you 
look  at  programming  problems.  If  the 
modules  are  designed  well,  the  same 
module  can  be  used  by  many  programs. 
Changing  the  module  changes  all  of  the 
programs  without  having  to  relink  ev¬ 
ery  program.  Users  can  customize  their 
software  in  their  own  favorite  language 
without  having  access  to  proprietary 
portions  of  the  main  program. 

Try  some  experiments  with  DLLs. 
You  will  find  your  own  interesting  uses 
for  them,  and  may  well  eliminate  com¬ 
plaints  about  how  large  your  programs 
have  grown. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  104.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  2. 


Dr.  Dobb’s  Journal,  May  1990 

410 


Getting  a  Handle 
on  Virtual  Memory 

Virtual  memory  management  should  be  supported 
by  the  compiler 


Walter  Bright 


Programmers  are  well  aware  that 
there  are  serious  memory  limi¬ 
tations  when  programming  un¬ 
der  MS-DOS  on  the  PC.  These 
problems  are  variously  called 
“ram  cram,”  “the  640K  barrier,”  “brain¬ 
damaged  8086”  —  and  occasionally 
even  more  colorful  terms.  There  are 
several  different  strategies  for  dealing 
with  this  memory  limitation  problem, 
including  the  implementation  of  virtual 
memory  managers. 

Most  existing  software-based  virtual 
memory  managers  are  clumsy  to  use: 
They’re  prone  to  obscure,  and  severe 
bugs  that  can  make  regular  pointers  in 
C  look  simple.  Furthermore,  the 
conventions  of  these  packages  had  to 
be  rigorously  adhered  to.  Even  if  the 
program  using  a  virtual  memory  man¬ 
ager  finally  got  debugged,  the  results 
were  inefficient  and  the  syntax  was 
aesthetically  ugly.  Ugly  syntax  is  a  sure 
sign  of  a  poor  solution. 

A  better  solution  to  virtual  memory 
is  to  have  the  compiler  directly  support 
it.  A  C  or  C++  compiler  could  support 
a  new  pointer  type  called  a  “handle.” 
The  syntax  for  accessing  memory  refer¬ 
enced  by  the  handle  would  then  be 
taken  care  of  by  the  compiler.  This 
article  describes  the  implementation  of 
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handles  for  expanded  memory  under 
MS-DOS  using  Zortech  C/C++. 

Handle  Pointers 

The  handle  refers  to  dynamically  allo¬ 
cated  data,  serving  the  same  general 
purpose  as  a  regular  pointer.  The  dif¬ 
ference  is  that  while  data  pointed  to 
by  a  regular  pointer  is  allocated  on  the 
heap,  the  data  pointed  to  by  a  handle 
can  reside  in  expanded  memory,  ex¬ 
tended  memory,  or  a  disk  sector. 

To  actually  refer  to  the  data,  the  han¬ 
dle  must  be  converted  into  a  pointer 
by  a  function.  The  function  extracts  a 
logical  page  number  and  an  offset  from 
the  handle;  the  logical  page  is  then 


swapped  into  a  physical  page,  and  the 
offset  is  added  to  the  physical  page 
address.  The  result  is  returned  as  a 
pointer.  This  process  simulates  virtual 
memory  swapping  in  software. 

For  handles  to  be  useful,  they  must 
adhere  to  the  following  criteria: 

•  Handles  must  be  easy  and  natural  to 
use. 

•  The  compiler  must  do  as  much  of 
the  work  as  possible. 

•  Handles  should  be  implemented  as 
a  special  pointer  type. 

®  Porting  programs  using  handles  to 
computers  that  directly  support  vir¬ 
tual  memory  must  be  easy. 
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(continued  from  page  40) 

•  The  source  code,  when  ported  to  a 
virtual  memory  machine,  must  run 
as  efficiently  as  if  it  had  been  written 
with  conventional  pointers. 

•  There  should  be  no  special  func¬ 
tions  to  call  to  access  a  handle. 

•  The  initialization  and  termination  must 
be  handled  automatically. 

•  The  behavior  of  handles  must  be 
adjustable  via  library  routines. 

•  Handles  should  be  upwardly  com¬ 
patible  with  C++.  (Because  C++  is 
the  wave  of  the  future,  adding  an 
extension  that  will  be  ugly  to  work 
into  C++  would  be  a  major  impedi¬ 
ment.) 
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•  The  handle  must  be  a  compatible 

extension  to  ANSI  C. 

How  will  handles  look  in  source  form? 
With  PC  C  compilers,  it  is  already  com¬ 
mon  to  support  multiple  pointer  types 
with  the  syntax  shown  in  Figure  1 . 

Supporting  handles  in  the  same  style, 
then,  suggests  the  following  syntax: 

long  _handle  *h;  /*  h  is  a  handle 

to  a  long  V 

The  keyword  _handle  was  chosen 
because  it  is  compatible  with  name 
space  rules  for  extensions  to  ANSI  C. 
The  underscore  convention  is  used  be¬ 
cause,  as  it  turns  out,  the  identifier  han¬ 


dle  is  used  by  a  lot  of  existing  code. 
Finally,  the  keyword  virtual  would  con¬ 
flict  with  C++  use  of  that  keyword. 

Implementation 

A  handle  is  a  32-bit  type.  The  high  16 
bits  refer  to  the  page,  in  a  manner 
defined  by  the  library  implementation. 
The  low  1 6-bits  form  the  offset  into 
that  page.  Obviously,  this  restricts  the 
page  size  to  less  than  64K  in  length. 
Handles  are  unique;  no  two  handles 
can  refer  to  the  same  location  in  handle 
space. 

Pointer  arithmetic  with  handles  fol- 

The  handle  refers  to 
dynamically  allocated 
data,  serving  the  same 
general  purpose  as  a 
regular  pointer 


lows  the  same  rules  and  behaviors  as 
does  far  pointer  arithmetic  (that  is,  only 
the  16-bit  offset  is  manipulated).  Com¬ 
parisons  are  also  handled  the  same 
way  as  for  far  pointers,  that  is,  for  <  <= 
>=  and  >  the  comparison  is  done  for 
the  16-bit  offset  only.  For  =  =  and  !=, 
comparison  involves  the  full  32-bit 
value. 

The  high  16  bits  of  a  handle  refer  to 
the  page  where  the  data  is  stored.  Be¬ 
cause  it’s  desirable  to  avoid  a  perfor¬ 
mance  penalty  if  expanded  memory  is 
absent,  the  format  of  the  page  refer¬ 
ence  is  a  bit  tricky.  If  expanded  mem¬ 
ory  is  not  present,  handles  will  point 
into  real  memory.  The  best  way  to  do 
that  is  with  a  far  pointer,  the  handle 
format  must  be  able  to  distinguish  a 
handle  from  a  regular  far  pointer. 

The  8086  has  a  20-bit  address  space, 
of  which  the  high  16  bits  form  the 
segment.  All  possible  16-bit  segment 
values  are  valid  segment  values,  so  there 
isn’t  a  simple  way  to  distinguish  a  han¬ 
dle  from  a  far  pointer.  On  the  PC,  the 
ROM  BIOS  occupies  the  high  end  of 
the  address  space.  Programs  almost 
never  access  that  part  of  the  address 
space  (and  if  they  do,  they  can  use  a 
regular  far  pointer).  Valid  handle  val¬ 
ues  are  only  manipulated  by  library 
functions,  and  are  only  created  for  dy¬ 
namically  allocated  data. 

Segment  values  from  OxFEOO  to 
OxFFFF  can  therefore  be  defined  as 
handles.  (This  is  controlled  and  is  adjust¬ 
able  by  the  library  portion  of  the  han- 
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die  support.)  This  yields  256  pages. 
Because  this  is  the  number  of  pages 
that  will  be  allocated  in  expanded  mem¬ 
ory,  and  each  expanded  memory  page 
has  16K  bytes  in  it,  256  pages  make  for 
a  total  of  4  Mbytes  of  handle  memory 
space.  This  ought  to  be  sufficient  space 
for  most  applications,  and  you  can  ex¬ 
tend  the  range  of  handles  to  more  than 
OxFEOO  to  OxFFFF. 

It’s  the  library  implementation’s  job 
to  distinguish  a  handle  from  a  far 
pointer.  The  segment  portion  is  com¬ 
pared  against  OxFEOO.  If  the  16-bit  seg¬ 
ment  is  less  than  OxFEOO,  the  handle  is 
a  regular  far  pointer.  Otherwise  the 
upper  16  bits  of  the  handle  refer  to 
logical  page  number  (segment  -OxFEOO). 

Conversions  from  handles  to  far  point¬ 
ers  occur  whenever  a  handle  pointer 
is  dereferenced  or  when  a  handle  is 
cast  to  a  far  pointer.  The  conversion 
process  is  done  by  a  library  routine 
that  swaps  the  logical  page  into  the 
address  space  and  returns  a  far  pointer 
into  it.  Figure  2  shows  examples  that 
do  handle  conversions  to  far  pointers. 
Conversions  from  far  pointers  to  han¬ 
dles  are  just  a  type  of  ‘point,’  that  is, 
no  change  in  the  bit  pattern. 

The  optimizer  is  aware  that  handles 
are  a  special  type.  Its  main  job  is  to 
determine  when  a  new  handle  derefer¬ 
ence  is  necessary  and  when  a  previous 
conversion  can  be  used  instead.  Con¬ 
sider  the  example  in  Figure  3-  Clearly, 
b  only  needs  to  be  converted  to  a  far 
pointer  once.  It  converts  the  code  to 
that  shown  in  the  second  portion  of 
Figure  3- 

The  result  of  a  conversion  in  Figure 
3  cannot  be  used  if: 

1 .  The  value  of  the  handle  might  have 
changed. 

2.  A  handle  dereference  was  done  on 
another  handle  (thus  possibly  over¬ 
writing  the  previous  page  with  an¬ 
other). 

3.  A  function  was  called  (because  that 
function  may  convert  other  handles, 
resulting  in  case  2). 

Because  handle  memory  is  larger  than 
physical  memory,  pages  from  handle 
space  are  swapped  into  buffers  in  physi¬ 
cal  space.  Each  handle  conversion  may 
result  in  a  new  page  from  handle  space 
overwriting  a  previous  page,  invalidat¬ 
ing  any  pointers  into  that  page.  This 
explains  the  reasoning  behind  assum¬ 
ing  that  any  handle  conversion  invali¬ 
dates  any  previous  conversions. 

Of  course,  you  can  always  convert  a 
handle  to  a  pointer  yourself.  If  you 
know  that  a  function  call  does  not  con¬ 
vert  any  handles,  then  the  conversion 
is  still  valid  after  the  function  call.  Also, 


if  the  library  implementation  of  handle 
conversions  uses  more  than  one  physi¬ 
cal  page  (the  expanded  memory  ver¬ 
sion  described  shortly  uses  four),  you 
can  rely  on  at  least  that  many  conver¬ 
sions  being  valid  simultaneously. 

Handles  and  Expanded  Memory 

Let’s  look  at  how  Zortech  C  and  C++ 
implement  handles.  It  turns  out  that 


Figure  1:  Typical  pointer  types  used  in 


int_handle  *h; 
struct  A  handle  *h2; 
int  far  *f; 
int  i; 

extern  void  func(int  far  *pi); 

f  =  h; 

*h  =  i; 
h[3]  =  *f; 
i  =  *(h  +  6); 
h2->b  =  i; 
func(h); 
h  =  (int  far  *)  h; 

Figure  2:  Converting  pointers  from 
handle  to  far 


expanded  memory  is  particularly  well 
suited  for  implementing  handles.  It  is 
fast;  swapping  a  logical  page  into  a 
physical  page  usually  requires  a  simple 
write  into  an  I/O  register.  Expanded 
memory  can  be  efficiently  emulated 
on  386  machines  by  using  the  memory 
mapping  features  of  the  CPU.  (QEM- 
386  from  QuarterDeck  is  an  example 
of  this  type  of  utility.)  There  are  even 


PC  implementations  of  C 


struct  { int  a,b; }  Jiandle  *h; 
h->a  =  1 ; 
h->b  =  2; 

/*  Converted  code  7 

struct  { int  a,b; }  handle  *h,  far  *p; 

P  =  h; 

p->=a  =  1 ; 
p->=b  =  2; 


Figure  3:  Example  showing  that  the 
optimizer  is  handle  aware 


void  *p;  /*  pointer  type  is  default  for  the  memory  model  7 

char  far  *pc;  /*  far  (segment  and  offset  pair)  pointer  7 

int  near  *p;  /*  near  (offset  only,  segment  is  assumed)  7 
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emulators  that  fake  expanded  memory 
by  using  extended  memory  (memory 
above  1  Mbyte)  or  even  a  hard  disk.  A 
final  impetus  for  using  expanded  mem¬ 
ory  is  that  it  is  part  of  DOS  4.0. 

The  expanded  memory  concept  is 
that  one  or  more  logical  pages  of  bank- 
switched  memory  are  mapped  into  real 
memory  (physical  pages)  as  needed. 
This  corresponds  directly  to  the  handle 
concept  of  a  large  amount  of  memory 
(handle  space)  of  which  a  subset  is 
mapped  into  physical  memory  buffers. 
The  mapping  of  a  logical  page  to  a 
physical  page  occurs  when  a  handle  is 
dereferenced. 

Expanded  memory  makes  it  possi¬ 
ble  to  have  two  physical  pages  actually 
map  onto  the  same  logical  page.  In 
other  words,  expanded  memory  allows 
two  different  addresses  to  refer  to  the 
same  memory  location!  This  implemen¬ 
tation  of  handles  carefully  avoids  de¬ 
pending  on  this  “feature,”  as  that  capa¬ 
bility  is  impossible  to  emulate  with  disk 
or  extended  memory  implementations 
of  expanded  memory. 

Initialization  is  handled  automatically 
by  the  C  run-time  startup,  so  no  extra 
work  is  necessary.  Termination  is  a  bit 
trickier.  When  a  program  terminates  and 
returns  to  DOS,  DOS  automatically  frees 
up  any  memory  used  by  the  program 
and  makes  it  available  for  the  next  one. 
Unfortunately,  this  does  not  happen 
with  expanded  memory.  A  program 
must  always  explicitly  free  its  expanded 
memory  pages  or  they  will  be  unavail¬ 
able  for  use  by  other  programs  until 
the  machine  is  rebooted.  All  exit  paths 
from  the  program  must  be  covered. 
Even  Ctrl-break  must  be  intercepted. 

Storage  allocation  in  handle  space 
is  done  by  handle_malloc( ),  han- 
dle_realloc( ),  and  related  functions. 
Each  16K  page  is  converted  into  a  heap, 
with  the  usual  free  list  data  structure. 
There  is  a  special  data  stmcture  in  page 
0  that  contains  the  size  of  the  maxi¬ 
mum  available  free  block  in  each  page, 
so  the  storage  allocator  can  directly 
swap  in  the  page  it  needs  to  allocate 
from,  instead  of  sequentially  swapping 
in  each  page  until  the  allocation  suc¬ 
ceeds.  This  is  of  critical  importance  if 
a  disk-swapping  expanded  memory  emu¬ 
lator  is  used!  If  there  is  insufficient  free 
expanded  memory  space  to  satisfy  an 
allocation  request,  or  if  the  size  of  a 
request  exceeds  16K,  the  routines  fall 
back  to  allocating  from  conventional 
DOS  memory. 

The  Expanded  Memory  3-2  subset 
of  EM  4.0  is  used  to  provide  maximum 
portability;  in  fact,  the  more  exotic  fea¬ 
tures  of  4.0  aren’t  needed  for  handle 
support.  It’s  possible  to  use  expanded 
memory  in  addition  to  using  handles, 


though  the  two  uses  should  be  kept 
independent  to  avoid  conflicts. 

When  to  Use  Handles 

The  overhead  of  dereferencing  han¬ 
dles  is  much  higher  than  the  overhead 
of  dereferencing  pointers,  both  in  pro¬ 
gram  size  and  speed.  Therefore,  the 
best  candidates  for  handles  are  those 
data  structures  that  are  infrequently  ac¬ 
cessed  both  in  the  number  of  times  the 
dereference  statically  occurs  in  the  pro¬ 
gram  and  in  the  number  of  times  the 
dereferences  are  executed. 

Expanded  memory 
makes  it  possible  to  have 
two  physical  pages 
actually  map  onto  the 
same  logical  page 


Handles  give  a  sharp  increase  in  the 
amount  of  memory  available.  The 
proper  data  structure  for  something  that 
will  reside  in  handle  space  is  one  that 
favors  speed  over  memory  compact¬ 
ness.  Locality  of  data  is  also  important 
(locality  means  that  related  data  should 
be  clustered  into  the  same  page,  in¬ 
creasing  the  likelihood  that  the  desired 
page  is  already  swapped  in).  For  ex¬ 
ample,  a  bubble  sort  across  data  in 
handle  space  is  to  be  avoided.  If  your 
expanded  memory  implementation 
swaps  to  disk,  the  swap  file  on  disk 
may  get  read  and  written  in  its  entirety 
several  times  during  such  a  sort! 

If  database-wide  searches  are  neces¬ 
sary,  try  putting  the  access  structure  in 
conventional  memory  and  put  the  leaves 
in  handles.  This  makes  the  lookup  fast 
and  efficient,  and  the  end  data  is  paged 
in  only  when  it  is  needed. 

Listing  One  (page  110)  shows  a  ver¬ 
sion  of  the  classic  Unix  wc  (word  count) 
program,  converted  from  using  the  stan¬ 
dard  pointer  and  dynamic  storage  allo¬ 
cation  to  using  handles  and  handle 
storage  allocation.  The  primary  advan¬ 
tage  of  using  handles  in  a  program 
such  as  wc  is  that  they  increase  the 
program's  capacity  without  a  signifi¬ 
cant  performance  penalty.  The  handle 
version  of  wc  is  just  as  fast  as  the  origi¬ 
nal  version,  which  used  regular  point¬ 
ers.  Files  with  several  megabytes  of 
text  can  be  processed  by  the  handle 
version  (assuming  that  expanded  mem¬ 
ory  is  available). 

Portability  isachieved  simply:  Vne -han¬ 


dle  keyword  is  #defined  to  nothing,  so 
all  handles  revert  to  being  regular  point¬ 
ers.  Second,  the  handle  storage  alloca¬ 
tion  routines  can  be  #defined  to  be  the 
standard  malloc,  free,  and  so  on,  rou¬ 
tines.  Thus,  handle-specific  code  can 
quickly  be  made  portable  to  other  com¬ 
pilers  and  environments.  The  Zortech 
compiler  provides  a  simple  mechanism 
for  eliminating  handles  from  a  program: 
Simply  add  the  following  line  to  any 
program  before  it  ^includes  handle. h: 
#define  NO_HANDLE  1 

Debugging 

Debugging  C  applications  that  use  a  lot 
of  dynamically  allocated  memory  is  no¬ 
toriously  difficult.  Experienced  C  pro¬ 
grammers  have  reluctantly  learned  to 
live  with  this.  Unfortunately,  handle- 
based  applications  have  all  the  liabili¬ 
ties  of  pointers,  plus  a  few  more.  The 
worst  problem  is  when  a  stray  pointer 
places  unwanted  data  into  a  page  that 
has  been  swapped  out.  Such  a  bug  will 
only  rarely  exhibit  symptoms,  and  there¬ 
fore  can  be  difficult  to  pin  down.  An¬ 
other  problem  occurs  when  more  than 
four  dereferenced  handles  are  used  si¬ 
multaneously.  The  bug  will  only  show 
up  if  they  happen  to  all  fall  on  different 
logical  pages.  Here  are  some  techniques 
you  can  use  to  deal  with  these  problems: 

•  Write  and  debug  the  program  with 
handles  disabled  (^defined  to  look 
like  ordinary  far  pointers).  If  handles 
are  then  enabled  and  the  program 
fails,  you  can  confine  your  search  for 
the  bug  to  the  use  of  handle  pointers. 

•  Use  object-oriented  style  for  data  struc¬ 
tures  that  use  handles.  This  will  con¬ 
fine  the  actual  code  that  dereferences 
the  handles  to  a  few  places,  hence  a 
smaller  place  to  look  for  bugs. 

•  Carefully  look  for  simultaneous  ac¬ 
cesses  through  handles.  Satisfy  your¬ 
self  by  doing  “gedanken”  experiments 
(thought  experiments)  that  it  will  never 
be  greater  than  four.  Test  suites  are 
unreliable  at  flushing  out  these  types 
of  bugs;  the  code  simply  has  to  be 
written  correctly. 

•  Look  for  function  calls  that  could  dere¬ 
ference  handles.  As  always,  program 
defensively.  Assume  that  all  function 
calls  invalidate  previous  handle  dere¬ 
ferences. 

When  converting  code  from  using 
malloc  to  handle_malloc ,  watch  out 
for  converting  from:  p  =  (char  *)  mal- 
loc(n);  to:  h  =  (char  *)  handle  _mal- 
loc(n)\  instead  of  the  correct:  h  =  (char 
handle  *)  handle_malloc(n );  The  cast 
to  ( char  *)  dereferenced  the  handle 
and  stored  a  far  pointer  into  h  instead 
of  the  handle! 
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(continued  from  page  44) 

Other  Uses 

Handle  space  could  be  a  disk  file.  The 
disk  file  is  divided  up  into  blocks  of 
equal  size  (16K  seems  a  good  num¬ 
ber).  These  are  paged  in  and  out  of  a 
small  number  of  physical  buffers  0=2). 
An  advantage  of  a  disk  file  implemen¬ 
tation  is  that  the  limit  on  the  size  of 
handle  space  is  equal  to  the  size  of  the 
disk.  Also,  the  data  can  persist  from 
one  invocation  of  the  program  to  an¬ 
other.  Disk  paging  would,  however, 
be  rather  slow. 

Extended  memory  can  be  used  for 
handles  space.  Extended  memory  is 
the  memory  above  1  Mbyte  on  286-  and 
386-based  computers.  It  is  only  acces¬ 
sible  via  protected  mode  (DOS  runs  in 
real  mode).  To  use  extended  memory, 
the  CPU  must  switch  into  protected 
mode,  copy  the  extended  memory 
pages  to  and  from  real-mode  buffers, 
and  switch  back  to  real  mode.  It’s  not 
as  fast  as  expanded  memory  hardware, 
but  it’s  much  faster  than  paging  to  disk. 

The  minimum  number  of  simultane¬ 
ous  accesses  is  determined  by  the  num¬ 
ber  of  physical  pages  available  simulta¬ 
neously.  With  expanded  memory,  this 
is  four.  It  is  recommended  that  at  least 
two  be  available,  otherwise  functions 


such  as  memcpyC )  could  not  be  used 
to  directly  copy  from  one  handle  to 
another;  instead,  a  temporary  buffer  in 
real  memory  would  have  to  be  used. 
Programs  written  for  Microsoft  Win¬ 
dows  use  a  handle-like  storage  alloca¬ 
tion  scheme.  The  library  implementa¬ 
tion  of  the  handles  could  be  written  as 
a  shell  around  the  Windows  functions, 
thus  easing  one  of  the  more  frustrating 
things  about  programming  for  Windows. 

Handles  in  VM  Operating  Systems 

Handle  pointers  are  useful  for  other 
applications  besides  extending  the  mem¬ 
ory  space  available.  Under  virtual  mem¬ 
ory  operating  systems,  such  as  Unix  or 
OS/2,  there  is  no  need  for  more  mem¬ 
ory.  There  is  also  no  hardware  support 
for  bank-switched  memory  like  ex¬ 
panded  memory. 

Alas,  one  fundamental  problem  al¬ 
ways  remains.  There  is  usually  a  differ¬ 
ence  in  how  a  data  structure  is  stored 
in  memory  and  how  it  is  stored  on 
disk.  Pieces  of  a  data  structure  in  mem¬ 
ory  are  typically  connected  to  one  an¬ 
other  by  pointers.  Memory  pointers  writ¬ 
ten  to  disk  have  no  meaning  when 
read  back  off  a  disk,  so  the  data  struc¬ 
ture  must  be  translated  when  written 
to  disk.  The  memory  pointers  are  con¬ 


verted  into  symbolic  references  when 
written  out;  when  the  data  structure  is 
read  back  from  the  disk,  the  symbolic 
references  are  converted  back  to  real 
pointers. 

Handle  pointers  can  solve  this  prob¬ 
lem.  Recall  that  a  handle  consists  of  a 
logical  page  number  and  an  offset  into 
that  page.  The  logical  pages  can  simply 
be  represented  by  disk  blocks.  The 
library  implementation  of  handle  point¬ 
ers  would  be  rewritten  to  read  and 
write  pages  from  a  specified  disk  file 
rather  than  bank-switching  expanded 
memory.  The  in-memory  data  structure 
is  exactly  the  same  as  the  disk  file  struc¬ 
ture.  Writing  out  the  data  file  becomes 
a  call  to  a  handle  function  that  flushes 
any  in-memory  pages  to  disk.  Reading 
in  the  data  structure  becomes  the  sim¬ 
ple  task  specifying  which  file  to  use! 
Dereferencing  a  handle  will  cause  its 
page  to  be  read  in  from  disk.  As  an 
additional  benefit,  disk  I/O  will  be  mini¬ 
mized.  Two  major  applications  that 
might  benefit  from  this  approach  are 
databases  and  applications  that  consist 
of  multiple  programs  that  share  data 
via  files. 

Wrapping  Up 

Handle  pointers  are  an  elegant  solu¬ 
tion  to  an  entire  class  of  programming 
problems.  The  first  (and  what  tne 
Zortech  implementation  initially  ad¬ 
dresses)  is  extending  the  address  space 
available.  The  second  is  in  simplifying 
and  speeding  up  writing  a  data  struc¬ 
ture  to  disk  and  reading  it  back  again. 
The  third  is  in  defining  a  file  format  by 
which  data  can  be  easily  read  and  writ¬ 
ten  to  files  accessed  by  multiple  pro¬ 
grams. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  Z/D/Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listing  begins  on  page  110.) 


Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  3. 
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Object  Swapping 

Familiar  memory  management  techniques 
don’t  always  apply  to  OOPS 


Jan  Bottorff  and  Jim  Bolland 


There  have  been  several  techno¬ 
logical  stages  in  the  develop¬ 
ment  of  object  memory  man¬ 
agement.  These  have  consisted 
of  the  simple  memory  resident 
strategy,  the  Xerox  PARC  OOZE  and 
LOOM  systems,  and  operating  system- 
based  virtual  memory. 

The  oldest  answer  to  the  memory 
problem  was  to  keep  expanding  mem¬ 
ory  to  fit  increasingly  sophisticated  use. 
Although  fast  and  simple  —  and  suit¬ 
able  to  some  situations  —  this  approach 
tends  to  be  expensive.  We  have  all 
proved  to  ourselves  the  truth  of  the  old 
programmer’s  axiom  that  the  complex¬ 
ity  of  software  grows  to  fill  all  available 
memory.  Obviously,  unlimited  mem¬ 
ory  expansion  became  an  unfeasible 
solution  to  the  needs  of  users. 

In  the  mid-seventies,  a  team  of  de¬ 
velopers  at  the  Xerox  Palo  Alto  Re¬ 
search  Center  implemented  the  first  true 
object-swapping  system  for  Smalltalk- 
76  called  OOZE.1  Later  they  imple¬ 
mented  a  second  system  called  LOOM.2 
The  radical  innovation  found  in  both 
of  these  systems  was  that  they  swapped 
small  pieces  of  memory,  namely  ob¬ 
jects.  LOOM  contained  an  advancement 
over  OOZE:  In  addition  to  swapping 
objects,  the  virtual  address  space  itself 


Jan  is  a  system  software  developer  spe¬ 
cializing  in  object-oriented  languages 
and  graphical  user  interfaces.  He  has 
been  writing  software  and  has  been 
consulting  for  more  than  15  years.  He 
can  be  reached  on  CompuServe  at 
74775,546.  Jim  is  a  software  engineer 
specializing  in  operating  system  inter¬ 
nals  and  computer  languages.  He  can 
be  reached  at  The  Whitewater  Group, 
600  Davis  St.,  Evanston,  IL  60201. 


was  virtualized. 

As  time  went  on,  machines  with  vir¬ 
tual  addressing  and  larger  and  larger 
physical  memories  became  common. 
Programs  tended  to  use  the  operating 
system’s  paging  instead  of  doing  their 
own  memory  management.  An  object- 
oriented  system  in  a  paging  environ¬ 
ment  causes  a  lot  of  paging  activity 
because  object  access  is  very  random. 
A  partial  solution  was  to  keep  frequently 
used  objects  together  in  a  small  set  of 
pages.  This  made  object  access  less 
random,  thus  reducing  paging  activity. 
The  one  drawback  on  some  systems  is 
that  this  requires  hardware  that  sup¬ 
ports  paging. 

Many  newer  environments  have  some 
means  of  providing  virtual  memory: 
OS/2  1.2  swaps  segments  of  up  to  64K- 
bytes  while  Unix  and  OS/2  2.0  provide 


paging.  These  virtual  memory  systems 
are  an  improvement  over  simpler  sys¬ 
tems,  but  they  don’t  address  some  of 
the  unique  problems  of  an  object-ori¬ 
ented  environment. 

If  you  analyze  the  access  patterns  of 
a  large  system  written  for  object-ori¬ 
ented  environments  such  as  Actor  or 
Smalltalk,  you  find  the  memory  ad¬ 
dress  space  is  accessed  in  a  much  more 
random  pattern  than  in  a  C  program. 
You  also  find  that  in  each  subsystem 
(for  example,  a  specific  type  of  win¬ 
dow  interaction  or  the  processing  of 
an  algorithm)  the  number  of  objects 
that  must  be  accessed  is  fairly  small, 
typically  a  few  hundred.  If  you  com¬ 
bine  both  of  these  characteristics  — 
random  distribution  of  objects  through 
the  address  space  and  the  small  work¬ 
ing  set  needed  for  each  subsystem  — 
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(continued  from  page  48) 

the  problems  of  conventional  virtual 

memory  systems  become  apparent. 

Consider  the  following  comparison 
among  a  segment  swapping  system,  a 
paging  system,  and  an  object  swap¬ 
ping  system  such  as  that  in  Actor,  which 
is  a  pure  object-oriented  language  and 
program  development  tool  for  the  Mi¬ 
crosoft  Windows  environment.  Assume 
in  this  example,  that  the  total  universe 
of  objects  is  spread  over  360K  of  ad¬ 
dress  space.  Also  assume  there  are  10K 
objects  with  an  average  size  of  36  bytes 
in  the  complete  system.  Using  10  per¬ 
cent  of  the  objects  as  the  working  set 
only  consumes  36K-bytes.  This  large 
working  set  would  actually  be  the  com¬ 
bined  working  set  of  several  subsys¬ 
tems.  These  represent  typical  values. 

In  a  segment  swapping  system  with 
64K-byte  segments,  there  will  be  about 
1820  objects  per  segment.  Due  to  the 
randomness  factor,  each  segment  would 
only  hold  about  182  objects  or  6.5K- 
bytes  for  the  working  set. 

In  a  paging  system,  there  will  be 
about  114  objects  per  page.  Per  page, 
about  11  objects  or  396  bytes  will  actu¬ 
ally  be  used  for  the  working  set. 

In  both  segment  swapping  systems 


and  paging  systems,  the  entire  360K 
address  space  should  be  memory  resi¬ 
dent.  Otherwise  complete  access  to  the 
working  set  will  cause  the  system  to 
swap  or  page  constantly. 

Virtual  memory  systems 
are  an  improvement 
over  simpler  systems,  but 
they  don’t  address  some 
of  the  unique  problems 
of  an  object-oriented 
environment 


A  better  solution  is  to  swap  much 
smaller  units  of  memory,  specifically, 
individual  objects.  In  Actor,  the  work¬ 
ing  set  of  1000  objects  would  consume 
36K-bytes.  An  additional  8K  would  be 
used  by  the  system  to  maintain  swap¬ 
ping  information.  The  total  memory 


required  to  hold  our  working  set  is 
only  44K-bytes.  This  represents  only 
13  percent  of  the  memory  required  for 
a  segment  swapping  or  paging  system. 
Once  the  working  set  is  loaded,  execu¬ 
tion  performance  is  nearly  the  same  as 
other  swapping  alternatives. 

Object  Swapping 

In  terms  of  memory  management,  Actor 
objects  are  broken  up  into  two  major 
categories:  static  and  dynamic.  Dynamic 
objects  are  created  by  the  executing  pro¬ 
gram  and  managed  by  an  internal  gar¬ 
bage  collection  system  in  the  Actor  ker¬ 
nel.3  They  are  typically  temporary  re¬ 
sults  used  only  while  the  program  is 
executing.  Static  objects  are  created  and 
deleted  at  program  development  time 
using  the  development  system.  Most 
static  objects  will  be  compiled  program 
code  and  constants.  Static  objects  typi¬ 
cally  outnumber  dynamic  ones  by  a 
ratio  of  5  to  1 .  Their  required  memory 
also  follows  the  5  to  1  ratio.  For  these 
reasons,  object  swapping  was  designed 
to  handle  static  objects  only. 

Data  Structures 

Internal  Actor  data  structures  allow  static 
memory  requirements  to  be  reduced 
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(continued  from  page  50) 
by  about  87  percent.  These  data  struc¬ 
tures  can  also  be  applied  to  other  de¬ 
velopment  environments. 

Every  object,  except  for  Integers  and 
Characters,  has  an  entry  in  a  large  array 
structure  called  the  “object  table”  or 
OT  (see  Figure  1).  The  OT  entry  con¬ 
tains  the  current  address  of  the  object 
in  memory  or  on  disk  if  it  is  swapped 
out.  It  also  contains  two  flags  pertain¬ 
ing  to  the  object’s  state.  One  flag  is 
called  the  “touched  bit,”  which  indi¬ 
cates  whether  or  not  an  object  has  been 
accessed.  The  other  flag  is  called  the 
“dirty  bit,”  which  indicates  whether  or 
not  the  object  has  been  changed. 

For  objects  that  are  swapped  into 
memory,  a  header  is  placed  at  the  be¬ 
ginning  of  the  object.  This  header  con¬ 
tains  a  few  flag  bits,  the  disk  address 
where  the  object  was  swapped  in  from, 
and  an  age  field  used  for  discarding 
objects  from  memory.  The  header  also 
contains  other  information  used  in  Ac¬ 
tor,  such  as  the  object’s  size. 

A  block  of  memory  is  allocated  at 
program  initialization  time  to  hold  all 
of  the  memory  resident  static  objects. 
This  is  called  the  “swap  area.”  A  typical 
size  for  good  performance  is  around 


50K-bytes.  The  top  15  percent  of  this 
area  is  called  the  “overflow  area.”  The 
overflow  area  will  be  explained  later. 

Processes  Involved  in  Object  Swapping 

•  Static-object  creation 

•  Static-object  referencing 

•  Static-object  aging 

•  Static-object  deletion 

•  Swap-area  compaction 

Static  object  creation  occurs  when 
the  executing  program  explicitly  re¬ 
quests  it.  An  area  based  on  the  size  of 
the  new  object  is  allocated  at  the  cur¬ 


rent  allocation  pointer  (see  Figure  2). 
The  disk  address  in  the  swapping 
header  (see  Figure  3)  is  initialized  with 
a  special  signature  to  designate  that  it 
has  no  disk  address  yet.  The  age  is 
initialized  to  a  low  value.  An  OT  entry 
is  allocated  from  a  free  list,  and  initial¬ 
ized  with  the  object’s  memory  address. 
New  objects  are  marked  as  dirty  in 
their  OT  entry.  The  object  is  now  ready 
for  use  by  the  system. 

Objects  are  accessed  via  their  object 
pointer  (OP)  value.  The  OP  is  simply 
the  offset  into  the  OT.  Object  access  is 
shown  in  Example  1.  Addressing  turns 
an  OP  into  a  physical  address  for  the 


Object 

Pointer 

(OP) 


OT  entry 


Memory  or  disk  address 

Other  flags 

/ 


Dirty  bit  - 

Touched  bit 


I 


Object  table  (OT) 


Figure  1:  The  object  table 
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object.  This  process  swaps  the  object 
in  from  disk  if  necessary.  An  important 
property  of  addressing  an  object  is  that 
no  other  object’s  physical  address  may 
be  changed  in  the  process.  This  stabil¬ 
ity  of  addresses  is  required  when  the 
system  needs  to  address  more  than  one 
object  at  a  time.  Moving  one  object 
would  invalidate  the  other  object’s  ad¬ 
dress.  If  swapping  in  the  addressed 
object  requires  more  memory  than  is 
available  in  the  swap  area,  a  fatal  error 
would  occur.  However,  Actor  is  inter¬ 
nally  tuned  for  this  not  to  happen  un¬ 
der  normal  conditions.  If  an  object  is 
already  in  memory,  its  touched  bit  is 


OBJECT  SWAPPING 


just  set  in  the  OT  and  its  memory  ad¬ 
dress  is  returned. 

Periodically  during  system  execution, 
one  of  two  things  will  happen:  All 
needed  objects  are  accessed  or  the  sys¬ 
tem  runs  out  of  memory  in  the  swap 
area.  Before  running  out  of  memory, 
something  must  happen  to  free  up  mem¬ 
ory.  This  is  the  job  of  the  aging  process. 

As  the  system  executes  a  routine  is 
called  periodically  that  walks  through 
a  few  object  table  entries.  When  the 
end  of  the  OT  is  reached  it  starts  over 
at  the  beginning. 

For  each  OT  entry  the  touched  bit  is 
tested.  If  the  object  was  touched  since 
the  last  pass,  the  age  field  in  the  object 


header  is  set  to  0,  indicating  the  object 
was  recently  used.  As  the  system  runs, 
accessing  objects  and  aging  them,  the 
age  fields  indicate  which  objects  were 
recently  used  and  which  were  not.  In 
this  way,  objects  can  be  discarded  on 
a  least  recently  used  (LRU)  basis. 

When  an  object  reaches  a  certain 
age  it  is  tested  for  being  changed.  The 
dirty  bit  in  the  OT  is  used  to  determine 
this.  If  the  object  is  unchanged,  the 

Except  during 
periods  of  many 
object  creations, 
objects  are  usually 
not  dirty 


swap  file  on  disk  still  contains  a  correct 
version  of  the  object.  In  this  case,  the 
OT  entry  is  updated  with  the  old  disk 
address  and  the  memory  block  is 
marked  “discarded.”  If  the  object  has 
changed,  it  is  written  back  to  its  allo¬ 
cated  location  on  disk.  The  aging  pro¬ 
cess  is  shown  in  Example  2. 

Except  during  periods  of  many  ob¬ 
ject  creations,  objects  are  usually  not 
dirty.  The  typical  ratio  is  about  500  to 
1  for  clean  to  dirty  objects.  This  means 
that  discarded  objects  rarely  cause  any 
disk  activity;  only  addresses  are  moved 
around  in  memory. 


Overflow 

Area 

Current 

Allocation 

Pointer 

Figure  2:  Swap  area 
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Disk  address 
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“Deleted” 

Mark 


Figure  3:  Object-swapping  header 
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A  special  case  occurs  when  a  newly 
created  object  is  swapped  out  for  the 
first  time.  This  is  detected  by  a  special 
invalid  disk  address.  Space  for  the  new 
object  is  allocated  at  the  end  of  the 
object  swap  file  and  the  object  is  writ¬ 
ten  out.  It  is  then  treated  like  all  the 
other  objects  in  the  system. 

If  an  object  is  accessed  again  after 
being  discarded  but  before  the  swap 
area  is  compacted,  a  new  memory  block 
is  allocated  and  the  object  is  swapped 
in.  This  does  leave  an  old,  unrefer¬ 
enced  copy  of  the  object  somewhere 
else  in  the  swap  space,  but  this  dual 
allocation  of  memory  for  a  single  ob¬ 
ject  rarely  occurs. 

Swap  Area  Compaction  is  the  means 
by  which  space  used  by  discarded  ob¬ 
jects  in  the  swap  area  is  recovered.  As 
objects  are  swapped  in,  the  current 
allocation  pointer  into  the  swap  area 
eventually  reaches  the  beginning  of  the 
overflow  area.  A  flag  is  set,  indicating 
that  swap  area  compaction  is  desired. 
At  the  moment  of  access,  the  system 
may  be  using  the  address  of  other  ob¬ 
jects,  so  compaction  does  not  occur 
immediately.  It’s  deferred  until  specific 
sync  points  are  reached.  Sync  points 
are  places  in  the  execution  of  Actor 
when  there  are  no  object  addresses  in 
use,  or  more  correctly,  the  addresses 
are  at  a  known  location.  The  system 
may  keep  executing  and  swapping  ob¬ 
jects  into  the  swap  area  before  a  sync 
point  is  reached.  This  is  why  there  is  a 
reserved  overflow  area.  All  objects 


Set  the  object's  touched  bit 
if  object  not  in  memory 
then 

Swap  object  in 
Update  OT  entry 
endif 

Get  the  object's  address 


Example  1:  Object  access 


swapped  in  after  requesting  compac¬ 
tion  but  before  reaching  a  sync  point 
must  fit  in  the  overflow  area. 

When  a  sync  point  is  reached,  exe¬ 
cution  stops  for  a  moment  while  the 
swap  area  is  compacted.  The  compac¬ 
tion  process  updates  the  physical  ad¬ 
dress  in  the  OT  of  any  static  objects 
currently  in  the  swap  area.  It  does  this 
by  first  overwriting  the  memory  ad¬ 
dress  in  the  OT  with  some  of  the  data 
in  the  object  header.  It  then  overwrites 
the  object’s  saved  data  area  with  the 
OP  of  the  object.  This  allows  an  effi¬ 
cient  sweep  through  the  swap  area  to 
move  all  valid  objects  to  the  beginning 
of  the  swap  area.  During  this  sweep  all 
object  headers  are  restored  from  infor¬ 
mation  saved  in  the  OT  entry  and  the 
OT  entry  is  updated  using  our  current 
location  in  the  swap  area  for  the  ob¬ 
ject’s  address.  Example  3  shows  pseu¬ 
docode  for  swap  area  compaction. 

The  final  process  in  object  swapping 
is  the  deletion  of  objects  from  the  swap 


for  "a  few"  OT  entries 
if  object  is  touched 
then 

Set  object's  age  to  0 
else 

if  object's  age  is  too  old 
then 

if  object  is  dirty 

then 

write  object  to  disk 
endif 

Set  object  address  in  OT  to 
disk  address 
Mark  object  memory  as 
"discarded" 
else 

Increment  object's  age 
endif 
endif 
endfor 


Example  2:  The  aging  process 
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file.  Like  object  creation,  this  is  done 
when  the  executing  program  explicitly 
requests  it.  The  equivalent  of  a  mark 
and  sweep  garbage  collection  is  done 
using  a  temporary  disk  file  to  store  any 
objects  to  be  kept.  As  this  proceeds, 
the  OT  entry  for  the  object  is  updated 
with  the  new  offset  into  the  temporary 
disk  file.  On  completion,  the  tempo¬ 
rary  disk  file  becomes  the  new  object 
swap  file,  the  swap  area  allocation 
pointer  is  reset  to  the  beginning  of  the 
swap  area,  and  the  system  starts  run¬ 
ning  again.  As  objects  are  now  accessed 
they  are  swapped  in  from  the  new  com¬ 
pacted  swap  file.  This  sweep  through 
the  swap  file  is  much  like  the  swap 
area  compaction  process  but  it  is  ap¬ 
plied  to  the  entire  swap  file. 

To  save  the  state  of  the  system,  a 
procedure  known  as  “taking  a  snap¬ 
shot”  is  used.  A  snapshot  simply  cre¬ 
ates  an  image  file  that  contains  copies 
of  the  OT,  the  swap  area,  and  the  cur¬ 
rent  swap  file.  To  start  up  the  Actor 


system,  the  snapshot  process  is  reversed: 
The  OT  and  swap  area  are  read  from 
the  image  file  into  memory  and  a  swap 
file  (which  is  a  working  copy  of  the 
swap  file  area  in  the  image  file)  is  cre¬ 
ated.  Dynamic  objects  are  also  stored  in 
the  snapshot  file  and  loaded  into  mem¬ 
ory  when  the  snapshot  file  is  restored. 

Conclusions, 

In  this  article,  we  have  shown  how  to 
implement  a  virtual  memory  system  that 
is  optimized  for  object-oriented  lan¬ 
guages.  It’s  unique  design  reduces  mem¬ 
ory  required  by  approximately  87  per¬ 
cent,  allowing  much  better  utilization 


OBJECT  SWAPPING 


of  available  memory.  Because  special 
hardware  support  is  not  required,  this 
architecture  can  run  on  many  kinds  of 
machines. 

The  performance  delivered  is  usu¬ 
ally  quite  high.  Tests  have  measured 
object  “swap  in’’  rates  as  high  as  320 
objects  per  second.  Average  perfor¬ 
mance  is  about  75  to  100  objects  per 
second.  Disk  caching  and  disk  speed 
can  affect  this  greatly. 

New  operating  environments  with 
built-in  virtual  memory  support  can  still 
benefit  from  object  swapping.  Unless 
enough  physical  memory  for  all  run¬ 
ning  programs  exists,  considerable  pag¬ 


ing  activity  may  occur. 

By  using  object  swapping,  more  com¬ 
plex  programs  can  be  run  before  per¬ 
formance  severely  degrades  from  pag¬ 
ing  activity.  A  developer  will  be  able 
to  produce  an  application  that  runs 
efficiently  on  a  larger  base  of  machines. 
This  also  allows  more  sophistication 
to  be  incorporated  into  the  application 
for  a  specific  hardware  configuration. 
Large  applications  can  easily  run  on 
640K  machines. 

Implementing  an  object  swapping 
system  in  an  application  written  in  C 
can  be  done,  but  will  require  the  pro¬ 
grammer  to  explicitly  call  access  rou¬ 
tines  whenever  an  object  is  needed.  A 
paging  system  is  easier  for  the  pro¬ 
grammer,  but  does  not  make  optimal 
use  of  memory.  Having  the  object  swap¬ 
ping  system  integrated  inside  a  lan¬ 
guage  such  as  Actor,  makes  its  use 
transparent  to  the  programmer.  This 
allows  Actor  to  make  optimal  use  of 
memory  and  free  the  program  from 
having  to  do  anything  specific  to  sup¬ 
port  it. 


for  each  valid  OT  Entry 

save  object  header  info  in 
OT  entry 

save  OP  in  object  header 
endfor 

Set  allocation  pointer  to  point  at 
the  start  of  the  swap  area 
for  each  object  in  the  swap  area 
if  valid  object 
then 

Move  object  to  current 
allocation  pointer 
Restore  object  header 

from  the  OT  using  saved  OP 
Set  OT  address  equal  to 
allocation  pointer 
Add  size  of  object  to 
allocation  pointer 

else 

Skip  this  object 
endif 
endfor 


Example  3-'  Pseudocode  for  swap 
area  compaction 
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A  Memory  Controller 

Extensions  to  your  library  routines  malloc  and  free 


Robert  A.  Moeser 


Many  useful  programs  have  no 
need  for  storage  manage¬ 
ment.  The  memory  they  need 
can  be  calculated  at  compile 
time,  and  when  run  time 
comes,  either  enough  memory  is  avail¬ 
able  or  it  isn’t.  Other  programs  have  a 
relatively  simple  pattern  of  memory  us¬ 
age;  they  consume  memory  in  the 
course  of  execution  and  never  return 
any  until  terminated,  when  the  system 
grabs  it  all  back.  Then  there  are  cases 
of  more  capricious  memory  use  —  in 
interactive  programs,  for  example, 
where  a  human  calls  the  shots.  You 
can  implement  programs  with  dynamic 
and  unpredictable  memory  usage  us¬ 
ing  the  routines  in  the  standard  C  li¬ 
brary,  but  this  can  result  in  complex 
code  that  is  hard  to  implement,  read, 
and  debug. 

This  article  presents  a  set  of  routines 
for  memory  management.  This  mem¬ 
ory  control  package  is  offered  as  an 
extension  to  your  library  routines  mal¬ 
loc  and  free.  It  implements  a  free-list 
approach  to  aid  in  recycling  portions 
of  memory.  It  consists  of  a  mere  seven 
functions  and  is  quite  compact. 

malloc  and  free  Basics 

Most  C  libraries  come  with  two  basic 
routines,  malloc  and  free,  malloc  re¬ 
turns  a  pointer  to  a  block  at  least  the 
size  requested.  It  is  then  up  to  the 
program  to  keep  track  of  the  block, 
using  it  however  it  will,  until  it  is  no 
longer  needed.  A  call  to  free  will  then 
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return  that  block  to  storage  and  make 
it  available  for  use  in  subsequent  re¬ 
quests.  There  are  other  allocation  rou¬ 
tines  in  the  standard  C  library,  but  they 
are  just  convenience  routines  and  can 
be  expressed  easily  in  terms  of  malloc 
plus  some  additional  code. 

In  many  cases,  writing  a  small  rou¬ 
tine  to  hide  the  call  to  malloc  can  make 
code  for  allocating  structures  a  little 
easier  to  read.  From  Kernighan  and 
Ritchie,  for  example,  is  the  classic  “tnode 
allocator”  shown  in  Example  1.  talloc 
hides  some  messy  details  and  localizes 


the  calls  to  the  library  storage  allocator 
for  instances  of  “tnodes”  to  one  rou¬ 
tine.  These  instances  are  freed  simply 
by  calling  free. 

A  little  more  sophisticated  is  the  pro¬ 
gram  that  anticipates  a  recurring  need 
for  structures  of  a  certain  type  and  pro¬ 
vides  not  only  a  special  allocator  but 
also  a  specialized  free  routine.  The  rou¬ 
tine  that  frees  instances  does  not  return 
them  to  the  library  storage  allocator 
but  instead  keeps  them  on  a  free-list. 
A  free-list  is  simply  a  singly  linked  list 
(continued  on  page  61) 


struct  tnode  *talloc() 

{ 

char  *malloc(); 

return  ((struct  tnode  *)  malloc (sizeof (struct  tnode))); 
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(continued  from  page  58) 
that  chains  freed  blocks  together.  The 
routine  that  doles  out  new  instances 
of  the  requested  type  first  checks  to  see 
if  any  instances  are  waiting  around  and 
gets  one  off  the  free-list  if  it  can.  If  it  can’t 
it  goes  to  malloc  for  “real”  storage. 

With  the  special  allocator  functions 
in  place  you  can  get  blocks  of  storage 
that  are  just  the  right  size,  frequently 
without  bothering  the  library  storage 
allocator.  Often  a  program  will  stabi¬ 
lize  around  a  certain  need  for  storage 
of  a  given  kind,  and  memory  manage¬ 
ment  calls  to  malloc  will  fall  off  nicely. 


Listing  One  (page  111)  is  an  example 
of  this  kind  of  free-list  allocator.  The 
two  routines  use  one  global  variable 
as  a  free-list  pointer,  and  dispense  and 
recover  instances  of  a  structure  called 
a  “Thing.”  It  is  a  nice  middle  ground 
between  relying  entirely  on  malloc  for 
allocation  on  the  one  hand  and  making 
a  static  declaration  that  10,  50,  or  500 
Things  will  be  needed  on  the  other. 

All  of  the  code  was  developed  and 
tested  with  Think  C  4.0  for  the  Macin¬ 
tosh.  It  was  compiled  with  prototypes 
required  and  full  pointer  type-check¬ 
ing.  The  memory  control  package  is 


MCon  Programming 
Interface  Functions 


This  section  identifies  the  seven  rou¬ 
tines  that  constitute  the  memory  con¬ 
troller  program  interface. 

newMCon 

MCon  newMCon(size_t  theltemSize); 

newMCon  is  used  to  register  an 
object  type.  The  input  argument  is 
simply  the  size  in  bytes  of  the  object 
to  be  controlled,  and  the  return  value 
is  an  MCon,  or  “magic  key.”  If  the 
package  is  unable  to  register  the  new 
object,  the  MCon  returned  will  be  zero. 
This  MCon  is  passed  to  the  other  rou¬ 
tines  in  the  package  that  need  to  know 
which  object  type  to  operate  on. 
newInstanceOf 

void  *newInstanceOf(MCon  theCon); 

newInstanceOf  takes  an  MCon  as 
its  argument  and  returns  a  pointer  to 
a  new  (or  recycled)  instance  of  the 
object  the  MCon  stands  for.  The  re¬ 
turn  type  is  void  *,  so  it  can  serve  as 
a  pointer  to  anything.  This  pointer 
will  be  zero  if  storage  is  unavailable, 
disposelnstance 

void  dispose!nstance(void  *theltem); 

disposelnstance  takes  as  its  argu¬ 
ment  a  pointer  to  any  instance  that  is 
no  longer  needed.  The  actual  storage 
is  not  freed  at  this  time,  but  is  kept 
on  a  free-list  for  objects  of  the  same 
type. 

purgeMCon 

void  purgeMCon(MContheCon); 

purgeMCon  takes  as  its  argument 
the  MCon  whose  free-list  should  be 
returned  to  the  library  storage  alloca¬ 
tor  by  free. 


disposeMCon 

counter  disposeMCon(MContheCon) 
disposeMCon  takes  as  its  argument 
the  MCon  for  an  object  type  that  will 
no  longer  be  needed,  and  de-regis- 
ters  it.  The  entire  free-list  and  the 
memory  control  package’s  internal  rep¬ 
resentation  for  the  object  type  are 
returned  to  the  library  storage  alloca¬ 
tor  by  calls  to  free.  The  return  value 
is  the  number  of  “orphans”  that  this 
action  creates  —  since  a  client  may 
have  active  instances  of  the  object 
under  its  control,  disposing  of  an  ob¬ 
ject’s  MCon  can  create  objects  which 
now  cannot  be  freed.  This  is  not  strictly 
an  error,  but  should  be  a  warning 
sign. 

purgeAllMCons 

void  purgeAllMCons(void); 

purgeAllMCons  is  a  convenience  rou¬ 
tine,  and  just  purges  the  free-list  of 
every  object  type  known  to  the  mem¬ 
ory  controller.  A  client  might  call  this 
in  a  desperate  attempt  to  satisfy  a 
memory  request. 
disposeAllMCons 
counter  disposeAllMCons(void); 

disposeAllMCons  is  also  a  conven¬ 
ience  routine,  and  deregisters  all 
known  object  types.  This  action  can 
create  orphans  in  the  same  sense  as 
disposeCon  above,  and  so  returns  the 
number.  It  really  ought  to  be  zero 
unless  the  client  has  created  objects 
meant  to  endure  until  program  termi¬ 
nation.  The  memory  controller  also 
shuts  itself  down  and  frees  all  mal- 
lod d  storage.  —  R.A.M. 
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accessed  by  the  client  through  just  seven 
routines  (see  the  accompanying  text 
box).  Listing  Two  (page  111),  mem.h, 
has  all  the  typedefs  and  prototypes  for 
the  package,  and  Listing  Three  (page 
111),  memories. c,  has  all  the  execut¬ 
able  code.  The  memory  control  pack¬ 
age  uses  only  your  library’s  malloc  and 
free  routines,  so  its  system  interface  is 
straightforward.  The  package  should 
therefore  be  easy  to  port  to  any  up-to- 
date  C  compiler  and  machine. 

The  Programming  Interface 

The  interface  to  the  memory  control 

The  code  acts  as  a  black 
box,  using  pointers  to 
create  the  desired 
behavior  for  any 
conceivable  variety  of 
objects  and  usage 
patterns 


package  is  simple.  A  client  using  the 
services  provided  sees  it  through  a  hand¬ 
ful  of  functions.  One  function  informs 
the  memory  controller  of  your  inten¬ 
tion  to  use  objects  of  a  certain  size, 
referred  to  here  as  “registration.”  There 
are  two  routines:  One  for  getting  point¬ 
ers  to  new  instances  of  a  registered 
object,  and  one  for  returning  instances 
no  longer  needed.  A  fourth  routine  is 
available  to  flush  the  free-list  for  any 
object  type  (functionality  not  provided 
in  the  example  above).  There  is  also  a 
routine  used  to  “de-register”  an  object 
type,  which  the  memory  controller  takes 
as  its  cue  not  only  to  flush  the  entity’s 
free-list  but  also  to  free  its  own  internal 
data  for  dealing  with  that  object  type. 

Finally,  there  are  two  convenience 
routines,  one  to  flush  the  free-lists  of 
all  known  object  types  and  another 
that  will  de-register  all  known  object 
types.  While  I  haven’t  used  these  last 
two  in  my  own  work,  they  were  easy 
to  provide  and  could  come  in  handy 
in  case  of  a  major  context  shift  or  pro¬ 
cessing  phase  change.  You  could  even 
call  them  on  program  exit,  although, 
because  all  the  memory  used  is  ulti¬ 
mately  obtained  by  malloc,  it  should 
find  its  way  back  to  the  system  by  itself. 
The  accompanying  text  box  summa¬ 
rizes  the  seven  functions  of  the  pro¬ 
gramming  interface. 
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(continued  from  page  62) 

To  use  the  memory  controller  pack¬ 
age,  include  the  mem.h  header  in  each 
source  file  where  its  functions  will  be 
needed.  Declare  a  variable  of  type  MCon 
for  each  different  object  type.  For  now, 
think  of  it  as  a  magic  key.  It  is  initial¬ 
ized  when  you  register  an  object  type 
with  a  call  to  newMCon.  Usually  these 
will  be  allocated  statically,  but  the  pack¬ 
age  makes  no  such  restriction.  So  the 
following  gets  you  a  magic  key  for 
“objectA,”  which  is  some  structure  or 
union  in  your  code: 

MCon  objectAMCon; 
objectAMCon  =  newMConfsizeof 

objectA); 

After  that,  you  use  this  MCon  to  specify 
that  it’s  an  objectA  you  want  when  you 
call  newInstanceOf  to  get  a  new  in¬ 
stance.  So  the  following  will  get  you  a 
pointer  to  an  objectA-sized  block: 

objectA  "anA; 

anA  =  newInstanceOfCobjectAMCon); 

and  disposelnstance(anA);  will  put  that 
storage  back  onto  the  free-list  for  ob¬ 
jectA.  The  other  routines  are  just  as 
simple  to  use. 

Please  keep  in  mind  that  just  as  it  is 


bad  to  free  something  that  was  not 
malloc' d,  so  it  is  bad  to  disposelnstance 
of  something  foreign  to  the  memory 
control  package.  And  one  certain  way 
to  make  something  foreign  is  to  dis¬ 
pose  of  its  controller  with  disposeMCon. 
Sometimes  these  orphans  are  what  you 
want,  but  beware.  I  also  caution  against 
freeing  an  instance  obtained  by  newIn¬ 
stanceOf.  Keep  direct  uses  of  malloc 
and  free  away  from  uses  of  the  memory 
controller. 

Implementation 

You  might  guess  that  an  MCon  is  noth¬ 
ing  more  than  a  pointer  to  a  structure 
which  holds  all  the  information  that 
the  memory  controller  needs  in  order 
to  accomplish  its  tasks  for  a  given  ob¬ 
ject.  This  includes  the  size  of  the  object 
and  a  pointer  to  a  free-list  of  object¬ 
sized  blocks. 

The  memory  controller  keeps  all 
MCon  objects  on  a  doubly  linked  list 
to  facilitate  creating  and  disposing  of 
them  in  response  to  a  client’s  newMCon 
and  disposeMCon  requests,  and  to  make 
purgeAllMCons  and  dispose AllMCons  a 
matter  of  traversing  the  list  and  per¬ 
forming  the  requested  operation  on 
each  MCon.  A  couple  of  internal  rou¬ 
tines  do  this  list  management. 

Each  MCon  object  also  maintains 


some  counters  to  track  the  use  of  its 
object  type.  They  keep  track  of  how 
many  objects  have  been  requested,  how 
many  are  still  “out  there”  somewhere 
under  control  of  the  client,  and  how 
many  are  currently  on  the  free-list.  Count¬ 
ers  are  used  to  validate  the  integrity  of 
the  internal  data  structures  and  can  be 
used  to  glean  useful  information  about 
usage  patterns. 

When  a  client  requests  registration 
of  a  new  object  type  through  the 
newMCon  routine,  the  memory  con¬ 
troller  creates  a  new  MCon  object,  fills 
in  its  fields,  and  links  it  into  the  master 
list  of  MCons.  When  the  memory  con¬ 
troller  actually  calls  malloc  to  get  stor¬ 
age  for  an  object  (the  object’s  free-list 
being  empty),  it  allocates  some  extra 
memory.  This  extra  memory,  hiding  in 
front  of  the  actual  block  you’ll  use  to 
store  your  object  data,  is  used  to  hold 
a  copy  of  the  MCon  pointer  that  was 
used  to  create  the  block.  The  idea  of 
hiding  information  in  front  of  an  allo¬ 
cated  block  is  nothing  new  —  in  fact 
malloc  itself  typically  uses  some  over¬ 
head  storage  this  way  in  its  own  sim¬ 
pler  efforts  to  manage  memory. 

In  this  way  disposelnstance  can  fig¬ 
ure  out  which  MCon’s  free-list  to  use. 
When  an  object  is  on  a  free-list,  this 
extra  storage  is  reused  to  hold  a  pointer 
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(continued  from  page  64) 
to  the  next  free  instance,  making  a 
singly  linked  list  of  free  blocks  of  the 
same  size. 

Now  the  final  trick  that  complicates 
the  implementation  somewhat:  Since 
the  memory  control  package  has  an 
unpredictable  need  for  objects  of  a  cer¬ 
tain  size  (MCon  objects),  it  uses  its  own 
routines  to  manage  storage  for  them! 
It  is  said  that  a  man  who  is  his  own 
lawyer  has  a  fool  for  a  client,  but  this 
use  of  the  memory  controller  seems 
OK.  The  MCon’s  MCon  is  the  con- 
trolCon.  When  the  package  is  active, 
this  MCon  serves  as  the  controller  for 
instances  of  MCon  objects.  The  actual 
object  is  also  the  head  and  tail  of  the 
doubly  linked  list  of  MCons.  This  MCon 
object  is  just  a  little  different  than  all  the 
other  blocks  handed  out  by  the  mem¬ 
ory  controller;  it  lacks  the  hidden  infor¬ 
mation  in  front  of  the  block,  so  it  gets 
allocated  by  just  calling  malloc  and  is 


Figure  1:  Memory  controller  map 


freed  (if  disposeAllMCons  is  called,  shut¬ 
ting  down  the  controller)  by  a  call  to 
free. 

Figure  1  shows  a  diagram  of  how 
memory  might  look  after  some  activity 
involving  the  memory  controller  has 
occurred. 

Extending  the  System 

The  basic  mechanism  can  be  easily 
modified  to  keep  more  information 
about  patterns  of  usage.  Any  amount 
of  additional  data,  such  as  serial  num¬ 
bers  or  time  stamps,  can  be  hidden 
with  each  instance.  The  various  mecha¬ 
nisms  can  be  turned  off  and  on  in  one 
place  for  development,  testing,  and  pro¬ 
duction  phases. 

Additional  functions  would  be  easy 
to  add  —  for  example,  a  copy  function 
to  return  a  copy  of  an  instance.  Bring¬ 
ing  such  extensions  into  the  purview 
of  a  single  memory  controller  like  this 
one  provides  one-stop  shopping  for  all 
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( continued  from  page  66) 
kinds  of  tricks. 

Variable-sized  objects  such  as  strings 
present  a  problem  in  this  scheme.  In 
my  own  code,  I  once  used  a  method  I 
dubbed  the  “Procrustean  Allocator.”  I 
had  MCons  for  a  few  different  object 
sizes  and  rudely  grabbed  the  nearest 
one  that  fit.  The  sizes  were  all  powers 
of  two,  and  I  used  the  services  of  the 
memory  controller  to  accomplish  the 
allocation  task  with  a  little  array  of 
MCons.  There  is,  of  course,  no  reason 
you  can’t  continue  to  use  malloc  and 
free  wherever  you  like,  as  the  memory 
controller  in  no  way  precludes  other 
uses  of  these  basic  functions. 

Listings  Four  and  Five  (page  112) 
provide  a  complete  program  that  torture- 
tests  the  memory  controller.  It  randomly 
registers  objects  of  various  sizes,  ran¬ 
domly  creates  and  frees  instances  of 
them,  and  occasionally  de-registers  ob¬ 
ject  types. 

Conclusion 

This  set  of  routines  provides  simple 
access  to  a  particular  memory  manage¬ 
ment  technique.  The  code  acts  as  a 
black  box,  using  pointers  to  create  the 
desired  behavior  for  any  conceivable 
variety  of  objects  and  usage  patterns. 
It  is  self-starting  and  self-terminating 
and  provides  its  services  with  minimal 
overhead.  By  using  this  package,  you 
can  improve  the  readability,  if  not  the 
performance,  of  programs  that  call  it. 
With  a  few  additions,  it  could  serve  as 
a  statistics-gathering  device  for  mem¬ 
ory  use  or  as  the  basis  for  writing  in  a 
traditional  language,  using  an  object- 
oriented  philosophy. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  111.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  5. 
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Demystifying 

16-Bit  VGA 

There’s  more  to  VGA  than  meets  the  eye 


Michael  Abrash 


A  year  or  two  ago,  a  friend  in  the 
industry  made  the  mistake  of 
mentioning  to  a  headhunter  (ex¬ 
cuse  me,  an  employment  re¬ 
cruiter)  that  he  was  interested 
in  hiring  someone  with  object-oriented 
programming  skills,  which  were  rare 
at  the  time.  From  that  moment  forth, 
every  resume  that  came  through  that 
particular  agency  boasted  of  object- 
oriented  programming  experience.  My 
friend  would  ask  each  candidate  if  he 
or  she  had  any  experience  with  object- 
oriented  programming,  and  each  one 
would  answer  yes.  Then  my  friend 
would  ask  exactly  what  object-oriented 
programming  is.  Not  a  one  of  them  had 
a  clue. 

Which  brings  us,  in  a  slightly  round¬ 
about  way,  to  16-bit  VGA. 

What  16-Bit  VGA  Really  Is 

16-bit  VGA.  Those  seductive  words, 
promising  what  every  PC  user  craves  — 
performance  —  are  everywhere.  “16- 
bit  VGA,”  ads  shout.  “16-bit  VGA:  Does 
It  Matter?”  articles  and  reviews  ask.  “Do 
I  need  a  16-bit  VGA?”  every  power 
user  wonders,  and,  “Can  I  afford  one?” 

It  seems  as  if  16-bit  VGAs  have  been 
with  us  forever,  or  at  least  since  IBM 
came  down  from  the  mount  with  the 
PC,  but  in  fact  they’re  a  relatively  new 
development,  dating  back  only  a  year 
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or  so.  (IBM’s  Display  Adapter,  the  PC- 
bus  version  of  the  VGA,  was  —  and 
still  is  —  an  8-bit  adapter.)  As  such, 
they’re  a  lot  like  object-oriented  pro¬ 
gramming  was  when  my  friend  was 
looking  to  hire  a  programmer:  Widely 
used  as  a  buzzword,  claimed  by  many, 
and  not  particularly  well  understood 
by  the  reviewers  who  write  about  them, 
the  users  who  buy  them,  or  the  devel¬ 
opers  who  must  deal  with  them.  Most 
significantly,  16-bit  VGA  isn’t  a  stan¬ 
dard,  but  rather  a  catchall  name  for  a 
variety  of  VGA  enhancements.  Any  VGA 
with  a  16-bit  bus  interface  (that  is,  with 
two  connectors  that  plug  into  the  AT 
bus)  is  bound  to  be  advertised  as  a 
16-bit  VGA,  but  all  16-bit  VGAs  are  not 
created  equal,  and  the  value  of  a  given 
16-bit  VGA  varies  greatly  depending 
both  on  the  sorts  of  1 6-bit  operations 
it  offers  and  on  how  you  use  it. 

DDJ s  readers,  who  are  both  devel¬ 
opers  and  users  (and  sometimes  re¬ 
viewers  as  well)  would  surely  benefit 
from  a  solid  understanding  of  what 
16-bit  VGA  really  means  and  what  bene¬ 
fits  the  various  types  of  16-bit  VGA 
offer.  It’s  from  that  perspective  that  I’ll 
attempt  to  clear  up  some  misconcep¬ 
tions  and  confusion  about  16-bit  VGA 
in  this  article;  most  importantly,  we’ll 
see  why  (happily  and  contrary  to  some 
reports)  programmers  need  not  treat 
8-  and  16-bit  VGAs  differently. 

Performance 

Let’s  begin  by  placing  the  one  and  only 
reason  for  the  existence  of  1 6-bit 
VGAs  —  performance  —  in  context.  16- 
bit  VGAs  can  allow  screen-oriented  pro¬ 


grams  to  run  faster  than  other  VGAs, 
but  it’s  not  really  correct  to  say  that 
they  run  those  programs  faster;  more 
accurately,  16-bit  VGAs  slow  programs 
down  less. 

What’s  the  distinction?  More  powerful 
graphics  adapters,  such  as  the  8514/A 
and  adapters  built  around  the  TI  34010 
graphics  chip,  have  dedicated  proces¬ 
sors  and  specialized  hardware  that  al¬ 
low  them  to  offload  work  the  CPU 
would  otherwise  have  to  do  and  to 
perform  that  work  very  rapidly,  so  they 
really  can  run  screen-oriented  programs 
faster  than  if  the  CPU  were  required  to 
do  all  the  work  itself. 

In  contrast,  the  best  a  VGA  can  do 
is  get  in  the  processor’s  way  less.  You 
see,  all  VGA-based  graphics  operations 
are  performed  directly  by  the  CPU  — 
the  8088,  80286,  80386,  or  whatever 
processor  happens  to  be  in  a  given  PC. 
The  VGA  has  only  a  bit  of  hardware 
assist  on  board,  and  has  no  indepen¬ 
dent  processing  ability  at  all.  The  VGA 
is  basically  a  set  of  I/O  ports  and  a 
memory  map  to  be  manipulated  di¬ 
rectly,  and  at  a  very  low  level,  by  the 
CPU.  Given  that,  the  only  way  a  VGA 
can  contribute  to  improved  performance 
is  by  not  slowing  the  CPU,  that  is,  by 
allowing  the  CPU  rapid  access  to  I/O 
ports  and  memory.  Ideally,  the  CPU 
would  be  able  to  make  every  access 
to  VGA  memory  as  rapidly  as  to  system 
memory,  and  likewise  for  I/O  ports. 

That’s  the  ideal,  but  it’s  far  from  the 
reality.  To  understand  why,  we  must 
first  understand  how  the  AT  bus  han¬ 
dles  8-bit  adapters.  That  discussion  has 
two  facets:  The  splitting  up  of  16-bit 
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accesses  to  8-bit  adapters,  and  the  auto¬ 
matic  slowing  down  of  all  accesses  to 
8-bit  adapters.  Before  we  can  cover 
those  topics,  however,  we  must  talk 
about  wait  states. 

Wait  States  in  the  AT 

Wait  states  are  cycles  during  which  the 
CPU  does  nothing  because  the  bus  or 
some  memory  or  I/O  device  tells  it  to 
wait.  Put  another  way,  they’re  states 
that  are  thrown  away  by  the  CPU  at  the 
request  of  external  circuitry.  While  wait 
states  aren’t  desirable  because  they  re¬ 
duce  performance,  they’re  necessary 
because  they  allow  slower  memory  and 
I/O  devices  to  function  properly  with 
a  fast  CPU.  For  example,  the  80286  is 
capable  of  performing  a  memory  or 
I/O  access  in  just  two  cycles.  However, 
the  bus  inserts  one-wait-state  on  each 
access  to  most  16-bit  devices,  includ¬ 
ing  system  memory,  in  a  standard  AT, 
as  shown  in  Figure  1.  This  increases 
access  time  to  three  cycles,  reducing 
overall  performance  but  allowing  the 
use  of  slower,  cheaper  chips. 

Wait  states  are  also  inserted  by  an 
adapter  whenever  the  adapter  can’t  re¬ 
spond  at  the  maximum  speed  of  the 
bus  or  processor.  As  we’ll  see,  some 
VGAs  insert  additional  wait  states,  while 
others  avoid  additional  wait  states  at 


least  some  of  the  time. 

1 6-Bit  Accesses  to  8-Bit  Adapters 

There  are  two  fundamental  classes  of 
adapters  that  may  be  plugged  into  the 
AT  bus:  8-bit  adapters  and  16-bit  adapt¬ 
ers.  The  two  are  distinguished  by  the 
extra  bus  connector  that  appears  only 
on  16-bit  adapters;  in  addition,  16-bit 
adapters  must  announce  to  the  bus 
that  they  are  indeed  capable  of  han¬ 
dling  16-bit  accesses,  by  raising  a  par¬ 


ticular  bus  line  on  the  16-bit  connector 
early  on  during  each  access. 

What  happens  if  an  adapter  doesn’t 
have  the  1 6-bit  connector,  or  if  it  doesn’t 
announce  that  it’s  a  16-bit  device?  Why, 
then  the  AT’s  bus  does  two  things. 
First,  the  bus  splits  each  word-sized 
access  to  that  adapter  into  2-byte-sized 
accesses,  sending  the  adapter  first  1- 
byte  and  then  the  other.  That’s  not  all 
the  bus  does,  though:  During  each  of 
those  byte-sized  accesses  to  an  8-bit 


The  80286’s  access  time 
in  the  absence  of  wait 
states  (2  cycles) 


The  wait  state  inserted 
by  the  bus  on  each 
access  to  a  normal 
16-bit  device  on  the  AT 
bus  (1  cycle) 


Cycle  n-1 


Cycle  n 


Cycle  n+1 


Cycle  n+2 


Cycle  n+3 


The  total  time 
required  to  perform 
a  byte-size  access 
to  a  normal  16-bit 
device  on  the  AT 
bus  (3  cycles) 


Figure  1:  At  least  three  cycles  are  required  for  each  byte-sized  access  (or 
word-sized  access  to  an  even  address)  to  a  normal  16-bit  device  on  the  AT 


bus.  Each  access  to  a  special  zero-wait-state,  16-bit  device  may  take  as  few 
as  two  cycles;  each  word-sized  access  to  an  odd  address  of  a  16-bit  device 
takes  twice  as  long  as  a  byte-sized  access 
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adapter,  the  AT  bus  inserts  three  extra 
wait  states  (in  addition  to  the  one-wait 
state  that’s  routinely  inserted),  effec¬ 
tively  doubling  the  access  time  per  byte 
of  such  adapters  to  six  cycles,  as  shown 
in  Figure  2.  These  extra  wait  states, 
which  I’ll  refer  to  as  8-bit-device  wait 
states,  form  a  pivotal  and  little-under¬ 
stood  element  of  16-bit  VGA.  Together 
with  the  splitting  of  word-sized  accesses 
into  2-byte-sized  accesses,  8-bit-device 
wait  states  can  quadruple  the  access  time 
per  word  of  8-bit  adapters;  instead  of 
accessing  one  word  every  three  cycles, 
as  is  possible  with  16-bit  adapters,  the 
AT  can  access  only  1-byte  every  six  cy¬ 
cles  when  working  with  8-bit  adapters. 

Three  extra  wait  states  are  inserted 
on  accesses  to  8-bit  adapters  because 
the  first  8-bit  adapters  were  designed 
for  the  PC’s  4.77-MHz  bus,  not  the  AT’s 
8-MHz  bus.  In  order  to  ensure  that  PC 
adapters  worked  reliably  in  ATs,  the 
designers  of  the  AT  decided  to  slow 
accesses  to  8-bit  adapters  to  PC  speeds 
by  inserting  wait  states  to  double  the 
access  time.  Modern  adapters,  such  as 
the  VGA,  can  easily  be  designed  to  run 
at  AT  speeds  or  faster,  whether  they’re 
8-  or  1 6-bit  devices  —  but  the  AT  bus 
has  no  way  of  knowing  this,  and  insists 
on  slowing  them  down  —  just  in  case. 
It  should  be  obvious  that  true  1 6-bit 
operation,  where  an  adapter  responds 
as  a  16-bit  device  and  handles  a  word 
at  a  time,  is  most  desirable.  Not  at  all 
obvious  is  that  it’s  also  desirable,  that 
an  adapter  respond  as  a  1 6-bit  device 
even  if  it  can  internally  handle  only  a 
byte  at  a  time.  In  this  mode,  an  inher¬ 
ently  8-bit  adapter  announces  to  the 
bus  that  it’s  a  16-bit  device;  on  writes, 
it  accepts  a  word  from  the  bus  and  then 
performs  two  8-bit  writes  internally, 
and  on  reads,  it  performs  two  8-bit 
reads  internally  and  then  sends  a  word 
to  the  bus.  From  the  perspective  of  the 
bus,  each  word-sized  operation  seems 


to  be  a  1 6-bit  operation  to  a  true  1 6-bit 
adapter,  but  in  truth  two  accesses  are 
performed,  so  the  operation  takes  twice 
as  long  as  if  the  adapter  were  a  16-bit 
device  internally. 

Why  bother?  The  advantage  of  hav¬ 
ing  an  8-bit  adapter  respond  as  if  it 
were  a  16-bit  adapter  is  this:  The  bus 
is  fooled  into  thinking  the  adapter  is  a 
16-bit  device,  so  it  doesn’t  assume  that 
the  adapter  must  run  at  PC  speeds  and 
doesn’t  insert  three  extra  wait  states 
per  byte.  From  now  on,  I’ll  use  the 
word  “emulated”  to  describe  the  mode 
of  operation  in  which  an  adapter  that’s 
internally  an  8-bit  device  responds  as 
a  1 6-bit  adapter;  this  mode  contrasts 
with  the  true  1 6-bit  operation  offered 
by  adapters  that  not  only  respond  as 
1 6-bit  devices  but  are  1 6-bit  devices 
internally.  AT  plug-in  memory  adapt¬ 
ers,  for  example,  are  true  1 6-bit  adapt¬ 
ers.  16-bit  VGAs,  on  the  other  hand, 
may  be  either  true  or  emulated  16-bit 
adapters;  in  fact,  as  well  see,  a  single 
VGA  may  operate  as  either  one,  de¬ 
pending  on  the  mode  it’s  in. 

Emulated  1 6-bit  operation  is  at  heart 
nothing  more  than  a  means  of  announc¬ 
ing  to  the  AT  bus  that  an  inherently 
8-bit  adapter  can  run  at  AT  speeds 
thereby  making  the  three  8-bit-device 
wait  states  vanish.  While  emulated  16- 
bit  adapters  can  run  up  to  twice  as 
slowly  as  true  1 6-bit  adapters  (word¬ 
sized  accesses  must  still  be  performed 
a  byte  at  a  time),  emulated  16-bit  op¬ 
erations  can  double  the  performance 
of  an  inherently  8-bit  adapter  that  is 
otherwise  capable  of  responding  in¬ 
stantly,  by  cutting  access  time  from  six 
to  three  cycles. 

8-Bit  and  16-Bit  Adapters  Don't  Mix 

If  there  is  one  8-bit  display  adapter  in 
an  AT,  all  display  adapters  in  that  AT 
must  be  8-bit  devices.  Consequently, 
all  16-bit  VGAs  automatically  convert 


Figure  2:  At  least  six  cycles  are  required  for  each  byte-sized  access  to  an  8-bit 
device  on  the  AT  bus 
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(continued  from  page  72) 
to  8-bit  operation  if  an  8-bit  adapter  is 
present.  If  you  put  a  monochrome 
adapter  in  your  AT  along  with  your 
expensive  16-bit  VGA,  what  you’ll  get 
is  8-bit  VGA  performance. 

Why  this  happens  is  a  function  of 
the  addressing  information  available  to 
an  adapter  at  the  time  it  has  to  an¬ 
nounce  it  is  a  16-bit  device;  I  lack  both 
the  expertise  and  the  space  to  explain 
it  in  detail.  The  phenomenon  does  ex¬ 
ist,  however,  and  the  conclusion  is  sim¬ 
ple:  Don’t  bother  getting  a  1 6-bit  VGA 
if  you’re  going  to  put  an  8-bit  display 
adapter  in  your  system  as  well. 

Wail  States  in  Other  AT-Bus  Computers 

All  AT-bus  80386-based  computers  slow 
down  both  8-  and  1 6-bit  adapters  con¬ 
siderably.  (Obviously,  1 6-bit  VGAs  are 
wasted  in  8-bit  PCs,  in  which  they  op¬ 
erate  as  8-bit  devices.)  AT-bus  80386 
computers  insert  wait  states  —  often  a 
great  many  wait  states  —  on  accesses 
to  16-bit  devices  in  order  to  slow  the 
bus  down  to  approximately  the  375 
nanoseconds  excess  time  speed  of  the 
AT  bus,  so  that  AT  plug-in  adapters 
will  work  reliably.  A  33-MHz  80386  is 
capable  of  accessing  memory  once  ev¬ 
ery  60  nanoseconds  (two  cycles);  ten 


wait  states  must  be  inserted  to  slow 
accesses  down  to  about  the  375- 
nanosecond  access  time  of  a  standard 
AT.  Clearly,  memory  on  1 6-bit  plug-in 
adapters  responds  considerably  more 
slowly  than  32-bit  memory  in  80386 

Most  significantly, 
16-bit  VGA  isn’t 
a  standard  but 
rather  a  catchall 
name  for  a 
variety  of  VGA 
enhancements 


computers;  the  80386  in  the  above  ex¬ 
ample  is  idle  more  than  80  percent  of 
the  time  when  accessing  plug-in  16-bit 
memory.  Because  of  this,  you  can  ex¬ 
pect  to  see  VGAs  built  onto  the  moth¬ 
erboards  of  most  high-performance  com¬ 
puters  in  the  future,  thereby  completely 


bypassing  the  many  wait  states  inserted 
by  the  AT  bus. 

In  many  80386  computers,  8-bit  adapt¬ 
ers  are  worse  still.  A  number  of  80386 
motherboards  slow  accesses  to  8-bit 
adapters  down  to  about  the  PC’s  bus 
speed  of  838  nanoseconds  per  access, 
which  could  mean  as  many  as  about 
25  wait  states  in  the  above  example. 
However,  a  number  of  80386  comput¬ 
ers  slow  both  8-  and  16-bit  adapters 
down  to  AT  speeds;  in  these  comput¬ 
ers,  the  performance  distinction  between 
8-  and  16-bit  adapters  vanishes. 

What  of  Micro  Channel  computers? 
They  don’t  distinguish  between  8-  and 
1 6-bit  devices  —  but  that’s  a  moot  point, 
because  Micro  Channel  computers  have 
VGAs  built  right  onto  the  motherboard. 
For  the  remainder  of  this  article,  I’ll  talk 
only  about  AT-bus  VGAs. 

To  summarize,  byte-sized  accesses 
to  an  8-bit  adapter  take  twice  as  long 
on  ATs  and  many  80386  computers  as 
accesses  to  a  1 6-bit  adapter  if  both 
adapters  are  otherwise  capable  of  re¬ 
sponding  instantly;  word-sized  accesses 
take  twice  as  long  again  on  8-bit  adapt¬ 
ers.  Most  VGAs  aren’t  capable  of  re¬ 
sponding  instantly,  though,  and  in  mem¬ 
ory  and  I/O  response  time  lies  another 
part  of  the  1 6-bit  VGA  performance  tale. 

VGA  Memory 

Before  we  can  look  at  the  response 
time  of  VGA  memory,  we  must  clarify 
exactly  what  sort  of  VGA  memory  we’re 
talking  about.  For  practical  purposes, 
there  are  three  types  of  VGA  memory: 
ROM,  text-mode  memory,  and  graphics¬ 
mode  memory.  A  16-bit  VGA  might 
actually  provide  16-bit  access  in  one, 
two,  or  all  three  areas,  and  16-bit  ac¬ 
cess  might  be  either  true  or  emulated 
for  ROM  and  text-mode  memory.  In 
addition,  1 6-bit  access  provides  differ¬ 
ent  benefits  in  each  area.  Next,  we’ll 
look  at  16-bit  operation  in  each  VGA 
memory  area,  and  1 6-bit  I/O,  as  well. 

ROM 

It’s  easy  to  provide  true  1 6-bit  access 
to  a  VGA’s  ROM,  and  most  16-bit  VGAs 
do  so.  If  a  1 6-bit  VGA  has  two  ROM 
chips,  it’s  a  pretty  safe  bet  that  it  offers 
true  1 6-bit  ROM  operation,  which  in 
turn  translates  into  a  performance 
improvement  of  close  to  four  times  for 
VGA  ROM  code.  Just  what  does  that 
massive  speedup  do  for  us? 

The  VGA’s  ROM  contains  an  ex¬ 
tended  video  BIOS  that’s  responsible 
for  the  text  placed  on  the  screen  by 
DOS  and  BIOS  functions,  a  category 
that  includes  the  DOS  prompt,  direc¬ 
tory  listings,  and  text  drawn  with  print/ 
and  writeln ,  but  not  the  text  drawn  by 
virtually  any  major  word  processor,  text 
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(continued  from  page  74) 
editor,  or  other  program  that  offers  a 
full-screen  interface.  The  VGA’s  BIOS 
also  provides  functions  for  drawing  and 
reading  dots  in  graphics  mode  at  rela¬ 
tively  low  speeds;  again,  most  graphics 
programs  ignore  these  functions  and 
access  the  video  hardware  directly.  Fi¬ 
nally,  the  VGA’s  BIOS  supports  miscel¬ 
laneous  functions  such  as  setting  the 
color  palette  and  returning  configura¬ 
tion  information. 

Consequently,  the  primary  benefit 
of  1 6-bit  ROM  access  is  speeding  up 
directory  listings,  the  TYPE  command, 
program  output  sent  to  the  standard 
output  device,  and  the  like,  which  can 
make  the  computer  feel  sprightlier  and 
more  responsive.  On  the  other  hand, 
most  manufacturers  provide  RAM-load¬ 
able  BIOSes,  which  are  generally  faster 
than  even  16-bit  ROM  BIOSes,  espe¬ 
cially  in  fast  80386  computers,  because 
they  run  from  system  memory.  Also, 
many  computers  can  copy  the  VGA’s 
BIOS  into  shadow  RAM,  non-DOS  sys¬ 
tem  memory  reserved  especially  for  the 
purpose  of  replacing  ROM  with  fast  RAM. 

On  balance,  16-bit  access  to  the  VGA’s 
ROM  BIOS  is  nice  to  have  when  a  RAM 
or  shadow  RAM  BIOS  is  not  in  use, 
because  it  speeds  up  certain  common 
operations.  16-bit  ROM  access  does  not, 
however,  affect  the  performance  of  pro¬ 
grams  that  do  direct  screen  output,  in¬ 
cluding  most  commercial  PC  software. 

A  Brief  Aside  on  Benchmarks 

It’s  not  easy  to  benchmark  VGAs  in 
ways  that  correspond  to  meaningful 
user-performance  improvements.  A  num¬ 
ber  of  programs  used  to  test  VGAs  are 
actually  BIOS  tests,  because  it’s  easy 
to  exercise  the  various  BIOS  functions; 
alas,  that  falls  far  short  of  fully  exercis¬ 
ing  the  VGA  standard,  for  many  pro¬ 
grams  ignore  the  BIOS  altogether  and 
access  the  VGA’s  hardware  directly. 
Other  benchmarks  just  measure  raw 
memory  access  speed;  they  measure 
ideal  conditions  that  are  rarely  achieved 
in  the  real  world.  Raw  memory  access 
speed  doesn’t  necessarily  map  well  to 
the  sorts  of  operations  —  bitblts,  line 
draws,  scrolling,  fills,  and  the  like  — 
that  performance-sensitive  screen-ori¬ 
ented  programs  actually  perform. 

There  are  two  types  of  meaningful 
benchmarks.  Benchmarks  that  meas¬ 
ure  actual  programs  doing  useful,  time- 
consuming  work  (redrawing  screens 
in  Autocad  or  scrolling  through  a  docu¬ 
ment  in  a  Windows-based  word  pro¬ 
cessor,  for  example)  are  certainly  rele¬ 
vant.  Better  yet  are  benchmarks  you 
perform  yourself  with  the  VGA  soft¬ 
ware  you  plan  to  use.  Performance  is 
not  absolute:  It  is  a  relative  measure 
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that  is  meaningful  only  in  context.  What 
good  will  it  do  you  to  buy  the  VGA 
that  runs  Autocad  fastest  if  you  do  all 
your  drawing  work  in  Fastcad?  There’s 
no  guarantee  that  a  VGA  that  performs 
well  with  one  program  will  perform 
well  with  another,  if  for  no  other  rea¬ 
son  than  that  the  performance  of  driver- 
based  programs  varies  as  much  with 
driver  quality  as  with  hardware  speed, 
and  each  VGA  manufacturer  provides 
its  own  set  of  drivers. 

Use  your  own  software  to  test  drive 

The  VGA  has  up  to 
152K  of  graphics 
memory  per  screen,  and 
needs  to  scan  about 
nine  million  bytes  of 
video  data  onto  the 
screen  every  second 


any  VGA  you’re  considering  buying. 
You’ll  be  glad  you  did. 

Text-Mode  Memory 

The  second  type  of  VGA  memory  is 
text-mode  memory.  Some  VGAs  pro¬ 
vide  true  1 6-bit  access  to  text-mode 
memory,  while  others  provide  emu¬ 
lated  16-bit  access.  True  16-bit  VGA  is 
clearly  the  superior  of  the  two  in  this 
context;  word-sized  writes  actually  hap¬ 
pen  quite  often  in  text  mode,  as  both 
a  character  and  its  attribute  are  fre¬ 
quently  written  to  memory  with  a  sin¬ 
gle  instruction.  Emulated  16-bit  access 
alone  may  or  may  not  improve  perfor¬ 
mance,  depending  on  whether  or  not  a 
given  VGA  can  respond  fast  enough  to 
take  advantage  of  the  three  cycles  per 
byte -sized  access  that  1 6-bit  emulation 
saves.  The  end  result  is  that  emulated 
1 6-bit  text-mode  memory  can  as  much 
as  double  the  speed  of  access  to  text¬ 
mode  memory,  while  true  16-bit  text¬ 
mode  memory  improves  performance 
by  up  to  four  times  over  8-bit  VGA. 

A  two-  to  four-fold  increase  in  text¬ 
mode  memory  access  certainly  makes 
for  snappy  response  for  text-mode  pro¬ 
grams  that  go  directly  to  display  mem¬ 
ory,  including  most  spreadsheets  and 
word  processors.  However,  because  rela¬ 
tively  few  bytes  of  display  memory  con¬ 
trol  an  entire  screen,  display  memory 
access  speed  is  rarely  the  primary  limit¬ 


ing  factor  in  the  performance  of  text¬ 
mode  programs,  so  the  perceptible  ef¬ 
fect  of  1 6-bit  text-mode  VGA  is  not  as 
dramatic  as  the  numbers  might  sug¬ 
gest.  All  in  all,  16-bit  access  to  text¬ 
mode  memory,  such  as  1 6-bit  access 
to  the  BIOS  ROM,  can  make  for  an 
enjoyable,  if  not  stunning,  increase  in 
the  responsiveness  of  certain  programs. 

Graphics-Mode  Memory 

That  leaves  us  with  just  one  VGA  mem¬ 
ory  area  to  check  out  graphics-mode 
memory.  While  this  is  the  area  in  which 
1 6-bit  VGA  can  do  the  least  to  increase 
memory  access  speed,  because  true  16- 
bit  accesses  can’t  be  supported  within 
the  VGA  standard,  it  is  ironically  also 
the  area  that  brings  out  the  best  in 
1 6-bit  VGA  —  given  the  right  circum¬ 
stances. 

As  any  VGA  user  knows,  it’s  in  graph¬ 
ics  mode  that  the  VGA  feels  slowest; 
that’s  becoming  all  the  more  apparent 
with  the  rise  of  graphical  interfaces  such 
as  Windows  and  Presentation  Manager. 
Making  a  non-VGA-  compatible  display 
adapter  that  supports  faster  graphics 
than  a  VGA  is  not  difficult  at  all;  the 
aforementioned  8314/A  and  34010- 
based  adapters  fit  that  description,  for 
example.  The  trick  is  to  improve  graph¬ 
ics  performance  without  losing  VGA 
compatibility,  so  that  the  improved  per¬ 
formance  automatically  benefits  every 
one  of  the  hundreds  of  programs  that 
support  the  IBM  VGA. 

Display  Memory  Access  Speed  in  Graphics 
Mode 

As  I  mentioned  earlier,  the  best  a  VGA 
can  do  is  get  out  of  the  way  of  the  CPU 
to  the  greatest  possible  extent.  To  see 
why  this  is  most  important  in  graphics 
mode,  let’s  look  at  a  few  numbers.  The 
VGA  has  up  to  152K  of  graphics  mem¬ 
ory  per  screen,  and  needs  to  scan  about 
nine  million  bytes  of  video  data  onto 
the  screen  every  second.  That  alone 
takes  close  to  80  percent  of  all  avail¬ 
able  memory  accesses  on  a  standard 
VGA.  VGA  memory  must  also  be  ac¬ 
cessed  many  times  by  the  CPU  in  order 
to  draw  any  sizable  image,  because 
there  are  so  many  pixels  on  the  screen, 
in  so  many  colors;  however,  those  ac¬ 
cesses  must  be  shoehorned  between 
the  video  data  reads  described  earlier. 
(For  further  information  about  the  con¬ 
flicting  demands  on  display  memory, 
see  my  article  “Display  Adapter  Bot¬ 
tleneck,”  PC  Tech  Journal,  January 
1987.) 

How  to  resolve  these  heavy  dual  de¬ 
mands  on  display  memory?  One  choice 
is  to  give  priority  to  the  video  data  and 
make  the  CPU  wait  frequently.  This  is 
simple  and  inexpensive  to  implement; 
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(continued  from  page  76) 
the  only  drawback  is  that  CPU  perfor¬ 
mance  suffers. 

There  are  a  variety  of  other  ap¬ 
proaches  to  VGA  graphics-mode  mem¬ 
ory  design,  all  of  which  improve  per¬ 
formance  to  some  degree.  Some  VGAs 
use  faster  memory  than  IBM’s  VGA  does, 
freeing  up  more  display  memory  ac¬ 
cesses  for  the  CPU.  Other  VGAs  use 
different  memory  architectures,  such 
as  paged-mode  or  video  RAM,  that  re¬ 
duce  the  overhead  of  supplying  video 
data  and  allow  the  VGA  to  service  the 
CPU  faster.  There  are  a  number  of  other 
performance-enhancing  techniques  in 
use;  the  point  is  that  there  are  a  variety 
of  means  by  which  fully  IBM-compat¬ 
ible  VGAs  can  insert  fewer  wait  states 
and  slow  the  CPU  less,  improving  over¬ 
all  graphics  performance. 

Interesting,  but  what  does  it  have  to 
do  with  16-bit  VGA?  Simply  this:  Only 
emulated  1 6-bit  VGA  can  be  imple¬ 
mented  in  graphics  mode;  true  16-bit 
VGA  is  a  physical  impossibility,  as  we’ll 
see  shortly.  Emulated  16-bit  VGA  mat¬ 
ters  only  because  it  eliminates  wait 
states;  three  wait  states  per  byte-sized 
access  to  display  memory  on  an  AT 
and  often  more  in  an  80386-based  ma¬ 
chine.  If  a  VGA  inserts  more  than  three 
wait  states  per  access  anyway,  because 


the  memory  is  inherently  slow  or  be¬ 
cause  the  CPU  must  wait  while  video 
data  is  fetched,  then  emulated  16-bit 
VGA  won’t  make  a  blessed  bit  of  differ¬ 
ence.  If,  on  the  other  hand,  a  VGA  is 
inherently  capable  of  responding  as 
quickly  as  normal  AT  system  memory 
(as  is  theoretically  the  case  with  a  VGA 
built  around  120-nanoseconds  VRAM), 
then  the  8-bit-device  wait  states  spell 
the  difference  between  a  VGA  that  re¬ 
sponds  in  three  cycles  and  one  that 
responds  in  six  cycles. 

In  a  nutshell,  the  faster  a  VGA’s  mem¬ 
ory  architecture,  the  more  the  16-bit 
interface  matters.  The  16-bit  interface 
allows  VGAs  with  inherently  fast  mem¬ 
ory  access  times  to  respond  up  to  twice 
as  fast  as  they  otherwise  would,  slow¬ 
ing  the  CPU  less  and  allowing  higher 
graphics  performance  overall. 

Of  course,  not  all  16-bit  VGAs  are 
twice  as  fast  as  8-bit  VGAs;  for  instance, 
VGAs  that  provide  slow  memory  ac¬ 
cess  won’t  benefit  from  the  16-bit  inter¬ 
face  at  all.  In  addition,  the  overall  per¬ 
formance  improvement  experienced  by 
graphics  software  on  even  the  fastest 
16-bit  VGA  depends  on  the  frequency 
with  which  that  software  accesses  dis¬ 
play  memory.  Plotting  software  that  per¬ 
forms  several  floating-point  calculations 
for  each  point  drawn  is  not  going  to 


be  measurably  affected  by  VGA  speed, 
while  software  that  spends  most  of  its 
time  copying  blocks  of  display  mem¬ 
ory  around  (scrolling  or  updating  large 
areas  of  the  screen,  for  example)  may 
indeed  run  nearly  twice  as  fast  on  a 
16-bit  VGA  as  on  an  equivalent  8-bit 
VGA,  and  the  advantage  over  slower 
VGAs  may  be  greater  still.  Drivers  weigh 
heavily  into  the  performance  equation 
as  well,  as  noted  above. 

The  Myth  of  1 6-Bit  Operations 

There’s  a  myth  that  16-bit  VGA  im¬ 
proves  graphics  performance  only  when 
16-bit  accesses  to  memory  are  used; 
on  the  basis  of  this  myth,  many  people 
have  concluded  that  because  graphics 
software  written  for  the  IBM  VGA  gener¬ 
ally  performs  8-bit  operations,  it  won’t 
benefit  from  16-bit  VGA.  Not  true.  As 
we’ve  just  seen,  in  graphics  mode  the 
great  virtue  of  16-bit  VGA  has  nothing 
to  do  with  16-bit  operations;  rather,  it 
is  that  the  16-bit  interface  serves  to  fool 
the  AT  bus  into  not  inserting  8-bit- 
device  wait  states. 

In  fact,  16-bit  VGAs  must  operate  as 
8-bit  devices  internally  in  graphics 
mode,  offering  emulated  but  not  true 
16-bit  operation.  This  is  unavoidable 
because  the  VGA  architecture  is  an  8- 
bit  architecture,  with  8-bit  internal 
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(continued  from  page  78) 
latches,  8-bit  data  masks,  and  so  on. 
While  VGA  designers  could  certainly 
create  1 6-bit  latches  and  the  like,  stan¬ 
dard  VGA  software,  which  expects  the 
normal  8-bit  setup,  wouldn’t  work  prop¬ 
erly  anymore  —  and  running  standard 
VGA  software  faster  is  the  object  of 
1 6-bit  VGA.  Consequently,  1 6-bit  VGAs 
actually  break  each  16-bit  access  into 
two  8-bit  accesses  internally,  just  as  the 
AT  bus  does  during  1 6-bit  accesses  to 
8-bit  devices,  but  without  the  three- 
wait  states  the  AT  bus  inserts.  (As  I 
noted  earlier,  some  VGAs  really  do  sup¬ 
port  single  16-bit  accesses  in  text  mode; 
this  is  possible  because  in  text  mode 
display  memory  appears  to  the  CPU  to 
be  a  single,  linear  plane  of  memory, 
and  none  of  the  VGA’s  8-bit  hardware 
assist  features  come  into  play.) 

What  does  all  this  mean?  It  means  that 
programmers  need  not  worry  about  al¬ 
tering  or  fine-tuning  graphics  code  for 
16-bit  VGAs;  standard  VGA  code  will 
run  fine  (but  faster),  and  16-bit  opera¬ 
tions  are  no  more  desirable  on  16-bit 
VGAs  than  on  8-bit  VGAs.  Hallelujah! 

I/O  Access  Speed 

Finally,  we  come  to  the  last  aspect  of 
16-bit  VGA  performance:  I/O.  I/O  to 
the  VGA  ports  is  performed  frequently 
in  graphics  mode  in  order  to  set  the  bit 
mask,  the  map  mask,  the  set/reset  color, 
and  so  on.  These  I/O  accesses  are  sub¬ 
ject  to  the  same  8-bit  device  wait  states 
as  memory  accesses,  so  it’s  desirable 
that  VGAs  respond  as  16-bit  devices  to 
I/O  as  well  as  memory  accesses.  I/O 
is  less  critical  in  text  mode,  where  it  is 
used  primarily  to  move  the  cursor,  but 
16-bit  I/O  can  help  there,  too. 

As  it  happens,  not  all  16-bit  VGAs 
do  support  1 6-bit  I/O,  so  this  is  yet 
another  area  in  which  1 6-bit  VGAs  can 
differ  widely,  and  yet  another  feature 
for  a  VGA  purchaser  to  check  out. 

Conclusion 

What’s  the  bottom  line  on  16-bit  VGA? 
First  and  most  important,  16-bit  VGA 
is  a  user  issue,  not  a  programming  is¬ 
sue;  developers  need  not  spend  time 
worrying  about  separate  drivers  or  code 
optimized  for  1 6-bit  VGAs.  1 6-bit  VGAs 
may  have  extended  modes  or  special 
features  that  require  or  benefit  from 
custom  code,  but  that  has  nothing  to 
do  with  16-bit  VGA  itself,  which  is  pri¬ 
marily  a  way  to  trick  the  AT  bus  into 
not  inserting  wait  states,  and  some¬ 
times  a  way  to  provide  true  1 6-bit  ac¬ 
cess  to  ROM  and  text-mode  memory, 
as  well. 

Second,  while  16-bit  VGA  can  make 
text-mode  operation  more  responsive, 
it  produces  the  most  visible  and  sorely 


needed  improvement  in  graphics  mode, 
but  only  for  VGAs  that  provide  memory- 
access  times  close  to  that  of  system 
memory.  In  those  cases,  however,  16- 
bit  VGA  can  provide  an  appreciable 
performance  boost,  as  much  as  dou¬ 
bling  the  execution  speed  of  graphics 
software  over  8-bit  VGA,  although  the 
improvement  depends  heavily  on  the 
frequency  with  which  the  software  ac¬ 
cesses  display  memory  and  the  VGA’s 
I/O  ports. 

In  summary,  the  speedup  from  16- 
bit  VGA  is  incremental,  not  revolution¬ 
ary,  but  is  significant  nonetheless.  The 


VGA  is  the  last  gasp  of  directly  CPU- 
controlled,  bit-mapped  graphics,  and 
16-bit  VGA  squeezes  the  last  ounce  of 
performance  from  that  old  standard. 
Whether  you  need  that  extra  edge  de¬ 
pends  on  the  software  you  use,  but  at 
least  now  you  understand  the  many 
facets  of  1 6-bit  VGA  and  can  better 
match  your  needs  to  the  features  of  the 
many  16-bit  VGAs  on  the  market. 
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Multiprocessing 

Smalltalk/V 

A  look  at  the  CX  Multiprocessing 
Extension  Kit 


Kenneth  E.  Ayers 


The  origins  of  object-oriented  pro¬ 
gramming  in  general  and  Small¬ 
talk  in  particular  are  closely  tied 
to  the  simulation  of  real-world 
events  and  systems.  A  primary 
reason  for  this  association  is  Smalltalk’s 
facility  for  describing  the  behavior  of  a 
simulated  system  in  terms  of  those  real 
objects  with  which  the  implementor  is 
familiar.  Thus,  the  programmer  of  a 
highway  traffic  simulation  can  create 
car  objects  and  truck  objects  and  give 
them  behaviors  that  mimic  their  real- 
world  counterparts.  Likewise,  someone 
who  is  studying  the  flow  of  people 
through  supermarket  checkout  lines  can 
create  objects  representing  customers, 
checkers  and  baggers  and  have  them 
carry  out  actions  that  are  familiar  to 
anyone  who  has  spent  time  waiting 
behind  a  shopping  cart. 

As  an  added  benefit,  extensible  sys¬ 
tems  such  as  Smalltalk  permit  the  de¬ 
veloper  of  a  simulation  system  to  con¬ 
struct  his  or  her  own  task  language 
with  which  to  describe  the  flow  of  in¬ 
formation  back  and  forth  between  the 
various  participants  in  the  simulation. 
This  task  language  then  becomes  a  part 
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of  the  development  system. 

Until  recently,  though,  the  availabil¬ 
ity  of  object-oriented  languages  such 
as  Smalltalk  were  limited  to  those  us¬ 
ing  powerful  (and  expensive)  worksta¬ 
tions  or  minicomputers.  Fortunately,  that 
changed  when  Digitalk  (Los  Angeles, 
Calif.)  introduced  Smalltalk/V  and  its 
more  powerful  brother,  Smalltalk/V  286. 
And,  with  a  growing  community  of 
devoted  followers,  third-party  support 
has  finally  begun  to  emerge.  Because 
Smalltalk  is  such  an  open-ended  sys¬ 
tem,  this  support  commonly  assumes 
the  form  of  toolkits  that  extend  the 
capabilities  of  Smalltalk’s  built-in  envi¬ 
ronment.  One  such  toolkit  is  the  CX 
Multiprocessing  Extension  Kit  from  Com- 
putas  Expert  Systems. 

The  Goods 

The  CX  Multiprocessing  Extension  Kit 
(the  Kit)  provides  many  useful  exten¬ 
sions  to  the  Smalltalk/V  or  Smalltalk/V 
286  environments.  Within  its  15  sepa¬ 
rate  modules,  the  Kit  provides  extended 
functionality  ranging  from  basic  utility 
methods  all  the  way  up  to  a  complete 
data  acquisition  class  hierarchy.  As  is 
expected  in  the  Smalltalk  world,  source 
code  is  provided  for  all  of  the  classes 
and  methods;  and  filein’s  (scripts  to 
read  source  code  into  the  Smalltalk 
system)  are  available  for  installing  each 
of  the  modules.  Briefly,  the  modules 
include: 

•  Basic  Extensions  —  are  general  meth¬ 
ods  used  by  other  modules  in  the  Kit 

•  Process  Extensions  —  support  the 
creation  of  named  processes,  binding 


variables  to  a  process,  and  assigning 
process  priorities 

•  Semaphore  Extensions  —  provide 
enhancements  to  inter-process  commu¬ 
nications  including  named  semaphores, 
limited-capacity  semaphores,  and  syn¬ 
chronized  message  queues 

•  Screen  Controller  —  allow  updates 
to  partially  obscured  windows  and  dis¬ 
playing  variable  graphic  information 
over  a  constant  background  image 

•  Process  Status  Window  —  imple¬ 
ments  a  standard  window  for  real-time 
monitoring  processes  and  semaphores 

•  Date/TimeServices  —  enhanceSmall- 
talk/V  with  the  ability  to  format  date 
and  time  output,  and  convert  between 
formats 

•  Event  Queue  Mechanism  —  adds 
timed  events  (either  relative  or  abso¬ 
lute  date/time)  and  a  monitor  process 
that  watches  the  system’s  clock  for  event 
triggers 

•  Acknowledge  Mechanism  —  per¬ 
mits  a  background  process  to  tempo¬ 
rarily  gain  control  of  the  user  interface 
for  the  purpose  of  acknowledging  or 
verifying  actions 

•  Data  Acquisition  Protocol  —  imple¬ 
ments  a  class  hierarchy,  under  the  ab¬ 
stract  class  Instrumentation ,  that  pro¬ 
vides  a  complete  Smalltalk/V  interface 
to  the  MicroMac  4000  controller  from 
Analog  Devices.  The  protocol,  which 
serves  as  a  functional  template,  can  be 
modified  to  support  other  types  of  instru¬ 
mentation  controllers  and  subsystems 

•  Miscellaneous  Extensions  —  con¬ 
tain  six  additional  modules  not  directly 
related  to  multiprocessing  including  a 
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Form  Inspector  that  displays  the  con¬ 
tents  of  a  displayable  image;  enhance¬ 
ments  to  Smalltalk/V’s  Freehand  Draw¬ 
ing  (that  is,  painting)  application  and 
its  associated  Bit  Editor;  improvements 
in  the  behavior  of  the  built-in  TextEdi- 
tor  class;  new  versions  of  the  class 
Browsers;  and  an  Application  Browser 

The  Goodies 

Several  of  the  extensions  provided  by 
the  CX  Multiprocessing  Extension  Kit  de¬ 
pend  upon  capabilities  added  by  one  or 
more  of  the  Goodies  disks  available  (as 
options)  from  Digitalk.  These  depend- 
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encies,  as  well  as  the  dependencies  within 
the  Kit’s  internal  modules,  are  clearly 
specified  in  the  documentation. 

Of  primary  concern,  however,  is  the 
lack  of  support  for  multiprocessing  in 
the  original  Smalltalk/V.  Users  of  Small- 
talk/V  must  install  the  Goodies  #\  pack¬ 
age  before  any  of  the  CX  multiprocessing 
extensions  can  be  used.  Users  of  Small¬ 
talk/V  286  do  not  have  this  concern. 

Otherwise,  the  Data  Acquisition  Mod¬ 
ule  depends  upon  the  Digitalk  Com¬ 
munication  Kit  (for  serial  communica¬ 
tions);  the  Freehand  Drawing  extensions 
depend  upon  Goodies  #1  (to  load  and 
store  images);  the  Text  Editor  exten¬ 


sions  require  Goodies  #2;  and  the 
Browser  and  Application  Browser  mod¬ 
ules  need  both  Goodies  #2  and  Good¬ 
ies  #3- 

One  further  note  must  be  offered 
because  it  presents  a  problem  when 
attempting  to  load  the  CX  Multi¬ 
processing  Kit.  Smalltalk/V  and  Small¬ 
talk/V  286  do  not  support  floating  point 
numbers  without  a  math  coprocessor 
present  in  the  system.  The  CX  Data 
Acquisition  module  is  the  only  module 
that  appears  to  require  floating  point 
capabilities.  In  order  to  load  any  other 
modules  from  the  kit  on  a  system  that 
does  not  have  an  80x87,  the  methods 
containsFloat  and  asFloat ,  in  the  Basic 
Extensions  module  (CXBSCEXT.PRJ), 
must  be  commented  out.  (Note:  The 
Goodies  # 2  kit  provides  software  float¬ 
ing  point  support.) 

The  Package 

The  evaluation  copy  I  received  was 
marked  Version  1.0.  It  was  supplied 
on  a  single  3-5-inch  (720K  format)  disk¬ 
ette  (a  5-25-inch  format  is  also  avail¬ 
able).  The  data  necessary  to  build  the 
installation  package  has  been  com¬ 
pressed  into  several  special  .EXE  files. 
One  of  two  batch  files  (one  for  Small¬ 
talk  /  V  and  one  for  Smalltalk  /  V  286) 
are  invoked  to  initiate  the  creation  of 
more  than  60  source  code  and  exam¬ 
ple  files. 

A  concise,  well  written,  105-page  man¬ 
ual  describes  each  of  the  modules  and 
provides  simple  installation  instructions 
in  the  required  sequence.  The  number 
of  examples  given  in  the  manual  is 
somewhat  limited,  although  the  Small¬ 
talk/V  source  code  for  many  others  is 
available  in  various  files.  Consistent  with 
Smalltalk/V’s  tutorial,  these  examples 
can  be  selected  and  executed  using  the 
File  Browser. 

Multiprocessing? 

The  Smalltalk/V  286  Virtual  Machine 
(its  kernel)  contains  support  for  sched¬ 
uling  the  execution  of  multiple  pro¬ 
cesses  with  consideration  for  priority 
levels.  In  the  context  of  Smalltalk,  a 
process  is  a  block  of  code  that  is  capa¬ 
ble  of  executing  as  an  independent 
program.  During  its  lifetime,  a  process 
can  assume  any  one  of  several  states: 
Active,  the  process  is  currently  execut¬ 
ing  and  “owns”  the  computer;  Ready, 
the  process  is  ready  to  run  but  is  wait¬ 
ing  to  be  scheduled  for  execution; 
Blocked,  the  process  is  waiting  for  some 
resource  to  become  available  or  for  some 
event  to  occur  (for  example,  a  signal 
from  another  process);  and  Dead,  the 
code  associated  with  the  process  has 
reached  its  logical  point  of  termination. 

A  process  is  created  by  sending  the 
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message  fork  or  forkAt: aPriority  to  a 
block.  An  example  is  [self  run] forkAt: 2. 
In  response,  the  Smalltalk/V  kernel  will 
create  a  Process  object,  whose  code  is 
the  expression  in  the  block  (’self  run’), 
and  schedule  it  for  execution  at  the 
next  available  opportunity.  That  op¬ 
portunity  comes  when: 

1 .  The  current  active  process  terminates, 
becomes  blocked  or  voluntarily  relin¬ 
quishes  control  by  executing  the  state¬ 
ment  Processor  yield. 

2.  There  are  no  other  ready  processes 
at  a  higher-priority  level. 

3.  There  are  no  other  ready  processes 
at  the  same  priority  level  that  have  been 
ready  for  a  longer  period  of  time. 

Note  that  Smalltalk’s  scheduling  is 
non-preemptive  or  cooperative.  There 
is  no  time  sheer  that  periodically  says 
“Okay  process,  you’ve  had  enough  time. 
Time  to  let  this  other  process  have  its 
chance.”  In  Smalltalk,  it’s  up  to  the 
programmer  to  assure  that  processes 
are  “courteous”  and  periodically  give 
others  a  shot  at  running  the  show. 

By  its  very  nature,  multiprocessing 
capabilities  are  ideally  suited  to  tasks 
such  as  industrial  control  and  monitor¬ 
ing,  and  to  a  class  of  applications  known 
as  discrete  event  simulations.  In  both  of 
these  types  of  applications,  multi¬ 
processing  allows  each  individual  object 
participating  in  the  application  to  be  rep¬ 
resented  by  separate  processes.  Processes 
communicate  with  one  another  by  send¬ 
ing  messages  (via  message  queues)  or 
by  signaling  (via  semaphores)  the  occur¬ 
rence  of  some  event  required  for  coordi¬ 
nating  their  activities. 


Lining  Up  an  Example  Application 

To  demonstrate  the  use  of  multi¬ 
processing  and  apply  some  of  the  many 
features  offered  by  the  CX  Multi¬ 
processing  Kit,  I  have  included  a  sim¬ 
ple  application  that  provides  an  ani¬ 
mated  simulation  of  checkout  counters 
at  a  typical  supermarket.  In  this  appli- 

There  seems  to  be 
little  evidence 
of  redundancy 
or  overkill 


cation,  there  are  five  basic  classes  of 
objects  and  processes: 

1.  Customer  processes  (instances  of 
class  Customer)  enter  a  checkout  line, 
wait  to  be  served,  empty  their  carts, 
and  then  leave. 

2.  Checkout  clerk  processes  (class 
Checker)  accept  items  from  the  cus¬ 
tomer  and  hand  them  off  to  be  put  into 
grocery  sacks. 

3.  Bagger  processes  (class  Bagger)  ac¬ 
cept  items  from  the  checkout  clerk  and 
place  them  into  grocery  sacks. 

4.  Checkout  counter  processes  (in¬ 
stances  of  class  CheckoutCounter)  are 
assigned  one  checkout  clerk,  one 
bagger,  and  a  queue  of  customers  who 
are  waiting  to  be  serviced. 

5.  The  “store”  itself  (represented  by 
the  class  MarketSimulator),  is  a  single 
process  that  generates  new  customers 


and  collects  information  about  the  simu¬ 
lation  as  it  runs.  The  classes  Customer, 
Checker,  Bagger,  and  CheckoutCoun¬ 
ter  are  all  subclasses  of  the  class 
MarketActor.  Listing  One  (page  114) 
lists  the  classes  while  Listing  Two  (page 
118)  lists  the  simulation  program  itself. 

MarketActor  is  an  abstract  superclass 
that  provides  all  of  the  common  func¬ 
tionality  such  as  displaying  and  ani¬ 
mating,  accessing  size  and  position  in¬ 
formation,  and  starting  and  stopping 
the  object’s  associated  process.  The  sub¬ 
classes  add  additional  behaviors  that 
are  more  appropriate  to  the  particular 
type  of  simulated  actor. 

Internally,  the  coordination  between 
the  checkout  counter,  the  customer, 
the  checker,  and  the  bagger  are  carried 
out  by  passing  command  messages  to 
other  processes  using  instances  of  the 
class  MessageQueue  (which  was  added 
by  the  CX  package).  The  typical  se¬ 
quence  of  events  for  this  animated  simu¬ 
lation  is  shown  in  Example  1 . 

All  of  these  interactions  model  quite 
closely  (at  least  in  my  mind)  the  inter¬ 
actions  between  real  people  at  a  check¬ 
out  counter.  Note,  however  that  much 
of  the  interaction  I  have  included  (that 
is,  “take  this  item”  and  “got  it!”)  is  for 
the  purpose  of  animating  the  simula¬ 
tion  and  serves  no  real  purpose  if  the 
goal  were  merely  to  gather  information 
about  the  simulated  process.  Figure  1 
depicts  a  snapshot  of  this  simulation 
while  it  is  running. 

Setting  up 

Setting  up  the  sample  simulation  also 
makes  use  of  some  of  the  tools  pro¬ 
vided  as  part  of  the  CX  Multiprocessing 
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(continued  from  page  86) 

Kit.  In  particular,  the  BitEditor  is  used 
to  create  a  set  of  images  used  in  the 
animation  sequences.  To  do  this,  evalu¬ 
ate  with  doit,  the  Smalltalk  expressions 
shown  in  Example  2. 

Then,  for  each  of  the  keys  ( Person  Up , 
etc.)  evaluate  the  expression  BitEditor 
new  openOn.-  ( Marketlmages  at:  ‘<key>  ’). 
Create  the  animation  images  using  those 
in  Figures  1  -  4  as  a  guide.  Because  the 
BitEditor  uses  a  fixed  scale  and  can 
only  handle  bit  maps  up  to  about  60 
pixels  in  height,  the  individual  images 
should  be  magnified  using  the  expres¬ 
sion  in  Example  3.  Finally,  enter  the 
simulation  classes  in  the  order  shown 
in  Figure  5. 


Open  the  simulation  window  by  evalu¬ 
ating  the  expression  MarketWindow 
new  open.  The  simulation  is  started  by 
popping  up  the  pane  menu,  START 
SIMULATION,  and  clicking  on  it. 

Conclusions 

The  basic  multiprocessing  capabilities 
found  in  the  Smalltalk/V  286  environ¬ 
ment  are  sufficient,  with  some  ingenu¬ 
ity,  to  create  fairly  elaborate  simula¬ 
tions.  The  methods  and  classes  included 
as  part  of  the  CX  Multiprocessing  Ex¬ 
tension  Kit  offer  many  much  needed 
enhancements  to  those  limited  capa¬ 
bilities.  This  is  particularly  true  of  the 
classes  EventQueue  and  Message  Queue, 
which  facilitate  the  implementation  of 


Customer  (upon  removing  an  item  from  the  cart) : 
self 

animate;  "Lean  forward" 
send: #takeltem  to:checker. 

Checker  (upon  receiving  'takeltem'  command): 
self 

animate;  "Turn  to  left"; 
send': #takeltem  to:bagger; 
send:#gotIt  to:customer. 

Bagger  (upon  receiving  'takeltem'  command) : 
self 

animate;  "Turn  to  right" 
send:#gotIt  to:  checker; 
display.  "Turn  back  forward" 

Customer  (upon  receiving  'gotlt'  command) : 
self 

display.  "Stand  up  straight" 

Checker  (upon  receiving  'gotlt'  command  from  bagger) 
self 

display;  "Turn  back  forward  again" 
send : #removeItemFromCart  to : customer . 

Customer  (when  the  cart  is  empty) : 
self 

moveTo: counter  exitPosition;  "Move  to  exit" 
send: InextCustomer  to: counter. 


Example  1:  Typical  sequence  of  events  in  the  checkout  counter  simulation 


Marketlmages 

Marketlmages 

Marketlmages 

Marketlmages 

Marketlmages 

Marketlmages 

Marketlmages 

Marketlmages 


:=  Dictionary  new: 7. 

at : 'PersonUp'  put: (Form  width:16  height:16). 

at : ' PersonRight'  put: (Form  width:16  height:16). 

at : ' PersonDown'  put: (Form  width:16  height:16). 

at : ' PersonLeft'  put : (Form  width: 16  height:16). 

at :' Customer'  put: (Form  width:16  height:32). 

at : ' CustomerReaching'  put: (Form  width:16  height:32). 

at:'Counter'  put: (Form  width:32  height:64). 


Example  2:  Smalltalk  expressions  to  be  evaluated  with  doit 


! oldlmage  newlmage ! 

Marketlmages  keysDo : [ :key ! 

oldlmage  :=  Marketlmages  at: key. 
newlmage  :=  oldlmage  magnify : oldlmage  boundingBox 

by:2@2 . 

Marketlmages  at: key  put : newlmage ] . 


I  Example  3-'  Smalltalk  expression  used  to  magnify  image 
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timed  events  and  interprocess  commu-  extremely  cumbersome  and  prone  to 
nications.  (When  I  first  implemented  the  unexplained  failures.  The  decision  to 
example  application  accompanying  this  pass  command  messages  between  pro¬ 
article,  I  did  so  without  using  the  mes-  cesses  made  the  flow  of  information 
sage  queuing  capabilities.  The  result  was  explicit  and  made  the  entire  application 


Figure  1:  Snapshot  of  the  market  simulation  in  action 


Figure  2:  Animation  image  for  PersonUp 


Figure  3-'  Animation  image  for  Customer 


much  more  understandable.) 

The  package  offers  an  extraordinar¬ 
ily  large  number  of  features,  all  of  which 
appear  to  be  quite  useful  to  the  serious 
Smalltalk/V  developer.  Furthermore, 
there  seems  to  be  little  evidence  of 
redundancy  or  overkill.  Some  of  the 
features,  particularly  the  browser  ex¬ 
tensions,  are  worthy  of  a  review  by 
themselves. 

One  of  the  few  real  faults  I  could 
find  was  the  lack  of  concrete  exam¬ 
ples.  As  seems  to  be  common  practice, 
many  of  the  examples,  while  certainly 
complete  and  accurate,  are  rather  triv¬ 
ial.  To  someone  having  limited  experi¬ 
ence  with  Smalltalk’s  multiprocessing 
features,  that  type  of  example  fails  to 
illustrate  adequately  the  key  concepts 
involved  in  creating  and  coordinating 
multiple  processes.  Personally,  I  would 
prefer  to  see  one  or  two  really  com¬ 
plete  examples  than  a  hundred  ways 
to  print  “hello  world”  using  multiple 
processes. 

From  an  operation  point  of  view,  the 
use  of  named  processes  and  sema¬ 
phores  tends  to  impair  Smalltalk’s  gar¬ 
bage  collection  and  tends  to  leave  in¬ 
accessible  objects  lying  around  un¬ 
claimed.  In  all  fairness,  this  anomaly  is 
documented;  yet  its  occurrence  is  still 
disconcerting.  I  noticed  that  the  use  of 
the  Process  Status  Window  also  seemed 
to  produce  a  similar  effect. 

It  is  noted  that  the  use  of  timed  events 
creates  a  high-priority  background  pro¬ 
cess  to  watch  the  clock  and  look  for 
events  that  need  to  be  triggered.  This 
appeared  to  affect  the  performance  of 
other  parts  of  my  simulation,  slowing 
it  down  considerably.  Thus,  for  exam¬ 
ple,  to  implement  a  “sleep  for  n  sec¬ 
onds”  method,  I  found  that  watching 
the  time  myself  produced  better  results 
than  scheduling  an  event  for  n  seconds 
in  the  future.  Undoubtedly,  for  infre¬ 
quent  events  occurring  at  some  abso¬ 
lute  date/time,  this  feature  would  be 
invaluable;  but  for  short,  repetitive  de¬ 
lay  operations  it  seemed  to  incur  a 
considerable  overhead. 

Finally,  though  the  cost  of  the  exten¬ 
sion  package  itself  is  certainly  reason¬ 
able,  the  hidden  costs  of  the  Goodies, 
required  to  make  full  use  of  its  capa¬ 
bilities,  nearly  triples  the  upfront  cost 
of  using  this  package.  Even  though  the 
Goodies  packages  do  offer  a  lot  of 
added  functionality  at  a  reasonable 
price,  I  feel  it  only  fair  to  warn  the 
potential  user  that  they  represent  an 
additional  cost. 

The  net  result  of  my  experience  ex¬ 
ploring  the  CX  Multiprocessing  Exten¬ 
sion  Kit  was  certainly  positive.  I  have 
gained  additional  insight  into  the  realm 
of  multiprocessing  within  the  context 
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Figure  4:  Animation  image  for  Counter 


Figure  5:  Hierarchy  of  classes  for  the 
market  simulation 


Product  Information 

CX  Multiprocessing  Extension  Kit 
Computas  Expert  Systems 
A.S  (Veritasveien  1) 

P.O.  Box  410 

N-1322  Hovik,  Norway 

Requirements:  Smalltalk/V  2.0  or  later 

Goodies  disks  #1,  #2,  and  #3 

Smalltalk/V  286,  1.1  or  later 

recommended 

Price:  $99.95 


of  Smalltalk  and  feel  certain  that  poten¬ 
tial  users  of  this  package  would  benefit 
from  its  diverse  capabilities. 

But  for  now,  I’m  going  to  get  back 
to  my  simulated  market  and  see  if  I  can 
answer  the  question  that  has  plagued 
modern  man  since  the  opening  of  the 
first  supermarket:  Why  is  the  shortest 
line  always  the  slowest? 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  114.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  8. 
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Accessing  Hardware 
from  80386 

Protected  Mode  Part  I 

Understanding  the  386  architecture  may  simply  be 
a  matter  of  building  on  what  you  already  know 


Stephen  Fried 


At  one  time,  I  ran  a  flight  school 
that  taught  people  how  to  fly 
aircraft  and  sailplanes.  Of  all 
the  equipment  we  operated, 
the  trickiest  to  manage  was  our 
fleet  of  Cessna  L-19  “Bird  Dogs,”  which 
we  used  to  tow  gliders  and  banners. 
The  key  to  transitioning  a  pilot  into  an 
L-19  was  getting  the  idea  across  that 
he  wasn’t  flying  an  ordinary  airplane, 
but  one  which  had  several  distinct  per¬ 
sonalities.  For  example,  if  you  limit  the 
flaps  to  30  degrees  and  the  power  to 
150  HP,  an  L-19  flies  just  like  a  Skyhawk 
or  C-170  (in  fact,  it  has  the  same  wing 
as  both).  However,  when  you  go  to 
full  power,  or  full  flap,  what  you  get  is 
an  airplane  that  performs  much  like  a 
helicopter.  This  split  personality  was 
designed  into  the  L-19  for  the  Army, 
who  used  it  for  forward  air  control  and 
covert  operations  in  Vietnam.  This  same 
performance  made  it  a  great  tow  plane 
but  a  very  expensive  aircraft  to  transi¬ 
tion  pilots  into.  In  fact,  over  a  15  year 
period  we  had  three  major  accidents 
transitioning  experienced  pilots,  and 
the  Civilian  Air  Patrol  (CAP)  lost  so 
many  Bird  Dogs  that  they  were  eventu¬ 
ally  forced  to  sell  them  off. 

Without  a  shadow  of  a  doubt,  the 


Stephen  is  the  vice  president  of  Micro- 
Way’s  R&D.  He  is  well  known  in  the 
field  for  his  PC  numeric  and  HF  chemi¬ 
cal  laser  contributions.  You  can  reach 
him  at  Micro  Way  Inc.,  P.O.  Box  79, 
Kingston,  MA  02364 


“bird  dog”  of  microprocessors  has  to 
be  the  80386.  In  the  case  of  the  L-19, 
our  experienced  pilots  could  argue  for 
hours  about  the  right  way  to  make  a 
landing  (where  you  put  the  flaps  down, 
where  you  added  power,  and  whether 
you  three  pointed  it  or  landed  on  the 
mains).  Transitioning  the  386  from  real 
to  protected  mode  is  every  bit  as  com¬ 
plicated  as  making  a  short  field  landing 
in  a  Bird  Dog.  The  process  involves 
building  tables  in  real  memory,  transi¬ 
tioning  to  protected  mode,  transition¬ 
ing  from  16-  to  32-bit  mode,  building 
paging  tables  and,  finally,  transitioning 
to  paged  mode.  The  exact  sequence 
used  is  a  matter  of  personal  choice, 
and  at  every  stretch  the  processor  and 
the  assembly  code  that  drives  it  has  its 
own  distinct  personality.  The  resulting 
code  is  as  difficult  to  decipher  as  any 
that  has  ever  been  written  for  a  com¬ 
puter. 

Getting  By 

Fortunately,  it  is  not  necessary  for  ordi¬ 
nary  folk  to  get  involved  in  the  writing 
of  kernel  routines.  However,  if  you 
plan  to  directly  access  your  386  AT’s 
facilities,  such  as  the  screen  buffers,  it 
will  be  necessary  to  understand  the 
rudiments  of  80386  memory  manage¬ 
ment  and  how  it  affects  application 
development. 

Just  how  confused  are  people  about 
the  80386?  Our  80386  protected-mode 
compilers  have  been  available  for  over 
two  years,  and  our  products  have  been 


used  to  port  millions  of  lines  of  Fortran 
and  C.  Yet,  as  I  discovered  in  writing 
this  article,  we  had  been  making  an 
incorrect  claim  that  it  was  possible  for 
the  80386  to  run  multiple  segments,  each 
of  which  could  have  up  to  4  gigabytes 
of  code  or  data.  As  we’ll  see  shortly,  this 
assertion  is  not  really  correct. 

When  I  asked  myself  how  I  could 
write  outstanding  code  for  a  processor 
that  I  didn’t  understand,  I  quickly  came 
to  the  conclusion  that  it  wasn’t  neces¬ 
sary  to  understand  the  80386  to  code 
it,  but  to  just  understand  the  two  modes 
that  virtually  all  386  code  runs  in. 

Protected  Mode 

The  majority  of  80386s  running  in  PCs 
see  two  types  of  service:  Real  mode 
and  32-bit  flat  protected  mode.  99.9 
percent  of  all  386  applications,  includ¬ 
ing  those  written  with  DOS  extenders, 
Unix,  Xenix,  and  OS/2,  run  in  32-bit 
flat  protected  mode.  The  mode  is  called 
flat  or  small  because  all  of  the  code  and 
data  of  a  program  exist  in  a  single 
segment,  which  resembles  the  32-bit 
address  space  of  a  typical  mainframe. 
In  the  case  of  DOS  extenders,  the  proc¬ 
essors  slip  in  and  out  of  real  mode  to 
access  MS-DOS. 

Unix,  Xenix,  and  the  future  386  re¬ 
lease  of  OS/2  run  entirely  in  protected 
mode.  Because  these  operating  sys¬ 
tems  are  either  multitasking  or  mul¬ 
tiuser,  the  protection  of  operating  sys¬ 
tem  facilities,  and  therefore  all  hard¬ 
ware,  becomes  a  major  issue.  As  a  re- 
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suit,  these  operating  systems  make  it 
impossible  to  write  the  kind  of  fast 
running  “misbehaved”  applications  that 
are  the  subject  of  this  article.  They  ac¬ 
complish  this  by  running  the  user’s  code 
at  a  low  RPL  (request  privilege  level) 
and  making  system  facilities  only  ac¬ 
cessible  from  code  running  at  a  high 
RPL.  Therefore,  the  subject  of  this  arti¬ 
cle  applies  to  code  running  on  DOS 
extenders  only. 

Probably  the  biggest  problem  with 
learning  the  80386  is  the  fact  that  most 
of  the  books  on  the  subject  were  writ¬ 
ten  for  or  by  operating  system  types. 
As  it  turns  out,  the  80386  has  two  sides: 
A  complex  one  that  takes  months  to 
fully  appreciate  and  a  simple,  physical 
one  that  is  an  almost  trivial  extension 
of  the  8086  architecture. 

A  32-bit  8086 

The  easiest  way  to  approach  this  multi¬ 
personality  processor  is  to  treat  it  like 
a  32-bit  8086  that  can  be  attached  to  a 
piece  of  hardware  that  makes  paged 
memory  possible.  To  help  facilitate  this 
exposition,  imagine  that  the  year  is  1984, 
that  we  work  for  Intel,  and  that  we 
have  been  asked  to  design  a  32-bit 
8086.  (We  will  ignore  the  fact  that  the 
80286  exists  and  that  we  have  been 


asked  to  create  a  processor  that  also 
runs  most  80286  code.) 

Recall  that  the  8086  has  six  general- 
purpose  8/l6-bit  registers  which  were 
adapted  from  similar  8-  and  16-bit  reg¬ 
isters  in  the  8080.  Also  recall  that  the 

There  is  a  movement 
in  the  386  extender 
industry  towards 
running  in  ring  3 
instead  of  ring  0 


address  space  of  the  8086  was  extended 
to  20  bits  by  adding  four  16-bit  seg¬ 
ment  registers  to  the  8080  architecture 
that  point  to  64K-bytes  windows, called 
“segments,”  that  can  be  located  on  any 
of  the  64K  paragraphs  (a  modulo  16 
address)  that  exist  in  a  megabyte  of 
physical  memory. 

Segmentation  was  the  trick  that  made 
the  16-bit  registers  of  the  8086  capable 


of  spanning  a  20  bit  address  space.  The 
problem  we  are  now  faced  with  is  that 
we  want  to  address  more  than  a  mega¬ 
byte  and  we  want  to  use  32-bit  regis¬ 
ters  for  computing  addresses. 

To  generate  an  upward  compatible 
architecture,  we  will  now  mimic  what 
we  did  when  we  expanded  the  8080 
to  16-bits.  We  will  use  segments  to  act 
as  windows  into  the  address  space  and 
let  our  general-purpose  registers  con¬ 
tain  offsets  into  the  segment  windows. 
We  are  now  faced  with  several  prob¬ 
lems.  Our  segments  must  be  capable 
of  holding  a  lot  of  information,  and  to 
keep  segments  from  hogging  valuable 
address  space,  there  should  be  some 
way  to  specify  their  size.  Finally,  to 
simplify  upward  compatibility,  we  will 
stay  with  16-bit  segment  registers. 

What  comes  out  of  these  require¬ 
ments  is  a  segment  that  can  be  located 
at  any  system  address  in  a  32-bit  ad¬ 
dress  space  and  whose  size  is  not  fixed, 
but  specified  by  a  32-bit  integer.  De¬ 
scribing  the  size  and  location  of  a  32- 
bit  segment  in  a  32-bit  address  spade 
takes  64  bits  of  information  and  clearly 
violates  our  desire  to  leave  our  seg¬ 
ment  registers  16  bits  wide.  We  resolve 
this  by  letting  the  segment  register  con¬ 
tain  a  16-bit  index  into  a  table  that  is 
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stored  in  memory  and  contains  the  8 
bytes  needed  to  describe  our  new  32- 
bit  segment.  This  index  is  called  a  “se¬ 
lector,”  and  the  table  it  references  a 
“descriptor  table.”  The  location  of  a 
segment  will  henceforth  be  called  its 
“base,”  and  we  use  the  term  “limit”  to 
describe  its  size. 

To  make  it  possible  for  the  processor 
to  access  descriptors  quickly,  we  incor¬ 
porate  registers  into  the  processor  that 
hold  the  base  and  limit  for  all  the  cur¬ 
rently  active  segments.  We  also  expand 
the  number  of  segment  registers  from 
the  four  of  the  8086  (cs,  ds,  ss,  es )  to 
six,  through  two  new  data  segments, 
fs  and  gs. 

Attribute  Bits 

To  implement  protection,  we  must  free 
up  a  few  of  the  64  bits  that  we  dedi¬ 
cated  to  the  descriptors  above.  We  do 
this  by  reducing  the  size  of  the  limit 
from  32  to  20  bits.  This  limits  the  size 
of  a  segment  to  a  megabyte,  so  we  use 
one  of  the  12  bits  that  have  just  been 
freed  up  to  specify  the  granularity  of  a 
segment.  When  this  bit  is  set  to  zero, 
the  segment  is  said  to  have  “byte  granu¬ 
larity”  and  its  limit  is  a  20-bit  integer. 
When  this  bit  is  1,  the  limit  value  gets 
multiplied  by  4K-bytes,  yielding  a  4- 
gigabyte  upper  value  to  the  limit,  with 
4K  granularity. 

The  other  1 1  bits  that  we  have  carved 
from  our  original  32-bit  limit  are  used 
to  specify  protection  attributes.  These 
include  bits  that  describe  whether  the 
segment  is  a  16-  or  32-bit  attribute  (that 
is,  the  processor  has  a  16-  and  32-bit 
default  mode  specified  by  this  bit),  the 
privilege  level  of  the  segment  CO.  .3),  a 
“present”  bit  (if  this  bit  is  not  set,  the 
selector  is  invalid),  a  DT  bit  that  distin¬ 
guishes  ordinary  memory  segments 
from  those  that  describe  system  re¬ 
sources  (which  are  ignored  here),  and 
four  TYPE  bits  that  specify  16  possible 
usages  for  a  segment  (read-only,  read/ 
write,  execute-only,  execute/read). 

Of  the  12  attribute  bits,  the  only  ones 
that  we  will  encounter  are  those  that 
specify  the  granularity,  protection  level, 
and  segment  TYPE.  The  attribute  bits 
are  used  by  the  processor  to  ensure 
that  every  time  a  byte  is  accessed  from 
memory,  the  program  accessing  the  byte 
has  the  right  to  access  the  byte  in  ques¬ 
tion,  that  the  byte  lies  in  the  segment, 
and  that  it  is  being  used  for  its  intended 
purpose  (you  can  only  execute  code, 
not  data,  and  vice  versa). 

As  a  result  of  the  depth  of  protection 
provided  by  the  processor,  bugs  which 
would  cause  crashes  in  8086  systems, 
cause,  more  often  than  not,  memory 
protection  faults  in  80386  systems.  This 
makes  debugging  much  easier.  You 


simply  run  the  program  under  an  80386 
debugger  and  when  the  processor  hits 
the  fault,  examine  the  program  to  de¬ 
termine  what  caused  an  illegal  access 
request.  It  is  usually  impossible  to  back¬ 
track  after  an  8086  error  because  the 
original  error  destroys  the  processor 
stack,  which  causes  the  CPU  to  jump 
to  data  instead  of  code,  resulting  in 

As  a  result  of  the  depth 
of  protection  provided 
by  the  processor,  bugs 
that  would  cause 
crashes  in  8086  systems 
cause  memory 
protection  faults  in 
80386  systems 


everything  becoming  scrambled.  Errors 
such  as  stack  underflows  cause  imme¬ 
diate  exceptions  in  the  80386,  making 
it  possible  to  backtrack  before  the  pro¬ 
cessor  has  destroyed  the  information 
needed  to  track  down  the  bug. 

General  Registers 

So  far  we  have  spent  all  of  our  time 
worrying  about  how  to  extend  the  con¬ 
cept  of  a  64K  segment  into  a  general- 
purpose  32-bit  segment.  Now  that  we 
have  created  a  32-bit  segmented  frame¬ 
work  for  accessing  information  in  mem¬ 
ory,  we  must  worry  about  extending 
the  size  of  the  six  8086  general-pur¬ 
pose  registers:  ax,  bx,  cx,  dx,  si,  and 
di.  We  will  do  the  same  thing  with 
them  that  we  did  when  we  extended 
the  8080  architecture  from  8  to  16  bits. 
We  create  a  new  32-bit  register  for  each, 
having  its  lowest  16  bits  named  after 
the  corresponding  8086  register,  and 
its  two  lowest  bytes  named  after  the 
8-bit  registers  of  the  8086.  For  example, 
the  16-bit  register  ax,  which  contains 
the  8-bit  registers  al  and  ah  in  the  8086, 
gets  expanded  in  the  80386  into  a  32- 
bit  register  eax,  which  has  a  16-bit  com¬ 
ponent  ax  and  two  8-bit  components 
al  and  ah. 

The  registers  ebx,  esi,  and  edi  are 
used  in  exactly  the  same  manner  as  bx, 
si,  and  di.  We  also  add  some  new 
addressing  modes  that  simplify  accesses 
of  vectors  but,  otherwise,  our  architec¬ 
ture  looks  remarkably  like  an  8086. 


Addresses  are  computed  in  these  32-bit 
registers  and  are  used  as  offsets  into 
the  1-  to  4-gigabyte  segments  that  we 
developed  earlier.  Intersegment  jumps 
and  calls  are  NEAR  in  the  80386,  but 
when  running  in  32-bit  mode,  NEAR 
changes  its  meaning  from  the  16  bits 
of  the  8086  to  32  bits. 

Supporting  Syntax 

To  simplify  the  encoding  of  instruc¬ 
tions,  we  use  the  same  opcodes  for 
mov  eax,  eax  as  we  did  for  mov  ax, 
ax,  and  so  on.  The  size  of  the  register 
operands  is  determined  in  two  ways. 
One  of  the  attribute  bits  in  the  segment 
descriptor  describes  a  segment  as  be¬ 
ing  16  or  32  bits.  In  addition,  when  the 
processor  is  running  in  16-bit  mode,  a 
prefix  byte  can  be  used  ahead  of  an 
instruction  to  indicate  that  the  oper¬ 
ands  of  that  instruction  are  only  32  bits. 
A  similar  prefix  makes  it  possible  to 
use  16-bit  registers  in  32-bit  mode. 

The  use  of  an  override  prefix  makes 
it  possible  to  write  16-bit  code,  which 
accesses  the  32-bit  registers.  However, 
when  running  in  real  mode,  accessing 
32-bit  registers  does  not  buy  much,  as 
the  size  of  segments  in  real  mode  is 
limited  to  64K  and  the  address  space 
is  limited  to  the  first  megabyte.  In  fact, 
we  create  real  mode  to  make  it  possi¬ 
ble  to  run  8086  code  without  doing 
anything,  and  to  provide  an  execution 
environment  for  setting  up  descriptor 
tables  in  memory,  so  that  the  processor 
is  capable  of  setting  itself  up  before 
jumping  into  protected  mode. 

Other  Features 

There  are  a  few  other  features  that  I 
should  at  least  mention.  The  overlooked 
details  include  several  control  regis¬ 
ters,  three  types  of  descriptor  tables, 
task  segment  switches  (48-bit  intraseg¬ 
ment  FAR  calls),  paging  tables,  and 
8086  virtual  mode.  One  of  the  facilities 
that  we  have  to  mention,  the  IDT  (in¬ 
terrupt  descriptor  table)  makes  it  pos¬ 
sible  for  the  processor  to  create  differ¬ 
ent  interrupt  tables  for  different  tasks. 

These  rather  abstract  facilities  make 
it  possible  for  these  two  personality 
processors  to  use  software  control  to 
exhibit  many  other  personalities  (most 
of  which  will  never  see  the  light  of  day 
in  the  real  world).  In  addition,  they 
make  it  possible  to  implement  demand- 
paged  virtual  memory  that  is  very  effi¬ 
cient.  Virtual  memory  is  available  for 
all  of  the  operating  systems  and  envi¬ 
ronments  that  Microway’s  NDP  C  works 
with,  making  it  possible  to  run  main¬ 
frame  programs  on  386  systems  that 
only  have  1  to  2  Mbytes  of  RAM  and  a 
lot  of  free  space  on  a  hard  disk. 
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A  Quick  look  at  the  Map 

The  80386  has  a  “physical”  side  that  is 
quite  close  to  the  physical  side  pre¬ 
sented  by  the  8086,  and  an  abstract 
side  that  we  can  ignore.  We  will  now 
examine  this  physical  side  and  make 
the  connection  between  the  environ¬ 
ment  of  our  protected-mode  applica¬ 
tion  and  the  real-mode  resources  that 
the  processor  takes  advantage  of  for 
doing  I/O  in  an  80386  “AT”  system. 

Figure  1  shows  the  local  descriptors 
for  a  program  running  under  Phar  Lap 
with  the  no  page  switch  on.  These 
values  were  obtained  by  running  an 
NDP  C  program  under  the  Phar  Lap 
386DEBUG  program  and  using  the  ell 
command  to  dump  the  local  descriptor 
table.  The  selector  numbers  on  the  left 
side  of  the  table  are  the  values  that  a 
programmer  passes  into  the  386  seg¬ 
ment  registers  to  activate  a  segment. 
Because  386DEBUG  was  invoked  with 
paging  off,  the  BASE  values  in  Figure 
1  correspond  to  physical  addresses. 

The  memory  map  has  a  number  of 
these  selectors  pinpointed  on  its  left 
side.  Looking  at  selectors  0C  and  14, 
we  see  that  their  corresponding  seg¬ 
ments  are  located  at  the  start  of  what 
IBM  calls  “extended  memory”  (the  start 
of  the  second  megabyte  of  memory). 
If  we  had  invoked  386DEBUG  with 
paging  on,  the  primary  difference  in 
our  segment  memory  map  would  be 
that  0C  and  14  would  be  moved  down 
into  the  first  megabyte  to  save  memory. 
However,  with  paging  enabled,  it  would 
not  be  possible  to  read  the  physical 
location  of  a  segment  from  the  selector 
BASE  value,  as  the  processor  performs 
an  additional  address  translation  with 
paging  enabled.  Therefore,  we  will  ex¬ 
amine  some  of  the  selectors  in  Figure 
1  that  have  been  set  up  by  the  DOS 
extender  before  going  on  to  see  what 
happens  when  paging  is  enabled. 

Selector  1C  has  been  set  up  so  that 
it  contains  the  current  screen  buffer. 
This  selector  has  a  base  that  starts  at 
address  0B800:0  (in  8086  notation)  and 
is  OFFFH  +  1  byte  in  length  ( 16K  bytes). 
The  fact  that  this  segment  corresponds 
exactly  to  the  screen  buffer  was  no 
accident.  The  Phar  Lap  DOS  Extender 
queried  the  system  to  find  out  what 
kind  of  graphics  adapter  was  active, 
and  based  on  this  information  created 
an  entry  in  the  LDT  (local  descriptor 
table)  that  precisely  matched  the  de¬ 
vice.  It  is  also  important  to  point  out 
that  the  use  of  selector  1CH  is  preferred 
over  selector  34H  (which  maps  in  the 
entire  first  megabyte  of  RAM)  for  screen 
buffer  accesses,  because  an  out-of- 
bounds  write  will  result  in  a  protection 
fault  when  using  1CH,  but  could  have 
disastrous  results  if  34H  were  used. 
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The  selectors  OCH  and  14H  were 
created  for  user  code  and  data.  Note 
that  these  selectors  have  the  same  loca¬ 
tion  base  and  limit.  In  fact,  they  are 
identical  in  every  way,  except  for  the 
attribute  flags.  The  format  of  the  attrib¬ 
ute  byte  is: 

upper  lower 

!  P  I DPL !  DT 1  ITYPE! 

Looking  over  the  memory  map,  we 
see  that  the  flag  byte  has  only  two 
values:  92H  and  9AH.  The  lower  nibble 
in  92H  indicates  that  the  segment  is  of 
type  2,  which  means  the  segment  is 
read/write  (for  data  only).  All  but  one 
of  the  segments  must  therefore  contain 
data.  Looking  at  the  map,  we  discover 
that  the  segment  that  we  have  identi¬ 
fied  with  “user  code”  has  an  attribute 
of  9A.  The  TYPE  nibble,  OAH,  indicates 
that  selector,  OCH,  is  execute/read  only 
(code). 

The  upper  nibble  contains  miscella¬ 
neous  information  about  the  segment, 
including  the  present  bit,  two  bits  that 
specify  the  privilege  level,  and  a  bit 
which,  when  set,  specifies  that  the  de¬ 
scriptor  describes  memory  (as  opposed 
to  a  task  switch  or  special  system  en¬ 
tity).  The  binary  translation  of  9  is  1001, 
which  translates  into  the  segment 
marked  as  present  in  memory  with  a 
privilege  level  of  0.  Privilege  level  0  is 
the  highest  available,  and  is  frequently 
referred  to  as  “ring  0.” 

Segments  that  run  in  ring  0  are  theo¬ 
retically  capable  of  creating  havoc  by 
playing  games  with  systems’  tables  that 
should  only  be  accessed  by  the  operat¬ 
ing  system  or  DOS  extender.  As  a  prac¬ 
tical  matter,  the  only  time  we  have  had 
to  deal  with  invisible  system  tables, 
such  as  the  global  descriptors,  was  in 
the  early  80386  days,  before  the  DOS 
extenders  had  calls  for  mapping  in  new 
hardware,  such  as  the  Weitek  copro¬ 
cessor  (which  is  now  automatically 
mapped  in  by  all  DOS  extenders). 

As  long  as  the  program  you  write 
goes  through  systems  calls  provided 
by  Phar  Lap  and  Eclipse  to  modify  lower- 
level  system  tables,  such  as  the  inter¬ 
rupt  descriptor  table,  the  program  that 
results  will  conform  to  the  VCPI  speci¬ 
fication,  which  means  it  will  run  with 
VCPI  operating  environments,  such  as 
Desqview-386,  Netware-386,  Phar  Lap, 
and  Eclipse. 

As  a  point  of  interest,  Eclipse  runs 
programs  in  ring  3.  There  is  a  move¬ 
ment  in  the  386  extender  industry  to¬ 
ward  running  in  ring  3  instead  of  ring 
0.  As  long  as  the  operating  environ¬ 
ments  continue  to  provide  the  memory 
mapping  capabilities  that  are  utilized 


below,  we  have  no  objection  to  run¬ 
ning  in  ring  3  over  0.  However,  we 
think  there  is,  and  will  continue  to  be, 
a  need  for  operating  environments  that 
provide  direct  access  to  all  system  re¬ 
sources,  as  a  counter  measure  to  oper¬ 
ating  systems  such  as  OS/2  and  Unix, 
which  are  attempting  to  shut  off  access 
to  these  facilities. 

Real  Memory  from  Protected  Mode 

To  move  a  block  of  characters  and 
attributes  into  screen  RAM  in  an  8086 
system,  we  might  employ  a  block  move. 
This  technique  is  frequently  used  by 
spreadsheets  that  build  an  image  in 
memory  of  what  the  screen  is  going  to 
contain  and  then  instantaneously  move 
this  buffer  to  screen  RAM  by  using  a 
single  processor  instruction.  To  set  up 
a  block  move  in  an  8086,  we  point  the 
ds.si  registers  at  the  source,  the  es.di 
registers  at  the  destination,  place  the 
number  of  bytes  to  be  moved  in  cxand 
then  use  a  rep  movsb  instruction  to 
have  the  processor  make  the  transfer 
for  us. 

The  code  for  an  80386  block  move 
is  identical,  except  that  we  now  use 
32-bit  registers  to  hold  32-bit  offsets, 
and  where  we  used  physical  paragraphs 
in  ds  and  es,  we  now  use  the  appropri¬ 
ate  selectors.  In  addition,  where  we 
placed  the  count  in  cx,  we  now  place 
the  count  in  ecx,  which  is  a  32-bit  regis¬ 
ter  and  makes  it  possible  to  move  more 
than  64K  with  a  single  instruction.  For 


example,  to  move  a  16K  buffer  of  char¬ 
acter  attribute  pairs  to  a  monochrome 
screen  buffer  located  at  paragraph  B800, 
we  would  employ  one  of  the  two  se¬ 
quences  of  code  shown  in  Figure  2, 
depending  on  whether  we  were  run¬ 
ning  in  real  mode  or  80386  32-bit  mode 
under  Phar  Lap. 

The  program  assumes  that  the  buffer 
being  moved  is  contained  by  the  cur¬ 
rent  data  segment  in  ds.  It  then  sets  up 
a  FAR  pointer  to  the  destination  (screen 
buffer  at  B800:0).  Note  that  where  the 
real-mode  code  used  the  physical  para¬ 
graph  of  the  screen  buffer,  the  80386 
uses  the  selector  set  up  by  Phar  Lap. 
Next,  the  code  points  si  or  esi  at  the 
buffer  to  be  moved.  Again,  note  that 
where  a  16-bit  offset  was  used  by  the 
real  mode  code,  a  32-bit  offset  is  now 
being  used  by  the  80386  for  the  32-bit 
code.  Finally,  the  program  sets  the  num¬ 
ber  of  bytes  to  be  moved  in  cx  or  ecx, 
and  requests  the  processor  to  carry  out 
the  block  move.  Except  for  the  first 
line,  these  two  sequences  are  virtually 
identical. 

Because  the  selectors  in  Figure  1  can 
access  all  of  the  memory  in  the  first 
physical  megabyte  of  RAM,  we  have 
just  demonstrated  that  it  is  possible  to 
access  all  of  a  system’s  “real”  memory 
from  a  program  running  in  protected 
mode.  In  our  example,  the  source  buffer 
is  contained  by  the  default  data  seg¬ 
ment,  14H,  which  is  located  in  “extended” 
memory  above  the  first  megabyte. 


Selector 

BASE 

Limit 

Flags 

Use 

Gran 

Comment 

04 

53030 

FF 

92 

32 

BYTE 

DOS  EXTEND 

OC 

100000 

2FF 

9A 

32 

BYTE 

USER  CODE 

14 

100000 

2FF 

92 

32 

BYTE 

USER  DATA 

1C 

B8000 

FFF 

92 

32 

BYTE 

DOS  SCREEN 

24 

53030 

FF 

92 

32 

BYTE 

DOS  EXTEND 

2C 

52f60 

B9 

92 

32 

BYTE 

DOS  EXTEND 

34 

00000000 

FFFFF 

92 

32 

BYTE 

1st  MEG 

3C 

COOOOOOO 

FFFF 

92 

32 

BYTE 

WEITEK 

Figure  1:  The  local  descriptors  for  a  program  running  under  Phar  Lap 


Real  mode  32-bit  protected  mode 


mov 

ax,0B800H 

mov 

eax.lCH 

;  set  destination 

mov 

es,ax 

mov 

es,ax 

;  segment 

xor 

di,di 

xor 

edi,edi 

;  dest  offset  =  0 

mov 

si, buffer 

mov 

esi, buffer 

;  set  source  offset 

mov 

CX.1000H 

mov 

ecx,1000H 

;  set  count 

rep 

movsb 

rep 

movsb 

;  perform  block  move 

Figure  2:  16-bit  vs.  32-bit  assembly  code  to  move  a  16K  buffer  of  character 
attribute  pairs  to  a  monochrome  screen  buffer 
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(Continued  from  page  96) 

48-bit  Address  Space? 

All  that  remains  to  our  expose  of  the 
386’s  flat  model  is  to  explore  the  opera¬ 
tion  of  ports,  interrupts,  and  paging. 
However,  before  we  leave  segmenta¬ 
tion,  there  is  one  myth  we  need  to 
burst.  The  typical  text  on  the  80386 
presents  the  processor  as  having  three 

To  move 
a  block  of 
characters  and 
attributes  into 
screen  RAM  in 
an  8086  system, 
we  might  employ  a 
block  move 


address  spaces  —  virtual,  linear,  and 
physical.  Up  to  this  point,  what  we 
have  been  exploring  is  the  linear  and 
physical,  which  are  both  identical  when 
paging  is  disabled.  The  mythical  ad¬ 
dress  space  turns  out  to  be  the  “virtual” 
one.  The  myth  was  born  because  indi¬ 
viduals  who  were  used  to  program¬ 
ming  in  the  large  or  huge  models  on 
the  8086  asked,  “What  would  happen 
if  we  could  write  large  or  huge  code 
on  an  80386,  instead  of  small  code?” 
They  quickly  came  to  the  conclusion 
that  programs  written  with  compilers, 
and  operating  systems  that  support  48- 
bit  pointers  (the  16-bits  of  the  selector 
count  for  16-  and  the  32-bit  maximum 
size  of  the  limit  count  for  32),  would 
be  capable  of  addressing  a  48-bit  ad¬ 
dress  space,  which  just  happens  to  con¬ 
tain  64  terrabytes! 

We  don’t  know  who  created  this  con¬ 
cept,  although  we  suspect  that  Intel 
marketing  told  its  systems’  architects 
(after  the  last  perceived  black  eye  they 
got  from  a  segmented  architecture)  that 
if  they  had  to  resort  to  segmentation 
again,  they  better  have  a  damn  good 
reason.  The  reality  of  the  situation  is 
that  practical  program  size  is  limited 
by  the  size  of  what  Intel  calls  the  “lin¬ 
ear”  address  space  (to  32-bits),  and 
that  a  48-bit  address  space  will  not 
become  a  reality  until  Intel  increases 
the  size  of  the  linear  address  space  in 
a  future  device. 


To  prove  the  point,  we  did  a  calcula¬ 
tion  of  what  would  happen  if  we  took 
a  simple  program  that  performed  a  ma¬ 
trix  multiply  and  extended  it  to  handle 
arrays  whose  total  size  was  greater  than 
4  gigabytes.  As  the  total  size  of  the 
arrays  in  our  problem  approach  4  giga¬ 
bytes  (each  of  the  three  arrays  approach 
1.3  gigabytes),  we  have  to  abandon 
our  80386  small  model,  and  Phar  Lap, 
in  favor  of  a  compiler-supported  mem¬ 
ory  model  and  operating  system  that 
utilizes  the  virtual  address  space  (which 
is  not  the  same  as  demand-paged  vir¬ 
tual  memory,  which  we  commonly  re¬ 
fer  to  as  “virtual  memory”). 

Once  our  problem  hits  the  1 .4-giga¬ 
byte  array  size,  it  is  impossible  to  have 
all  three  arrays  in  our  4-gigabyte  linear 
address  space  at  the  same  time.  So, 
we  take  advantage  of  the  present  bit 
in  the  descriptor  table  to  make  it  possi¬ 
ble  for  our  large  model  operating  sys¬ 
tem  to  swap  arrays  as  needed.  Our 
large  model  operating  system  makes  it 
possible  to  run  large  model  virtual  seg¬ 
ments.  When  we  compute  the  time  re¬ 
quired  to  swap  our  1.4-gigabyte  seg¬ 
ments  as  required  by  our  algorithm, 
we  discover  that,  assuming  we  have 
the  world’s  fastest  hard  disks,  our  code 
runs  100,000  times  slower  than  it  did 
in  the  small  model  currently  supported 
by  Phar  Lap,  Unix,  and  Xenix. 

The  largest  sized  array  that  our  large 
model  supports  is  4  gigabytes,  which 
means  our  problem  will  span  a  tiny  (in 
comparison  to  64  terrabytes)  12-giga- 
byte  address  space.  But  never  fear,  we 
have  still  not  finished  digging  into  our 
bag  of  8086  tricks.  By  resurrecting  FAR 
pointers,  the  huge  model,  and  tiling, 
we  can  hit  our  64  terrabyte  goal  —  and 
for  only  a  cost  factor  of  400  percent  in 
code  efficiency. 

What's  Next? 

That  these  systems  tricks  are  crucial  for 
future  Intel  products  is  quite  evident 
from  the  80486,  which,  unlike  the  80386, 
achieves  its  best  speed  with  small  model 
code  that  limits  data  accesses  to  the  ds 
segment  register  only.  It’s  amazing  what 
happens  to  the  best  laid  plans  of  prod¬ 
uct  managers,  public  relations,  and  sys¬ 
tem  types,  when  everyone  suddenly 
discovers  that  the  key  to  selling  sys¬ 
tems  is  simplicity  (i.e.,  RISC)!  But,  I 
hope  to  convince  you  next  month  in 
Part  II  of  this  article  that  the  only  use 
for  FAR  pointers  in  80386  code  appear 
in  operating  system  kernels. 
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Listing  One  (Text  begins  on  page  30.) 


//  GETDATA.C  Read  GBLDATA . OBJ  to 
//  02/12/89  by  Gary  Syck 

#include  <stdio.h> 

♦include  <fcntl.h> 

♦include  <io.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦include  <dos.h> 

♦include  "dll.h" 

//  Open  GBLDATA  and  read  data 
void 

GetData () 

{ 

int  fd; 
int  Idx; 

unsigned  long  Elmnts,  DSize; 
unsigned  PubGrp,  PubSeg; 
unsigned  DOff; 
unsigned  char  type; 
int  size; 
unsigned  char  *Data; 
unsigned  char  *DSptr; 
int  i,  j; 


get  global  variables  for  DLLs 


//  File  descriptor  for  GBLDATA. OBJ 
//  Index  numbers  from  the  file 
//  Number  and  size  of  global  data  items 
//  Group  and  segment  indexes  for  data 
//  Offset  for  initialized  data 
//  type  of  record  read 
//  size  of  the  record 
//  the  data  to  read 
//  Pointer  to  the  Data  segment 


if ( (fd=open (  "gbldata.obj",  0  BINARY ! 0  RDONLY  ) )  ==  -1  ) 

i 

printf(  "Unable  to  open  file\n"  ); 
exit {1) ; 

} 

DataSize  =  0; 

SymCnt  =  0; 

AllocNumb  =0; 

SymSize  *  0; 
type  =  0; 

DSptr  -  SDataSpace; 
while (  type  !=  MODEND  ) 

{ 

read{  fd,  (char  *)  itype,  sizeof(  unsigned  char  )); 
read(  fd,  (char  *)  &size,  sizeof(  int  )); 

Data  =  malloc(  size  ); 
read(  fd,  Data,  size  ); 
switch (  type  ) 

{ 

case  PUBDEF :  //  The  record  contains  public  symbols 

i=0; 

if (  Data[i]&0x80  ) 

{ 


PubGrp  -  (Data [i++] &0x7f ) «8; 
PubGrp  +-  Data[i++j; 


else 


PubGrp  “  Data[i++]; 
if(  Data[i]S0x80  ) 

{ 


PubSeg  =  (Data[i++]&0x7f)«8; 
PubSeg  +-  Data[i++j; 

} 

else 


PubSeg  =  Data[i++]; 
if  (  PubSeg  ==  0  ) 

i  +=  2;  //  skip  the  frame  number 

AllocateSyms () ;  //  make  memory  for  all  symbols 
/*  assume  all  public  defs  are  in  the  DGROUP  */ 
while (  i<size-l  ) 

{ 


Syms [SymCnt] .Name [Data [i] ]  =  '\0'; 

i  +=  Data[ij  +  2; 

if (  Data[i++]  ==  0x61  ) 

{ 

if(  Data[i]  <  128  ) 

Elmnts  =  (unsigned  long)  Data[i++]; 
else 


{ 

j  =  Data[i++]  -  127; 

Elmnts  =  OL; 

memcpyf  sElmnts,  &Data[i],  j  ); 
i  +=  j; 

) 

if(  Data[i]  <  128  ) 

DSize  =  (unsigned  long)  Data[i++]; 
else 
{ 

j  =  Data[i++]  -  127; 

DSize  =  OL; 

memcpy(  &DSize,  &Data[i],  j  ); 
i  +«  j; 

) 

Syms [SymCnt] .Size  =  (unsigned) 

(Elmnts  *  DSize); 
if (  (unsigned  long)  SymSize  + 

(unsigned  long)  (Elmnts  * 

DSize)  >=  32000L  ) 

AllocateSyms () ; 

SymSize  +=  (unsigned)  (Elmnts  * 

DSize) ; 

SymCnt ++; 

1 

) 

break; 

default : 

break; 


free (  Data  ) ; 

) 

close (  fd  ) ; 

AllocateSyms () ;  //  make  memory  for  all  of  the  symbols 

} 

//  make  a  memory  block  to  hold  the  previous  symbols 
void 

AllocateSyms () 

{ 

char  *Buff; 
unsigned  Seg,  Off; 
if (  SymSize  ) 

< 

Buff  -  malloc(  SymSize  ); 

Seg  =  FP_SEG (  Buff  ); 

Off  =  FP_OFF(  Buff  ) ; 

SymSize  =  0; 

while {  AllocNumb  <  SymCnt  ) 

{ 

Syms [AllocNumb] .Seg  =  Seg; 

Syms [AllocNumb] .Of fset  =  Off; 

Off  +=  Syms [AllocNumb] .Size; 
AllocNumb++; 

} 

I 

) 


End  Listing  One 


Syms [SymCnt] .Name  =  malloc(  Data[i]  +  2  ); 
strncpy (  Syms [SymCnt] .Name,  &Data[i+l], 

Data [i] 

Syms [SymCnt] .Name [Data [i] ]  =  '\0'; 
i  +=*  Data[ij+1; 

Syms [SymCnt] .Seg  =  FP_SEG (DSptr) ; 

Syms [SymCnt] .Offset  =  (FP_OFF (DSptr) ) + 

*((int  *)  &Data[i] 


Listing  Two 

;  STUB. ASM  Used  by  DLL  to  see  if  a  function  needs  to  be  loaded. 
;  02/12/89  By  Gary  Syck 


SymCnt ++; 
i  +=  2; 

if (  Data[i]&0x80  )  //  skip  over  the  type 

{ 

Idx  =  (Data  [i++] &0x7f )  «8; 
Idx  +=  Data[i++]; 


else 

Idx  =  Data[i++]; 

/*  Assume  all  data  is  for  the  data  segment  */ 
DOff  =  *  ( (int  *)  &Data[i]  ); 
i  +=  2; 

memcpy(  &DSptr [DOff] ,  &Data[i],  size-(i+l)  ); 
if(  DataSize  <  DOff  +  size  -  (i+1)) 

DataSize  =  DOff  +  size  -  (i+1); 

break; 

case  COMDEF:  //  record  contains  uninitialized  data 
i  =  0; 

while (  i  <  size-1  ) 

{ 

Syms [SymCnt] .Name  =  malloc(  Data[i]+2  ); 
strncpy (  Syms [SymCnt] .Name,  &Data[i+l], 

Datafi]  ); 


TITLE  stub. asm 
NAME  stub 


.8087 
STUBJTEXT 
STUB  TEXT 


SEGMENT 
ENDS 


WORD  PUBLIC  'CODE' 


} 

DATA 

SEGMENT 

WORD  PUBLIC  ' 

r  DATA' 

else 

DATA 

ENDS 

Idx  =  Data[i++]; 

CONST 

SEGMENT 

WORD  PUBLIC  ' 

’CONST' 

} 

CONST 

ENDS 

break; 

BSS 

SEGMENT 

WORD  PUBLIC  ' 

’BSS' 

LEDATA:  //  record  contains  data  for  data  segment 

BSS 

ENDS 

i  =  0; 

DGROUP 

GROUP 

CONST,  BSS, 

DATA 

if (  Data[i]&0x80  ) 

ASSUME 

CS:  STUB  TEXT^ 

7  DS :  DGROUP, 

SS:  DGROUP 

{ 

EXTRN 

LoadFunc : FAR 

;  Function 

to  get  a  function 

Idx  =  (Data  [i++] &0x7f )  «8; 

EXTRN 

FuncLst 

. : DWORD 

;  The  function  table 

Idx  +=  Data[i++]; 

DATA 

SEGMENT 

_DataSpace 
db  32000  dup (?) 


PUBLIC 
_DataSpace 
DATA  ENDS 


STUBJTEXT  SEGMENT 

ASSUME  CS:  STUBJTEXT 
PUBLIC  _Stub 
Stub  PROC  FAR 


mov 

mov 

mov 

mov 

or 

jne 

push 

push 

call 


bx, offset  _FuncLst 
ax, seg  _FuncLst 
es,  ax 

ax, WORD  PTR  es: [bx+4] 

ax, WORD  PTR  es: [bx+6] 

noload 

es 

bx 

FAR  PTR  LoadFunc 


;  this  is  modified  before  use 


;  save  ES  and  BX 
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pop 

pop 

noload: 

jmp 

_Stub  ENDP 

STUB_TEXT 

END 


DWORD  PTR  es: [bx+4] 


;  go  to  the  function 


End  Listing  Two 


strcpy(  FuncLst [FuncCnt] .Name,  Name  ); 
FuncLst [FuncCnt] .Loc  =  NULL; 

FuncLst [FuncCnt) .Flag  =  0; 
memcpy (  FuncLst [FuncCnt] . Stub, 

Stub,  STUBSIZE  ) ; 
memcpy ( SFuncLst [ FuncCnt ] . Stub [ 4 ] 

, &  FuncLst [ FuncCnt ] , 2 ) ; 
FuncCnt++; 

} 

ExtSyms [Extent] .Flag  =  2; 

Ext Syms [Extent] .SymNumb  =  j; 


Listing  Three 


//  LINKER. C  Link  a  module  at  run  time 
//  02/12/89  by  Gary  Syck 
♦include  <stdio.h> 

♦include  <string.h> 

♦include  <fcntl.h> 

♦include  <io.h> 

♦include  <stdlib.h> 

♦include  "dll.h" 

//  Load  the  function  in  the  FUNCTAB  entry 
void 

LoadFunc (  FUNCTAB  *func  ) 

{ 

char  FileName [15] ,  *p,  Name [80]; 
int  fd; 
unsigned  char  type; 
int  size; 

unsigned  char  *Data,  *Dp,  ‘LastFunc; 
int  i,  j,  In; 

unsigned  pubgrp,  pubseg,  dataseg; 
unsigned  DROff,  Loc,  FixDat; 
unsigned  Frameldx,  Targetldx,  TargetDisp,  tmp; 
unsigned  long  ltmp; 


int  dataoff; 
unsigned  LocalSize; 
struct  ( 

int  Flag; 
int  SymNumb; 

]  ExtSyms [20]; 
int  Extent; 
struct  { 

int  FuncNumb; 
int  Offset; 

]  Pubs [10]; 
int  PubCnt; 
struct  [ 

unsigned  Meth; 
unsigned  Idx; 

]  Threads [8]; 
void  *ptr; 

unsigned  char  *DSptr; 
unsigned  constseg; 


//  size  of  the  data  allocated  here 


//  1  =  data,  2  =  function 
//  What  symbol 


//  The  method  to  use 
//  The  index 


//  Where  constants  begin 


strncpy(  FileName,  &func->Name[l] ,  14  ); 

FileName [14]  =  ' \0'; 

if ( (p=strchr (  FileName,  '♦'  ))  !=  NULL  ) 

*p  =  ' \0' ; 

strcat(  FileName,  ".obj"  ); 

if ( (fd=open (  FileName,  0_RD0NLY:0_BINARY  ) )  ==  -1  ) 

{ 

printf(  "Unable  to  open  file:  %s\n",  FileName  ); 
return; 

} 

LocalSize  =  0; 

Extent  =  0; 

PubCnt  =  0; 
type  =  0; 

DSptr  =  SDataSpace; 
while (  type  !=  MODEND  ) 

{ 

read(  fd,  (char  *)  &type,  sizeof(  unsigned  char  )); 
read(  fd,  (char  *)  &size,  sizeof(  int  )); 

Data  =  malloc(  size  ); 
read(  fd,  Data,  size  ); 
switch (  type  ) 


case  THEADR: 
case  COMMENT: 
case  GRPDEF: 
case  MODEND: 
case  SEGDEF: 
case  LNAMES : 

break; 

case  EXTDEF : 


//  ignore  the  header 

//  ignore  comments 

//  these  are  always  the  same 


//  find  external  names 


for(  i=0;  i<size-l;  i  +=  ln+2  ) 

{ 

In  =  Data [i] ; 
if (  In  ) 

{ 

strncpy(  Name,  &Data[i+l],  In  ); 

Name [In]  =  ' \0' ; 

for(  j=0;  j<SymCnt  &&  strcmp( 

Syms [j] .Name,  Name  );j++); 
if (  j<SymCnt  ) 
f 

ExtSyms [ExtCnt] .Flag  =  1; 

ExtSyms [ExtCnt] . SymNumb  =  j; 

} 

else 


break; 

case  PUBDEF:  //  add  to 

i  =  0; 

if(  Data[i]&0x80  ) 


//  add  to  list  of  available  functions 


pubgrp  =  (Data [ i++] &0x7f )  «  8; 
pubgrp  +=  Data[i++j; 

} 

else 

pubgrp  =  Data[i++]; 
if  (  Data [i] &0x80  ) 

( 

pubseg  =  (Data [i++] &0x7f )  «  8; 
pubseg  +=  Data[i++j; 

} 

else 

pubseg  =  Data[i++]; 

if(  pubseg  ==  0  )  //  skip  the  frame 

i  +=  2; 

while (  i  <  size-1  ) 

{ 

In  =  Data[i] ? 
if(  In  ) 

{ 

strncpy(  Name,  &Data[i+l],  In  ); 
Name [In]  =  '\0'; 

} 

i  +=  In  +  1; 

memcpy (  &ln,  &Data[i],  sizeof(  int  )); 
i  +=  2; 

if (  Data[i]&0x80  ) 
i  +=  2; 

else 

i++; 

for(  j=0;  j<FuncCnt 

&&  strcmp(  FuncLst [j] .Name, 


(Listing  continued  on  page  106) 


for(  j=0;  j<FuncCnt 

&&  strcmp(  FuncLst [j] .Name, Name  );j++); 
if (  j>=FuncCnt  )  //  make  space  for  it 

FuncLst [FuncCnt] .Name  =  malloc 

(strlen (Name) +2  ); 


Dr.  Dobb’s Journal,  May  1990 

448 


105 


LINK  LIBRARIES 


Listing  Three  ( Listing  continued,  text  begins  on  page  30.) 

Name  ) ;  j++  ) ; 
Pubs [PubCnt] .FuncNumb  =  j; 

Pubs [PubCnt] .OffSet  =  In; 

PubCnt++; 

} 

break; 

case  LEDATA: 

i  =  0; 

if (  Data[i]&0x80  ) 

{ 

dataseg  =  (Data[i++]&0x7f)  «  8; 
dataseg  +=  Data[i++j; 

} 

else 

dataseg  =  Data[i++]; 

memcpy{  Sdataoff,  &Data[i],  sizeof(  int  )); 
i  +=  sizeof {  int  ) ; 

if(  dataseg  ==  2  )  //  it's  for  the  data  segment 
{ 

Dp  =  &DSptr  (DataSize+dataoff  ] ;. 
memcpy(  Dp,  &Data[i],  size  -  (  i+1  )); 
if (  LocalSize  <  dataoff  +  size  -  (i+1)) 
LocalSize  =  dataoff  +  size  -  (i+1); 
constseg  =  LocalSize+DataSize; 

) 

else  if (  dataseg  ==  3  )  //  for  const  segment 
{ 

Dp  =  SDSptr (constseg+dataoff ] ; 
memcpy(  Dp,  &Data[i],  size  -  (  i+1  )); 
if (  LocalSize  <  dataoff  +  size  -  (i+1)) 
LocalSize  =  dataoff  +  size  -  (i+1); 

) 

else  //  here  is  the  code 
( 

if (  dataoff  ==  0  ) 

LastFunc  =  malloc(  size  -  (i+1)  ); 

else 

LastFunc  =  realloc (  LastFunc,  size 

-  (i+1)  +  dataoff  ); 
Dp  =  SLastFunc [dataoff ] ; 
memcpy(  Dp,  &Data[i],  size- (i+1)); 
for(  j=0;  j<PubCnt;  j++  ) 

( 

FuncLst [Pubs [ j ] . FuncNumb  J . Loc 
=  &Last-  Func[Pubs[j] .Offset] ; 

) 

) 

break; 

case  FIXUPP:  //  only  look  at  the  fixup  fields  all 
//  threads  are  the  same, 
i  =  0; 


while (  i  <  size-1  ) 

( 

if(  (Data[i] ) &0x80  )  //  its  a  fixup 

( 

DROff  =  ( (Data[i]s3)«8)  +  Data  [i+1]; 
Loc  =  Data [i] ; 
i  +=  2; 

FixDat  =  Data[i++]; 

Frameldx  =  Targetldx  =  TargetDisp  =  0; 
if (  ! (FixDat&0x80)  &&  (FixDat&0x70) 

!=  0x50  ) 

/*  there  is  a  frame  index  */ 

{ 

if(  Data[i]&0x80  ) 

( 

Frameldx  =  (Data [i++] S0x7f )  «  8; 
Frameldx  +=  Data[i++j; 

) 

else 

Frameldx  =  Data[i++]; 

) 

if(  ! (FixDat&8)  )  /*  thread  index  */ 

( 

if (  Data[i]&0x80  ) 

( 

Targetldx  =  (Data [i++] &0x7f )  «  8; 

Targetldx  +=  Data[i++]; 

) 

else 

Targetldx  =  Data[i++]; 

) 

if (  ! (FixDat&4)  ) 

( 

memcpy(  &TargetDisp,  &Data[i], 

sizeof (  int  )); 

i  +=  2; 

) 

/*  fix  up  FixDat  from  threads  */ 
if  (  FixDat&Ox80  )  //  frame  from  thread 
{ 

j  =  ( (FixDat&0x70)  »4)  +  4; 
tmp  =  Threads [j] .Meth  «  4; 

FixDat  =  (FixDat&Oxf)  I  tmp; 
Frameldx  =  Threads [j] .Idx; 

) 

if(  FixDat&8  )  //  target  from  a  thread 

( 

j  =  FixDat&3; 

tmp  =  Threads [j] .Meth&3; 

FixDat  =  (FixDat&Oxf 4)  I  tmp; 
Targetldx  =  Threads!  j] .Idx; 

} 

switch (  Loc&OxlC  )  //  find  what  we  need 

{ 

case  0x4:  //  offset  fixup 

if (  (FixDat&7)  ==  4  ) 

( 

/*  get  the  value  to  be  fixed  */ 
memcpy(  &tmp,  &Dp[DROff], 

sizeof (int) ) ; 
if (  Targetldx  ==  2  )  //  data  seg 
( 

tmp  +=  ( (unsigned  long) 

&DSptr [DataSize] ) &0xff f f ; 

) 

else  if<  Targetldx  ==  3  ) 

{ 

tmp  +=  ( (unsigned  long) 

SDSptr [constseg] ) &0xffff; 

} 

/*  put  the  fixed  number  back  */ 
memcpy(  & Dp [DROff],  &tmp, 

sizeof (int) ) ; 

) 

else  if ( (FixDat&7)  ==  6  ) 

( 

if (  ! (Loc&0x40)  ) 

( 

ltmp  =  (unsigned  long) 

(FuncLst [ExtSyms [Targetldx-l] 
.SymNumb] .Loc) ; 
ltmp  -=  (unsigned  long) 

(&Dp [DROff] ) +2L; 
memcpy(  &Dp [DROff], 
&ltmp,  sizeof (int) ) ; 

} 

else  //  put  the  offset  in 

{ 

memcpy(  &Dp [DROff], 

&Syms (ExtSyms [Targetldx-l] 
.SymNumb] .Offset,  sizeof ( 
int  )); 

> 

) 

break; 

case  0x8:  //  segment  fixup 

if (  (FixDat&7)  ==  6  ) 

( 

memcpy(  & Dp [DROff] 

,  SSyms [ExtSyms [Target Idx- 1] 
.SymNumb] .Seg,  sizeof (  int  )); 

) 

break; 

case  OxC:  //  symbol  from  target 
if (  (FixDat&7)  ==  6  ) 

{ 

ptr  =  FuncLst [ExtSyms 

[Targetldx-l] .SymNumb] .Stub; 
memcpy(  &Dp[ DROff],  &ptr, 

sizeof (  void  *) ) ; 

(Listing  continued  on  page  108) 
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listing  Three  (Listing  continued,  text  begins  on  page  30.) 


) 

break; 

} 

} 

else  //  its  a  thread 

{ 

j  =  Data[i]&3; 
if (  Data [ i ] &0x40  ) 
j  +-  4; 

Threads!)]  .Meth  -  (Data[i]sOxlC)»2; 
i++; 

if(  Data[i]&0x80  ) 

{ 

tmp  =  (Data [i++] &0x7f)  «  8; 
tmp  +=  Data[i++j; 

} 

else 

tmp  =  Data[i++]; 

Threads [j] . Idx  =  tmp; 


break; 

default: 

printf(  "invalid  record:  %x  size:  %d\n",  type,  size  ); 
break; 

} 

free (  Data  ) ; 

} 

close (  fd  ) ; 

DataSize  +=  LocalSize; 


) 

End  Listing  Three 


Listing  Four 

//  DLL.C  Implement  DLLs  for  DOS 
//  02/12/89  by  Gary  Syck 
♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦define  MAIN 
♦include  "dll.h" 

void 

main(  int  argc,  char  *argv[]  ) 

{ 

void  (*func) (void) ; 
unsigned  char  *ptr; 

GetData ( ) ;  //  Read  the  global  data 

FuncCnt  *  2;  //  make  two  functions 

FuncLst [0] .Name  =  malloc(  10  ); 

strcpy (  FuncLst [0] .Name,  "_printf"  );  //  The  library  function  printf 

FuncLst [0] .Loc  =  printf; 

FuncLst [0] .Flag  =  1; 

memcpy(  FuncLst [0] .Stub,  &Stub,  STUBSIZE  ); 
ptr  =  FuncLst; 

memcpy(  SFuncLst [0] .Stub[l] ,  &ptr,  2  ); 

FuncLst [1] .Name  =  malloc(  10  ); 

strcpy (  FuncLst [1] .Name,  "_main"  );  //  The  first  function  to  run 

FuncLst [1] .Loc  =  NULL; 

FuncLst [1] .Flag  =  0; 

memcpy(  FuncLst [1] .Stub,  &Stub,  STUBSIZE  ); 
ptr  =  SFuncLst (1] ; 

memcpy(  SFuncLst [1] .Stub[l] ,  &ptr,  2  ); 
func  =  FuncLst [1] .Stub; 

(*func) ();  //  Call  the  main  function 

) 


End  Listing  Four 


Listing  Five 

//  Global  data  to  be  used  with  sample  DLL 
//  make  various  data  items 

char  Str[]  =  "Tester  equals"; 
int  Flubber=20; 
int  Tester=14; 


End  Listing  Five 
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Listing  Six 

//  sample  DLL  routine 
♦include  <stdio.h> 

void  main (void) ; 
void  Test (void) ; 

extern  int  Flubber; 
extern  char  Str[]; 
extern  int  Tester; 

//  print  hello  world  and  the  value  of  Flubber  then  call  Test 

void 

main  () 

( 

printf(  "Hello,  world:  %d\n",  Flubber  ); 

TestO; 

) 

//  print  a  message  and  the  values  of  Str  and  Tester 

void 

Test() 

{ 

printf(  "This  is  a  test  function\n%s:  %d\n",  Str,  Tester  ); 

) 


End  Listing  Six 


Listing  Seven 

//  DLL.H  Include  file  for  DLL 
//  02/12/89  By  Gary  Syck 


#ifdef  MAIN 
♦define  EXTERN 
♦else 

♦define  EXTERN  extern 
♦endif 


typedef  struct  { 
char 

unsigned 
unsigned 
unsigned 
)  SYMTAB; 

♦define  STUBSIZE  50 
typedef  struct  { 
char 
void 
int 

unsigned  char 


*Name;  // 
Size;  // 
Seg;  // 
Offset;  // 


♦Name;  // 

*Loc;  // 


Flag;  // 
Stub (STUBSIZE] ;  // 


)  FUNCTAB; 


SYMTAB 

Syms [200] ; 

// 

EXTERN 

int 

SymCnt ; 

// 

EXTERN 

int 

AllocNumb; 

// 

// 

EXTERN 

SYMTAB 

Syms [ ] ; 

// 

EXTERN 

int  SymCnt; 

// 

EXTERN 

unsigned  SymSize; 

// 

EXTERN 

int 

DataSize; 

// 

EXTERN 

FUNCTAB 

FuncLst [100] ; 

// 

EXTERN 

int 

FuncCnt; 

// 

extern  unsigned  char  DataSpace;  // 

extern  char  Stub;  // 

// 

// 


/*  record  types  */ 
♦define  THEADR 

0x80 

♦define 

♦define 

COMMENT  0x88 
MODEND 

0x8A 

♦define 

EXTDEF 

0x8C 

♦define 

TYPDEF 

0x8E 

♦define 

PUBDEF 

0x90 

♦define 

LINNUM 

0x94 

♦define 

LNAMES 

0x96 

♦define 

SEGDEF 

0x98 

♦define 

GRPDEF 

0x9A 

♦define 

FIXUPP 

0x9C 

♦define 

LEDATA 

OxAO 

♦define 

LI DATA 

0xA2 

♦define 

COMDEF 

OxBO 

//  Function  prototypes 

void  main(  int  argc,  char  *argv[]  ); 

void  LoadFunc (  FUNCTAB  *Func  ) ; 

void  GetData (void) ; 

void  AllocateSyms (void) ; 


Name  of  the  symbol 
size  of  the  symbol 
Segment  containing  the  symbol 
Offset  for  the  symbol 


name  of  the  function 
where  the  function  is  stored 
true  if  function  is  executing 
Function  to  call  this  function 


the  symbols  found 

The  number  of  symbols 

The  first  symbol  in  the  current 

allocation  block 

list  of  symbols 

number  of  symbols 

running  total  of  the  size  of  stuff 
how  many  bytes  in  DataSpace  are  used 

the  list  of  functions 

The  number  of  allocated  entries 

room  in  the  data  segment 
This  is  really  a  function.  It  is 
used  this  way  to  make  sure  the 
segment  gets  used  in  memcpy 


End  listings 


Dr.  Dobb’s  Journal,  May  1990 


109 

451 


VIRTUAL  MEMORY 


Listing  One  (Text  begins  on  page  40.) 


/*  Compile  with:  ZTC  wc  -ml  */ 

/*  (Use  large  model  so  strcmpO  can  handle  far  pointers.)  */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦include  <ctype.h> 

♦include  <handle.h> 

struct  tree 

{ 

char  _ handle  ‘word; 

int  count; 

struct  tree  handle  ‘left; 

struct  tree  handle  ‘right; 

>; 

int  readword(char  *w,  int  nbytes) 

( 

int  c; 
do  { 

c  =  getcharO; 

if  (c  ==  EOF) 

return  0; 

} 

while  ( ! isalpha (c) ) ; 
do  ( 

if  (nbytes  >  1) 

( 

*w++  =  c; 


c  =  getcharO; 

) 

while  (isalnum(c) ) ; 
*w  =  0; 
return  1; 


void  tree  insert (struct  tree  _ handle 


_handle  *pt,  char  *w) 


int  ob¬ 
struct  tree  _ handle  *p; 

while  ((p  =  *pt)  ! =  NULL) 

( 

if  ( (cmp  =  strcmp(w,p->word) )  ==  0) 
goto  gotit; 

pt  =  (cmp  <  0)  ?  &p->left  :  &p->right; 

) 

p  =  (struct  tree  _ handle  *)  handle_calloc (sizeof (struct  tree)); 

if  (!p  !!  (p->word  =  handle_strdup (w) )  ==  NULL) 

{ 

printf("Out  of  memory\n"); 

exit (EXIT_FAILURE)  ; 

} 

*pt  =  p; 
gotit : 

p->count++; 

1 

tree_print (struct  tree  _ handle  *p) 

{ 

while  (p) 

{ 

tree_print (p->left) ; 

printf("%5d  %s\n", p->count, (char  far  *)p->word); 
p  =  p->right; 


tree_free (struct  tree  _ handle  *p) 

( 

struct  tree  _ handle  *pn; 

while  (p) 

( 

handle_free(p->word) ; 

tree_free (p->left) ; 
pn  =  p->right; 
handle_free (p) ; 
p  =  pn; 

) 


struct  tree  _ handle  ‘root  =  NULL; 

char  word[32]; 

while  (readword(word, sizeof (word) ) ) 
t  ree_insert ( &  root ,  word)  ; 
tree_print (root)  ; 
tree_free (root) ; 

return  EXIT  SUCCESS; 


End  Listing 
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Listing  One  (  Text  begins  on  page  58.) 


typedef  struct  { 

int  anlnt; 
long  a Long; 

char  tenChars [10] ;  /*  details  are  unimportant  */ 

}  Thing; 

typedef  union  utag  { 

Thing  aThing; 
union  utag  *next; 

}  freeList; 


freeList  *freeThings  =  0;  /*  free  list,  empty  to  begin  */ 

Thing  *newThing()  /*  new  or  recycled  Thing  */ 

{ 

Thing  *t; 

if  (freeThings)  {  /*  any  on  free  list?  */ 

t  =  (Thing  *)  freeThings; 
freeThings  =  freeThings->next; 

} 

else  /*  no,  go  malloc  one  */ 

t  =  (Thing  *)  malloc (sizeof  *t) ; 
return  (t); 

} 

void  f reeThing (theThing)  /*  put  Thing  on  freeList  */ 

Thing  ‘theThing; 

{ 

((freeList  *)  theThing) ->next  =  freeThings; 
freeThings  -  (freeList  *)  theThing; 

} 

End  Listing  One 

Listing  Two 


controlCon->next  =  controlCon->prev  =  controlCon; 

return  (1);  /*  OK!  */ 

} 

/*  Register  a  new  type  (object)  for  management  by  the  memory  controller 
takes  size  of  the  object  as  an  argument  and  returns  an  MCon  object,  which 
is  zero  in  case  of  failure.  The  Mcon  object  is  used  later  to  manage  creation 
of  all  instances  of  the  new  object,  to  maintain  a  free  list  for  the  object 
and  to  keep  track  of  demand  for  the  object  */ 

MCon  newMCon (size_t  theltemSize) 

{ 

MCon  t; 
int  k; 

k  =  initMControl () ; 
if  ( ! k)  return  ((void  *)  0) ; 
t  =  newInstanceOf (controlCon) ; 
if  (!t)  return  ((void  *)  0); 
t->itemSize  =  theltemSize; 
t->nGiven  =  t->nOut  =  t->nFree  =  0; 
t->freeList  =  (void  *)  0; 
linkln (t) ; 
return  (t); 

} 

/*  Create  a  new  object.  Takes  the  object's  MCon  as  an  argument  (previously 
created  by  newMCon) .  Returns  a  pointer  to  a  new  instance  of  the  object  */ 
void  ‘newInstanceOf (MCon  theCon) 

( 

void  *t; 

if  (theCon->freeList)  (  /*  any  on  free  list?  */ 

t  =  theCon->freeList; 
theCon->freeList  =  * ( (MCon  *)  t) ; 
theCon->nFree — ; 

) 

else  /*  nope,  go  malloc  one  */ 

t  =  malloc (theCon->itemSize  +  (sizeof  theCon)); 
if  (!t)  return  ((void  *)  0);  /*  allocator  failure...  */ 

*((MCon  *)  t)  =  theCon;  /*  remember  the  controller  */ 

theCon->nGiven++; 

theCon->nOut++; 

return  ((void  *)  ( (MCon  *)  t  +  1 ) ) ; 

} 


/*  Header  for  memory  control  package 
C  1989  Robert  A.  Moeser,  all  rights  reserved  */ 

/*  some  things  probably  in  your  standard  headers...  */ 

#ifndef  _ size_t 

#define  _ size_t 

typedef  unsigned  long  size_t; 

#endif 


void  ‘malloc (size_t) ; 

void  free (void  *); 

int  printf(char  *,  ...); 

int  sprintf(char  *,  char  *,  ...); 

int  scanf (char  *,  . . . ) ; 

int  rand (void); 


/*  end  of  things  probably 
typedef  long  counter; 
typedef  struct  _mc  ( 

struct  _mc  ‘next; 
struct  _mc  *prev; 
size_t  itemSize; 
void  ‘freeList; 
counter  nGiven; 
counter  nOut; 
counter  nFree; 

)  *MCon; 


in  your  standard  headers...  */ 

/*  a  bit  excessive,  perhaps...  */ 

/*  used  for  doubly-linked  list  */ 

/*  of  all  mcs  */ 

/*  the  size  of  the  object  this  MCon  controls 
/*  a  free  list  of  objects  */ 

/*  number  of  items  handed  out  */ 

/*  number  still  out  there  somewhere  */ 

/*  length  of  free  list  */ 


*/ 


MCon  newMCon (size_t  theltemSize); 
void  ‘newInstanceOf (MCon  theCon); 
void  disposelnstance (void  *theltem) ; 
void  purgeMCon (MCon  theCon); 
counter  disposeMCon (MCon  theCon); 
void  purgeAllMCons (void) ; 
counter  disposeAUMCons  (void)  ; 


/*  0  =  could  not  get  storage  */ 
/*  0  =  could  not  get  storage  */ 


/*  number  of  orphans  created  by  action  */ 
/*  number  of  orphans  created  by  action  */ 


/*  Dispose  of  an  object.  Takes  a  pointer  to  the  object  to  dispose  of 
the  storage  is  kept  by  the  object's  MCon  on  a  free  list  for  reuse.  */ 
void  disposelnstance (void  ‘theltem) 

{ 

MCon  t; 
void  *x; 
int  g; 

t  =  * ( (MCon  *)  theltem  -  1);  /*  recover  controllor  */ 

t->nOut — ; 

t->nFree++; 

* ( (MCon  *)  theltem  -  1)  =  t->freeList; 
t->freeList  =  (MCon  *)  theltem  -  1; 

} 

/*  Purge  the  free  list  for  an  MCon.  Takes  the  MCon  whose  free  list  should  be 
returned  to  the  system  storage  allocator  */ 
void  purgeMCon (MCon  theCon) 

{ 

void  *bop,  *bop2; 
bop  =  theCon->freeList; 
while  (bop)  { 

bop2  =  * ( (void  “)  bop); 
free (bop) ; 
bop  =  bop2; 

} 

theCon->freeList  =  (void  *)  0; 
theCon->nFree  =  0; 

) 

/*  Unregister  a  type.  Takes  the  MCon  object  that  is  no  longer  needed 
returns  the  number  of  "orphans"  created.  Since  active  instances  are  entirely 
the  responsibility  of  clients  of  the  memory  control  package,  disposing  of 
an  MCon  can  mean  that  there  may  be  outstanding  objects  of  the 
no-longer-existing  type.  This  is  not  strictly  an  error,  but  since  there  is 
now  no  way  to  free  the  storage  used  by  the  orphans  should  be  a  warning  sign.  */ 


End  Listing  Two 

Listing  Three 

/*  A  Memory  Controller.  C  1989  Robert  A.  Moeser,  all  rights  reserved  */ 

#  include  "mem.h" 

static  void  linkln (MCon  theCon); 
static  void  linkOut(MCon  theCon); 
static  int  initMControl (void) ; 

void  debugCon (char  *); 
void  printCon (MCon  theCon); 

static  MCon  controlCon  =  0;  /*  0  ->  not  yet  initialized  */ 

/*  Initialize  the  memory  control  "package."  Returns  1  for  successful 
initialization  or  already  initialized;  returns  0  if  it  fails.  Called 
automatically  by  newMCon,  but  you  can  call  it  explicity  if  you  like.  */ 

int  initMControl (void) 

{ 

if  (controlCon)  return  (1);  /*  already  initialized!  */ 

controlCon  =  (MCon)  malloc (sizeof  ‘controlCon) ; 
if  ( IcontrolCon)  return  (0);  /*  sad  but  true!  */ 

controlCon->itemSize  =  sizeof  ‘controlCon; 

controlCon->nGiven  =  controlCon->nOut  =  controlCon->nFree  =  0; 
controlCon->freeList  =  (void  *)  0; 


counter  disposeMCon (MCon  theCon) 

{ 

counter  orphans  =  0;  /*  did  this  dispose  create  "orphans"  ?  */ 

orphans  =  theCon->nOut; 

purgeMCon (theCon) ;  /*  goodbye  the  free  list  */ 

linkOut (theCon) ; 

disposelnstance ( (void  *)  theCon); 

return  (orphans);  /*  number  of  "orphans",  should  be  0!  */ 

} 

/*  Purge  the  free  list  of  every  object  type  known  to  the  memory  controller 
a  client  might  call  this  in  a  desperate  attempt  to  satisfy  a  memory  request  */ 
void  purgeAllMCons (void) 

{ 

MCon  bop; 

bop  =  controlCon; 

do  { 

purgeMCon (bop) ; 
bop  =  bop->next; 

)  while  (bop  !=  controlCon); 

} 

/*  Unregister  all  types.  This  action  can  create  orphans  in  the  same  sense  as 
disposeMCon  above,  and  so  returns  the  number.  It  really  ought  to  be  zero 
unless  the  client  has  created  objects  meant  to  endure  until  program 
termination.  Since  all  types  are  deactivated  the  additional  step  of 
deactivating  the  memory  controller  itself  is  taken.  All  storage  used  by  the 
package  is  returned  to  the  system  storage  allocator.  */ 

counter  disposeAUMCons  (void) 

{ 

MCon  bop,  bop2;  (Listing  continued  on  page  112) 
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Listing  Three  (Listing  continued,  text  begins  on  page  58.) 

bop  =  controlCon->next; 
while  (bop  !=  controlCon)  { 
bop2  =  bop->next; 
orphans  +=  disposeMCon (bop) ; 
bop  =  bop2; 

} 

purgeMCon (controlCon) ; 
free ( (void  *)  controlCon) ; 

controlCon  =  (void  *)  0;  /*  de-initialize  me  */ 

return  (orphans);  /*  total  number  of  "orphans",  should  be  0!  */ 

} 

/*  Internal  Routines  */ 

/*  Link  a  new  MCon  into  the  doubly-linked  list  of  all  known  MCons 

the  list  head  and  tail  is  the  MCon  for  MCons,  so  there  is  always  at  least  one 

item  on  the  list  and  the  first  item  is  always  the  MCon's  MCon  */ 

static  void  linkIn(MCon  theConToAdd) 

{ 

theConToAdd->next  =  controlCon->next; 
theConToAdd->prev  =  controlCon; 
controlCon->next  =  theConToAdd; 

(theConToAdd->next) ->prev  =  theConToAdd; 

} 

/*  Unlink  an  MCon  (called  upon  destruction  of  an  Mcon  */ 
static  void  linkOut (MCon  theConToDel) 

{ 

(theConToDel->prev) ->next  =  theConToDel->next; 

(theConToDel->next) ->prev  =  theConToDel->prev; 

) 

/*  Debugging  and  Utility  Routines  */ 

/*  Print  a  list  of  known  MCons  with  statistics.  Takes  a  tag  to  accompany 
printout  as  an  argument.  */ 
void  debugCon(char  *s) 

{ 

MCon  bop; 
printf("%s",  s); 
if  ((controlCon)  { 

printf("  -me  is  OFF!\n"); 
return; 

} 

bop  -  controlCon; 
do  { 

printCon(bop) ; 
bop  =  bop->next; 

}  while  (bop  !=  controlCon); 

} 


char  *freeBop; 
int  freeCount; 
int  OK; 

freeBop  =  theCon->freeList; 
freeCount  =  0; 
while  (freeBop)  { 

freeCount++; 

freeBop  =  *((char  **)  freeBop); 

} 

OK  =  freeCount  ==  theCon->nFree; 
printf("%lx  =  %lu\t%ld\t%ld\t%ld\t%lx\t%s\n", 
theCon, 

theCon->itemSize, 
theCon->nGi ven , 
theCon->nOut, 
theCon->nFree, 
theCon->freeList, 

OK  ?  "<ok>"  :  " <N0K> " ) ; 

End  Listing  Three 

Listing  Four 

/*  Part  1  of  torture-test  of  the  memory  controller  */ 

#  include  <stdio.h> 

#  include  <console.h> 

void  torture (void) ; 
main() 

{ 

int  i; 

for  (i  =  0;  i  <  100;  i++) 


End  Listing  Four 


Listing  Five 

/*  Part  2  of  torture-test  of  the  memory  controller  */ 
#  include  "mem.h" 


#  define  MAXTYPES  20 

#  define  MAXINSTANCES  500 

#  define  BASESIZE  25 

#  define  MAXEXTRA  25 

#  define  NPASSES  50000 


/*  Print  one  MCon.  Make  a  quick  check  on  the  integrity  of  the  internal 

data  structure.  */ 

void  printCon(MCon  theCon) 

{ 


void  torture (void) ; 
void  error (char  *) ; 
void  makeNewType (void) ; 
void  makeNewObject (void) ; 
void  freeSomeOb ject (void) ; 
int  randle (int); 
void  debugCon(char  *); 
struct  {  ' 

MCon  mCon; 
long  thelD; 

}  regType [MAXTYPES ] ; 
struct  { 

void  *mObj; 
long  typelD; 

}  mBag [ MAXINSTANCES ] ; 
int  nlnstances  =  0; 
int  nTypes  =  0; 
long  seriallD  =  1000; 
void  torture {) 

( 

counter  orphans  =  0; 
size_t  sizeltem; 
int  typeldx,  objldx; 
int  nPotential,  nActual; 
long  tID; 
int  i,  x; 
long  looper; 
char  msg[64] ; 

for  (looper  =  0;  looper  <  NPASSES;  looper++)  { 

if  (orphans)  error ("orphans  have  been  created"); 
if  (! nTypes)  ( 

if  (nlnstances)  error ("instances  but  no  active  types"); 
makeNewType ( ) ; 

) 

x  =  randle (10) ; 
switch  (x)  ( 
case  0 


case  1 


case  2 


case  7 


case  3 


case  8 


:  /*  make  a  report  */ 

sprintf (msg,  "loop  %ld  :  %d  instances  of  %d  types\n", 
looper, 
nlnstances, 
nTypes) ; 
debugCon (msg)  ; 
break; 

:  /*  register  a  new  type  if  room  */ 

makeNewType () ; 
break; 

:  /*  make  a  new  object  if  room  */ 

makeNewObject () ; 
break; 

:  /*  make  many  new  objects  */ 

nPotential  =  ((MAXINSTANCES  -  nlnstances)  »  2)  +  7; 
nActual  =  randle (nPotential) ; 
while  (nPotential — ) 

makeNewObject () ; 

break; 

:  /*  free  an  object  if  any  exist  */ 

freeSomeOb ject () ; 
break; 

:  /*  free  many  objects  */ 

nPotential  =  ((MAXINSTANCES  -  nlnstances)  »  3)  +  3; 
nActual  =  randle (nPotential) ; 
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while  (nPotential — ) 

f reeSomeOb ject ( ) ; 

break; 

case  4  :  /*  purge  free  list  of  a  type  if  any  exist  */ 

if  (nTypes)  { 

typeldx  =  randle (nTypes) ; 
purgeMCon (regType [typeldx] .mCon) ; 

} 

break; 

case  9  :  /*  purge  a  number  of  free  lists  */ 

if  (nTypes)  { 

nActual  =  randle (nTypes) ; 
for  (i  =  0;  i  <  nActual;  i++)  { 

typeldx  =  randle (nTypes) ; 
purgeMCon (regType (typeldx] .mCon) ; 

} 

} 

break; 

case  5  :  /*  free  all  of  a  registered  type  if  any  exist  */ 

if  (nTypes)  ( 

typeldx  =  randle (nTypes) ; 
tID  =  regType [typeldx] .the ID; 
for  (i  =  0;  i  <  nlnstances;  ) 

if  (mBag[i] .typelD  ==  tID)  { 

disposelnstance (mBag[i] .mObj); 
nlnstances — ; 

mBag[i]  =  mBag [nlnstances] ; 

) 

else  i++; 

/*  and  maybe  kill  the  controllor  */ 
if  (randle (13)  >  7)  { 

orphans  +=  disposeMCon (regType [typeldx] .mCon) ; 
nTypes — ; 

regType [typeldx]  =  regType [nTypes] ; 

) 


break; 

case  6  :  /*  free  all  instances  of  all  types  */ 

if  (randle (20)  <  15)  break; 
for  (i  =0;  i  <  nlnstances;  i++) 

disposelnstance (mBag [i] .mObj) ; 
nlnstances  =  0; 

/*  kill  some  controllers  */ 
for  (i  =  0;  i  <  nTypes;) 

if  (randle (15)  >  13)  ( 

orphans  +=  disposeMCon (regType [ i] .mCon) ; 
nTypes — ; 

regType [ i ]  =  regType [ nTypes ] ; 

) 

else  i++; 

/*  and  maybe  kill  all  the  rest  and  shut  down!  */ 
if  (randle (20)  >  17)  { 

orphans  +*  disposeAUMCons  () ; 
nTypes  =  0; 

} 

break; 

} 

} 

printf ("\n%ld  passes. . .\n",  NPASSES) ; 

) 

void  makeNewType () 

{ 

MCon  tCon; 

size_t  sizeltem; 

if  (nTypes  <  MAXTYPES)  { 

sizeltem  =  BASESIZE  +  randle (MAXEXTRA) ; 
tCon  =  newMCon (sizeltem) ; 
if  (ItCon)  ( 

error ("could  not  make  controllor"); 
return; 

) 

regType [ nTypes ] .mCon  =  tCon; 
regType [nTypes] .thelD  =  serialID++; 
nTypes ++; 

1 

} 

void  makeNewObject () 

{ 

int  typeldx; 
void  *tObj; 

if  ((nlnstances  <  MAXINSTANCES)  &&  nTypes)  ( 
typeldx  =  randle (nTypes) ; 

tObj  =  newInstanceOf (regType [typeldx] .mCon) ; 
if  ( ! tObj)  { 

error ("could  not  get  object  memory"); 
return; 

) 

mBag [nlnstances] .mObj  =  tObj; 

mBag[nInstancesj .typelD  =  regType [typeldx] .thelD; 
nlnstances++; 

} 

} 

void  f reeSomeOb ject () 

{ 

int  objldx; 
if  (nlnstances)  ( 

objldx  =  randle (nlnstances) ; 
disposelnstance (mBag [objldx] .mObj) ; 
nlnstances — ; 

mBag[objIdx]  =  mBag [nlnstances ] ; 

) 


void  error (char  *s)  /*  print  error  message  and  hang  */ 

{ 

char  hang [12]; 

printf ("\nERROR  :  %s\n",  s); 
scanf("%s",  hang); 

} 

randle (int  n)  /*  random  number  up  to  not  including  n  */ 


if  (n  <=  0)  error("bogus  randle  call"); 
return  (rand()  %  n) ; 


End  listings 
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E  X  A  M  I  N 


Listing  One  (Text  begins  on  page  82.) 

Object  subclass:  #RandomNumber 
instanceVariableNames:  " 
classVariableNames:  'Seed' 
poolDictionaries :  ' '  . 

"RandomNumber  class  methods" 
new 

!n! 

Seed  isNil  ifTrue: [self  reset]. 

n  :=  Seed.  Seed  :=  (Seed  *  263  +  30011)  bitAnd: 16r7FFF. 
An. 

from:min  to:max 

A(self  new  \\  (max  -  min  +  1))  +  min. 
randomize 

Seed  :=  Time  millisecondClockValue  bitAnd: 16r7FFF. 
reset 

Seed  :=  0. 

Object  subclass:  #MarketActor 

instanceVariableNames:  'running  msgQueue  position  notify' 
classVariableNames:  " 
poolDictionaries:  ". 

"Market Actor  class  methods" 
new 

Asuper  new  initialize, 
priority 
A2 . 

imageName 

A' PersonUp' . 
f ormNamed : anlmageName 

AMarketImages  at : anlmageName. 

form 

Aself  formNamed: self  imageName. 
extent 

Aself  form  extent, 
height 

Aself  form  height, 
width 

Aself  form  width. 

"Market Actor  instance  methods" 
initialize 

msgQueue  :=  MessageQueue  new.  running  :=  false, 
release 

msgQueue  release.  msgQueue  :=  nil.  notify  :=  nil. 
super  release. 
alternateForm 

Aself  formNamed: self  class  alternatelmageName. 
display 

self  display:self  form  at:position. 
display  :aForir. 

self  display :aForm  at:position. 
display :aForm  at:aPoint 

aForm  displayAt :aPoint . 
animate 

self  display: self  alternateForm. 
erase 

Display  white: self  frame. 

form 

Aself  class  form. 
formNamed: anlmageName 

Aself  class  formNamed: anlmageName. 
frame 

Aposition  extent: self  extent, 
extent 

Aself  class  extent, 
height 

Aself  class  height, 
width 

Aself  class  width. 
messageQueue 
AmsgQueue . 
receive 

AmsgQueue  receive. 
send:aMessage  to:anObject 

self  send:aMessage  to:anObject  with:nil. 
send:aMessage  to:anObject  with: anArgument 
! queue ! 

(queue  :=  anObject  messageQueue)  isNil 
ifFalse: [ 

queue  send:aMessage. 
anArgument  isNil 

ifFalse: [queue  send: anArgument] ] . 

Processor  yield, 
position :aPoint 

position  :=  aPoint. 
moveBy: delta 

self  moveTo: position  +  delta. 
moveTo: aPoint 

self  erase;  position: aPoint;  display, 
start 

running 

ifFalse:  [ 

running  :=  true. 

[self  run]  forkAt:self  class  priority]. 

run 

! action! 

[running] 

whileTrue: [ 

action  :=  self  receive. 

(running  and: [self  respondsTo : action] ) 
ifTrue: [self  perform: action] ] . 
self  shutdown, 
stop : notif ySemaphore 

notify  :=  not if ySemaphore. 
running 

ifTrue: [ 

running  :=  false. 


»  G  R  0  0  M 


self  send:#wakeUp  to: self] 
ifFalse: [self  notify] . 

shutdown 

self  erase;  notify, 
notify 

(notify  isKindOf Semaphore)  ifTrue: [notify  signal], 
sleep : numberOf Seconds 
! timeout ! 

timeout  :=  Time  now  asSeconds  +  numberOfSeconds . 

[running  and: [Time  now  asSeconds  <  timeout]] 
whileTrue: [Processor  yield] . 

wakeUp 

"Do  nothing  —  in  case  the  receiver 
is  waiting  at  the  message  queue." 

MarketActor  subclass:  #Bagger 
instanceVariableNames:  'checker' 
classVariableNames:  " 
poolDictionaries:  ". 

"Bagger  class  methods" 
alternatelmageName 
A' PersonRight' . 

"Bagger  instance  methods" 
release 

checker  :=  nil.  super  release, 
checker : aChecker 

checker  :=  aChecker. 
takeltem 
running 

ifTrue: [ 
self 

animate; 
sleep: 1; 

send:#gotIt  to:checker; 
display] . 

MarketActor  subclass:  IChecker 

instanceVariableNames:  'bagger  customer' 
classVariableNames:  " 
poolDictionaries:  ". 

"Checker  class  methods" 
alternatelmageName 
A,PersonLeft' . 

"Checker  instance  methods" 
release 

bagger  :=  nil.  customer  :=  nil.  super  release, 
bagger :aBagger 

bagger  :=  aBagger. 
checkOutCustomer 

customer  :=  self  receive, 
got  It 

running 

ifTrue: [ 
self 

display; 

send:#removeItemFromCart  to:customer] . 

takeltem 

running 

ifTrue: [ 
self 

animate; 

send: jftakeltem  to:bagger; 
sleep: 1; 

send:#gotIt  to:customer] . 

MarketActor  subclass:  #CheckoutCounter 

instanceVariableNames:  'checker  bagger  customers  nowServing' 
classVariableNames :  ' MaxCustomers ' 
poolDictionaries :  ' ' . 

"CheckoutCounter  class  methods" 
initialize 

MaxCustomers  isNil  ifTrue: [MaxCustomers  :=  3]. 

new 

self  initialize.  Asuper  new. 
imageName 

A' Counter' . 
maxCustomers 

self  initialize.  AMaxCustomers. 
maxCustomers : aNumber 

MaxCustomers  :=  aNumber. 
priority 
A3. 

"CheckoutCounter  instance  methods" 
initialize 

checker  :=  Checker  new.  bagger  :=  Bagger  new. 
checker  bagger : bagger.  bagger  checker: checker, 
customers  :=  OrderedCollection  new : MaxCustomers . 
super  initialize, 
release 

bagger  release,  checker  release.  nowServing  release, 
bagger  :=  nil.  checker  :=  nil.  nowServing  :=  nil. 

[customers  isEmpty] 

whileFalse: [customers  removeFirst  release] . 
customers  release,  customers  :=  nil.  super  release, 
position  .-aPoint 

super  position: aPoint. 
checker  position: aPoint 

+  ( (self  width  //  2) 

@  (self  height  //  4)). 

bagger  position: aPoint  +  (00  self  height  *  3  //  4)  . 
checkoutPosition 

Aposition  -  (Customer  width  @  0) . 
endOfLinePosition 

(Listing  continued  on  page  118) 
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Listing  One  (Listing  continued,  text  begins  on  page  82.) 

Aposition 

-  (Customer  width 

@  (customers  size  +  1  *  Customer  height)). 

exitPosition 

Aposition  +  ( (0  -  Customer  width)  0  self  height) . 
length 

■"■customers  size 

+  (nowServing  isNil  ifTrue:[0]  ifFalse: [1] ) . 

display 

super  display,  checker  display,  bagger  display. 
addCustomer 

! aCustomer ! 

aCustomer  :=  self  receive, 
running 

ifTrue: [ 

customers  add: aCustomer. 
self  length  ==  1 

ifTrue: (self  nextCustomer] ) . 

nextCustomer 

running  ifTrue: [Aself] . 
customers  isEmpty 

ifTrue:  [nowServing  :=  nil] 
ifFalse: [ 

nowServing  :=  customers  removeFirst. 
self  send:#moveToCheckout 

to: nowServing  with : checker . 
customers  do: [: aCustomer ! 
aCustomer  isNil 

ifFalse: [self  send: #moveForward 
to:aCustomer] ] ] ] . 

start 

super  start,  bagger  start,  checker  start, 
shutdown 

!  semaphore  I 

self  update: 0.  semaphore  :=  Semaphore  new. 
customers  do: [: aCustomer ! 

aCustomer  stop: semaphore,  semaphore  wait]. 
nowServing  isNil 

ifFalse: [nowServing  stop  semaphore,  semaphore  wait], 
checker  isNil 

ifFalse: [checker  stop  semaphore,  semaphore  wait], 
bagger  isNil 

ifFalse: [bagger  stop: semaphore,  semaphore  wait], 
super  shutdown, 
update 

! aValue ! 

((aValue  :=  self  receive)  isKindOf: Number) 
ifTrue: [self  update : aValue ] . 
update: aValue 

!  fieldWidth  textPosition  extent! 
textPosition  := 

position  +  ((self  width  //  2) 

@  ((SysFont  height  +  2)  negated)). 

fieldWidth  :*  3. 

extent  :=  (SysFont  width  *  fieldWidth) 

@  SysFont  height. 

aValue  ==  0 

ifTrue:  [Display  white: (textPosition  extent :extent) ] 
ifFalse: [ (aValue  printstring  flushedRightln: fieldWidth) 
displayAt: textPosition] . 

MarketActor  subclass:  tCustomer 

instanceVariableNames :  'counter  checker  items  leaving' 
classVariableNames:  'Minltems  Maxltems' 
poolDictionaries :  ' ' . 

"Customer  class  methods" 
alternatelmageName 

A'CustomerReaching' . 
imageName 

A' Customer' . 

new 

Minltems  isNil  ifTrue: [Minltems  :»  5.  Maxltems  :=  25]. 

Asuper  new. 

"Customer  instance  methods" 
initialize 

items  :=  RandomNumber  from:MinItems  to:MaxItems. 
leaving  :=  false,  super  initialize, 
release 

checker  :=  nil.  counter  :=  nil.  super  release, 
counter : aCheckoutCounter 

counter  :=  aCheckoutCounter. 
cartlsEmpty 

Aitems  <-  0. 
moveToEndOfLine 

running  ifTrue: (self  moveTo: counter  endOfLinePosition] . 
moveForward 

running  ifTrue: [self  moveBy:0  0  self  height]. 
moveToCheckout 

checker  :=  self  receive, 
running 

ifTrue: [ 
self 

moveTo: counter  checkoutPosition; 

send: fcheckOutCustomer  to: checker  with : self; 

update; 

removeltemFromCart] . 

leaveStore 

running 

ifTrue: [ 
self 

update; 

moveTo: counter  exitPosition; 
send: fnextCustomer  to: counter, 
running  :=  false,  leaving  :=  true]. 

got  It 

self  display;  sleep: 1. 


remove 1 1  emFr omCa  r t 
running 

ifTrue: [ 

self  cartlsEmpty 

ifTrue: [self  leaveStore] 
ifFalse: [ 
self 

update; 

animate; 

send:#takeltem  to:checker. 
items  :=  items  -  1]]. 

shutdown 

super  shutdown,  leaving  ifTrue: [self  release], 
update 

(running  and: [counter  notNil]) 

ifTrue: [self  send:#update  to:counter  with:items] . 


End  Listing  One 


Listing  Two 

Object  subclass:  #MarketSimulator 
instanceVariableNames : 

'running  notify  counters  frame  statusFrame 
totalCustomers  startTime' 

classVariableNames:  'MaxTime  MaxCounters  MinTime  ' 
poolDictionaries:  ". 

"MarketSimulator  class  methods" 
new 

MaxCounters  :=  3.  MinTime  :=  1.  MaxTime  :*■  15. 

Asuper  new  initialize, 
priority 
A2 . 

"MarketSimulator  instance  methods" 
initialize 

totalCustomers  :=  0.  running  :=  false, 
release 

1  to:counters  size  do : ( : i ! 

(counters  at:i)  release, 
counters  at:i  put:nil]. 
counters  release,  counters  :=  nil. 
notify  :=  nil.  super  release, 
reframe :aFrame 

! statusHeight  w  h  maxCounters  maxCustomers  x  y! 
CursorManager  execute  change, 
frame  :=  aFrame. 

statusHeight  :=  SysFont  height  +  4. 
statusFrame  :=  aFrame  origin  +(202) 

extent: (aFrame  width  -  4)  0  statusHeight. 
w  :=  CheckoutCounter  width  +  Customer  width  +  2. 
h  :=  CheckoutCounter  height  +  Customer  height  +  4. 
maxCounters  :=  ((aFrame  width  -  Customer  width)  //  w) 
min: MaxCounters. 

maxCustomers  :=  ((aFrame  height  -  statusHeight  -  h) 

//  Customer  height) 

min : CheckoutCounter  maxCustomers . 

x  :=  aFrame  origin  x 

+  ((aFrame  width  -  (maxCounters  *  w) )  //  2) 

+  Customer  width, 
y  :=  aFrame  corner  y  -  h. 

CheckoutCounter  maxCustomers :maxCustomers . 
counters  :=  Array  new : maxCounters . 

1  to:maxCounters  do : [ : i ! 
counters 

at:i  put: (CheckoutCounter  new 
positions  0  y; 
display; 
yourself) . 

x  :=  x  +  w] . 

CursorManager  normal  change. 
send:aMessage  to:anObject 

self  send:aMessage  to:anObject  with:nil. 
send:aMessage  to:anObject  withianArgument 
! queue ! 

(queue  :=  anObject  messageQueue)  isNil 
ifFalse:  [ 

queue  send:aMessage. 

anArgument  isNil  ifFalse: [queue  send: anArgument] ] . 
Processor  yield, 
sleep : numberOf Seconds 

! timeout  lastTime  time! 

timeout  :=  Time  now  asSeconds  +  numbe rOf Seconds . 
lastTime  :=  0. 

[running  and: [ (time  :=  Time  now  asSeconds)  <  timeout]] 
whileTrue: [ 

time  =  lastTime 
ifFalse : [ 
self 

timeRemaining: (timeout  -  time); 
elapsedTime. 
lastTime  :=  time] . 

Processor  yield] . 

shortestLine 

! fewest  length  shortest ! 
fewest  :=  9999. 

1  to: counters  size  do : [ : i ! 

(length  :=  (counters  at:i)  length)  <  fewest 
ifTrue: [fewest  :=  length,  shortest  :=  i] ] . 
fewest  <  CheckoutCounter  maxCustomers 
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ifTrue: [A counters  atishortest] 
ifFalse: [Anil] . 
newCustomer 

! counter  customer! 

(counter  :=  self  shortestLine)  isNil 
ifFalse: [ 

customer  :=  Customer  new 
counter : counter; 

position: counter  endOfLinePosition; 

display; 

start; 

yourself. 

totalCustomers  :=  totalCustomers  +  1. 

('CUSTOMERS  SERVED:',  totalCustomers  printstring) 
displayAt:statusFrame  origin, 
self  send:#addCustomer  to:counter  with : customer ] . 

start 

counters  do: [ :aCounter ! 

aCounter  isNil  ifFalse: [aCounter  start]], 
running 

ifFalse: [ 

startTime  :=  Time  now. 
running  : =  true. 

[self  run]  forkAt:self  class  priority], 
run 

self  newCustomer. 

[running] 

whileTrue: [ 

self  sleep: (RandomNumber  from:MinTime  to:MaxTime) . 
running  ifTrue: [self  newCustomer]]. 
self  shutdown. 

(notify  isKindOf Semaphore) 
ifTrue: [notify  signal]. 

running 

Arunning. 

s  t op : not i f y Semapho  re 
running 

ifTrue: [ 

notify  notifySemaphore. 
running  :-  false] 
ifFalse: [ 

self  shutdown. 
notifySemaphore  signal]. 

shutdown 

! semaphore  1 

semaphore  :=  Semaphore  new. 
counters  do: [: aCounter ! 
aCounter  isNil 
ifFalse: [ 

aCounter  stop: semaphore, 
semaphore  wait]]. 

elapsedTime 

Itime  field  offset! 

time  :=  Time  now  subtractTime: startTime. 
field  'ELAPSED  TIME  ' ,  time  printstring, 
offset  :=*  statusFrame  center  x 

-  ((SysFont  stringWidth: field)  //  2). 
field  displayAt: statusFrame  origin  +  (offset  @  0). 

t imeRemaining : seconds 

IfieldWidth  field  offset! 

fieldWidth  :=  3. 

field  :=  'NEXT  CUSTOMER: ' , 

(seconds  printstring  flushedRightln: fieldWidth) . 
offset  :=  statusFrame  width 

-  (SysFont  stringWidth: field) . 

field  displayAt: statusFrame  origin  +  (offset  @  0). 

Object  subclass:  MarketWindow 

instanceVariableNames:  'topPane  aPane  simulator' 
classVariableNames :  'Version  Frame  Title' 
poolDictionaries :  "  . 

"MarketWindow  class  methods" 
initialize 

Frame  :=  Display  boundingBox  insetBy:16. 

Title  :-  'Market  Checkout  Simulation' . 

Version  :=  '  (Version  1.0  —  02/24/90  —  KEA) ' . 

new 

self  initialize. 

Asuper  new. 

"MarketWindow  instance  methods" 
open 

topPane  :=  TopPane  new 
model: self; 
label: Title,  Version; 
menu : IwindowMenu; 
rightlcons:# (collapse) ; 
yourself. 

topPane  addSubpane: 

(aPane  :=  GraphPane  new 
model : self ; 
name:#initPane: ; 
menu : #paneMenu ; 

framingRatio: (0  @  0  extent:l  @  1)). 
topPane  reframe: Frame. 

topPane  dispatcher  openWindow  scheduleWindow. 
close 

self  stop. 
initPane : aFrame 

Display  white: aFrame. 
self  initSimulator: aFrame . 

AForm  fromDisplay: aFrame. 
initSimulator: aFrame 
simulator  isNil 
ifTrue: [ 

simulator  :=  MarketSimulator  new 
ref rame: aFrame; 
yourself] . 

(continued  on  page  120) 
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listing  Two  (Listing  continued,  text  begins  on  page  82.) 


paneMenu 

(simulator  isNil  or: [simulator  running]) 
if True: [ AEmptyMenu  new] 
if False: [AMenu 

labels START  SIMULATION' 
lines:# () 

selectors : # ( start ) ] . 

windowMenu 

AMenu 

labels : ' cycle\collapse\close'  withers 
lines:# () 

selectors: # (cycle  collapse  closelt) . 

start 

simulator  start. 

stop 

! semaphore  I 
simulator  isNil 


ifFalse: [ 

CursorManager  execute  change, 
semaphore  :=  Semaphore  new. 
simulator  stop  semaphore, 
semaphore  wait;  release, 
simulator  release,  simulator  :=  nil. 
CursorManager  normal  change] . 


End  listings 
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Complex  Systems, 
Fractals,  and  Chaos 

Too  bad  complexity  isn’t  a  little 
simpler.  Last  month  I  presented 
several  of  the  current  views  on 
how  to  manage  complex  systems. 
These  were  all  software  engineering 
strategies  for  getting  organized,  the  idea 
being  that  we  need  lots  of  order  if  we 
hope  to  cope  with  complexity  in  un¬ 
predictable  environments. 

This  month  chaos  gets  its  turn. 

There  is  mounting  evidence  that  the 
management  of  a  complex  system  in 
an  uncertain  environment  requires  a 
healthy  dose  of  chaos.  Some  of  that 
evidence  was  presented  in  a  recent 
Scientific  American  article,  “Chaos  and 
Fractals  in  Human  Physiology,”  by  Ary 
L.  Goldberger,  David  R.  Rigney,  and 
Bruce  J.  West,  (February,  1990).  Gold¬ 
berger  et  al  focus  on  the  management 
of  one  of  the  most  complex  of  systems, 
the  human  body,  but  their  conclusions 
are  interesting  for  what  they  say  about 
complex  systems  in  general.  There  is 
nothing  inherently  biological  in  their 
mathematics. 

Every  operating  system  designer 
knows  you  need  a  little  randomness 
to  avoid  certain  problems.  The  Dining 
Philosophers  problem,  discussed  here 
and  more  fully  in  David  Harel’s  book, 
Algorithmics  (Addison- Wesley,  1987), 
is  a  classic  case  of  deadlock  that  cannot 
be  resolved  without  introducing  an  ele¬ 
ment  of  randomness.  Any  strictly  deter¬ 
ministic  solution  to  the  Dining  Philoso¬ 
phers,  problem  is  guaranteed  to  fail. 
While  this  sounds  like  what  Goldber¬ 
ger  et  al  are  saying  about  chaos  in 
human  physiology,  there  is  an  impor¬ 
tant  difference.  Goldberger  et  al  are 
not  merely  describing  a  useful  random 


Michael  Swaine 


tweaking  of  an  existing  model,  but  throw¬ 
ing  out  an  existing  mathematical  model 
and  replacing  it  with  another. 

That  new  model  is  deterministic 
chaos,  and  that  phrase  is  not,  appar¬ 
ently,  an  oxymoron.  (My  favorite  re¬ 
cent  additions  to  the  oxymoron  lexicon 
are  “Justice  Rehnquist,”  thanks  to  John 
Perry  Barlow,  retired  cattle  rancher,  Grate¬ 
ful  Dead  lyricist,  and  computer  book 


author;  and  “reputable  astrologer,”  an 
oxymoronic  self-characterization  by  a 
notorious  Reagan  family  advisor.) 

Deterministic  chaos  arises  from  the 
discipline  of  nonlinear  dynamics,  which 
is  the  study  of  systems  that  respond 
disproportionately  to  stimuli.  There  are 
certain  situations  in  which  nonlinear 
systems  that  are  strictly  deterministic 
nevertheless  behave  in  seemingly  ran¬ 
dom  ways.  This  is  not  true  random¬ 
ness,  but  a  constrained  but  erratic  be¬ 
havior  called  “chaos.”  It  is  the  chaos 
of  the  heart. 

Times  of  the  Heart 

The  conventional  physiological  model 
that  covers  health,  disease,  and  aging 
is  homeostasis.  According  to  this  model, 
physiological  systems  act  to  reduce  vari¬ 
ability  and  to  maintain  constant  or  regu¬ 
larly  periodic  internal  states.  Fluctua¬ 
tions  in  heart  rate  have  been  viewed 
as  the  response  to  external  stresses, 
and  it  has  been  assumed  that  the  physi¬ 
ological  system  functions  to  return  the 
heart  rate  to  its  normal  level.  A  per¬ 
fectly  normal  heart  in  a  perfectly 
stressless  environment  would,  under 
this  model,  tick  like  a  metronome. 

The  authors  argue  that  the  conven¬ 
tional  model  is  wrong.  Within  the  past 
five  years  evidence  has  been  accumu¬ 
lating  that  chaotic  behavior  in  physi¬ 
ological  systems  may  be  the  product 
of  healthy  functioning,  while  regular, 
periodic  behavior  or  steady-state  be¬ 
havior  is  symptomatic  of  some  prob¬ 
lem.  Healthy  young  hearts  often  ex¬ 
hibit  the  greatest  irregularity,  while  regu¬ 
larity  of  heartbeat  is  sometimes  a  pre¬ 
cursor  of  heart  failure. 

One  study  the  authors  cite  depends 
on  examining  heart  rate  data  plotted 
as  Fourier  spectra  and  phase-space 
plots.  Fourier  analysis  displays  periodi¬ 
city  clearly  as  spikes;  steady-state  be¬ 
havior  as  low,  flat  lines;  and  chaotic 
behavior  as  a  broad  spectrum.  Phase- 
space  plots  give  a  different  picture,  but 
are  even  better  at  identifying  chaotic 
behavior.  In  phase-space  plots,  perio¬ 
dicity  shows  up  as  clearly  cyclic  figures 
called  “limit  cycles,”  steady-state  behav¬ 
ior  maps  into  a  point,  and  chaotic  be¬ 
havior  produces  something  called  a 


“strange  attractor,”  which  looks  clearly 
chaotic. 

The  results  they  cite  are  impressive. 
A  healthy  heart  produced  a  broad 
Fourier  spectrum  and  a  strange  attrac¬ 
tor.  Unhealthy  hearts  showed  either  a 
Fourier  spike  and  a  limit  cycle,  or  a 
nearly  flat  Fourier  spectrum  and  a  point 
attractor.  Chaos,  apparently,  is  healthy. 

This  chaos  seems  to  be  directed  from 
the  nervous  system,  where  researchers 
are  finding  evidence  of  further  chaos. 
Significantly,  heart-rate  variability  de¬ 
creases  after  a  heart  transplant,  which 
requires  severing  a  connection  between 
the  heart  and  the  nervous  system.  Chaos 
also  seems  to  be  present  in  the  nervous 
control  of  hormonal  secretion  and  in 
other  areas  in  the  nervous  system.  One 
model  shows  how  chaos  could  be  pro¬ 
duced  in  the  nervous  system:  It  in¬ 
volves  feedback  loops  among  neurons. 

There’s  another  chaotic  clue  in  the 
nervous  system.  The  branching  struc¬ 
ture  of  neurons  seems  to  have  fractal 
dimension,  which  is  significant  because 
of  the  connection  between  fractals  and 
chaos. 

River's  Edge 

Just  what  the  relationship  between 
chaos  and  fractals  is  is  not  entirely  clear. 
But  there  is  a  connection:  Fractals  are 
often  the  remnant  of  chaotic  nonlinear 
dynamics.  The  picture  seems  to  be  this: 
A  chaotic  process  shapes  an  environ¬ 
ment,  and  the  trace  left  behind  is  a 
fractal. 

A  fractal,  then,  is  a  geometric  form 
with  the  following  distinctive  charac¬ 
teristics:  Infinite  detail  and  self-similar¬ 
ity  at  any  scale.  No  matter  how  closely 
you  examine  it,  you  find  more  detail, 
and  it  looks  more  or  less  the  same  at 
any  level  of  magnification.  A  fractal  can 
be  an  infinitely  branching  line,  an  infi¬ 
nitely  lumpy  surface,  or  any  similarly 
hairy  object  of  higher  dimensionality. 

The  dimensionality  of  a  fractal  is  more 
complicated  than  this,  though.  Because 
of  its  infinite  detail,  a  fractal  does  not 
really  have  a  dimension  in  the  conven¬ 
tional  sense.  An  infinitely  branching 
line  has  no  single  measure  of  length, 
and  is  not  a  one-dimensional  object.  A 
fractal’s  dimension  is  defined  to  be  a 
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function  of  the  probability  that  it  touches 
any  given  point  in  the  space  containing 
the  fractal.  The  dimension  of  an  infi¬ 
nitely  branching  line  fractal  is  a  num¬ 
ber  between  1  and  2.  This  fractional 
dimensionality  is  where  fractals  get  their 
name.  There  are  some  dizzying  conse¬ 
quences  of  this  fractional  dimension¬ 
ality,  such  as  the  ideas  that  a  coastline 
doesn’t  have  any  definable  length,  and 
that  a  river  has  no  edge. 

Fractals  have  received  a  lot  of  atten¬ 
tion  in  computer  science  since  their 
discovery  by  Benoit  Mandelbrot.  But 
they  are  not  just  of  academic  interest. 
In  cinematic  computer  graphics  and 
elsewhere,  fractals  are  proving  to  be 
powerful.  If  you  want  to  model  branch¬ 
ing  anatomical  structures  such  as  lungs 
and  nerves,  flora-like  trees  or  shrub¬ 
bery,  or  coastlines  or  river  meanders  or 
mountain  chains  or  any  sort  of  terrain, 
you  will  do  well  to  examine  fractals. 

There  have  been  a  number  of  arti¬ 
cles  and  books  about  fractals  in  nature, 
reminiscent  of  past  articles  and  books 
on  mathematics  in  nature.  Mathemati¬ 
cal  functions  and  forms  such  as  the 
spiral  and  helix,  and  the  phi  function 
and  Fibonacci  series,  crop  up  with  amaz¬ 
ing  frequency  in  natural  forms.  Books 
such  as  H.E.  Huntley’s  The  Divine  Pro¬ 


portion  and  Theodore  A.  Cook’s  The 
Curves  of  Life ,  popular  treatments  both 
available  in  Dover  paperback  editions, 
describe  how  such  mathematical  enti¬ 
ties  appear  in  odd  places  in  nature. 

The  Fibonacci  sequence  is  particu¬ 
larly  common  in  nature.  The  sequence 
begins  1,1  and  each  succeeding  term 
is  the  sum  of  the  two  that  precede  it. 
The  pattern  of  interlocking  spirals  on 
the  face  of  a  sunflower,  with  Fib(n) 
spirals  twisting  clockwise  and  Fib(n+1) 
spirals  twisting  counter  clockwise,  the 
two  sets  of  spirals  defined  on  the  same 
set  of  florets,  is  particularly  impressive. 
For  sunflowers,  the  value  of  n  is  8, 
producing  interlocking  spirals  of  21  and 
34  florets.  The  same  mathematic  struc¬ 
ture  appears  in  other  plants:  Pinecones 
and  pineapples  show  the  same  spirals, 
but  with  a  different  value  for  n. 

Intriguing  as  these  examples  of  mathe¬ 
matics  in  nature  are,  they  don’t  seem 
to  offer  any  deep  insights  into  nature. 
Apparently  the  number  of  florets  in 
each  row  outward  constrains  the  num¬ 
ber  of  florets  in  the  next  concentric 
row  in  a  way  consistent  with  the  sim¬ 
ple  rule  for  generating  Fibonacci  num¬ 
bers.  Something  like  that.  In  any  case, 
the  math  may  be  nifty,  but  the  underly¬ 
ing  natural  process  generally  turns  out 


on  examination  not  to  be  profound. 

With  fractals,  there  seems  to  be  some¬ 
thing  deeper  at  work. 

My  Science  Project 

Since  reading  The  Science  of  Fractal 
Imagesby  Heinz-Otto  Peitgen  and  Diet- 
mar  Saupe  (Springer- Verlag,  1988),  I’ve 
been  playing  with  one  particular  algo¬ 
rithm  for  producing  graphic  forms  that 
branch  like  plants.  A  program  that  I’ve 
written  uses  simple  transformational 
rules  to  produce  branching  structures 
that  look  more  like  trees  than  anything 
I  could  ever  produce  by  hand. 

What  I  find  more  interesting,  and 
what  has  kept  me  fiddling  with  the 
algorithm  off  and  on  for  two  years,  is 
its  apparent  relevance  to  the  process 
of  growth.  It’s  fascinating  to  watch  the 
process  of  development  of  these  fractal 
flora.  Starting  from  a  single  shoot,  the 
graphic  develops  into  a  twig  with  a 
couple  of  offshoots,  then  into  some¬ 
thing  that  looks  like  a  b-tree  in  a  wind¬ 
storm,  finally  turning  into  a  credible 
sketch  of  a  bare  tree.  While  there  exist 
algorithms  for  putting  leaves  on  the 
branches,  it’s  not  the  verisimilitude  of 
the  static  image  that  impresses  me,  but 
the  accuracy  of  the  simulation  of  the 
development  process. 

Note:  The  development  of  the  frac¬ 
tal,  the  series  of  stages  it  goes  through 
as  it  increases  in  complexity,  is  strictly 
an  artifact  of  the  way  fractals  are  de¬ 
fined.  Although  it  is  possible  to  pick 
parameters  so  as  to  create  a  final  image 
resembling  one  plant  or  another,  it  isn’t 
possible,  so  far  as  I  can  tell,  to  control 
the  process  of  development  by  the 
choice  of  parameters.  I’ve  made  no 
attempt,  in  any  case,  to  mirror  any  kind 
of  natural  process;  the  program  does 
it  —  er,  naturally. 

Something  is  going  on  in  the  devel¬ 
opment  of  the  fractal  that  has  something 
deep  in  common  with  what  goes  on 
in  the  growth  of  a  plant.  Fractals  know 
something  about  biological  growth. 

Perhaps  it  has  something  to  do  with 
what  the  Scientific  American  authors 
say  about  fractals:  That  they  are  often 
the  remnant  of  chaotic  nonlinear  dy¬ 
namics.  Apparently  the  presence  in  an 
object  of  a  static  structure  well  mod¬ 
eled  by  a  fractal  is  some  evidence  of 
chaotic  nonlinear  dynamic  processes 
at  work  in  the  development  of  the  ob¬ 
ject.  If  that’s  what’s  happening  in  my 
fractal  flora,  then  the  algorithm  is  do¬ 
ing  more  than  drawing  nice  tree-like 
pictures.  It  is  a  fairly  deep  simulation 
of  the  process  of  growth  in  organisms. 

I  don’t  want  to  overstate  the  point.  I 
don’t  think  we’re  on  the  verge  of  algo¬ 
rithms  for  simulating  human  develop¬ 
ment  that  will  acquire  and  lose  their 
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(continued  from  page  124) 
gill  slits  as  ontogeny  recapitulates  phy¬ 
togeny.  But  it  is  intriguing  that  the  frac¬ 
tal  flora  simulate  stages  of  natural  growth 
with  no  prompting  in  the  form  of  rigged 
parameters.  The  fact  that  fractals  have 
infinite  detail  and  self-similarity  implies 
a  tot  about  how  they  develop,  and  in 
fact  allows  a  very  simple  initial  rule  to 
apply  at  successively  more  complex 
stages  of  development,  just  as  the  rules 
for  organic  development  must  apply  to 
the  early  stages  of  organ  development 
and  also  to  the  later  stages  in  which 
organs  interact  in  complex  systems. 

Fractals  and  DNA  appear  to  have 
similar  problems  to  solve.  Is  it  possible 


that  they  solve  them  in  similar  ways? 

Field  of  Dreams 

One  of  the  dreams  of  science  fiction, 
and  consequently  of  the  artificial  intel¬ 
ligence  community  that  reads  science 
fiction  stories  for  research  topics,  has 
always  been  the  system  that  programs 
itself.  The  machine  that  actively  seeks 
out  knowledge  in  order  to  grow  more 
wise.  The  vague  notions  of  how  this 
might  come  about  seem  always  to  rest 
on  faith  in  critical  mass.  Even  Douglas 
Hofstadter’s  vision  of  artificial  conscious¬ 
ness  assumes  that  sufficient  complex¬ 
ity  somehow  magically  transforms  a 
system  into  an  intelligence. 


Critical  mass  probably  isn’t  enough; 
natural  systems  need  a  plan  of  devel¬ 
opment,  the  genetic  blueprint.  It  seems 
reasonable  to  expect  that  highly  com¬ 
plex  and  adaptive  artificial  systems 
would  need  some  plan,  too.  The  cur¬ 
rent  Most  Likely  to  Succeed  paradigm 
for  machine  learning,  or  adaptive  sys¬ 
tems,  is  neural  nets.  Currently,  neural 
nets  are  designed  with  as  much  naivete 
regarding  neurophysiology  as  regard¬ 
ing  neuroanatomy.  There  is  little  rea¬ 
son  to  think  that  exposing  a  blank  slate 
neural  net  to  unpredictable  events  will 
lead  it  somehow  to  cope  with  its  envi¬ 
ronment.  If  neural  nets  are  to  grow 
more  complex  in  useful  ways,  don’t 


126 

462 


Dr.  Dobbs  Journal,  May  1990 


we  need  to  build  in  a  plan  for  recogniz¬ 
ing  what  is  useful,  and  shouldn’t  it  be 
a  plan  that  can  admit  of  more  sophisti¬ 
cated  interpretation  as  the  system  gets 
more  sophisticated? 


Do  artificial  neural  nets,  such  as  real 
networks  of  neurons,  need  a  dose  of 
chaos? 

DDJ 


Fractal  Flora 


Here’s  a  sketch  of  the  fractal  program 
I’ve  written.  It  doesn’t  merit  a  pseu¬ 
docode  description,  because  the  un¬ 
derlying  algorithm  is  not  efficient.  My 
purposes  had  as  much  to  do  with 
teaching  HyperTalk  as  with  explor¬ 
ing  fractals,  so  I  implemented  it  so  as 
to  keep  the  concepts  visible,  employ 
simple  user-comprehensible  graphic 
tools,  and  use  only  HyperTalk  code. 
A  serious  exploration  of  fractals  would 
have  to  abandon  all  of  these  con¬ 
straints. 

The  program  uses  turtle  graphics, 
which  is  to  say  that  the  user  describes 
the  figures  to  be  drawn  in  terms  of 
strings  of  one-character  commands, 
which  specify  the  direction  and  move¬ 
ment  of  an  imaginary  drawing  turtle. 
(When  you’ve  been  editor  of  a  maga¬ 
zine  originally  called  Dr.  Dobb’s Jour¬ 
nal  of  Tiny  BASIC  Calisthenics  and 
Orthodontia,  you  learn  how  to  write 
things  like  that  with  a  straight  face.) 
The  program  draws  the  fractals  by 
passing  the  turtle  graphic  commands 
to  a  simple  turtle  graphic  engine. 

The  program  recognizes  these  tur¬ 
tle  graphic  commands: 

Drawing:  F  Forward  1  unit,  pen 
down;  U  Forward  1  unit,  pen  up 
Orientation:  <Turn  one  unit  left; 
>Turn  one  unit  right 
Context:  [  Store  current  turtle  po¬ 
sition  &  direction;  ]  Reset  turtle  to 
previous  position  &  direction 


Figure  1:  Typical  fractal  flora 


Fractals  start  from  a  simple  base 
figure,  and  are  transformed  to  new 
levels  of  complexity  via  transforma¬ 
tion  rules.  The  program  steps  through 
these  levels,  transforming  the  current 
string  of  turtle  graphic  characters  into 
a  new  string.  It  draws  the  current 
version  of  the  fractal  from  the  turtle 
graphic  string  at  each  level.  The  “true” 
fractal  requires  infinite  levels  of  de¬ 
tail,  so  the  program  is  only  drawing 
successive  approximations.  Figure  1 
shows  a  typical  image  generated  by 
the  program. 

The  program  starts  by  prompting 
the  user  for  parameters.  The  user  must 
give  the  fractal  a  title,  a  base  string  of 
turtle  graphic  commands  (the  single 
command  F  is  typical),  a  repeatMode, 
a  unitAngle,  and  a  set  of  rules  for 
transforming  the  base  string  to  pro¬ 
duce  higher  levels  of  the  fractal.  Re¬ 
peatMode  controls  how  the  program 
steps  through  the  levels,  and  unitAn¬ 
gle  (0-360)  controls  how  sharply  the 
turtle  turns. 

A  typical  transformation  rule  is  F 
->  F[>F][<F].  This  turns  each  straight 
line  at  level  n  into  a  fork  consisting 
of  one  step  forward  and  branches  to 
the  left  and  right.  The  user  enters 
these  transformation  rules  in  response 
to  specific  prompts.  Each  such  prompt 
shows  a  turtle  graphic  character  and 
asks  what  it  is  to  be  transformed  into. 
Initially,  these  characters  are  just  the 
characters  in  the  base  string,  but  as 
new  rules  are  added,  they  may  add 
new  characters,  requiring  new  rules. 
Rules  not  involving  commands  [and] 
will  produce  figures  such  as  coast¬ 
lines  and  mountain  ridges;  using  [and] 
will  produce  branching  structures  such 
as  trees  and  blood  vessels. 

Perhaps  the  main  point  of  describ¬ 
ing  this  process  is  to  show  how  ineffi¬ 
cient  fractals  are.  Because  each  trans¬ 
formation  is  a  function,  one  could,  I 
suppose,  decide  how  many  levels 
deep  you  want  to  go  and  compute 
the  composition  of  the  functions 
needed,  applying  this  function.  For 
me,  computing  and  drawing  each  suc¬ 
cessive  level  is  important  because  it 
is  the  process  of  fractal  growth  that 
I’m  interested  in.  —  M.S. 
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SD  ’90  and  ANSI 
at  Last 


This  column  comes  to  you  from 
the  Software  Development  ’90  con¬ 
ference  at  Oakland,  California. 
Every  year,  the  conference  gets 
bigger  and  better.  I  am  honored  this 
year  to  have  been  invited  to  participate 
on  the  Comparative  Language  Panel 
representing  C  and  C++.  More  about 
that  later. 

SD  ’90  is  the  place  where  vendors 
of  programmers’  products  —  compil¬ 
ers,  function  libraries,  CASE  tools,  edi¬ 
tors,  debuggers,  and  so  on  —  show  their 
stuff  to  the  programmers  who  attend. 
Besides  the  product  exhibits,  there  are 
workshops  and  lectures  all  week  long. 

The  highlight  of  the  show  was  a 
two-day  session  with  Bjame  Stroustrup. 
The  creator  of  C++  gave  a  wall-to-wall 
discussion  of  how  to  make  the  transi¬ 
tion  to  his  creation,  the  language  that 
will,  I  believe,  prevail  in  the  ’90s. 

Turbo  Debugger  and  Tools 

Borland  surprised  us  all  in  a  press  con¬ 
ference  on  Tuesday.  They  announced 
their  new  Turbo  Debugger  and  Tools 
product,  but  that  wasn’t  the  surprise. 
The  first  jolt  came  while  we  sat  waiting 
for  the  show  to  start.  The  crowd  was 
moving  past  my  seat  when  I  realized 
that  a  German  Shepherd  had  her  head 
in  my  lap.  It  was  Duchess,  Debe  Nor- 
ling’s  seeing  eye  dog,  patiently  waiting 
for  Debe  to  find  a  place  to  sit.  Debe  is 


Al  Stevens 


a  C  freelance  programmer  and  writer 
who  has  kindly  reviewed  some  of  my 
books  in  other  publications. 

The  purpose  of  the  press  conference 
was  to  show  some  new  stuff  from 
Borland.  Eugene  Wong  demonstrated 
the  new  Turbo  Debugger,  Profiler,  and 
Assembler.  He  interspersed  the  daz¬ 
zling  demonstration  with  the  expected 
number  of  cheap  shots  at  Microsoft 


accompanied  by  the  usual  approving 
laughter  from  the  audience.  The  big 
surprise  came  at  the  conclusion  of  the 
presentation.  Eugene  began  to  tell  us 
about  a  nifty  optimizing  C  compiler 
that  works  with  the  Turbo  Debugger 
and  Turbo  Profiler.  The  audience  paled 
when  Eugene  told  us  that  the  C  com¬ 
piler  in  question  was  Watcom  C!  Then, 
wonder  of  wonders,  he  introduced  Ian 
McPhee,  the  president  of  Watcom  who 
came  to  the  podium  to  exhort  the  vir¬ 
tues  of  Watcom  C  8.0. 

That  peculiar  chain  of  events  left  the 
entire  conference  wondering  if  Borland, 
vendor  of  the  respected  Turbo  C,  had 
lost  their  corporate  marbles.  Does  Gim- 
bel’s  tout  Macy’s?  It  took  me  a  couple 
of  days  to  run  down  an  “informed 
source”  in  Borland  to  get  an  explana¬ 
tion.  David  Intersimone,  Borland’s  trav¬ 
eling  evangelist,  assured  me  that 
Borland  is  not  surrendering  the  high- 
end  C  compiler  market  to  Watcom  or 
anyone  else.  It’s  just  that  they  want  to 
position  the  debugger  and  profiler  as 
everyone’s  favorite  tool  collection,  re¬ 
gardless  of  the  compiler  they  use. 
Borland  revealed  the  formats  that  a 
compiler  must  emit  in  order  to  be  com¬ 
patible,  and  invited  all  the  other  com¬ 
piler  folks  to  sign  up.  But  so  far  Wat¬ 
com  is  the  only  outfit  to  get  on  board. 
That’s  good  news  for  professional  de¬ 
velopment  shops.  You  can  use  Turbo 
C  and  the  Tools  to  develop  a  system 
and  Watcom  C  for  the  final  compile. 
Watcom’s  optimizer  is  one  of  the  best. 

What's  New? 

I  saw  a  number  of  neat  C  products  but 
not  much  that  was  new.  Most  vendors 
showed  new  versions  of  existing  prod¬ 
ucts.  I  was  particularly  impressed  with 
a  package  called  “Pro-C”  that  is  trying 
to  replace  most  of  us.  You  interactively 
describe  a  system  that  uses  screens  and 
a  data  base  and  Pro-C  from  Vestronix 
(another  Canadian  developer)  emits  C 


code  that  you  can  tweak  and  compile 
to  implement  the  system,  reminiscent 
of  the  application  generators  of  yore 
that  crank  out  Cobol.  I  haven’t  tried  it, 
but  the  demonstration  was  impressive. 

The  Comparative  Language  Panel 

Warren  Keuffel  of  Miller-Freeman  in¬ 
vited  me  to  represent  C  and  C++  on  this 
year’s  Comparative  Language  Panel  at 
SD  ’90.  The  panel  members  each  wrote 
a  program  to  a  specification  prescribed 
by  Warren,  then  used  their  programs  to 
emphasize  the  strengths  of  their  lan¬ 
guages.  Here’s  the  specification. 

“You  are  bidding  for  a  lucrative  con¬ 
tract  with  MegaBucks  Corporation,  de¬ 
veloping  all  of  their  software.  As  part 
of  the  bidding  process,  MegaBucks  has 
asked  you  to  write  a  small  program 
which  demonstrates  the  strengths  of 
your  tools.  The  program,  a  gas  mileage 
checker  for  the  president  of  MegaBucks, 
accepts  as  (minimum)  input  the  date, 
the  number  of  gallons  of  gas  purchased, 
and  the  price  paid  for  the  gas.  Output 
is  any  meaningful  graphical  display  or 
printed  report  which  will  impress  the 
MegaBucks  executives.” 

One  of  the  speakers  at  SD  ’90  was 
Ken  Orr  who  wrote  and  published  a 
book  in  1981  called  Structured  Require¬ 
ments  Definition.  The  book  discusses 
the  theory  of  output-oriented  design, 
which  says,  “determine  the  outputs  and 
work  backwards.”  Warren’s  specifica¬ 
tion  for  the  panel  carries  that  idea  to  a 
new  level.  This  is  my  first  design  that 
starts  with  any  meaningful  output  that 
will  impress  the  client. 

Warren’s  purpose,  of  course,  was  to 
give  us  enough  leeway  to  use  our  lan¬ 
guages  to  their  best  advantage.  I  de¬ 
cided  to  forego  fancy  graphics  outputs 
because  such  libraries,  while  available 
to  C  and  C++  programmers  are  not 
intrinsic  parts  of  the  languages  them¬ 
selves.  Instead,  I  used  the  simple  stan¬ 
dard  input  and  output  functions  from 
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1987  Corvette 

License 

#  JXA283 

Date 

miles 

gas 

cost 

mpg 

cost/mile 

2-01-90 

550 

40 

45.00 

13 

0.08 

2-09-90 

450 

30 

32.50 

15 

0.07 

totals 

1000 

70 

77.50 

14 

0.08 

1989  Dodge  License  # 

HMS001 

Date 

miles 

gas 

cost 

mpg 

cost/mile 

2-02-90 

250 

10 

11.25 

25 

0.05 

2-04-90 

10 

0 

0.00 

0 

0.00 

2-04-90 

122 

7 

7.00 

17 

0.06 

totals 

382 

17 

18.25 

22 

0.05 

Figure  1:  Gas  mileage  report 


both  languages  and  wrote  filter  pro¬ 
grams  that  read  an  input  file  and  write 
a  report. 

We  each  had  10  minutes  for  our  pres¬ 
entations.  Warren  sat  down  front  and 
glared  between  us  and  his  watch.  I  felt 
like  the  guy  who  talks  fast  in  the  TV 
commercials.  Even  though  I  was  doing 
two  languages,  Warren  wouldn’t  give 
me  20  minutes.  Must  be  because  he 
works  for  that  other  magazine. 

Figure  1  shows  the  report.  The  trip 
report  displays  trips  by  automobiles 
showing  the  date,  miles  traveled,  gaso¬ 
line  purchased,  cost,  miles  per  gallon, 
and  cost  per  mile.  Figure  2  is  the  input. 
I  assumed  that  the  system  had  a  data 
entry,  validation,  and  sorting  process, 
and  that  the  input  would  be  correct 
and  in  sequence,  so  I  built  the  test 
input  file  as  shown  in  Figure  2.  The  first 
three  lines  are  the  first  car  description 
with  the  license  number,  model  year, 
and  make.  Then  come  five-line  trip 
records  with  date,  odometer  in,  odome- 


JXA283 

1987 

Corvette 

02/01/90 

10550 

10000 

40 

45.00 

02/09/90 

11000 

10550 

30 

32.50 

end 

HMS001 

1989 

Dodge 

02/02/90 

5450 

5200 

10 

11.25 

02/04/90 

5460 

5450 

0 

0 

02/04/90 

5582 

5460 

7 

7 

end 

end 


Figure  2:  Report  input 
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(continued  from  page  130) 
ter  out,  gallons  bought,  and  money 
spent.  The  trip  records  for  a  vehicle  are 
terminated  with  an  “end”  record.  The 
file  is  likewise  terminated. 

At  this  point  I  made  what  may  be  an 
accidental  dubious  historic  decision.  I 
decided  to  write  the  C++  program  first. 
After  completing  the  C++  program,  I 
ported  it  to  C.  This  might  be  the  only 
time  anyone  has  done  that.  I  did  it 
because  I  was  too  lazy  to  start  from 
scratch  again.  All  the  pieces  were  in 
place  in  the  C++  program,  and  all  I 
needed  to  do  was  move  them  around. 

This  reverse  exercise  in  inertia  gave 
me  the  opportunity  to  observe  the  ex¬ 
tent  to  which  the  C++  treatment,  with 
its  almost  object-oriented  flavor,  would 
influence  the  appearance  of  the  C  pro¬ 
gram.  Would  the  approach  to  C  look 
different  than  it  would  have  if  I  had 
started  from  scratch?  The  conclusions 
I  drew  are  two-edged.  The  program 
does  not  look  substantially  different 
than  other  C  programs  of  similar  scope. 
The  difference  is  in  how  I  think  about 
the  program.  I  designed  the  C++  pro¬ 
gram  by  beginning  with  the  data  ob¬ 
jects  and  building  classes.  As  I  thought 
about  the  algorithms  that  a  class  needed, 
I  considered  them  to  be  methods  of  the 
class,  functions  that  are  bound  to  the 
class  and  not  executed  in  any  other 


context.  The  C  port  has  those  same 
algorithms  but  they  are  not  bound  to 
the  data  structures,  at  least  not  in  the 
code.  They  are,  however,  bound  to¬ 
gether  in  my  mind.  That  program  is 
object-oriented  in  spirit  if  not  in  sub¬ 
stance,  but  you  wouldn’t  know  it  by 
looking  at  it.  Strange. 

Let’s  look  at  the  C  program  first.  List¬ 
ing  One,  page  146,  is  auto.h,  the  header 
!  file  that  describes  the  data  structures. 
You  can  see  the  C++  influence  right 
away.  All  the  data  items  have  object 
names  even  if  only  by  way  of  a  typedef . 
Listing  Two,  page  146,  is  auto.c,  the 
rest  of  the  program.  This  is  an  unremark¬ 
able  program,  one  that  reads  the  input 
and  writes  the  report.  See  if  you  can 
find  much  in  the  way  of  C++  influence 
here. 

Now  consider  the  C++  system.  List¬ 
ing  Three,  page  146,  is  auto.hpp,  a 
header  file  that  describes  the  classes 
for  the  program.  The  first  notable  dif¬ 
ference  between  this  file  and  auto.h  is 
that  the  date  structure  has  a  display 
function  built  into  it.  That  same  func¬ 
tion  exists  in  the  C  program,  but  it  is 
not  bound  as  tightly  to  the  structure  it 
supports.  In  C  you  could  call  it,  pass  it 
anything  that  looked  like  a  date,  and  it 
would  display  something.  In  C++  the 
only  way  to  call  it  is  through  an  in¬ 
stance  of  the  ^restructure. 


The  Automobile  and  Trip_Record 
classes  have  the  same  data  members 
that  their  equivalent  C  structures  have, 
but  they  also  have  constructor,  de¬ 
structor,  and  other  member  functions. 
There  are  overloaded  functions  and  op¬ 
erators  and  other  of  the  C++  extensions. 
Listing  Four,  page  148,  is  auto.cpp,  the 
code  for  the  member  functions.  Then 
Listing  Five,  page  148,  is  autorpt.cpp, 
the  code  for  the  application. 

The  distribution  of  code  is  different 
in  the  C++  program.  Much  of  what  you 
find  in  the  auto.c  part  of  the  C  program 
goes  into  the  class  member  functions 
and  could  be  tucked  away  as  part  of  a 
reusable  class  library  for  the  program¬ 
mers  who  work  for  the  purveyors  of 
the  Automobile  Use  Tracking  Output 
System  (AUTOS.  See  how  easy  acro¬ 
nyms  are?) 

There  are  two  questionable  short¬ 
cuts  in  the  C++  program.  The  memory 
for  the  instances  of  Automobiles  and 
Trip_Records  comes  from  the  free  store 
and  never  gets  sent  back.  Their  alloca¬ 
tion  occurs  in  functions  that  return  the 
objects  themselves  rather  than  the  point¬ 
ers,  so  when  they  are  ready  to  go  out 
of  scope,  the  pointer  values  are  not 
around  to  be  deleted.  This  apparent 
insanity  came  as  the  result  of  some  as 
yet  unresolved  conflict  between  me  and 
the  Zortech  compiler.  The  problem  was 
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(continued  from  page  132) 
probably  mine,  and  the  deadline  for 
the  panel  approached,  so  I  took  the 
easy  way  out. 

Had  I  not  had  that  problem  I  might 
have  needed  to  code  an  overloaded 
assignment  function  for  the  Automo¬ 
bile  class.  Its  destructor  deletes  the 
strings  that  contain  the  license  number 
and  manufacturer.  If  you  use  objects 
of  this  class  as  designed  in  an  assign¬ 
ment,  the  sending  object’s  pointers  will 

I  decided 
to  write  the  C++ 
program  first 


get  deleted  twice  when  the  two  objects 
go  out  of  scope.  A  well-designed  class 
will  include  an  assignment  function  that 
correctly  manages  free  store  pointers 
in  the  sending  and  receiving  objects. 
But  because  the  Automobile  class  never 
gets  assigned  in  such  a  way,  the  prob¬ 
lem  does  not  occur,  and  I  did  not  spend 
the  time  to  build  an  assignment  func¬ 
tion. 

The  point  of  the  presentation  was 
to  stress  the  strengths  of  the  languages. 
The  strengths  of  C  are  well  known.  Its 
greatest  strength  is  its  newest,  how¬ 
ever,  and  that  is  that  the  standard  has 
been  approved.  C  is  a  standard  lan¬ 
guage.  It  delivers  tight,  concise  code, 
is  known  by  many  programmers,  and 
holds  the  confidence  of  many  manag¬ 
ers.  Those  strengths  add  up  to  lots  of 
jobs  for  programmers  and  almost  lots 
of  programmers  to  fill  the  jobs.  C  is 
especially  suited  for  systems  program¬ 
ming  because  of  its  tight  code,  because 
you  can  get  close  to  the  machine,  and 
because  it  is  loosely  typed. 

Don’t  laugh.  One  of  the  strengths  of 
C++  is  that  it  is  strongly  typed.  But  C++ 
serves  different  purposes  with  its  object- 
oriented  approach  to  software  design 
and  development  and  its  facility  that 
allows  a  programmer  to  extend  the  lan¬ 
guage  with  new  data  types.  My  favorite 
strength  of  C++  is  that  when  the  OOPS 
way  doesn’t  seem  to  fit,  I  can  lapse  into 
good  old  reliable  C. 

Both  languages  share  the  advantage 
that  when  you  choose  them,  you  do 
not  automatically  sign  up  to  a  particu¬ 
lar  user  interface  or  data  base  model. 
They  are  implemented  on  many  sys¬ 
tems  with  separate  function  and  class 
libraries  that  support  these  things. 

Other  languages  represented  on  the 
panel  were  SCHEME,  Rexx,  Smalltalk, 
and  MicroStep.  When  the  panel  was 


over,  Warren  asked  each  of  us  to  choose 
the  language  we  would  use  if  we 
needed  to  switch  to  one  of  the  others. 
I  had  never  used  any  of  the  other  lan¬ 
guages  and  so  I  chose  the  one  I  could 
read  without  already  knowing  it.  That 
one  was  Rexx,  an  interpreted  prototyp¬ 
ing  language. 

Crotchet  of  the  Month: 

Installation  Programs 

It  was  2:00  a.m.  My  eyes  were  droop¬ 
ing  and  my  jaws  were  locked.  I  hate 
installation  programs  that  don’t  work. 
Zortech  C++  2.0  is  a  case  in  point.  It 
arrived  in  the  afternoon,  and  I  eagerly 
set  about  to  install  it,  anxious  to  use  it 
for  the  exercises  in  a  book  I’m  writing 
called  Teach  Yourself  C++  and  for  the 
SD  ’90  Comparative  Language  Panel 
just  mentioned.  Because  the  book  gets 
into  some  of  the  features  of  C++  2.0,  I 
need  a  2.0  compiler  to  test  the  exer¬ 
cises.  Just  now,  Zortech  is  the  only  2.0 
compiler  I  have. 

The  Zortech  installation  program 
started  out  bad  and  went  downhill  af¬ 
ter  that.  Its  first  message  is  one  about 
screen  refreshes.  That  message  is  not 
the  one  specified  in  the  Installation 
Guide  as  the  first  one.  That  apparent 
contradiction  set  me  to  tearing  through 
the  manual  trying  to  figure  where  I  was 
or  if  I  was  running  the  wrong  program. 
Then,  although  Zortech  sent  me  3.5- 
inch  diskettes,  the  program  tells  me 
that  it  is  installing  from  5.25-inch  disk¬ 
ettes.  That  made  me  worry.  Next,  a 
screen  that  asks  which  disk  drive  I  am 
installing  on  accepts  my  D  and  imme¬ 
diately  disappears  with  no  reassurance 
that  it  knows  where  it  is  installing.  The 
feeling  it  gave  was  that  an  error  had 
occurred,  and  the  doubt  caused  me  to 
restart  several  times.  When  at  last  I 
figured  that  the  program  must  know 
what  it  was  doing,  it  took  off,  asking 
for  the  compiler  disks,  one  by  one. 
After  copying  files  from  Compiler  Disk¬ 
ette  #4,  the  program  asked  for  Com¬ 
piler  Diskette  #5.  There  is  no  Compiler 
Diskette  #5.  The  only  way  out  of  the 
program  was  to  press  Ctrl-Break.  The 
installation  program  nicely  terminated, 
informing  me  that  it  had  done  so  at 
my  request  and  then  locked  up  the 
system.  Arrgh! 

Hoping  beyond  hope,  I  assumed  that 
the  compiler  files  I  needed  had  been 
copied  and  that  I  could  copy  the  ones 
from  the  Tools,  Debugger,  and  Library 
Source  diskettes.  The  documentation 
said  I  could.  However,  it  turns  out  that 
the  Tools  diskette  is  not  a  Tools  disk¬ 
ette  at  all  but  a  copy  of  the  Debugger 
diskette.  I  have  no  tools,  it  seems.  Well, 
that’s  OK,  I’ll  get  them  later.  With  ev¬ 
erything  else  that  I  thought  I  needed 
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in  place,  I  loaded  the  ZTCHELP  pro¬ 
gram.  This  is  Zortech’s  on-line  TSR  help 
program  after  the  fashion  of  similar 
programs  available  with  Borland  and 
Microsoft  language  products.  It  tells  me, 
however,  that  it  cannot  find  its  data 
file,  ZTC.HLP.  The  documentation  says 
there  should  be  one.  I  found  a  file 
named  ZTCP.HLP  and  renamed  it. 
Great,  now  ZTC  can  find  its  data  base. 
I  loaded  the  ZED  editor,  typed  “printf” 
and  pressed  Shift-Fl,  the  ZTCHELP  hot 
key.  One  pretty  window  with  much 
unreadable  stuff  in  it.  Stuff  happens. 

It’s  11:00  the  following  morning.  My 
eyes  are  wide  open  and  my  jaws  are 
relaxed.  A  call  to  Zortech’s  technical 
support  person  reveals  that  a  foul-up 
in  the  London  office  was  the  culprit 
and  that  it  had  been  caught  and  cor¬ 
rected.  He  told  me  how  to  get  the  help 
system  working  and  that  my  compiler 
is  complete.  They  are  sending  me  new 
diskettes  complete  with  tools,  and  I 
am  underway  once  again. 

To  the  folks  at  Zortech  and  anyone 
else  who  builds  tools  for  programmers: 
When  a  software  developer  can’t  get 
something  as  simple  as  the  installation 
program  and  distribution  diskettes  right, 
it  makes  us  wonder  about  the  quality 
of  the  software  that  almost  gets  in¬ 
stalled.  Why  do  you  developers  feel 
the  need  to  get  cute  with  pretty  win¬ 
dows  that  ask  a  few  questions  and  then 
do  nothing  more  than  make  subdirec¬ 
tories,  copy  files,  and  mangle  our  CON¬ 
FIG.SYS  and  AUTOEXEC.BAT  files?  It 
would  be  OK  if  you  could  get  the  pro¬ 
grams  to  work,  but  you  can’t,  obvi¬ 
ously,  and  you  needn’t  have  bothered 
trying.  That  sort  of  installation  program 
is  nice  for  poor  old  word  processor 
and  spreadsheet  users  who  might  not 
know  about  DOS  and  such,  but  we 
compiler  users  are  programmers,  for 
Pete’s  sake.  Tell  us  what  and  where  the 
files  are  and  where  to  put  them.  And 
let  us  tell  you  where  to  put  your  stupid 
installation  programs.  Finally,  try  to  get 
the  distribution  package  right.  Try  to 
get  all  the  files  on  the  disks  where  you 
say  they  are.  Try  to  get  a  little  control 
on  your  quality. 

ANSI  Standard  C 

The  ANSI  Board  of  Standards  Review 
approved  the  draft  proposed  standard 
for  C  as  an  ANSI  standard  in  the  De¬ 
cember -January  time  frame.  This  is  a 
monumental  achievement  that  reflects 
years  of  hard  work  by  a  small  number 
of  dedicated  souls  called  collectively 
the  “X3J11  committee.”  The  next  sev¬ 
eral  years  will  involve  the  committee 
in  the  task  of  interpreting  the  standard, 
which  involves  telling  anyone  who  asks 
what  this  or  that  paragraph  in  the  docu- 
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ment  really  means.  I  wouldn’t  want 
that  job. 

By  the  time  this  column  reaches  you, 
the  official  document  should  be  avail¬ 
able.  Its  name  is  the  “American  Na¬ 
tional  Standard  for  Programming  Lan¬ 
guage  C.”  It  is  formally  known  as  X3.159- 
1989.  It  is  hard  to  read.  See  what  fol¬ 
lows  for  two  reasonable  alternatives. 

Paperback  Writer 

Don’t  think  all  those  dedicated  X3J11 
volunteers  will  go  uncompensated. 
Some  of  them  are  writing  books,  an 
activity  of  which  I  heartily  approve. 

The  small  paperback  book  format  is 
popular  now  among  publishers  of  com¬ 
puter  books.  Every  subject  imaginable 
is  out  in  a  “quick  reference  guide,” 
which  means  a  small  book  and,  you 
hope,  a  small  price.  Such  a  book  is 
Standard  C  by  P.J.  Plauger  and  Jim 
Brodie  (Microsoft  Press,  1989).  Both 
authors  are  officers  on  the  X3J 1 1  com¬ 
mittee  and,  as  such,  can  be  considered 
authorities  on  the  subject.  This  book 
is  an  excellent  reference  manual  on  the 
syntax  and  function  libraries  of  stan¬ 
dard  C.  Typical  of  the  publishing  in¬ 
dustry,  the  book’s  publication  was  sched¬ 
uled  to  coincide  with  the  approval  of 
the  standard.  The  approval  was  de¬ 
layed  but  the  book  came  out  anyway. 
No  matter,  you’d  be  hard  put  to  find 
any  discrepancies. 

I  use  this  book  as  my  primary  refer¬ 
ence  work  when  I  want  to  write  a 
standard  C  program,  and  it  hasn’t  let 
me  down  yet.  I  have  two  complaints, 
though.  The  book  uses  the  “railroad 
track”  diagram  format  to  describe  the 
rules  of  syntax.  This  is  a  format  that  is 
generally  unfamiliar  to  most  program¬ 
mers  unless  they  design  languages  or 
write  compilers.  The  diagrams  can  be¬ 
come  complex  and  generally  unattrac¬ 
tive,  and  you  will  find  yourself  retreating 
to  the  description  of  the  diagram  format 
so  you  can  understand  the  diagrams. 

My  other  complaint  is  one  of  format. 
I’d  spend  less  time  looking  things  up 
in  the  book  if  the  function  descriptions 
were  organized  alphabetically  by  func¬ 
tion  rather  than  by  function  within  the 
name  of  the  header  file  that  contains 
the  function’s  prototype. 

Complaints  aside,  I  can  recommend 
this  book.  Every  C  programmer  should 
have  it. 

Mutt  and  Jeff 

The  little  Standard  C  book  just  dis¬ 
cussed  is  a  pure  reference  work.  No 
tutorial.  If  you  don’t  already  know  some¬ 
thing  about  C,  look  elsewhere.  Here  is 
where  to  look.  Another  prominent  mem¬ 
ber  of  the  X3J11  committee  is  Rexjaes- 
chke,  well-known  C  author,  consult¬ 


ant,  and  teacher.  He  has  written  a  big 
book  called  Mastering  Standard  C, 
(Professional  Press,  1989).  I  say  big 
book,  because  instead  of  the  little  pa¬ 
perback  format,  Rex  has  chosen  the  8.5 
x  11,  spiral  bound  format  for  this  com¬ 
prehensive  tutorial  on  standard  C.  Start 
with  this  one.  It  uses  the  tutorial  ap¬ 
proach,  describing  the  subjects  in  eas¬ 
ily  read  English  and  in  a  sequence  de¬ 
signed  to  teach  rather  than  describe. 
Besides,  it  lays  flat  on  your  desk,  stay¬ 
ing  open  to  the  page  you’ve  selected. 

Of  course  I  have  a  complaint.  I’ve 
been  looking  in  vain  for  a  use  for  the 
preprocessor’s  ##  token  pasting  opera¬ 
tor.  X3J 1 1  added  it  to  the  language,  and 
whoever  dreamed  it  up  must  have  had 
a  use  for  it.  However,  none  of  the  writ¬ 
ten  matter  I’ve  seen  tells  me  what  the 
heck  it  is  for.  You  would  not  expect  a 
reference  work  to  tell  you  how  you 
might  want  to  use  some  feature,  but  a 
tutorial  should  offer  at  least  a  glimmer, 
especially  when  the  subject  is  as  ab¬ 
struse  as  this  token  pasting  operator. 
Rex  apparently  doesn’t  understand  it 
either.  He  not-so-deftly  sidesteps  the 
issue  by  saying  that  it  is  too  advanced 
to  be  discussed. 

If  you  want  to  learn  the  C  language 
and  are  willing  to  spend  some  time 
learning  it  end-to-end,  Mastering  Stan¬ 
dard  C  is  a  good  way  to  go. 

"Just  Say  Si" 

Soon  we’ll  stop  saying  “ANSI  C”  and 
start  saying  “Standard  C.”  Then,  when 
the  old  non-conforming  compilers  bite 
the  dust,  we’ll  drop  the  “standard.” 
Maybe  someday,  when  the  two  finally 
converge,  we’ll  stop  saying  “C++”  and 
just  say  C. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  146.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  14. 
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Grinding  the 
Speckled  Axe 


here’s  an  old  story  they  tell  up 
in  Wisconsin: 

A  farm  boy  found  an  old  axe 
chunked  into  a  tree  stump  while 
trampin’  the  deep  woods.  He  brought 
it  home,  touched  up  the  edge  with  his 
trusty  whetstone,  and  found  that  it  still 
cut  wood  as  well  as  an  axe  oughter. 
The  axe  head  had  gotten  mighty  rusty 
over  the  years,  though,  and  was  all 
pitted  and  rough. 

So  the  boy  asked  his  paw  if  he’d 
grind  the  axe  head  full  bright  agin  on 
the  big  grinding  wheel  out  aside  the 
barn.  And  his  paw  said,  “Sure,  son  —  if 
you  turn  the  wheel.” 

So  the  boy  pushed  the  pedal  of  the 
big  grinding  wheel  while  his  paw 
pressed  the  old  axehead  agin  it.  The 
sparks  flew,  because  his  paw  was  a 
strong  man  and  held  the  axe  head  hard 
agin  the  wheel.  The  rust  was  ground 
away,  but  under  it  all  the  deepest  rust 
spots  still  showed  as  speckles  all  over 
the  new  bright  steel. 

So  the  man  kept  the  axe  head  pressed 
hard  agin  the  wheel,  knowing  his  son 
wanted  it  ground  full-bright.  But  after 
half  an  hour,  the  speckles  were  fewer 
but  still  there,  and  the  boy  let  up  on  the 
pedal  so  that  the  wheel  stopped. 

“Come  on,  son,”  his  paw  said,  “we’ll 
make  those  speckles  go  away  afore 
sundown!” 

But  the  boy,  when  he  stopped  pant- 
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ing,  lowered  his  eyes  and  said,  “Y’know, 
paw,  I  heard  at  school  last  week  that 
speckled  axes  was  fersure  the  latest 
thing.” 

The  Axe  or  the  Pits? 

The  next  time  you  find  yourself  work¬ 
ing  long  past  sundown  grinding  the 
pits  from  a  speckled  axe,  think  hard 
about  the  very  serious  question:  What 


am  I  working  on?  The  axe  or  the  pits? 

It’s  a  funny  thing  about  this  pro¬ 
gramming  stuff.  Unlike  a  lot  of  work  I 
can  think  of  (like  being  a  soda  jerk  at 
Walgreen’s  or  going  around  the  back¬ 
yard  in  March  picking  up  what  the 
dog’s  been  doing  all  winter)  it’s  fun.  It 
can  become  so  much  fun  that  watching 
the  sparks  and  pumping  the  pedal  take 
on  a  fascination  all  their  own,  regard¬ 
less  of  the  work  actually  being  done. 

Complicating  the  issue  is  the  fact 
that  a  lot  of  us  (and  I’m  certainly  right 
in  there)  grind  away  at  the  pits  because 
it  feels  good,  without  needing  to  get 
anything  in  particular  accomplished. 
This  is  why  there  are  Mandelbrot  Set 
programs  all  over  the  place;  man,  you 
want  sparks? 

Now  and  then  I  think  it’s  well  worth 
drawing  a  sharp  line  between  work 
that  has  to  be  done  because  the  job 
needs  doing,  and  work  that  gets  done 
because  it  feels  good.  If  you  get  a  kick 
out  of  spinning  elaborate  menuing  and 
windowing  systems  out  of  thin  air,  the 
tendency  is  to  launch  in  and  do  it  all 
over  again  whenever  you  pick  up  a 
consulting  project  or  get  a  new  assign¬ 
ment  from  the  boss.  Remember:  They’re 
not  paying  you  for  the  shine.  They’re 
paying  you  for  the  edge. 

Unearthing  a  Truly  Ugly  Truth 

This  bears  on  the  theme  I  began  last 
month,  which  is  the  art  of  designing 
with  object-oriented  techniques.  OOP 
brings  a  level  of  modularity  and  loose 
coupling  to  structured  programming  that 
has  been  almost  unknown  until  today. 
The  same  well-designed  object  hierar¬ 
chy  can  be  used  as  the  foundation  for 
many  different  applications,  in  part  be¬ 
cause  of  that  modularity,  and  in  part 
because  OOP  is  unexcelled  at  general¬ 
izing  functionality.  It’s  the  ultimate  in 
efficient  boilerplating  schemes:  Take  a 
generic  field  object  and  add  to  it  only 
what  it  needs  to  become  a  date  field 


object,  or  a  phone  number  field  object, 
or  a  Boolean  field  object.  Take  what 
you  can.  Add  only  what  you  must. 

So  what  I’m  going  to  tell  you  to  do 
early-on  in  an  OOP  development  pro¬ 
ject  is  this:  Take  a  walk  in  the  woods. 
See  what’s  lying  around,  and  see  what 
you  can  bring  back  with  you.  Resist, 
as  much  as  possible,  the  Not  Invented 
Here  syndrome.  If  it  works,  and  if  it’s 
even  remotely  close  to  what  you  need, 
grab  it.  If  necessary,  bend  your  spec 
to  align  it  with  the  architecture  of  the 
object  libraries  you  find. 

I  say  this  for  a  very  important  reason. 
With  going  on  a  year  of  object-oriented 
exploration  behind  me,  I  have  identi¬ 
fied  (and  others  have  verified)  a  Truly 
Ugly  Truth:  Designing  a  workable  and 
efficient  object  hierarchy  is  murder. 
Much  of  the  ease  and  the  magic  in 
Smalltalk  stems  from  the  fact  that  its 
standard  class  libraries  are  works  of 
brilliance,  they’re  done,  they  have  some 
history  (Smalltalk  was  in  “design  mode” 
for  about  15  years  before  becoming 
available  for  small  machines),  and 
they’re  yours  with  the  language.  Much 
the  same  is  true  of  Actor,  and  if  it 
doesn’t  have  as  many  years  of  history, 
that’s  mostly  because  its  authors  built 
on  the  better  features  of  well-known 
and  thoroughly  shaken-out  languages 
such  as  C  and  Pascal. 

This  sounds  a  little  like  I’m  growing 
disenchanted  with  OOP  in  general.  Not 
true  —  but  as  I  said  in  an  earlier  col¬ 
umn,  the  hype  has  gotten  way  out  of 
hand,  especially  when  we  don’t  really 
know  what  OOP’s  true  value  to  the 
programming  art  will  turn  out  to  be. 
People  have  been  attributing  “easy,  has¬ 
sle-free  prototyping”  to  the  OOP  na¬ 
ture  of  languages  such  as  Smalltalk,  when 
in  fact  the  ease  of  prototyping  was  due 
to  the  brilliance  and  completeness  of 
the  class  libraries.  Prototyping  in  “na¬ 
ked"  (that  is,  class-less)  Object  Pascal 
is  no  easier  than  prototyping  in  Ex- 
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tended  Pascal,  or  whatever  people  will 
eventually  come  to  call  the  Turbo  Pas¬ 
cal  standard  language  definition. 

So  if  you’re  launching  into  an  ambi¬ 
tious  design  project  in  Object  Pascal 
or  (God  help  us)  C++,  do  not  expect 
the  OOP  nature  of  the  underlying  lan¬ 
guage  to  make  things  easier  on  you. 
On  the  contrary,  you  will  soon  be  up 
to  your  nether  parts  in  some  of  the 
most  intractable  decisions  of  your  en¬ 
tire  career. 

Drawing  the  Line  Between 
Parent  and  Child 

Let  me  give  you  a  very  simple  f’rin- 
stance,  one  that  came  up  during  the 
terrific  Get-TUG-Gether  seminar  and 
party  in  Seattle  last  summer.  (I’d  love 
to  shake  your  hand  up  there  this  year  — 
information  is  in  the  “Products  Men¬ 
tioned”  box  at  the  end  of  this  column.) 
I  was  explaining  polymorphism  to  the 
group,  and  using  the  example  of  a  field 
editor  class.  I  drew  a  figure  on  the 
whiteboard  that  looked  something  like 
the  one  shown  in  Figure  1 . 

The  idea  was  to  create  an  abstract 
class  named  Field,  which  would  never 
actually  be  instantiated.  Field  would 
take  care  of  all  those  things  that  every 


field  —  regardless  of  its  type  —  would 
have  to  do:  Clear  some  number  of  char¬ 
acters  in  a  line,  lay  down  a  title,  indi¬ 
cate  that  this  particular  field  is  active, 
and  so  on.  But  Field  would  not  actually 
have  any  “guts”  with  which  to  edit 
data.  Instead,  child  objects  of  Field 
would  be  derived  from  Field  to  do  the 
actual  editing,  through  an  Edit  virtual 
method  present  in  each. 

In  Figure  1,  I  show  them  as  String- 
Field,  IntegerField,  and  DateField.  A 
StringField  object  would  simply  accept 
string  data  and  allow  simple  line-type 
edits  on  the  string  data.  An  IntegerField 
would  allow  entry  of  only  numeric  dig¬ 
its  and  supporting  characters  like  the 
minus  sign.  If  the  user  attempted  to 
press  “W”  while  executing  Integer- 
Field.Edit,  the  object  would  beep  and 
refuse  the  character.  Similarly,  Date- 
FieldEdit  would  validate  a  date  char¬ 
acter  by  character,  perhaps  within  a 
template  separating  day,  month,  and 
year  subfields.  In  any  event,  you  edit 
the  data  in  any  of  these  related  objects 
simply  by  executing  an  object’s  Edit 
method. 

This  works  —  I’ve  actually  written 
the  code  since  then  —  but  as  the  esti¬ 
mable  Brian  Foley  of  Turbo  Power  Soft- 


Figure  2:  A  more  memory-efficient  arrangement 
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ware  rose  to  point  out,  this  system  is 
very  inefficient  from  a  code  standpoint. 
The  three  child  objects  shown  in  Fig¬ 
ure  1  have  a  lot  of  code  in  common, 
because  all  three  control  a  cursor  within 
a  delimited  portion  of  a  line,  picking 
up  characters  from  the  keyboard  and 
formatting  them  on  the  screen. 

Brian  took  the  time  to  rearrange  the 
figure  much  as  I’ve  shown  it  in  Figure 
2.  Fie  placed  virtually  all  of  the  field 
editing  code  in  a  parent  object  named 
StringField,  because  beneath  it  all,  we 
encode  most  data  in  string  form  any¬ 
way.  What  actually  differs  among  the 
various  types  of  data  is  how  the  data 
is  validated.  The  child  objects  all  gather 
information  from  the  user  by  calling 
their  collective  parent's  Edit  method, 
and  then  examine  that  data  for  adher¬ 
ence  to  the  specific  requirements  of 
the  data  type  after  the  user  has  pressed 
Enter.  The  StringField  parent  class  has 
no  validation,  because  any  string  data 
enterable  by  the  user  is  legal  tender. 
StringField  is,  however,  a  usable,  non¬ 
abstract  class. 

Brian’s  arrangement  eliminates  nearly 
all  duplication  of  code  among  the  vari¬ 
ous  objects.  And  like  my  earlier  ar¬ 
rangement,  it  also  works.  The  line  is 
drawn  differently  between  parent  and 
child.  Which  is  best? 

There’s  no  single  answer.  And  it’s 
an  even  messier  question  than  I’ve 
shown  so  far.  Suppose  I  want  to  add  a 
BooleanField  object  to  the  hierarchy? 
That  is,  I  want  a  field  to  select  between 
two  available  choices  like  Yes/No,  Male/ 
Female,  Active/Suspended,  Alive/De¬ 
ceased.  But  I  don’t  want  the  user  to 
have  to  actually  type  out  either  of  the 
two  values.  I  want  each  field  to  have  a 
default  value,  and  to  allow  the  user  to 
toggle  between  the  two  values  for  a 
given  field  with  the  click  of  a  mouse 
or  a  press  on  the  space  bar. 

It  gets  pretty  obvious  that  Boolean- 
Field  needs  to  be  descended  from  some¬ 
thing  else,  something  probably  one  level 
higher  than  StringField.  Also,  entering 
the  full  value  of  a  field  in  string  form 
and  then  validating  the  string  after  En¬ 
ter  is  pressed  forbids  something  I  like 
a  lot:  Character-by-character  entry  vali¬ 
dation.  In  Figure  1,  an  IntegerField  will 
beep  a  “W”  the  moment  it’s  pressed. 
In  Figure  2,  the  “W”  won’t  be  detected 
or  an  error  reported  until  the  user 
presses  Enter.  The  user  has  to  go  back 
and  “fix”  the  data  —  when  initially,  he 
or  she  wouldn’t  have  been  allowed  to 
enter  invalid  data  to  begin  with. 

You’ll  find  that  subtle  changes  in  the 
structure  of  an  object  hierarchy  have 
lots  of  odd  little  side-effects  like  that. 
You  might  leap  initially  to  Brian’s  ar¬ 
rangement  in  a  quest  for  code  effi¬ 


ciency,  only  to  find  that  user  operabil¬ 
ity  of  the  application  suffers. 

Distribution  or  Extension 

I’ve  run  into  this  little  conundrum  a 
time  or  two  since  then.  There  seem  to 
be  two  general  ways  to  construct  an 
object  hierarchy.  The  line  between  the 
two  is  not  sharply  drawn,  and  in  fact  it 
may  not  be  a  line  at  all  —  it’s  less  a 
difference  of  technique  than  a  differ¬ 
ence  of  emphasis.  My  first  approach 
emphasized  the  distribution  of  func¬ 
tionality  through  an  abstract  class.  When 
you  take  this  approach,  you  often  de¬ 
sign  a  whole  tree  full  of  relatively  small 
and  simple  abstract  classes,  none  of 


which  are  capable  of  instantiation.  Each 
abstract  class  adds  something  fairly  sim¬ 
ple,  conceptually,  to  the  hierarchy.  From 
these  abstract  classes  you  derive  the 
“leaves”  of  the  hierarchy  tree,  which 
are  the  fully  functional  classes  that  may 
be  instantiated  and  do  real  work. 

The  other  approach,  by  contrast,  em¬ 
phasizes  fully  workable  objects  almost 
from  the  start.  The  first  objects  designed 
lean  toward  the  general-purpose  —  as 
in  Brian’s  string  editor  —  but  they  are 
nonetheless  fully  functional  objects.  Ab¬ 
stract  classes  are  kept  to  a  minimum,  and 
the  more  general  objects  are  extended 
to  produce  additional  objects,  like  the 
IntegerField  and  DateField  objects. 
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The  two  approaches  differ  in  an¬ 
other  fundamental  way.  Using  many 
abstract  classes  allows  you  to  cast  a 
great  many  objects  into  just  two  or  three 
major  object  hierarchies.  Avoiding  ab¬ 
stract  classes  tends  to  produce  numer¬ 
ous  small  object  hierarchies,  sometimes 
with  only  two  or  three  classes  in  each. 

OK.  Which  approach  is  better?  Hear 
me  well:  We  don’t  know.  This  is  not 
the  same  as  saying,  It  doesn’t  matter. 
There  is  no  information  as  to  whether 
maintainability  or  reusability  is  affected 
over  time  by  the  approach  taken  to 
OOP  design.  For  every  question  you 
unearth,  the  answer  only  yields  two  or 
three  more  questions. 

Getting  Bananas  the  Hard  Way 

Using  one  or  two  monster  hierarchies 
has  the  downside  of  giving  you  the 
whole  gorilla  even  when  you  only  want 
the  banana,  as  so  aptly  put  by  Scott 
Guthery  in  his  article  in  the  December 
1989  DDJ ,  “Are  the  Emperor’s  New 
Clothes  Object  Oriented?"  My  answer 
to  Scott  is  fairly  simple:  Hey,  guy,  any¬ 
body  who  chases  a  gorilla  to  get  a 
banana  deserves  whatever  he  gets.  I 
get  my  bananas  from  the  produce  de¬ 
partment  at  Safeway.  Gorillas  are  not 
involved  in  the  transaction. 

And  that’s  a  point  that  I’m  not  sure 
has  been  made  as  clearly  as  it  should: 
OOP  is  a  tool  that  can  be  brought  to 
bear  on  different  problems,  not  all  of 
them  requiring  a  massive  hierarchy  and 
pervasive  polymorphism.  OOP  can  be 
used  to  enforce  modularity  on  small 
structures,  such  as  the  “when”  stamp  I 
discussed  in  last  month’s  column.  The 
when  stamp  is  a  banana;  it  stands  pretty 
much  alone  and  can  be  used  and  reused 
as  a  modular  unit. 

I  suspect  the  smart  path  is  to  build 
large  object  hierarchies  only  when  the 
hierarchy  as  a  whole  is  the  mechanism 
you’re  after.  In  other  words,  don’t  glue 
together  diverse  and  unrelated  items 
into  a  single  hierarchy  just  because  it 
seems  the  politically  correct  thing  to 
do.  I  have  seen  an  unannounced  prod¬ 
uct  that  is,  essentially,  the  infrastruc¬ 
ture  of  an  event-driven  application, 
rolled  up  into  a  single  large  and  bril¬ 
liantly  conceived  object  hierarchy.  It 
incorporates  text  windowing,  mouse 
and  keyboard  input,  dialog  boxes,  vari¬ 
ous  types  of  buttons  and  controls,  an 
event  processing  loop,  and  so  on  — 
everything  but  the  parts  of  the  app  that 
do  the  specific  work  the  application 
was  designed  to  do.  Trying  to  find  and 
extract  a  “window”  object  in  the  hierar¬ 
chy  for  reuse  is  nonsensical  — the  win- 
dow-ness  of  the  objects  in  the  hierar¬ 
chy  is  distributed  in  a  highly  stochastic 
fashion  across  the  hierarchy.  If  you 
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want  the  infrastructure,  you  take  it  all 
or  leave  it  on  the  shelf. 

After  all,  trying  to  extract  the  liver 
from  a  gorilla  will  at  best  leave  you 
with  something  not  especially  useful  — 
and  it  annoys  the  hell  out  of  the  gorilla. 

Object  Professional  Arrives! 

By  the  time  you  read  this,  Turbo  Power 
Software’s  massive  Object  Professional 
library  will  be  on  the  streets.  I’ve  been 
watching  the  product  grow  for  some 
time,  and  I  have  beside  me  a  galley 
proof  of  the  documentation.  It’s  quite 
a  product,  and  I’ll  be  having  more  to 
say  about  it  in  the  future. 

Anybody  who 
chases  a  gorilla 
to  get  a  banana 
deserves  whatever 
he  gets 


OPRO,  as  the  folks  at  Turbo  Power 
have  begun  to  call  it  informally,  is  an 
evolutionary  step  up  from  Turbo  Pro¬ 
fessional  5.0.  It’s  a  massive  collection 
of  about  130  object  types  in  50  units, 
with  1600  pages  (!)  of  documentation  — 
something  that  may  set  a  new  record 
for  a  toolbox  product,  and  one  likely 
to  stand  for  a  good  long  while. 

OPRO  follows  the  “banana  model” 
of  object  libraries.  It’s  a  truck  load  of 
relatively  small  hierarchies,  most  of 
which  are  independent  of  one  another. 
The  largest  aggregate  of  functions  sup¬ 
ports  a  slick  text  windowing  system 
(OPRO  does  not  involve  graphics)  with 
overlapping  windows,  shadows,  scroll 
bars,  pick  lists,  menus,  and  context- 
sensitive  help  windows. 

I  could  spend  a  whole  column  just 
describing  what’s  in  OPRO,  but  space 
is  short.  Here  are  the  highlights: 

•  A  printing  manager  for  your  programs 
that  includes  a  mechanism  for  creating 
and  using  printer  device  drivers  as  well 
as  a  forms  and  reports  printing  mecha¬ 
nism. 

•  A  multiline  text  memo  field  object,  a 
full-blown  text  editor  object,  and  a  text 
file  browser  object. 

•  Long-array  objects  that  let  single  ar¬ 
rays  break  the  64K  barrier,  with  data 
stored  in  DOS  memory,  EMS,  or  on 
disk. 

•  Container  class  objects  for  creating 
stacks,  queues,  linked  lists,  and  so  on. 
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•  Swapping  TSR  support.  This  is  some¬ 
thing  pretty  unprecedented  as  far  as  I 
can  tell:  A  mechanism  by  which  you 
can  create  TSR  programs  that  occupy 
as  little  as  6K  of  DOS  RAM.  The  balance 
can  be  stored  in  EMS  (but  not  extended 
memory)  or  on  disk,  which  includes 
RAMdisks.  The  TSRs  you  write  are  trans¬ 
parently  protected  against  DOS  re-en- 
trancy  problems.  I’ll  cover  this  in  an 
upcoming  column  in  more  detail  — 
amazing. 

•  A  drop-in  keyboard  macro  facility  for 
your  programs. 

•  A  data-entry  screen  manager  with  an 
interactive  screen  forms  designer. 

•  A  swapping  DOS  shell. 

That’s  not  all,  either,  but  I’ve  not  had 
the  time  to  go  over  more  than  a  fraction 
of  it  so  far.  Most  remarkable  of  all, 
every  last  bit  of  source  code  is  included, 
right  down  to  the  .ASM  files.  Just  read¬ 
ing  the  code  is  a  helluvan  education 
in  creating  efficient  objects  in  Turbo 
Pascal. 

OPRO  was  not  an  easy  product  to 
write,  even  for  Kim  Kokkonen  and  his 
crew  of  wizards  down  on  Scotts  Valley 
Drive.  (I  could  hear  the  groans  drown¬ 
ing  out  the  sawmill  regularly  when  I 
had  the  window  open  in  the  fall.)  This 
is  why  I  recommend  that  when  an  ap¬ 
plication  has  to  happen  in  the  least 
amount  of  time,  glom  onto  a  major 
toolkit  product  and  write  your  applica¬ 
tion  around  it.  The  toolkit  may  not 
have  every  corner  of  every  window 
done  just  the  way  you  want  it.  There 
are,  for  example,  operational  details 
about  Object  Professional’s  window¬ 
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ing  system  that  I  don’t  care  for,  but 
these  are  speckles  on  the  axe.  Keep 
reminding  yourself:  You’re  working  on 
the  edge,  not  the  shine. 

If  you  can  buy  the  shine  somewhere, 
do  it.  And  don’t  assume  that  you  can 
necessarily  do  a  better  job  in  less  than 
a  geological  eon  of  pressing  the  axe 
against  the  stone. 

Market  Notes 

As  most  of  you  who  have  ever  consid¬ 
ered  marketing  your  software  profes¬ 
sionally  are  aware,  it’s  virtually  impos¬ 
sible  to  get  a  product  on  computer 
store  shelves  without  a  tremendous  bud¬ 
get  for  promotion  and  more  than  a  little 
luck.  So  I  watch  for  ways  that  a  small 
time  operator  can  make  some  money 
with  their  software,  and  another  good 
one  has  turned  up  recently. 

Bob  Napp,  managing  editor  of 
SoftDisk  Publishing,  is  looking  for  good 
software  to  publish  in  their  monthly 
disk-based  magazine  Big  Blue  Disk. 
Billed  as  "The  Monthly  Software  Col¬ 
lection,”  Big  Blue  Disk  is  an  amiable 
hodgepodge  of  DOS  software,  running 
from  batch  language  extension  utilities 
to  D&D-style  games.  A  recent  issue 
that  I  examined  contained  a  typing  tu¬ 
tor,  a  dungeon  game,  a  video  board 
detection  utility  for  batch  files,  an  ap¬ 


pointment  calendar  manager,  a  simple 
word  processor,  and  a  collection  of 
clip  art  for  the  Print  Shop  desktop  pub¬ 
lishing  program,  plus  a  letters  column 
and  a  few  other  odds  and  ends.  From 
the  consumer’s  standpoint  it  was  well 
worth  the  $9-95  cover  price,  and  their 
rates  for  authors,  while  not  the  stuff  of 
which  empires  are  made,  certainly  seem 
worth  it  to  me  for  modest  software 
projects. 

Contact  Bob  at  SoftDisk  Publishing 
and  get  their  author  kit. 

Apologies 

.  .  .to  the  C  people  who  have  had 
enough  of  my  C  bashing.  Truce,  truce. 
After  all  (and  yes,  I  have  violated  the 
spirit  of  this  contention  from  time  to 
time)  a  language  is  a  socket  wrench, 
not  a  religion  or  a  household  pet. 

And  the  truce  will  hold  as  long  as 
you  C  guys  stop  asking  me  when  I'm 
going  to  give  up  my  training  wheels. 

Deal? 

Contact  Jeff  Duntemann  on  MCI  Mail 
as  JDuntemann ,  or  on  CompuServe  as 
76117,1426. 

DDJ 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  15. 
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C  PROGRAMMING 


Listing  One  (Text  begins  on  page  129J 

/* - auto.h - */ 

/* 

*  simple  data  element  classes 
*/ 

typedef  long  odometer; 

typedef  double  Dollars; 

/* 

*  a  simple  date  class 
*/ 

typedef  struct  { 
int  mo,  da,  yr; 

}  date; 

/* 

*  Automobile  class 
*/ 

typedef  struct  { 
int  modelyear; 
char  manufacturer [20] ; 
char  license [9]; 

}  Automobile; 

/* 

*  Trip_Record  class 
*/ 

typedef  struct  { 
date  trip_date; 
odometer  odometer_in; 
odometer  odometer_out; 
int  gallons; 

Dollars  cost; 

]  Trip_Record; 


End  listing  One 


Listing  Two 

/* - auto.c - */ 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  <stdlib.h> 

♦include  "auto.h" 

static  Automobile  get_car (void) ; 
static  void  reportauto (Automobile) ; 
char  *display_date(date  dt); 
static  Trip_Record  get_trip (void) ; 
static  void  reporttrip (Trip_Record) ; 

void  main() 

( 

while  (1)  ( 

/*  -  a  report  for  each  car  in  the  input  -  */ 

Automobile  car  =  get_car(); 

Trip_Record  trip_totals  =  ( (0, 0,0} , 0, 0, 0, 0) ; 

if  (car .modelyear  ==  0) 
break; 

reportauto (car)  ; 

/* - prepare  the  detail  report - */ 

printf("\n  Date  miles  gas  cost  mpg  cost/mile"); 

printf  ("\n - - - - - - "); 

while  (1)  { 

/*  -  get  the  next  Trip_Record  from  the  input  -  */ 

Trip_Record  trip  =  get_trip(); 
if  (trip.trip_date.mo  ==  0) 
break; 

/* - report  the  trip - */ 

reporttrip (trip) ; 

/* - collect  totals  for  this  car - */ 

trip_totals.odometer_in  = 

max (trip_totals . odometer_in,  trip . odometer_in) ; 
trip_totals .odometer_out  =  trip_totals.odometer_out  ? 
min(trip_totals.odometer_out,  trip.odometer_out)  : 
t rip . odometer_out ; 

trip_totals .gallons  +=  trip. gallons; 
trip_totals .cost  +=  trip. cost; 

} 

reporttrip (trip_totals) ; 

) 

} 

/* - get  a  car's  description  from  the  input - */ 

static  Automobile  get_car (void) 

{ 

static  Automobile  car; 

car. modelyear  =  0; 
scanf("%s",  car. license) ; 
if  (strcmp(car. license,  "end")  !-  0)  { 

scanf("%d",  &car .modelyear) ; 
scanf ("%s",  car .manufacturer) ; 

} 

return  car; 

} 

static  void  reportauto (Automobile  car) 

{ 

printf ("\n\n%d  %s  License  ♦  %s\n", 

car .modelyear,  car .manufacturer,  car . license) ; 

} 

/* - get  a  trip  record  from  the  input  stream - */ 

static  Trip_Record  get_trip(void) 

( 


date  dt; 

char  strdate[9]; 
odometer  oin  =  0,  oout  =0; 
int  gas  =  0; 

Dollars  cost  =  0; 
static  Trip_Record  trip; 

dt.mo  =  0; 

scanf ("%s",  strdate) ; 
if  (strcmp (strdate,  "end"))  ( 
dt.mo  =  atoi (strdate) ; 
dt.da  =  atoi (strdate  +  3); 
dt.yr  =  atoi (strdate  +  6) ; 
scanf ("%ld",  &oin) ; 
scanf ("%ld",  &oout); 
scanf ("%d",  &gas); 
scanf ("%lf",  &cost); 

} 

trip.trip_date  =  dt; 
trip.odometer_in  =  oin; 
trip.odometer_out  =  oout; 
trip. gallons  =  gas; 
trip. cost  =  cost; 
return  trip; 

} 

static  void  reporttrip (Trip_Record  trip) 

( 

int  miles  =  (int)  (trip.odometer_in  -  trip.odometer_out) ; 
printf ("\n%s  %5d  %5d  %M.2f  %5d  %^8.2f", 
trip.trip_date.mo  ? 

display_date(trip.trip_date)  : 

"totals  ", 
miles, 

trip. gallons, 
trip. cost, 

trip. gallons  ?  miles  /  trip. gallons  :  0, 
miles  ?  trip. cost  /  miles  :  0 
) ; 

} 

char  *display_date (date  dt) 

( 

static  char  d [ 9] ; 

sprintf(d,  "%2d-%02d-%02d",  dt.mo,  dt.da,  dt.yr); 
return  d; 

} 


End  listing  Two 


Listing  Three 

//  auto.hpp 

// - 

//  simple  data  element  classes 

// - 

typedef  long  odometer; 
typedef  double  Dollars; 

//  - 

//  a  simple  date  class 

// - 

struct  date  ( 

int  mo,  da,  yr; 
char  ‘display (void) ; 

}; 

// - 

//  Automobile  class 

// - 

class  Automobile  { 
private : 

int  modelyear; 
char  ‘manufacturer; 
char  ‘license; 
public: 

Automobile (char  ‘license,  int  year,  char  ‘make); 
Automobile () ; 

“Automobile () ; 
char  ‘display (void) ; 

int  nullcar (void)  (return  modelyear  ==  0;} 

}; 

// - 

//  Trip  Record  class 

// - 

class  Trip_Record  { 
private: 

date  trip_date; 
odometer  odometer_in; 
odometer  odometer_out; 
int  gallons; 

Dollars  cost; 
public: 

Trip_Record(void) ; 

Trip  Record(date,  odometer,  odometer,  int,  Dollars); 
int  mileage (void)  (return  odometer_in  -  odometer_out; } 
char  ‘display (void) ; 


(Listing  continued  on  page  148) 
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C  PROGRAMMING 


Listing  Three  ( Listing  continued,  text  begins  on  page  129  J 


Listing  Five 


int  nulltrip (void)  {return  trip_date.mo  ==  0;} 
void  operator  +=  (Trip_Records) ; 


//  autorpt.cpp 

#include  <stream.hpp> 
♦include  <string.h> 
♦include  <stdlib.h> 
♦include  "auto.hpp" 


Listing  Four 

//  auto.cpp 

♦include  <stream.hpp> 
linclude  <string.h> 
linclude  <stdlib.h> 
linclude  "auto.hpp" 

char  *date: : display () 

{ 

return  form("%2d-%02d-%02d",  mo,  da,  yr) ; 

) 

//  — - -  constructors  - 

Automobile: : Automobile () 

{ 

modelyear  =  0; 

manufacturer  =  license  =  NULL; 

) 


End  Listing  Three 


Automobile: : Automobile (char  *lic,  int  year,  char  *make) 

{ 

license  =  new  char [strlen (lie) +1] ; 
strepy (license,  lie); 
modelyear  =  year; 

manufacturer  =  new  char [strlen (make) +1] ; 

'  strepy (manufacturer,  make); 

} 


// - destructor 

Automobile : : “Automobile ( ) 

{ 

if  (license  !=  NULL) 
delete  license; 
if  (manufacturer  !=  NULL) 
delete  manufacturer; 

) 


char  ‘Automobile : : display ( ) 
{ 


} 


return  form("%d  %s  License  I  %s", 

modelyear,  manufacturer,  license) ; 


♦define  max(a,b)  ( (a) > (b) ? (a) : (b) ) 

♦define  min (a, b)  ( (a) < (b) ? (a) : (b) ) 

void  Trip_Record: : operator  +=  (Trip_RecordS  trip) 

{ 

this->odometer_in  =  max (this->odometer_in,  trip.odometer_in) ; 
this->odometer_out  =  this->odometer_out  ? 

min (this->odometer_out,  trip.odometer_out)  : 
trip. odomet  e  r_out ; 
this->gallons  +=  trip. gallons; 
this->cost  +■  trip. cost; 

} 


//  -  constructors  - 

Trip_Record: :frip_Record() 

{ 

trip_date.mo  =  trip_date.da  =  trip_date.yr  =  0; 
odometer_in  =  odometer_out  =  0; 
gallons  =  0; 
cost  =  0; 

) 


Trip_Record: :Trip_Record(date  trdt,  odometer  oin,  odometer  oout, 
int  gas,  Dollars  cst) 

( 

trip_date  =  trdt; 
odometer_in  =  oin; 
odometer_out  =  oout; 
gallons  =  gas; 
cost  =  cst; 


char  *Trip_Record: :display () 

{ 

int  miles  =  mileage (); 

return  form("%s  %5d  %5d  %!8.2f  %5d  %l8.2f", 

trip_date.mo  ?  trip_date. display ()  :  "totals 

miles, 

gallons, 

cost, 

gallons  ?  miles  /  gallons  :  0, 
miles  ?  cost  /  miles  :  0 
)  ; 

} 


/  /  =================== — - - ============= - 

//  automobile  operating  costs  system 
//  ===================================== 

// - prototypes 

static  Automobiles  get_car (void) ; 
static  Trip_RecordS  get_trip (void) ; 
static  void  report (Automobiles) ; 
static  void  report (Trip_RecordS) ; 

main  () 

{ 

while  (1)  ( 

// - a  report  for  each  car  in  the  input 

Automobile  car  =  get_car(); 
if  (car.nullcar () ) 
break; 

report (car) ; 

//  -  prepare  the  detail  report 

cout  «  "\n  Date  miles  gas  cost  mpg  cost/mile"; 

cout  «  "\n - - - - - - " ; 

// - a  Trip_Record  to  hold  the  totals 

Trip_Record  trip_totals; 

while  (1)  ( 

//  -  get  the  next  Trip_Record  from  the  input 

Trip_Record  trip  =  get_trip(); 
if  (trip.nulltripO ) 
break; 

// - report  the  trip 

report (trip) ; 

// - collect  totals  for  this  car 

trip_totals  +=  trip; 

} 

report (trip_totals) ; 

) 

1 

// - get  a  car's  description  from  the  input 

static  Automobiles  get_car (void) 

( 

char  license [7]; 
int  modelyear  =  0; 
char  make [25]  =  ""; 

cin  »  license; 

if  (stremp (license,  "end")  !=  0)  ( 

cin  »  modelyear; 
cin  »  make; 

) 

Automobile  *car  =  new  Automobile (license,  modelyear,  make); 
return  ‘car; 

} 

static  void  report (Automobiles  car) 

( 

cout  «  "\n\n"  «  car. display ()  «  '\n'; 

} 


// - get  a  trip  record  from  the  input  stream 

static  Trip_RecordS  get_trip() 

I 

date  dt; 
dt.mo  =  0; 


char  strdate[9]; 
odometer  oin  =  0,  oout  =  0; 
int  gas  =  0; 

Dollars  cost  =  0; 

cin  »  strdate; 
if  (stremp (strdate,  "end"))  { 
dt.mo  =  atoi (strdate) ; 
dt.da  =  atoi (strdate  +3); 
dt.yr  =  atoi (strdate  +  6); 
cin  »  oin; 
cin  »  oout; 
cin  »  gas; 
cin  »  cost; 

} 

Trip_Record  ‘trip  =  new  Trip_Record (dt, oin,  oout,  gas,  cost) ; 
return  ‘trip; 


static  void  report (Trip_RecordS  trip) 

( 

cout  «  '\n'  «  trip. display () ; 

I 


End  Listings 


End  Listing  Four 
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E  X  A  M  I  N  1  N  G  ROOM 


Encapsulating 
C++  Books 

C++  resources  for 
your  bookshelf 


Andrew  Schulman 


For  a  long  time,  if  you  wanted  to 
learn  C++  and  happened  not  to 
work  down  the  hall  from  its  in¬ 
ventor,  Bjarne  Stroustrup,  the 
only  resource  you  could  turn  to 
was  Stroustrup's  book,  The  C++  Pro¬ 
gramming  Language ( Reading,  Mass.: 
Addison-Wesley,  1986,  328  pages, 
$22.93).  But  trying  to  learn  C++  from 
the  Stroustrup  book  is  like  trying  to 
learn  chemistry  from  the  Periodic  Ta¬ 
ble  of  the  Elements.  That  situation  has 
changed,  however,  and  there  are  fi¬ 
nally  some  good  books  from  which 
you  can  learn  C++. 

The  definitive  book  on  C++  2.0  is 
Stanley  B.  Lippman’s  C++  Primer  (Read¬ 
ing,  Mass.:  Addison-Wesley,  1989,  464 
pages,  $31.25).  Like  Stroustrup,  Lippman 
works  at  AT&T  Bell  Laboratories.  This 
is  a  tutorial,  not  a  reference.  After  a 
brief  discussion  of  the  more  C-like  fea¬ 
tures  of  C++,  Lippman  moves  quickly 
into  a  discussion  of  class.  The  book 
presents  thorough  discussions  of  the 
three  key  features  of  object-oriented 
programming:  abstract  data  types,  in¬ 
heritance,  and  dynamic  binding.  There 
are  also  several  discussions  of  when 
not  to  use  such  C++  features  such  as 
operator-  and  function-overloading.  1 
might  quibble  with  a  few  aspects  of  the 
book,  such  as  the  odd  interface  for  a 


Andrew  is  a  software  engineer  in  Cam¬ 
bridge,  Mass,  and  is  a  contributing 
editor  to  DDJ.  Andrew  can  be  reached 
at  32  Andrew  St.,  Cambridge,  MA 
02139. 


BitVector  class,  but  if  you  can  afford 
only  one  C++  book,  this  is  the  one  to 
get.  While  the  book  assumes  the  reader 
is  using  C++  2.0  (and  the  unsuspecting 
reader  using  C++  1.2  might  get  tripped 
up  in  a  few  places),  an  appendix  pre¬ 
sents  a  clear  discussion  of  the  differ¬ 
ences  between  C++  1.2  and  2.0.  An¬ 
other  appendix  discusses  the  differences 
between  C  and  C++. 

Like  Stroustrup’s  book,  though, 
Lippman’s  primer  largely  presents  the 
language  features,  and  provides  little 
direction  on  how  to  use  C++.  Another 
new  C++  book  makes  up  for  this  defi¬ 
ciency  by  encouraging  the  reader  to 
think  in  C++,  and  introduces  general 
principles  of  data  abstraction  and  object- 
oriented  programming:  Programming 
in  C++,  by  Stephen  C.  Dewhurst  and 
Kathy  T.  Stark  (Englewood  Cliffs,  New 
Jersey:  Prentice  Hall,  1989,  233  pages, 
$22.00).  They’ve  included  some  cutesy 
code  in  this  book  (for  example,  a  File 
class  in  which  the  class  constructor 
opens  the  file  and  the  destructor  closes 
the  file,  and  an  iterator  object  that  uses 
operatorC )(  )),  but  one  of  the  authors’ 
goals  is  to  show  how  C++  supports  a 
wide  variety  of  programming  methods 
and  techniques.  An  entire  chapter  is 
devoted  to  libraries,  a  crucial  topic  en¬ 
tirely  missing  from  other  books  on  C++. 
This  book  appears  in  the  superb  “Pren¬ 
tice  Hall  Software  Series,”  edited  by 
Brian  Kernighan. 

Object-oriented  design  is  largely  bot¬ 
tom-up,  emphasizing  the  creation  of 
reusable  classes  that  are  then  soldered 


together  to  form  different  applications. 
Brad  Cox,  author  of  Objective-C,  has 
popularized  this  notion  under  the  name 
“Software-IC”  (which  Cox  unfortunately 
then  went  on  to  trademark).  True  to  its 
spartan  C  heritage,  however,  C++  com¬ 
pilers  don’t  come  with  extensive  librar¬ 
ies  of  such  reusable  classes.  Therefore, 
beginning  C++  programmers  need, 
above  all,  some  useful  classes  such  as 
those  that  Smalltalk  programmers  take 
for  granted. 

One  new  C++  book  addresses  this 
problem  by  providing  you  with  tons 
of  reusable  classes:  The  C++  Answer 
Book ,  by  Tony  L.  Hansen  (Reading, 
Mass.:  Addison-Wesley,  1990,  578  pages, 
$26.95).  As  the  C  Answer  Book,  is  to 
K&R,  so  the  C++  Answer  Book,  is  to 
Stroustrup.  It  provides  answers  for  ev¬ 
ery  exercise  in  the  book.  For  example, 
Exercise  6.11  is  “Define  a  class  imple¬ 
menting  arbitrary  precision  arithmetic”; 
Hansen’s  answer  runs  over  30  pages. 
Exercise  7.10  (marked  as  difficulty- 
level  *5  by  Stroustrup)  is  “Design  and 
implement  a  library  for  writing  event- 
driven  simulations.  Hint:  <task.h>”; 
Hansen’s  answer  runs  almost  40  pages. 
As  the  book  is  tied  to  Stroustrup,  there 
is  little  use  of  C++  2.0  here.  Surpris¬ 
ingly,  the  book  not  only  employs  Unix, 
but  also  recognizes  the  importance  of 
MS-DOS.  In  addition  to  using  AT&T’s 
cfront  Translator,  the  answers  were 
tested  on  the  Zortech  C++  compiler 
1.5.  Where  exercise  5.5  for  defining  an 
arithmetic-expression  class  also  suggests 
toying  with  different  ways  of  printing 
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the  expression,  including  assembly 
code,  Hansen  proceeds  to  do  so  using 
not  only  the  AT&T  WE32100,  but  also 
the  Intel  8086.  An  amazing  book!  My 
only  quibble  is  the  large  number  of 
typographical  errors  (like  most  books 
out  of  AT&T,  this  one  was  typeset  by 
the  author).  The  forthcoming  fourth 
printing  will  correct  these  errors. 

Where  does  C++  fit  into  the  hierar¬ 
chy  of  programming  languages?  How 
does  it  differ  from  Smalltalk?  from 
Modula-2?  from  Ada?  from  C?  If  you  are 
interested  in  programming  languages 
in  general,  and  want  to  view  C++  in 
some  larger  context,  get  Ravi  Sethi’s 
textbook,  ProgrammingLanguages:  Con¬ 
cepts  and  Constructs  (Reading,  Mass.: 
Addison-Wesley,  1989,  478  pages, 
$40.95).  Sethi  is  one  of  the  co-authors 
of  the  famous  “dragon  book”  on  com¬ 
pilers  and,  again,  works  at  Bell  Labs. 
Sethi’s  chapters  on  “Data  Encapsula¬ 
tion”  and  “Inheritance”  both  contain 
extensive  discussions  of  C++. 

In  general,  when  there  are  both  trade 
and  academic  books  on  a  subject  such 
as  C++,  it  is  safer  to  go  with  the  aca¬ 
demic  book.  Fortunately,  this  is  chang¬ 
ing:  Bruce  Eckel’s  Using  C++  (Berkeley: 
Osborne/McGraw-Hill,  1989,  617  pp., 
$24.95)  is  a  wonderful  book.  I  don’t 
normally  buy  books  from  Osborne/ 
McGraw-Hill  (which  publishes  a  lot  of 
books  that  are  either  identical  to,  or 
worse  than,  the  manuals  they  purport 
to  supplement),  but  I  made  an  excep¬ 
tion  here  because  of  Eckel’s  name  on 
the  cover  (Bruce  wrote  the  brilliant  “Pro¬ 
grammer’s  Guide  to  the  Parallel  Port” 
in  Vol.  1,  No.  1  of  the  late  lamented 
Turbo  Technix).  One  of  the  interesting 
examples  is  a  program  for  the  game  of 
Life.  Bruce  realized  that  Life  is  actually 
a  problem  in  simulation  and  modeling, 
so  his  code  presents  a  framework  in 
which  the  rules  of  the  simulation  can 
be  easily  changed.  Other  examples  in¬ 
clude  a  tiny  AWK  interpreter  named 
TAWK  (which  appeared  in  DDJ  in  May 
1989),  a  clock-based  control  system, 
and  a  drawing  program  called  Micro- 
CAD,  which  uses  the  mouse  and  graph¬ 
ics  package  from  Zortech  C++.  All  the 
code  is  available  on  disk.  Great  stuff! 

If  you  are  already  proficient  in  C++ 
and  are  looking  for  advanced  material, 
check  out  the  proceedings  of  the  C++ 
conferences  and  workshops  given  by 
USENIX  (USENIX  Proceedings ,  C++ 
Workshop,  Santa  Fe,  New  Mexico:  1987, 
468  pp.,  and  USENIX  Proceedings,  C++ 
Conference,  Denver,  Colo.,  1988,  362 
pp.,  USENIX  Association,  P.O.  Box  2299, 
Berkeley,  CA  94710,  $30.00  each).  Some 
trade  publisher  ought  to  pick  these  up 
and  make  them  more  widely  available. 

The  Denver  volume  includes  Strous- 


trup’s  papers  on  “Parameterized  Types 
for  C++”  and  “Type-safe  Linkage  for 
C++.”  Other  papers  include  “Excep¬ 
tion  Handling  without  Language  Ex¬ 
tensions”  by  William  M.  Miller,  and 
“Pointer  to  Class  Members  in  C++”  by 
Lippman  and  Stroustrup. 

The  Santa  Fe  proceedings  includes 
these  papers  by  Stroustrup:  “The  Evo¬ 
lution  of  C++  from  1985  to  1987,”  “What 

Those  who  disagree  with 
pushing  C++  in  the 
direction  of  Smalltalk, 
and  want  to  keep  the 
language  closer  to  its 
C  origins,  would  still 
benefit  from  examining 
Gorlen’s  code 


is  ‘Object-Oriented  Programming’?”  “Pos¬ 
sible  Directions  for  C++,”  and  “A  Set 
of  C++  Classes”  (with  Jon  Shopiro). 
Other  useful  papers  in  the  Santa  Fe 
volume  are  “Two  Extensions  to  C++: 
A  Dynamic  Link  Editor  and  Inner  Data” 
by  Gautron  and  Shopiro,  “C++  on  the 
Macintosh”  by  Friedenbach,  and  “An 
Object-Oriented  Class  Library  for  C++ 
Programs”  by  Keith  Gorlen. 

Keith  Gorlen  is  at  the  National  Insti¬ 
tute  of  Health  (NIH),  and  is  the  author 
of  the  NIH  class  library,  a  Smalltalk-like 
class  hierarchy  for  C++  (class  Object  is 
at  the  root  of  the  class  inheritance  tree). 
Even  those  who  disagree  with  this  push¬ 
ing  of  C++  in  the  direction  of  Smalltalk, 
and  want  to  keep  the  language  closer 
to  its  C  origins,  would  still  benefit  from 
examining  Gorlen’s  code,  which  is  prob¬ 
ably  the  largest  body  of  public-domain 
C++  source  code  available  today.  Mi¬ 
chael  Murphy  of  Cambridge,  Mass, 
ported  the  NIH  library  to  MS-DOS,  and 
it  may  be  found  on  the  ImageSoft  BBS 
(516-767-9074)  and  on  BIX  (listings  area 
c. plus. plus).  There  is  also  an  active  C++ 
forum  (c. plus. plus)  on  BIX,  in  which 
Bjarne  Stroustrup  (bstroustrup)  partici¬ 
pates. 

DDJ 

Vote  for  your  favorite  feature/article. 
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A  new  release  of  Think  Pascal,  Version 
3.0,  now  includes  Symantec’s  Think 
Class  Library  and  support  for  MacApp, 
the  class  library  from  Apple.  The  Think 
Class  Library  has  code  for  all  the  stan¬ 
dard  Macintosh  user  interface  compo¬ 
nents  and  behaviors.  This  library  can  be 
used  with  either  Think  Pascal  or  C.  And 
Think  Pascal  provides  extensive  sup¬ 
port  for  object-oriented  programming. 

DDJ  spoke  with  Claris’  Dennis  Co¬ 
hen  and  Stonecutter  Software’s  Don 
Sawtelle,  two  programmers  who  have 
been  using  Think  Pascal  3.0  through¬ 
out  its  beta  testing  stage.  Cohen  said  “I 
do  all  my  final  builds  in  Think  Pascal 
3.0.  The  environment  is  great.  For  an 
individual  programmer  it’s  phenome¬ 
nal.  For  a  team,  MPW  is  probably  better 
because  of  the  projector  and  the  tools 
for  use  with  the  projector.”  Sawtelle 
added  that  “It’s  [3.0]  excellent.  There’s 
nothing  better  in  terms  of  delivering 
commercial  applications,  because  of  its 
speed  and  the  excellent  interface  for 
source-level  debugging.”  Sawtelle  didn’t 
see  the  lack  of  a  Projector  as  much  of 
a  problem:  “It’s  so  compatible  with 
MPW,  you  can  run  both  simultaneously 
under  Multifinder.  ” 

Also  new  to  Think  Pascal  3.0  is  the 
class  browser,  a  graphical  navigation 
aid  that  lets  you  view  the  interrela¬ 
tionship  of  your  program’s  classes. 
Think  Pascal  3.0  has  an  integrated  en¬ 
vironment,  instant  incremental  linking, 
and  source-level  debugging  tools.  Pro¬ 
ductivity  enhancements  include  better 
segmentation  control,  improved  MPW 
compatibility,  resource  editing  tools, 
and  user  interface  enhancements.  The 
retail  price  is  $249,  and  upgrades  cost 
$69-  Reader  service  no.  20. 

Symantec  Corporation 
10201  Torre  Ave. 

Cupertino,  CA  95014-2132 
408-253-9600 

Version  6.0  of  Microsoft  C  Professional 
Development  System  has  been  an¬ 
nounced  by  Microsoft.  Microsoft  C 
6.0  includes  performance-oriented  im¬ 


provements  in  the  compiler  as  well  as 
additional  software  development  tools, 
including  an  integrated  development 
environment  called  the  Programmer’s 
Workbench. 

New  optimization  technology  added 
to  the  compiler  includes  register-based 
parameter  passing,  a  globally  optimiz¬ 
ing  code  generator,  segment-based  point¬ 
ers  to  memory,  and  pragma-level  (func¬ 
tion-level)  control  over  optimizations. 
The  compiler  now  allows  in-line  as¬ 
sembly  language  in  the  style  of  Quick-C. 

The  Programmer’s  Workbench  is  new 
to  Microsoft  C,  and  is  an  integrated 
development  environment  similar  to  that 
of  Quick-C,  with  pull-down  menus,  dia¬ 
log  boxes,  and  windowing  capabili¬ 
ties.  With  the  Workbench  are  updated 
versions  of  CodeView,  the  make  utility, 
the  Microsoft  Editor,  and  source 
browser.  The  Workbench’s  open  archi¬ 
tecture  allows  third-party  vendors  to 
offer  additional  tools. 

The  Source  Browser  is  a  program 
navigation  tool  that  lets  you  view  the 
calling  structure  (call  tree)  of  an  entire 
application,  find  the  definition  of  a  vari¬ 
able  or  function,  or  visit  all  references 
to  a  variable  or  function. 

The  new  version  of  CodeView  can 
now  reside  in  extended  memory,  leav¬ 
ing  only  a  15K  footprint  in  conven¬ 
tional  DOS  memory.  CodeView  now 
supports  multiple  files  and  multiple 
views  into  memory,  browsing  through 
structures  and  arrays,  dynamic  record- 
and-replay  of  debugging  sessions,  de¬ 
bugging  of  multi-threaded  programs  and 
DLLs,  and  remembering  of  configura¬ 
tion  data  from  one  session  to  another. 

Improvements  in  OS/2  support  now 
allow  multi-threaded  DLLs  (by  contrast, 
C  5.1  allows  only  multi-threaded  apps 
or  single-threaded  DLLs).  The  compiler 
will  run  under  either  DOS  or  OS/2, 
and,  under  OS/2,  will  allow  compo¬ 
nents  of  the  compiler  to  operate  in  the 
background.  Both  the  compiler  and 
linker  now  have  an  incremental  pro¬ 
cessing  mode  for  faster  operation. 

The  recommended  configuration  is 
640K  RAM,  10  Mbytes  of  hard  disk 
space,  and  384K  Extended  Memory  or 
LIM  4.0.  The  suggested  retail  price  is 
$495.  Microsoft  is  also  releasing  a  new 
version  of  QuickC  with  QuickAssem- 
bler.  Reader  service  no.  32. 

Microsoft  Corporation 
1  Microsoft  Way 
Redmond,  WA  98052 
206-882-8080 

Insite  Peripherals  recently  announced 
availability  of  its  1325  Floptical  Disk 
Drive  to  OEMs.  The  Floptical  Drive 
makes  use  of  optical  technology  to  store 
up  to  20  Mbytes  on  a  standard  high- 


density  3-5-inch  diskette  that  embeds 
optical  servo  tracks  into  the  surface  of 
the  media.  The  drive  includes  an  opti¬ 
cal  system  that  detects  these  “grooves” 
and  converts  the  images  to  electronic 
signals,  which  are  used  for  servo  track¬ 
ing  information.  Magnetic  data  is  writ¬ 
ten  to  “land”  areas  between  neighbor¬ 
ing  grooves. 

The  company  also  notes  that  its 
I325VM  version,  which  additionally 
reads  and  writes  to  standard  720K  and 
1.44-Mbyte  diskettes,  will  be  available 
in  volume  to  OEMs  later  this  year.  The 
company  claims  that  the  Floptical’s  SCSI 
interface  makes  it  two  to  three  times 
faster  than  typical  floppy  drives  and 
approximately  50  percent  as  fast  as  a 
Winchester  drive.  1325  evaluation  kits, 
which  include  the  Floptical  Drive  and  a 
PC  to  AT  host  adapter,  are  available  to 
OEMs  for  $600.  Reader  service  no.  21. 
Insite  Peripherals 
4433  Fortran  Dr. 

San  Jose,  CA  95134 
408-946-8080 

A  series  of  modular  tools  for  memory 
management  is  available  with  the  util¬ 
ity  program  Above  DISC,  Version  3-1, 
from  Above  Software.  Above  DISC  is 
an  expanded  memory  simulation  (EMS) 
program  for  DOS  users.  Some  of  the 
added  features  are  a  hard  disk  spill¬ 
over  with  disk  caching  for  hard  disk 
emulation,  and  the  ability  to  increase 
conventional  memory  to  736K  on  sys¬ 
tems  with  EGA/VGA  adaptors. 

The  hard  disk  spill-over  feature  is  for 
286  and  386  users.  It  increases  memory 
without  additional  RAM  chips,  convert¬ 
ing  extended  memory  to  expanded  mem¬ 
ory  for  applications  that  require  large 
amounts  of  expanded  memory.  The 
conventional  memory  enhancement  on 
EGA  and  VGA  color  systems  is  for  all 
PC/XT/AT,  286,  and  386  users,  and 
comes  from  accessing  an  additional  96K 
from  the  video  memory  on  the  sys¬ 
tem’s  motherboard.  And  you  can  turn 
this  feature  on  and  off,  as  when  you 
need  full  access  to  your  EGA/VGA  graph¬ 
ics  capability.  Above  DISC  comes  bun¬ 
dled  with  AboveLAN,  for  moving  No¬ 
vell  NET3.COM  or  NET4.COM  drivers 
into  the  first  64K  of  extended  memory 
in  order  to  run  larger  applications  such 
as  Excel  off  of  the  network.  Also  bun¬ 
dled  is  AboveMEM,  which  converts  up 
to  512K  of  extended  memory  into  EMS 
for  increased  speed  with  Lotus  1-2-3. 
Above  DISC  3.1  sells  for  $119.  Reader 
service  no.  22. 

Above  Software  Inc. 

3  Hutton  Centre 
Santa  Ana,  CA  92707 
714-545-1181 

(continued  on  page  158) 
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(continued  from  page  153) 

A  productivity  tool  for  C  programmers 
is  available  from  Silico-Magnetic  In¬ 
telligence.  Better-C  is  a  generic  C  pro¬ 
gram  methodology  and  generator  that 
works  with  most  popular  C  compilers. 
According  to  Kalman  Toth,  chief  scien¬ 
tist  on  the  project,  the  product  is  based 
on  complexity  management,  natural  lan¬ 
guage  naming,  top-down  design,  and 
programming  with  objects.  One  of  the 
benefits  of  Better-C  is  its  pliability  for 
projects  involving  teams  of  programmers. 

Ed  Hoffman  of  IDG  Consulting  told 
DDJ that  his  shop  used  Better-C  to  con¬ 
vert  one  of  their  programs  to  C.  “One 
of  our  products  is  an  AI  system  that  had 
been  written  in  a  whole  system  of  lan¬ 
guages  by  many  different  programmers. 
There  were  over  200,000  lines  of  good 
code,  but  it  got  really  hard  to  find  things, 
and  we  had  duplicate  functions.  Better- 
C  helped  us  to  get  organized  —  to  re¬ 
code  the  project.  We  answered  a  few 
questions  in  the  beginning,  and  it  as¬ 
signed  standard  names  for  us.  It  doesn't 
generate  modules  you  can  execute,  but 
it  helps  you  write  better  C  code  —  it 
can  make  you  look  like  a  very  well 
organized  C  programmer.” 

An  initial  module  frame  generator 
automatically  generates  a  framework 
for  a  new  module  —  it  sets  up  the  nec¬ 
essary  files  and  spans  a  framework  for 
the  new  module.  Objects  are  treated 
as  files  —  they  can  be  lists,  trees,  data¬ 
bases,  windows,  or  whatever.  The  open 
function  gets  object  handles  and  the 
close  function  destroys  objects.  And  Bet- 
ter-C  provides  exact  methods  for  or¬ 
ganizing  programs,  by  using  encapsu¬ 
lated  modules  as  building  blocks.  Better- 
C  costs  $98,  and  the  Frame  Generator 
Source  code  also  costs  $98.  Reader  ser¬ 
vice.  no.  23. 

Silico-Magnetic  Intelligence 
24  Jean  Lane 

Chestnut  Ridge,  NY  10952 
914-426-2610 

If  embedded-systems  engineering  is 
your  field,  you  might  want  to  look  into 
Avocet’s  AvCase,  an  integrated  set  of 
tools  for  the  code-compile-test  cycle 
of  your  software  projects.  According 
to  the  company,  they  integrated  the 
editor,  C  compiler,  assembler,  linker, 
and  simulator/source-level  debugger. 
And  everything  supposedly  ains  on 
your  PC. 

One  keystroke  can  compile,  assem¬ 
ble,  and  link  an  application.  When  it 
finds  an  error,  the  offending  module 
and  associated  error  message  are  dis¬ 
played  in  a  window  for  editing.  The 
complete  package  includes  an  AvCase 
8051  family  C  compiler  with  run-time 
library  and  source,  user  manuals,  and 


on-line  reference  database;  an  AvCase 
8051  family  Assembler  with  linker,  ob¬ 
ject  librarian,  hex  file  utility,  cross- 
reference  utility,  integrated  editor,  make 
utility,  user  manuals,  and  on-line  refer¬ 
ence  database  and  engine;  and  an 
AvCase  8051  family  Simulator  with 
source-level  debugging  and  user  man¬ 
ual.  This  whole  package  costs  $1895. 
Sold  separately,  the  C  compiler  and 
assembler  package  is  $995,  the  assem¬ 
bler  alone  is  $495,  and  the  simulator 
package  alone  is  $995.  Requires  an  IBM 
PC  or  compatible,  MS-DOS  2.0  or  later, 
640K  RAM,  and  a  hard  disk.  Reader 
service  no.  25. 

Avocet 
120  Union  St. 

P.O.  Box  490 
Rockport,  MA  04856 
207-236-9055 

More  memory  movement  is  possible 
with  Move  ’Em,  a  program  loader  from 
Qualitas.  Move  ’Em  moves  device  driv¬ 
ers,  network  system  drivers,  and  mem¬ 
ory-resident  programs  to  the  formerly 
inaccessible  memory  between  640K  and 
1  Mbyte.  Move  ’Em  works  on  all  PC 
platforms  from  the  XT  to  the  486. 

A  resident  program  optimization  fa¬ 
cility  automatically  determines  the  best 
loading  order  and  required  parameters 
for  memory-resident  programs  and  de¬ 
vice  drivers.  On  systems  equipped  with 
a  Chips  and  Technologies  ChipSet,  the 
built-in  shadow  RAM  (about  384K  of 
memory)  can  be  recovered  by  Move  ’Em. 

Move  ’Em  runs  on  any  IBM  PC  or 
compatible  with  an  EMS  4.0  memory 
board  with  at  least  256K  of  EMS  mem¬ 
ory,  and  PC-  or  MS-DOS  3  0  or  later.  It 
retails  for  $89. 

Also  from  Qualitas:  386MAX  and 
386MAX  Professional,  designed  for  PCs 
that  use  the  80386  or  80486.  These  man¬ 
agement  programs  locate  unused  pock¬ 
ets  of  addresses  between  640K  and  1 
Mbyte  and  move  TSRs,  device  drivers, 
and  other  memory-resident  programs 
into  that  space.  They  also  convert  pre¬ 
viously  unavailable  extended  memory 
above  1024K  into  EMS  memory,  which 
makes  it  compatible  with  the  EMS  4.0 
specification  that  many  large  applica¬ 
tions  require.  386MAX  sells  for  $74.95, 
386MAX  Professional  for  $129.95. 
Reader  service  no.  24. 

Qualitas 

7101  Wisconsin  Ave.,  Ste.  1386 
Bethesda,  MD  20814 
301-907-6700 

A  high-performance  graphics  card,  the 
ProDesigner  II  VGA,  is  due  for  release 
by  the  time  you  read  this.  Orchid  claims 
that  the  ProDesigner  II  is  twice  or  three 
times  as  fast  as  V-RAM  VGA  cards,  and 


that  your  rewrite  and  redraw  to  the 
screen  will  appear  “instantaneously.” 
ProDesigner  II  supports  up  to  1024  x 
768  resolution  in  16  colors  and  has 
512K  RAM;  ProDesigner  IIx  supports 
1024  x  768  resolution  in  256  colors  and 
has  1  Mbyte  of  RAM. 

Both  support  interlaced  and  non¬ 
interlaced  monitors,  and  are  downward- 
compatible  with  earlier  graphics  stan¬ 
dards.  The  proprietary  Translation  ROM 
allows  you  to  run  applications  written 
to  earlier  standards,  and  only  one  card 
is  necessary  to  run  VGA  applications. 
Software  drivers  are  included  for 
AutoCAD,  AutoShade,  GEM,  Lotus  1-2- 
3,  Ventura  Publisher,  Windows  286  and 
386,  and  WordPerfect.  And  Orchid 
claims  the  card  is  compatible  with  nearly 
all  monitors  on  the  market,  as  well  as 
ISA  and  EISA  machines.  Reader  service 
no.  28. 

Orchid  Technology 
45365  Northport  Loop  West 
Fremont,  CA  94538 
415-683-0300 

Books  of  Interest 

From  Addison-Wesley  comes  the  ef¬ 
fort  of  a  team  of  authors  that  produced 
Extending  DOS.  Ray  Duncan,  Charles 
Petzold,  M.  Steven  Baker,  Andrew 
Schulman,  Robert  Moote,  Ross  P.  Nel¬ 
son,  and  Stephen  R.  Davis  each  cover 
an  aspect  of  DOS  programming,  from 
architecture  to  Windows  and  DesqView 
operating  environments.  It  should  be 
available  this  month,  and  will  retail  for 
$22.95.  Reader  service  no.  30. 
Addison-Wesley 
Reading,  MA  01867 
617-944-3700 

Prentice  Hall  has  published  a  compre¬ 
hensive  guide  to  compiler  design  and 
construction  in  C  written  by  former 
DDJ  columnist  Allen  Holub,  who  told 
DDJ  “The  book  is  oriented  towards 
programming  —  the  programs  are  the 
core  of  the  book.  It’s  the  only  really 
thorough  introduction  to  compiler  de¬ 
sign  written  for  programmers  by  a  pro¬ 
grammer.”  Compiler  Design  in  C  cov¬ 
ers  such  basic  concepts  as  the  use  of 
Lex,  Occs,  Lexical  analysis,  top-down 
parsing,  code  generation,  run-time  li¬ 
brary  and  back  end,  and  optimization. 
Four  appendices  cover  miscellaneous 
support  routines,  grammars  and  gram¬ 
matical  transformations,  C  grammar,  and 
problems  with  Pascal  compilers.  Price: 
$42.20  for  650  pages.  Reader  service 
no.  31. 

Prentice  Hall 

Englewood  Cliffs,  NJ  07632 
201-592-2348 
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S  W  A  I  N  E'  S  FLAMES 


Three  on  a  Match 


As  soon  as  any  artificial  intelligence  technology  reaches  the  point  where  it  actually  works,  we 
become  reluctant  to  call  it  artificial  intelligence.  That’s  understandable,  but  it’s  also  annoying 
to  the  people  who  bring  the  technology  out  of  the  lab  and  into  the  market.  Their  very  success 
makes  them  look  like  braggarts  if  they  continue  to  label  their  work  as  they  did  before  it  was 
successful. 

Expert  systems  are  a  clear  cut  example  of  an  artificial  intelligence  technology  brought  successfully 
to  a  number  of  specialized  markets,  so  successfully  that  the  curse  of  AI  falls  heavily  on  expert 
systems.  It  seems  pretentious  to  call  them  artificial  intelligence.  So  it  must  be  adding  insult  to  injury 
to  suggest  that  even  the  term  “expert  system”  is  pretentious. 

One  of  the  standard  “mysteries”  of  artificial  intelligence,  posed  in  most  articles  and  beginning 
courses  on  the  subject,  is  the  difficulty  of  simulating  a  nonexpert.  Why,  the  puzzle  goes,  is  it  easier 
to  simulate  knowledge  and  behavior  of  an  expert  than  to  simulate  the  knowledge  and  behavior  of 
a  child  of  three?  or  of  a  chimpanzee? 

The  real  mystery  is  why  people  keep  asking  the  question,  “Isn’t  the  answer  obvious?”  The  first 
synonym  for  “expert”  in  Rodale’s  The  Synonym  Finder  is  “specialist.”  Specialization  is  a  narrowing 
of  focus,  and  there  is  no  mystery  at  all  about  why  it’s  easier  to  simulate  behavior  in  a  narrow 
domain  than  in  a  broad  one.  True,  narrowing  of  focus  is  not  one  of  the  defining  features  of  expert 
systems,  but  I’d  be  willing  to  bet  that  it  is  the  one  that  makes  them  successful.  Perhaps  it  would 
be  more  modest  and  more  meaningful  to  call  expert  systems  “specialized  systems.” 


Nuke  the  Innumerate 

According  to  the  editors  of  CD-ROM  End  User ,  who  use  the  following  expression  as  a  running  head 
throughout  their  useful  journal:  Y.(Digital  Data  x  Mbytes)  *  CD-ROM  >  E=mc2  means,  “The  sum  of 
megabytes  of  digital  data  plus  CD-ROM  is  greater  than  ...”  (the  ellipsis  is  theirs).  On  the  principle 
that  from  a  false  premise  any  conclusion  can  be  derived,  I  suppose,  that  they  can  assign  any 
meaning  they  like  to  this  meaningless  sequence  of  symbols.  Perhaps  I  shouldn’t  be  so  hard  on  the 
editors;  after  all,  they  are  only  using  the  expression  as  techie-looking  illustration.  But  the  expression 
is  so  egregiously  innumerate  that  it  calls  into  question  the  technical  accuracy  of  everything  in  the 
magazine.  To  cite  one  example,  should  we  trust  the  math  of  people  who  don’t  recognize  that 
they’ve  used  different  symbols  for  multiplication  in  one  expression? 

My  interpretation  of  the  expression  is,  “When  you  combine  megabytes  of  digital  data  on  CD-ROM 
ignorantly,  the  results  are  more  than  likely  to  blow  up  in  your  face." 


See  Tog  Flame 

I  praised  CD-ROM  End  User  here  recently,  and  I  still  think  it’s  an  informative  publication.  I  also 
praised  Dave  Thompson’s  Micro  Cornucopia ,  which,  alas,  appears  to  have  published  its  last  issue. 
Dave,  weary  of  the  grind  and  eager  to  get  on  with  other  things,  sold  the  publication  to 
Miller-Freeman,  who  probably  won’t  continue  Micro  C  as  a  magazine.  Too  bad. 

Another  of  my  favorite  publications,  Apple’s  developer  magazine  Apple  Direct ,  stubbed  its  toe 
recently  when  it  announced  Apple’s  new  hardware  products  days  ahead  of  the  official  announce¬ 
ment  date.  Another  setback  for  the  anti-Perestroika  cultural  reeducation  program  at  Apple. 

What  I  like  most  about  Apple  Direct ,  apart  from  its  timely  information  on  new  products,  is  a  user 
interface  design  column  written  by  Mr.  Tognazzini.  (Sometimes  he’s  Bruce,  sometimes  Bruce  “Tog,” 
but  usually  he’s  just  Tog,  which  is  also  his  AppleLink  address.)  Some  of  Tog’s  humor  may  not 
please  either  Apple  brass  or  developers:  “I  have  forwarded  your  link  .  . .  into  the  very  heart  of 
Apple  Engineering  Land,  and,  rest  assured,  we  shall  eventually  do  something  official.”  Tog’s 
opinions,  of  which  he  has  his  full  share,  frequently  deviate  from  the  party  line,  as  when  he  said 
that  he  would  “rather  die  than  defend  this  silly  business  of  throwing  disks  into  the  trash  to  eject 
them.” 

In  that  same  March  issue  that  preannounced  the  new  hardware,  Tog  had  some  sage  things  to  say 
about  user  testing  on  the  cheap.  Among  the  radical  ideas  is  that  user  testing  should  be  done  by 
members  of  the  design  team,  using  no  more  than  three  people  per  design  iteration.  User  testing 
can  show  you  things  you’d  never  guess  about  your  product  and  your  users.  Tog  relates  an 
experience  in  user  testing  of  an  in-box  tutorial  in  which  one  apparently  trivial  question  proved  to 
be  the  most  difficult  of  all.  The  “difficult”  questions  posed  no  problems  for  the  test  subjects,  but 
the  “easy”  question  proved  to  be  the  most  difficult  to  phrase  unambiguously.  He  just  wanted  to 
find  out  whether  the  test  subject  was  using  a  color  or  black-and-white  monitor.  It  took  six  iterations 
to  get  the  question  right. 

'J4iT i  c ILo-xJ)  ^yM-et 

Michael  Swaine 
editor-at-large 
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E  D  I  T  0  RIAL 


Putting 

HyperTheory  Into 
HyperPractice 


This  issue  of  DDJ showcases  the  power  and  promise  of  hypertext  technology,  not  just  in  theory 
but  in  practice.  Thanks  to  Scott  Johnson  and  the  crew  at  NTERGAID  (developers  of  the  Black 
Magic  authoring  system,  Hyperwriter,  and  other  hypertext  development  tools),  we’ve  taken 
the  exciting  (and  as  far  as  I  know,  unprecedented)  step  of  providing  you  with  an  electronic 
“hypertexted”  edition  of  DDJ. 

What  can  you  do  with  a  hypertext  version  of  DDJ!  Think  about  how  you  usually  read  DDJ.  You 
look  at  the  Table  of  Contents,  spot  an  article  that  seems  interesting,  turn  to  the  appropriate  page, 
and  begin  reading.  When  the  article  makes  reference  to  a  figure,  you  turn  more  pages.  And  when 
you  come  to  a  reference  to  source  code  listings,  you  usually  flip  halfway  through  the  magazine 
while  trying  not-to  lose  your  place. 

Hypertext  changes  this.  As  you  peruse  the  Table  of  Contents  on  your  PC  screen,  you  position  the 
cursor  on  the  title  of  an  article  and  call  up  its  description,  the  author’s  biography,  or  “turn”  to  the 
article  itself.  When  reading  the  article  and  encountering  a  “see  Listing  One”  or  similar  message,  you 
simply  click  on  the  message  and  the  listing  appears  on  the  screen. 

Getting  the  hypertext  edition  of  this  issue  is  easy.  It  comes  at  no  extra  charge  when  you  order 
this  month’s  source  code  listing  disk.  Alternatively,  you  can  download  the  electronic  issue  from  the 
DDJ  Forum  on  CompuServe.  (For  details,  look  for  the  “Availability”  notices  at  the  end  of 
just  about  every  article;  see  page  33,  for  example.) 

Since  the  hypertext  document  is  built  around  the  Hyperwriter  runtime  engine,  you  don’t  need 
any  special  software.  You  simply  “self’  extract  the  file  and  run  it.  You  will  need  a  PC  with  640K  of 
memory,  and  a  mouse  makes  it  a  lot  easier  to  use.  For  more  details  on  the  system  and  an  enhanced 
version  that  uses  bit-mapped  graphics,  see  this  month’s  lead  article  “The  DDJ  Hypertext  Project” 
where  Scott  describes  how  he  put  the  edition  together. 

Where  do  we  go  from  here?  Consider  that  if  you’re  like  most  readers,  you  keep  back  issues  of 
DDJ  as  reference  material.  Wouldn’t  it  be  great  to  have  15  years  worth  of  DDJ  at  your  fingertips, 
cross-referenced  and  linked  on  CD-ROM?  You  could  then  search  for  a  specific  topic  or  algorithm, 
bring  up  all  versions  of  it,  examine  the  code,  and  then  paste  it  into  your  application.  No,  we  aren’t 
planning  on  this  right  away,  but  it  does  give  us  something  to  dream  about. 


All  the  news  about  hypertext  isn’t  necessarily  fit  to  print,  however.  Why?  Because  the  trademark 
buzzards  are  at  it  again,  this  time  circling  over  the  term  “hypertext”  itself.  It  seems  that  a  company 
called  Hypersystems  S.R.L  of  Torino,  Italy  has  applied  for  a  U.S.  trademark  for  “HyperText,”  a 
stylized  version  of  the  term  “hypertext."  And  if  the  use  of  ®  in  their  product  literature  is  any 
indication,  the  company  seems  to  be  claiming  a  trademark  on  the  stylized  term  “HyperMedia”  too. 

Even  though  Hypersystem’s  U.S.  attorney  told  me  that  his  client  has  entered  a  disclaimer  for 
generic  use  of  the  term  “hypertext,”  hypertext  and  hypermedia  developers  are  nonetheless  up  in 
arms,  and  several,  including  NTERGAID,  Owl  International,  and  Autodesk,  have  filed  oppositions 
with  the  U.S.  Patents  and  Trademarks  Office. 

The  rule  of  thumb  is  that  if  a  word  is  either  descriptive  or  generic,  the  Trademark  Office  won’t 
issue  a  trademark.  To  me,  “hypertext”  seems  descriptive  because  it  simply  describes  a  system  of 
non-linear  reading  and  writing  and  it  is  generic  because  it  is  commonly  used  in  magazines,  books, 
dictionaries,  and  other  forms  of  documentation. 

If  you’re  as  annoyed  by  this  as  I  am,  you  should  know  about  a  couple  of  avenues  of  protest. 
Software  developers  who  have  a  hypertext-based  product,  and  therefore  a  vested  interest  in  seeing 
the  term  not  enter  the  Calcutta  of  trademarks,  can  file  an  official  “Notice  of  Opposition,”  while 
members  of  the  general  public  can  send  a  “Letter  of  Protest.” 

If  you  believe  that  a  trademark  on  the  term  “hypertext”  would  damage  you  or  your  product  in 
some  way,  you  should  file  a  Notice  of  Opposition  with  the  Trademark  Trial  and  Appeal  Board. 
You’ll  have  to  pay  a  fee  and  you  must  “set  forth  a  short  and  plain  statement”  stating  how  you 
would  be  damaged  by  the  trademark. 

Letters  of  Protest  should  be  sent  to  the  Office  of  the  Director  of  the  Trademark  Examining 
Operation.  The  purpose  of  your  letter  should  be  “to  bring  to  the  Office  facts  that  could  affect  or 
prevent  the  registration  of  the  mark  ....  The  letter  must  contain  proof  and  support  of  the 
information  ...”  before  your  protest  will  be  considered. 

For  more  information  about  either  the  Opposition  or  Protest,  contact  the  U.S.  Department  of 
Commerce,  Patent  and  Trademark  Office,  Washington,  DC  20231. 

In  closing,  let’s  not  forget  that  Ted  Nelson,  now  at  Autodesk,  coined  “hypertext”  in  1963  while 
Doug  Englebart,  now  at  Stanford  University,  defined  the  technology  even  before  that  —  and  neither 
found  it  necessary  to  trademark  the  word. 

WM 

'  Jonathan  Erickson 
editor-in-chief 
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LETTERS 


Hidden  Secrets 

Dear  DDJ, 

The  S-CODER  algorithm  Robert  Stout 
presented  in  the  January  1990  issue  of 
DDJ  seems  reasonable,  but  the  pro¬ 
grams  using  it  (Listings  One  and  Four) 
don’t  give  adequate  protection  against 
Kerckhoffs  superposition.  This  19th- 
century  technique  is  mentioned  in  the 
cryptographic  hobby  literature  (perhaps 
in  Secret  and  Urgent  by  Fletcher  Pratt 
or  The  Codebreakers  by  David  Kahn). 
The  method  is  not  very  computation¬ 
ally  intensive,  as  one  might  expect  given 
its  age. 

Consider  Listing  One.  Suppose  NF 
files  are  encrypted  with  the  same  key. 
Since  cryptextO  does  not  depend  on 
the  plaintext,  all  the  files  are  encrypted 
by  XORing  with  the  same  byte  stream 
X[l],  X[2],  ...  If  P[i,j]  is  the  rth  byte  in 
the  7th  plaintext  file  and  C[i,j]  is  the  ith 
byte  in  the  yth  ciphertext  file  we  have 

C[i,j]  =  P[i,j]  XOR  Xti] 

If  we  form  the  set  of  bytes  C[i,j],  j  = 
1,  .  .  .  NF  for  some  fixed  i,  all  these 
bytes  are  encrypted  by  XORing  with 
the  same  byte.  We  can  readily  find  the 
value  of  X[i]  that  decrypts  this  set  of 
bytes  most  resembling  plaintext.  For 
example,  if  we  assume  ASCII  plaintext, 
the  space  character  will  be  overwhelm¬ 
ingly  the  most  common  (ordinarily)  and 
X[i]  =  (most  common  byte  in  the  set 
C[i,j],  j  =  1,  .  .  .  ,  NF)  XOR  <space>  will 
be  right  most  of  the  time.  We  can  do 
this  for  each  value  of  i  separately  with¬ 
out  worrying  about  the  recursion  relat¬ 
ing  the  X[i]s. 

For  Listing  Four  the  first  thing  to 
observe  is  that  the  transposition  is  keyed 
with  a  sequence  of  random  numbers 
whose  seed  is  in  the  cryptanalyst’s  pos¬ 
session.  He  can  thus  remove  the  trans¬ 
position  at  will.  The  other  problem  is 
that  crypt_  ptris  initialized  to  (file  length) 


mod  (key  length).  The  file  length  is  not 
concealed  from  the  analyst,  however, 
and  the  key  length  might  well  be  less 
than  20.  With  several  hundred  files  en¬ 
crypted  with  the  same  key  in  his  pos¬ 
session,  the  analyst  can  assume  a  key 
length  and  then  group  together  sets  of 
files  whose  lengths  do  not  differ  modulo 
the  key  length.  He  can  then  still  use  the 
superposition  method  on  these  sets  of 
files.  If  he  has  assumed  the  wrong  key 
length  he  will  quickly  notice  that  the 
sets  of  bytes  C[i,j],  j  =  1,  .  .  .  ,  NF  will 
have  frequency  distributions  that  are 
too  smooth. 

I  suggest  two  changes.  First,  the  ran¬ 
dom  number  seed  should  depend  on 
cryptextl]  so  the  analyst  will  need  to 
deal  with  a  nontrivial  transposition.  Sec¬ 
ond,  the  initial  values  of  the  bytes  in 
cryptextO  should  be  modified  using  the 
sum  of  many  or  all  of  the  bytes  in  the 
plaintext  so  that  the  chances  of  many 
files  having  identical  key  streams  X[i] 
will  be  negligible.  This  sum  of  bytes 
can  be  put  openly  in  the  file  header 
along  with  the  length,  or  some  more 
devious  method  chosen. 

Stewart  Strait 

San  Diego,  Calif. 

Bob  responds:  First  of  all,  thank  you  for 
your  comments.  As  suggested  in  the 
article,  S-CODER  isn't  necessarily  an 
end  in  itself,  but  an  embeddable  en¬ 
cryption  engine.  The  final  listing  in  the 
article  begins  to  suggest  ways  to  create 
more  secure  applications,  although  the 
example  I  used  is  subject  to  fairly  straight¬ 
forward  cryptanalysis.  This,  inciden¬ 
tally,  was  deliberate,  leaving  open  the 
option  of  embedding  S-CODER  in  a 
more  secure  wrapper  as  a  challenge  to 
critics. 

Aside  from  the  principle  that  S- 
CODER  should  be  considered  more  of 
a  building  block  than  anything  else, 
the  two  primary  points  I'd  like  to  stress 
are  that: 

1.  The  unembellished  S-CODER  en¬ 
gine  was  not  suggested  as  being  par¬ 
ticularly  secure  when  faced  with  known 
plaintext  analysis,  but  is  rather  more 
suitable  for  short-term  security  or  un¬ 
known  plaintext  applications.  In  this 
sort  of  application,  the  only  require¬ 
ment  would  be  that  the  key  is  longer 
than  the  longest  item  of  plaintext,  which 
might  be  known  by  implication  (for 
example,  words  like  “the,  ”  a  company 
name,  etc.); 

2.  A  truism  of  data  security  is  that  a 
theoretically  secure  method  known  to 
everyone  (eg.,  DES)  is  often  less  desir¬ 
able  than  a  theoretically  less  secure 
method  (eg.,  an  enhanced  algorithm 
using  an  embedded  S-CODER  engine) 
which  is  not  known.  S-CODER  buried 


within  an  unknown  block  transposi¬ 
tion  cipher  as  suggested  in  the  article, 
or  something  equally  (or  even  more) 
obscure  presents  the  cryptanalyst  with 
the  immediate  problem  of  classifying 
the  algorithm  before  being  able  to  break 
it.  Knowing  only  that  S-CODER  is  bur¬ 
ied  in  there  somewhere  is  of  little  help 
since  S-CODER  is  a  stream  cipher  and 
any  enhanced  application  will  ran¬ 
domize  the  serial  dependencies  of  the 
S-CODER  encryption. 

Addressing  your  specific  objections, 
cryptextO  is  only  independent  of  the 
plaintext  during  the  first  pass  through 
it.  The  ability  (suggestion,  actually)  to 
set  crypt_ptr  at  some  arbitrarily  ran¬ 
dom  starting  point  within  cryptext 
makes  the  kind  of  analysis  you  suggest 
much  more  difficult.  If  we  assume  that 
the  initial  value  of  c rypt_ptr  is  deter¬ 
mined  by  some  unknown  feature  of  the 
plaintext,  the  relationship  between  i  and 
j  in  your  example  will  be  randomized. 
In  your  second  point,  you  ’re  absolutely 
correct  that  the  implementation  in  List¬ 
ing  Four  is  flawed  in  that  the  informa¬ 
tion  used  to  provide  the  additional  se¬ 
curity  is  openly  available  to  the  cryp¬ 
tanalyst.  Any  conceivable  method  used 
to  conceal  the  file  length  would  remove 
this  objection.  Once  this  vital  piece  of 
information  is  concealed,  the  next  step 
is  to  modify  the  actual  function  within 
which  S-CODER  is  embedded.  Ideally 
it  should  be fast,  as  is  the  block  transpo¬ 
sition  cipher  shown  in  the  listing,  but 
the  exact  method  should  be  known  only 
to  the  implementor.  This  is  what  I  meant 
above  when  I  said  that  an  unknown 
method  may  offer  more  security  than 
a  better,  yet  known,  method.  The  real 
value  of  Listing  Four  is  in  showing  that 
such  methods  needn ’t  sacrifice  any  sig¬ 
nificant  performance  over  the  raw  S- 
CODER  algorithm  to  offer  significant 
levels  of  security.  One  of  the  purposes 
of  the  article  was  to  encourage  people 
to  think  of  how  to  write  practical  soft¬ 
ware  rather  than  worry  about  theory 
so  much.  I  welcome  your  contribution 
and  will  consider  your  suggestions  in 
future  applications. 

Fighting  Software  Patents 

Dear  DDJ, 

Recently  your  magazine  lightly  touched 
on  the  subject  of  software  patents.  In 
the  April  1990  issue  of  Technology  Re¬ 
view  (Building  W59,  MIT,  Cambridge, 
MA  02139),  Brian  Kahin  presents  a  fright¬ 
ening  view  on  the  subject.  Even  if  part 
of  what  he  envisions  comes  to  pass, 
software  as  an  entrepreneurial  busi¬ 
ness  could  be  destroyed.  I  recommend 
this  article  to  all  who  work  in  the  art 
and  science  of  software. 

(continued  on  page  12) 
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( continued  from  page  8) 

I  do  not  understand  why  we  have 
put  up  with  this  kind  of  silliness.  An 
aroused  software  community  (users  and 
authors)  using  the  networks  (USENET, 
BITNET,  CompuServe),  bulletin  boards 
(both  local  and  national,  like  yours), 
and  their  personal  word  processors  can 
make  a  Very  Loud  Noise.  These  com¬ 
munications  resources  can  be  used  for 
information  exchange  and  coordina¬ 
tion.  If  everyone  then  processes  one 
letter  a  week  to  some  politician  some¬ 
where,  the  very  idea  of  software  pat¬ 
ents  can  be  quickly  forced  out. 

DDJ  is  a  technical  magazine.  The 
whole  idea  of  software  patents  seems 
to  have  arisen  from  technical  naivete 
in  legal  and  political  circles.  We  need 
to  have  solid  technical,  intellectual,  and 
philosophical  arguments  against  soft¬ 
ware  patents  circulated  amongst  our¬ 
selves  and  in  any  circles  that  are  af¬ 
fected.  I  urge  DDJ  readers  to  carry  out 
this  idea  and  start  a  word  processing 
campaign. 

Jim  Iwerks 

Rio  Rancho,  New  Mexico 

Pick-A-Fight  Interfaces 

Dear  DDJ, 

I  am  surprised  that  someone  with  as 
much  computer  experience  as  Bob 
Canup  would  write  such  a  one-sided 
and  narrow  minded  article  as  “Pick-A- 
Number  Interfaces,”  which  appeared 
in  the  February  1990  issue  of  DDJ.  Mr. 
Canup’s  entire  argument  seems  to  be 
based  upon  a  poorly  written  mailing 
list  program  that  he  had  had  experi¬ 
ence  with.  A  properly  written  applica¬ 
tion  level  interface  should  be  intuitive 
enough  for  any  new  user  to  feel  com¬ 
fortable  with  and  should  also  assist  the 
experienced  user  into  getting  the  job 
done  as  quickly  as  possible.  The  ulti¬ 
mate  goal  in  assisting  a  new  user  is  to 
make  the  application  as  “real  world” 
as  possible.  An  example  of  this  would 
be  to  use  the  letter  “B”  as  the  backup 
option.  The  relationship  between  the 
letter  “B”  and  the  word  “backup”  is 
simple  and  intuitive  and  lends  itself  to 
concepts  the  user  already  understands. 
Bob  proposes  forcing  the  user  to  learn 
a  new  and  unfounded  relationship  be¬ 
tween  the  number  six  and  “backup.” 

Webster  defines  the  word  “friend” 
as  “A  person  who  one  knows  well  and 
is  fond  of,”  this  is  exactly  the  type  of 
response  that  a  programmer  wants  to 
achieve  with  a  user  interface.  Modern 
UI  techniques  help  users  feel  like  they 
are  working  with  objects  they  know 
and  understand.  A  piece  of  paper  can 
be  represented  by  a  window;  just  as 
someone  may  lay  another  form  down 
on  their  desk,  they  can  lay  down  a  new 
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window  on  the  screen.  A  windowed 
interface  can  also  shield  the  user  from 
absorbing  information  they  do  not  pres¬ 
ently  need  and  at  the  same  time  graphi¬ 
cally  represent  their  “position”  within 
the  application.  Although  pointing  de¬ 
vices  such  as  a  mouse  can  be  a  hin¬ 
drance  to  the  experienced  user,  they 
are  often  helpful  to  the  new  user  by 
allowing  them  to  operate  an  applica¬ 
tion  without  having  to  know  a  prede¬ 
fined  set  of  relationships  between  the 
application  and  keyboard.  A  mouse  user 
can  simply  click  their  pointer  on  the 
word  “backup.”  It  may  take  slightly 
more  time  to  execute  the  command, 
however,  the  knowledge  required  to 
select  an  option  is  reduced  to  under¬ 
standing  the  operation  of  the  pointing 
device.  As  the  user  becomes  more  pro¬ 
ficient  at  their  own  pace  they  may  be¬ 
gin  to  use  the  keyboard  correlation 
commands.  On  the  other  hand,  the  key¬ 
board  user  must  not  only  know  how 
to  operate  the  keyboard  but  also  must 
learn  relationships  between  keys  and 
options  in  the  application  before  they 
can  operate  it  at  all.  Modern  interface 
techniques  provide  a  much  more  sup¬ 
portive  interface  for  the  user.  Mr. 
Canup  makes  the  assumption  that  the 
use  of  these  tools  is  the  problem,  when 
really  it’s  their  misuse.  I  may  be  able 
to  saw  a  piece  of  wood  in  half  using  a 
power  drill;  although  there  are  much 
more  effective  means,  does  this  mean 
that  the  power  drill  is  a  useless  frill? 
Obviously  not!  If  used  properly,  a  power 
drill  can  save  a  great  deal  of  time  in  a 
project.  I  am  certainly  glad  that  Mr. 
Canup  is  not  the  guiding  light  behind 
innovative  and  forward  thinking  user 
interface  design. 

David  Bennett 

CompuServe:  74635,1671 

Standards  Revisited 

Dear  DDJ, 

Since  you  gave  Tex  Ritter,  RE.,  a  full 
page,  I  hope  you  will  print  a  few  words 
of  mine.  Tex  Ritter,  P.E.,  takes  a  couple 
of  thousand  words  to  tirade  about  the 
standards  process  (“Letters”  DDJ,  Feb¬ 
ruary  1990),  but  reveals  that  he  has 
forgotten  those  portions  of  the  scien¬ 
tific  method  he  learned. 

He  didn’t  bother  to  learn  that  the 
"draft  standard”  is  not  an  early,  highly 
changeable  document  but  the  next-to- 
last  step  in  acceptance  and  is  nearly 
frozen  in  place  with  people  using  it  as 
a  basis  for  software. 

He  spent  many  hours  responding  to 
everyone’s  comments  that  he  received 
in  June  ’89  during  the  15-day  response 
time  and  considered  the  response  in 
September  “appallingly  condescend¬ 
ing.”  Again  he  didn’t  do  his  research. 


At  the  stage  he  did  all  that  work,  he 
only  had  the  right  to  respond  to  his 
own  previous  comments.  Other  peo¬ 
ple  merely  complain  that  it  takes  too 
long  to  search  for  the  changes  that 
caused  their  own  previous  comments. 

His  greatest  complaint  seems  to  be 
that  he  wanted  a  lot  of  features  that 
violate  the  Pascal  philosophy  of  rigid¬ 
ity  and  easy  teaching/grading  (which 
is  why  I  don’t  like  Pascal)  and  he  wanted 
strong  engineering  math  types.  In  the 
latter  case  he  should  be  using  Fortran, 
except  he  likes  the  lazy  ease-of-use  of 
never-standard  Turbo  Pascal. 

After  stating  that  voting  is  not  the 
way  to  select  a  standard,  he  decries  the 
“back  room  maneuvering”  that  put  to¬ 
gether  the  standard.  He  is  ignoring  the 
hundreds  of  hours  put  in  to  create  a 
consensus  document  that  could  be 
voted  on.  It  isn’t  democracy,  it  is  con¬ 
sensus  building  among  people  who 
are  scattered  across  3-6  million  square 
miles.  Of  course,  Ritter  would  prob¬ 
ably  object  if  the  meetings  were  held 
anywhere  but  at  his  Austin  home. 

All  I  know  about  the  standards  pro¬ 
cess  is  the  descriptive  articles  that  have 
appeared  in  Dr.  Dobb’s,  Unix  Review, 
and  C  User's  Journal.  Obviously,  I  know 
more  about  the  process  than  Mr.  Ritter, 
who  tried  to  participate  but  effectively 
entered  the  pool  with  a  belly  flop.  I 
hope  that  he  will  research  his  next 
project  (and  his  P.E.  work)  in  a  more 
professional  way,  so  he  does  not  waste 
his  time. 

Mike  Firth 
Dallas,  Texas 

Great  Minds . . . 

Dear  DDJ, 

It  is  most  interesting  that  Michael  Swaine 
has  created  an  article  on  the  War  on 
Bugs  as  a  pun  on  the  national  War  on 
Drugs  (“Swaine’s  Flames,”  DDJ  Febru¬ 
ary  1990).  I  enjoyed  the  sarcastic  hu¬ 
mor  and  appreciate  the  work  that  went 
into  making  that  article  fly. 

About  a  year  ago,  I  too  noticed  that 
bugs  and  drugs  had  many  similar  quali¬ 
ties  (for  example,  their  tenacity  and 
their  ability  to  break  down  morale), 
and  decided  to  include  the  following 
in  the  origin  line  on  my  FidoNet  BBS: 

’Origin:  Programmer’s  Oasis  / 

919  -  226  -  6984  —  Say  NO  to  Bugs! 
(1:151/402.0) 

Strangely  enough,  that  is  the  only  pun 
that  was  not  utilized  in  the  article!  Oh 
well.  Thanks  for  an  entertaining  col¬ 
umn  in  a  highly  enjoyable  magazine. 
Chris  Laforet 
Graham,  North  Carolina 

(continued  on  page  14) 
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(continued  from  page  12) 

Ritter  Redux 

Dear  DDJ, 

After  reading  Tom  Turba’s  response 
(April  1990  “Letters”)  to  my  published 
letter  (February  1990),  I  have  the  feel¬ 
ing  that  he  missed  his  true  calling:  He 
has  a  great  future  in  politics.  Although 
the  individual  facts  he  cites  may  well 
be  true,  the  impression  he  leaves  is 
deceptive.  Essentially  he  says:  “We  have 
rules  which  protect  your  interests;  if 
you  did  not  take  advantage  of  them,  it 
is  your  own  fault.”  But  it  is  one  thing 
to  leave  the  doors  open  to  participa¬ 
tion,  and  quite  another  to  announce 
where  the  doors  are,  and  what  is  on 
the  agenda.  A  casual  half-hour  with 
my  old  programming  magazines  turned 
up  no  less  than  eleven  articles  over  the 
past  two  years  on  or  about  ANSI  C 
standardization  issues;  in  contrast,  I 
found  no  articles  on  ANSI  Extended 
Pascal.  It  appears  that  Pascal  users  have 
had  no  notification  whatsoever  of  the 
Extended  Pascal  effort. 

Tom  says  that  he  invites  our  “partici¬ 
pation,”  but  there  is  participation  — 
where  one  may  have  the  chance  to 
speak,  only  to  be  ignored  —  and  PAR¬ 
TICIPATION  —  where  one’s  concerns 
are  satisfactorily  addressed.  I  obviously 
did  participate,  and  certainly  did  not 
approve  of  the  Extended  Pascal  speci¬ 
fication,  and  yet  Tom  tells  us  that  con¬ 
sensus  and  even  unanimity  was 
reached.  Such  participation  reminds  me 
of  the  communist  party  —  all  comrades 
are  equal,  but  some  are  on  the  central 
committee.  I  guess  if  you  don’t  physi¬ 
cally  walk  through  the  doors  you  must 
not  be  participating,  and  maybe  if  you 
do,  you  get  to  be  a  “visitor”  or  “ob¬ 
server.”  Clearly,  this  scheme  was  not 
designed  to  increase  participation. 

Apparently  Tom  has  now  gotten  a 
clue:  A  possible  future  project  (object- 
oriented  extensions)  may  be  announced 
to  the  user  community.  Great,  Tom, 
but  the  problem  is  the  current  specifi¬ 
cation,  not  extensions  to  it.  As  I  see  it, 
Extended  Pascal  was  developed  with¬ 
out  significant  involvement  from  the 
user  community,  so  the  process,  as  ar¬ 
duous  as  it  may  have  been,  was  fatally 
flawed.  The  resulting  “standard”  is  in¬ 
valid.  It  is  time  to  throw  this  one  away, 
and  start  on  one  we  can  all  accept. 

I  understand  that  those  may  be  chill¬ 
ing  words  to  some  people.  To  the  indi¬ 
viduals  who  have  participated  in  the 
many  long  debates  which  may  have 
taken  place,  this  might  seem  like  the 
destruction  of  all  their  work.  Yet  if  per¬ 
suasive  arguments  exist  for  the  various 
decisions,  they  should  again  prevail; 
all  that  would  be  lost  are  those  political 
victories  which  were  not  technically 


warranted.  To  software  companies  who 
see  standardization  as  a  marketing  tool, 
building  consensus  within  the  user  com¬ 
munity  must  seem  like  a  costly  and 
unnecessary  delay,  but  what  good  is  a 
standard  if  most  users  reject  it?  As  im¬ 
portant  as  these  views  are,  they  pale 
beside  their  effects.  For  example,  high 
school  students  are  being  subjected  to 
“Standard  Pascal,”  because  they  will 
eventually  take  placement  exams  which 
use  this  dialect.  Without  getting  into 
whether  a  likely  pencil-and-paper  exam 
can  have  any  bearing  on  the  interactive 
use  of  a  language  within  a  fast  devel¬ 
opment  environment,  it  is  clear  that 
even  a  marketplace-rejected  standard 
can  make  its  obnoxious  presence 
known. 

Tom  simply  failed  to  address  the  big¬ 
gest  problem  with  the  Extended  Pascal 
specification:  It  is  not  really  a  specifica¬ 
tion  at  all.  Look  at  it  this  way:  Suppose 
you  are  a  programmer  in  a  small  com¬ 
pany  hoping  to  write  portable  programs 
for  several  different  platforms.  After  buy¬ 
ing  or  licensing  a  “standard”  compiler 
for  each,  your  “portable”  programs  do 
not  compile  on  one  or  the  other.  Now, 
given  the  Extended  Pascal  specifica¬ 
tion,  will  you  be  able  to  decide  which 
compiler  is  at  fault? 

Pascal  is  a  STRUCTURED  program¬ 
ming  language.  In  contrast,  the  Ex¬ 
tended  Pascal  specification  is  “spaghetti 
code”  throughout.  In  the  version  I 
bought,  terms  were  poorly  defined,  mak¬ 
ing  the  specification  inherently  ambigu¬ 
ous.  The  spec  did  not  stand  alone,  but 
appeared  to  rest  on  previous  work, 
perhaps  upon  unnamed  compilers  on 
unnamed  machines.  The  shear  com¬ 
plexity  of  it  led  me  to  question  whether 
The  Committee  had  ever  dealt  with  an 
actual  complex  Pascal  program,  for  if 
they  had,  they  would  have  been  used 
to  partitioning  complexity  into  under¬ 
standable  chunks.  The  specification  is 
a  turkey,  not  just  because  it  does  not 
have  the  right  things  in  it,  but  because 
it  is  virtually  impossible  to  deeply  un¬ 
derstand  what  is  specified,  and  there¬ 
fore  impossible  to  understand  the  rami¬ 
fications  of  the  various  features  in  a 
final  product. 

But  you  don’t  have  to  take  MY  word 
for  it:  Tom  invites  your  participation, 
which  is  great!  Take  him  up  on  it!  If  you 
think  my  comments  are  mostly  sour 
grapes,  well,  just  get  Tom  to  send  you 
copies  of  all  the  comments  and  re¬ 
sponses  for  the  past  two  rounds,  and 
make  your  own  decision!  If  you  think 
that  the  Extended  Pascal  specification 
cannot  possibly  be  as  bad  as  I  say,  then 
Hey!  Get  Tom  to  send  you  a  copy  and 
read  it!  If  the  spec  looks  fine  to  you, 
tell  me  I'm  all  wet.  If  you  resent  the 


idea  that  major  standardization  deci¬ 
sions  gave  gone  on  without  widely  avail¬ 
able  printed  discussions  on  the  issues, 
let  Tom  know,  let  ANSI  and  ISO  know, 
and  also  let  your  compiler  vendor  know. 
Terry  Ritter,  P.E. 

Austin,  Texas 

Rhealstone  Suggestions 

Dear  DDJ, 

I  have  just  finished  reading  through  the 
April  1990  issue  of  Dr.  Dobb’s  and  was 
very  pleased  to  see  that  you  had  an 
article  with  an  actual  implementation 
of  the  Rhealstone  benchmark.  May  I 
suggest  a  couple  of  additions  which  I 
would  like  to  see  added  to  the  Rheal¬ 
stone  benchmark: 

1.  Intertask  message  latency  between 
tasks  that  are  on  different  nodes  of  a 
network.  This  metric  is  important  to 
developers  who  work  on  networked 
real-time  control  system  applications. 

2.  Message/datagram  throughput  be¬ 
tween  tasks  as  a  function  of  message 
size.  This  should  be  measured  between 
two  tasks  that  are  on  the  same  node 
and  also  between  tasks  that  are  on 
different  nodes. 

Nick  Busigin 
Stratford,  Ontario 
Canada 

Animation  Algorithm  Update 

Dear  DDJ, 

After  reading  the  letter  sent  by  Peder 
Jungck  (“Letters,”  April  1990),  I  felt  that 
some  clarification  was  necessary.  In  his 
letter,  Mr.  Jungck  stated  that  a  faster 
algorithm  would  be  to  separate  the  pixel 
data  into  logical  planes  before  the  data 
is  moved  to  the  EGA’s  physical  display 
planes.  Mr.  Jungck  was  apparently  as¬ 
suming  that  my  sample  program  trans¬ 
lated  the  initial  one  byte/pixel  format. 
This  is  to  maintain  a  rough  compatibil¬ 
ity  to  some  future  VGA  sprite  driver. 
This  first  part  is  only  run  once.  The 
second  part  uses  the  format  that  Peder 
suggested.  It  is  the  structure  that  is 
used  every  screen  refresh.  Although 
I’m  sure  Mr.  Jungck’s  program  is  a 
peach,  it  does  not  use  an  algorithm 
different  from  what  I  provided. 

Rahner  James 
Sacramento,  Calif. 

DDJ 

We  welcome  your  comments  ( and  sug¬ 
gestions).  Mail  your  letters  (include  disk, 
if  your  letter  is  lengthy  or  contains  code) 
to  DDJ,  501  Galveston  Dr.,  Redwood 
City,  CA  94063,  or  send  them  electroni¬ 
cally  to  CompuServe  76704,50  or  via 
MCI  Mail,  c/o  DDJ .  Please  include  your 
name,  city,  and  state.  We  reserve  the 
right  to  edit  letters. 
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The  DDJ 
Hypertext  Project 


How  our  hypertext  edition  happened 


J.  Scott  Johnson 


«F5  <  or  the  past  three  years,  I’ve  been  involved  in  the 
I  documentation,  design,  and  document  construction 
of  the  Black  Magic,  Help  System  II,  and  HyperWriter 
hypertext/hypermedia  authoring  systems.  Consider- 
JL  ing  this  month’s  theme,  preparing  a  hypertext  version 
of  Dr.  Dobb’s  Journal  using  HyperWriter  seemed  an  ideal, 
yet  challenging,  project.  This  article  describes  the  steps  I 
took  and  the  decisions  I  made.  While  some  of  these  steps 
were  unique  to  the  task  at  hand,  overall  this  is  typical  of 
most  hypertext  projects. 

Prototyping 

My  first  task  was  to  prototype  the  “look  and  feel”  of  the 
hypertext  version.  I  took  the  September  1989  issue  of  DDJ 
and  constructed  two  prototypes  of  the  document  —  one 
article-based,  the  other  card-based.  The  major  distinction 
between  the  two  can  be  summed  up  in  one  word:  scrolling. 
Article  documents  “scroll”  up  and  down  the  screen  while 
card-based  documents  “flip”  from  one  screen  to  another. 
An  article-based  document  can  have  unlimited  length  in  any 
of  its  nodes,  while  a  card-based  document  is  a  collection  of 
screen-sized  nodes  linked  together. 

Initially,  I  didn’t  know  which  approach  was  more  appro¬ 
priate.  Though  I  like  card-based  hypertext  documents  and 
understand  that  users  often  find  them  easier  to  navigate 
through,  I  first  opted  for  the  article  metaphor.  For  one  thing, 
card-type  documents  are  nearly  impossible  to  use  without 
a  mouse.  Mice,  though  common,  are  not  everywhere;  with 
an  article-metaphor  system,  keyboard  navigation  can  be 
efficiently  employed.  In  addition,  article-metaphor  hypertext 
tends  to  be  significantly  easier  to  create  than  card-based 
hypertext,  which  requires  you  to  “chunk”  the  material  across 
multiple  cards.  After  evaluating  the  two  metaphors  and  how 
readers  might  interact  with  them  on  the  screen,  I  ended  up 


Scott  is  the  president  of  N1ERGAID,  developers  of  a  variety 
of  hypertext  and  hypermedia  tools.  He  can  be  reached  at 
2490  Black  Rock  Tpke.,  Suite  337,  Fairfield,  CT  06430, 
203-368-0632,  or  on  BIX  as  s.johnson,  and  on  CompuServe 
at  75160,3357. 


using  elements  from  both,  as  described  in  the  next  section. 

Another  decision  I  had  to  make  during  the  prototyping 
stage  involved  the  size  of  the  document.  The  goal  was  to  fit 
everything  —  document,  runtime,  and  source  code  —  on 
one  or,  at  the  most,  two  floppy  disks.  This  conflicted, 
however,  with  my  desire  to  create  the  best  possible  docu¬ 
ment,  a  full  issue  of  DDJ  on  disk.  I  compromised  by  creating 
two  versions.  The  version  shipped  with  the  listings  disk  is  a 
bare-bones  hypertext  document  containing  articles  and  source 
code.  To  save  disk  space,  the  graphics  for  this  version  were 
created  with  the  extended  character  set.  The  other  version, 
however,  is  a  complete  issue  of  DDJ —  articles,  graphics, 
letters,  and  more.  Directions  on  how  to  obtain  both  docu¬ 
ments  are  at  the  end  of  this  article. 

Preparing  the  Data 

One  of  the  first  steps  in  creating  this  hypertext  was  data 
preparation.  I  was  supplied  with  ASCII  text  files  extracted 
from  DDJ s  typesetting  system,  which  could  be  readily  im¬ 
ported  into  HyperWriter.  This  made  the  text-end  of  things 
relatively  easy.  Graphics,  however,  were  a  different  story. 

Most  of  the  graphics  were  supplied  in  a  Macintosh  format. 
This  meant  converting  the  graphics  from  MacDraw  to  a 
MacPaint  bitmap  and  bringing  that  bitmap  to  the  PC  with  a 
Copy  II  PC  option  board.  Next,  I  converted  the  MacPaint 
bitmap  to  a  .PCX  bitmap  format,  correcting  the  aspect  ratio 
of  the  Macintosh  bitmap  to  appear  correctly  on  the  PC’s 
screen.  Finally  I  converted  the  corrected  .PCX  bitmap  into 
HyperWriter’s  compressed  bitmap  format  to  minimize  disk 
space.  Although  this  sounds  like  a  lot  of  work,  it  is  mostly 
just  tedious.  In  addition  to  converting  the  graphics  images, 
I  had  to  construct  versions  of  each  graphics  file  with  the 
extended  ASCII  character  set.  Once  these  tasks  were  done, 
the  real  work  of  building  the  document  could  begin. 

Planning 

When  all  the  data  was  in  the  computer  and  in  machine- 
readable  formats,  I  was  ready  to  start  building  the  docu¬ 
ment.  Right?  Not  quite.  I’ve  found  that  before  creating  any 
large  hypertext  document,  a  small  amount  of  planning  makes 
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worlds  of  difference.  An  early  constraint  was  to  optimize  the 
size  of  the  hypertext  document  to  accommodate  Hyper- 
Writer  (the  toolkit  I  used),  which  currently  works  only  with 
hypertext  documents  that  can  be  contained  within  memory. 

To  provide  fast  access  to  the  contents  of  documents  that 
are  actually  spread  across  several  files,  I  duplicated  the 
Table  of  Contents  cards  in  each  hypertext  document.  This 
eliminated  disk  delays  caused  by  simply  accessing  the  Table 
of  Contents.  Now,  disk  delays  occur  only  if  the  article  being 
accessed  is  actually  stored  in  another  hypertext  document. 
To  help  me  build  these  documents  that  all  share  a  common 
Table  of  Contents,  I  first  created  a  “kernel”  document  that 
contained  only  the  Table  of  Contents  cards.  I  then  used  the 
kernel  document  as  a  base  from  which  to  create  the  rest  of 
the  hypertext  documents. 

The  Actual  "Hypertexting" 

Once  I  finished  building  the  framework  of  the  hypertext 
documents  and  formatting  each  article,  the  real  work  of 
“hypertexting,”  or  creating  the  cross-referential  links,  could 
begin.  In  the  hypertext  field,  there  is  a  growing  distinction 
between  what  are  called  “objective”  and  “subjective”  links. 
An  objective  link  is  a  link  from  the  table  of  contents  to  a 
particular  article.  A  subjective  link,  on  the  other  hand,  is  an 


editorial  link  that  cross-references  relevant  material  or  makes 
a  comment  on  existing  material.  What  we’ve  found  so  far  is 
that  while  the  objective  links  are  essential,  the  subjective  links 
are  what  add  real  value  to  the  hypertext.  They  are  the  “frost¬ 
ing  on  the  hypercake”  (so  to  speak).  The  major  example  of 
subjective  links  in  the  DDJ  hypertext  are  the  links  to  the 
source  code  files.  These  links  allow  readers  to  dynamically 
view  both  the  articles  and  the  source  code.  Building  the 
subjective  links,  beyond  the  source  code  links,  required  ana¬ 
lyzing  the  material  and  then  creating  links  where  appropriate. 

Using  the  DDJ  Hypertext  Document 

When  you  first  open  the  DDJ  document,  you’ll  see  a  screen 
like  that  in  Figure  1,  which  represents  a  DDJ  cover.  This 
card-based  format  offers  access  to  the  different  sections  of 
the  Table  of  Contents.  Select  any  of  the  links  along  the 
bottom  of  the  screen  to  access  a  section  of  the  Table  of 
Contents.  Selecting  one  of  these  links  yields  a  Table  of 
Contents  card  like  that  in  Figure  2. 

You  can  select  any  of  the  links  from  a  Table  of  Contents 
card  and  access  an  article.  Articles  are  presented  in  article- 
metaphor  format.  A  sample  article  from  the  issue  is  shown 
in  Figure  3- 

I  made  an  interesting  observation  on  the  nature  of  hy- 
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The  basic  user 
interface  of  a 
hypertext  document 
is  not  the  hypertext 
software  but  rather 
the  document  itself 
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pertext  during  the  design  of  the  article-metaphor  parts  of  the 
document.  The  basic  user  interface  of  a  hypertext  document 
is  not  the  hypertext  software  but  rather  the  document  itself. 
The  arrangement  of  a  hypertext  document  —  that  is,  its 
node  and  link  structure  —  forms  the  bulk  of  the  user  inter¬ 


face  that  the  reader  encounters.  The  only  time  a  reader  steps 
outside  the  “document  as  interface”  is  when  he  or  she  elects 
to  use  the  features  of  the  hypertext  runtime  itself.  To  further 
enhance  the  document  as  user  interface,  and  to  lessen  the 
learning  curve  for  existing  readers  of  DDJ,  I  adopted  as 
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Figure  1:  The  DDJ  document  hypertext  cover 
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Figure  2:  The  Table  of  Contents  card 
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Building  Bn  Efficient  Hypertext  Help  System 


Knowing  how  help  files  and  the  hypertext  engine  interact  .is  essential 


Leo  Ho ten boon  and  Bichae!  Hose 

The  help  engine  is  nothing  nore  than  a  data  retrieval  tool 

that  takes  .a  string  and  naps  it  to  the  appropriate  topic 

text  , 

This  technology  provides  a  single  framework  for  integrating 
hypertext  into  an»;  application 

On-screen  dotrunentation  has  become  ubiquitous  in  contenporary  software,  from 
bus  loess  applications  to  programming  tools.  Like  anything  else,  the  quality 
and  usefulness  of  this  aid  varies  from  package  to  package.  The  technology  of 
hypertext<  however,  promises'  to  solve  many  of  the  organizational  and  speed 
problems  currently  found  in  some  on- screen  help  systems. 


Figure  3-  Sample  article  in  the  DDJ  hypertext  edition 


Objective  links  are  essential,  but  the 
subjective  links  are  what  add  real 
value  to  the  hypertext.  They  are  the 
“frosting  on  the  hypercake” 


many  of  DDJ s  standard  formatting  conventions  as  possible. 
See  Figure  3,  which  shows  the  beginning  of  one  of  DDJ s 
feature  articles.  The  one  major  difference  in  formatting 
conventions  is  the  substitution  of  different  colors  in  the 
hypertext  version  for  different  fonts  in  the  magazine. 

Multiple  Entry  Points 

Entry  points  provide  a  place  to  start  reading  or  browsing. 
Part  of  the  beauty  of  the  printed  page  is  that  you  have  not 
only  multiple  entry  points,  but  also  easy  access  to  those 
entry  points.  Some  examples  of  commonly  used  entry  points 
include  subheadings,  figures,  and  sidebars.  To  access  any 
of  these  entry  points  on  paper,  you  flip  through  the  pages 
of  a  magazine  article  or  book. 

Although  hypertext  allows  the  same  sort  of  entry  points 
as  paper  does,  those  entry  points  are  often  inaccessible 
because  they  are  off-screen.  To  address  this  problem,  each 
article  in  the  DDJ  document  has  a  top  line  similar  to  that 
shown  in  Figure  3,  allowing  easy  access  to  all  of  the  figures, 
subheadings,  and  tables  (the  different  entry  points  into  the 
article). 

Conclusion 

From  the  above  description,  you  may  get  the  impression 
that  creating  the  Dr.  Dobb’s  document  was  a  lot  of  work.  It 
was.  We  initially  allotted  six  weeks  for  the  job.  The  final 
version  was  produced,  working  part-time,  in  just  under 
three  weeks.  Overall,  much  of  that  time  was  devoted  to 
conceptual  activities  such  as  design  and  planning.  Building 
the  actual  document  was  relatively  easy  with  the  exception 
of  creating  the  subjective  links  —  that  took  real  analytical 
effort. 

Availability 

The  smaller  version  of  this  hypertext  document  is  available 
with  the  listings  disk.  The  enhanced  version  can  be  down¬ 
loaded  from  the  DDJ  Forum  on  CompuServe  or  you  can  get 
it  directly  from  me  for  a  small  handling  fee  ($15.00),  along 
with  an  expanded  version  of  this  article. 

The  bare-bones  version  of  the  document  only  requires  a 
monochrome  display  card  and  640K  of  RAM.  The  enhanced 
version  requires  a  CGA,  EGA,  HGA,  or  VGA  system,  640K 
of  memory,  and  a  hard  disk.  A  mouse  is  recommended.  You 
do  not  need  any  special  software  to  use  the  hypertext 
system  since  it  is  built  around  the  HyperWriter  runtime 
engine.  You  simply  extract  the  self-extracting  file  and  type 
DDJ.  Specific  instructions  are  provided  on  disk. 


DDJ 
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Building  A 

Hypertext  System 

Hypertext  for  every  programmers  toolbox 


Rick  Gessner 


There  has  been  so  much  talk  lately 
about  object-oriented  program¬ 
ming  that  it’s  easy  to  forget  that 
the  terms  “Hypertext  and  Hy¬ 
permedia”  came  into  vogue  just 
a  year  or  so  ago.  Of  course,  hypertext 
is  not  a  new  concept;  it’s  been  around 
since  the  1960s  when  Ted  Nelson  first 
introduced  the  concept  as  part  of  his 
Xanadu  project.  Popular  use  of  hy¬ 
pertext  systems  has  increased  dramati¬ 
cally  in  recent  years.  Software  compa¬ 
nies  such  as  Borland  International  and 
Microsoft,  for  instance,  have  designed 
interactive  help  components  for  their 
products  using  the  hypertext  model. 

The  advantage  of  hypertext  becomes 
evident  when  you  consider  the  inher¬ 
ent  disadvantages  of  the  traditional  in¬ 
formation  medium  —  the  printed  page. 
The  presentation  of  information  in  writ¬ 
ten  form  is  explicitly  linear.  Structur¬ 
ally,  details  embodied  by  the  text  are 
intended  to  move  from  the  general  to 
the  specific,  while  still  remaining  fo¬ 
cused  on  a  given  subject.  As  a  result, 
the  medium  is  confined  and  contextu¬ 
ally  inflexible. 

Hypertext  retains  the  capacity  for  the 
high  information  content  provided  by 
print  media,  but  removes  contextual 
limitations.  In  contrast  to  the  objec¬ 
tively  linear  nature  of  the  printed  page, 
a  hypertext  system  grants  the  user  “sub¬ 
jective  linearity.”  This  means  that  rather 
than  having  to  follow  the  explicit  course 
of  a  document,  the  user  can  choose  to 


Rick  is  developing  artificial  life  soft¬ 
ware  at  Anthrobotics  in  Tempe,  Ari¬ 
zona.  He  can  be  reached  at  1311  W. 
Baseline  #2145,  Tempe,  AZ  85283,  or 
on  CompuServe  at  71521, 1226. 


explore  an  exponential  array  of  con¬ 
textual  alternatives.  In  other  words,  the 
user  is  free  to  explore  any  information 
path  in  the  document.  From  the  pro¬ 
grammer’s  perspective,  this  approach 
removes  the  burden  of  deciding  the 
order  in  which  large  quantities  of  infor¬ 
mation  (such  as  those  found  in  help 
systems)  will  be  presented.  As  long  as 
the  data  is  related  contextually  within 
the  hypertext  system,  the  user  can  ac¬ 
cess  the  information  in  the  manner  that 
he  or  she  sees  fit.  (One  less  headache 
for  us!) 

The  purpose  of  this  article  is  to  de¬ 
mystify  hypertext  systems,  and  to  show 
you  how  to  take  advantage  of  the  hy¬ 
pertext  paradigm  in  your  own  programs. 
Along  the  way,  we’ll  also  touch  on  a 


couple  of  general-purpose  program¬ 
ming  tricks. 

And  Away  We  Go. . . 

A  wise  old  programmer  once  taught 
me  that  good  programming  is  as  much 
about  the  process  of  building  system 
tools  (providing  tools  for  ourselves)  as 
it  is  about  the  process  of  building  ap¬ 
plications  (providing  tools  for  others). 
The  hypertext  system  presented  here 
was  designed  to  provide  both  kinds  of 
tools:  A  system  tool  for  creating  and 
editing  “hyperdata  files”  (the  data  files 
used  in  a  hypertext  system),  and  an 
application  tool  that  allows  users  to 
browse  through  those  files. 

The  hypertext  system  presented  in 
this  article  is  a  page-oriented,  text-only 


22  Dr.  Dobb’s Journal,  June  1990 

492 


HYPER  TEXT  SYS T  E  M 


(continued  from  page  22) 
system  with  embedded  “hot-links”  to 
related  information.  (The  terms  “page” 
and  “screen”  are  synonymous.)  By  ac¬ 
tivating  any  of  these  hot-links,  the  user 
can  conveniently  move  from  one  item 
to  another,  and  from  one  help  page  to 
another.  Consider  the  screen  in  Figure 
1 .  A  hypertext  page  can  be  comprised 
of  any  text  that  you  want  in  the  page. 
The  embedded,  highlighted  regions 
(shown  in  outline)  represent  the  hot- 
links,  which  are  available  to  the  user 
as  a  method  of  navigation.  By  using  the 
arrow  keys  to  move  the  selection  bar 
(shown  in  inverse  video)  between  hot- 
links  and  then  pressing  the  Return  key, 
the  user  can  activate  any  page. 

You  might  have  noticed  that  the  word 
“Directory”  appears  twice  on  the  page 
shown  in  Figure  1.  The  first  time  this 
word  appears,  the  context  of  the  word 
represents  a  noun  that  means  “The  logi¬ 
cal  grouping  of  files  within  a  subdirec¬ 
tory.”  The  second  time  the  word  “Di¬ 
rectory”  appears,  it  is  used  as  a  verb 
that  means  “Display  the  contents  of  the 
current  directory.”  The  same  word  ap¬ 
pears  twice,  in  a  different  context  each 
time.  From  the  user’s  perspective,  the 
context  is  everything  —  it  is  the  basis 


Figure  1:  Sample  hypertext  dialogue 


Example  1:  A  typical  data  structure 


for  the  direction  that  the  user  takes 
while  using  the  system.  From  a  systems 
perspective,  the  contextual  meaning  of 
hyperdata  files  is  nonexistent;  it’s  all 
just  arbitrary  data.  Herein  lies  the  beauty 
of  hypertext.  A  user’s  perception  of 
context  can  be  exploited  by  using  only 
elementary  computing  techniques. 

Given  an  Infinite  Time,  and  an  Infinite 
Number  of  Monkeys . . . 

There  are  probably  as  many  different 
ways  to  write  a  hypertext  system  as 
there  are  ways  to  pronounce  “Bjarne 
Stroustrup.”  Obviously,  you  need  a  data 
structure  to  store  the  textual  data  that 
will  eventually  be  displayed,  as  well 
as  a  way  to  store  and  manipulate  hot- 
links.  Upon  first  consideration,  a  pro¬ 
grammer  might  build  data  structures 
that  look  like  the  structure  shown  in 
Example  1. 

Of  course,  there  is  nothing  mani¬ 
festly  wrong  with  this  approach.  (At 
least  that’s  what  I  told  myself  when  I 
did  it.)  Well,  almost  nothing  wrong.  A 
key  disadvantage  to  this  approach  is 
that  you  must  predefine  how  many 
hot-links  a  page  can  have,  and  then 
either  preallocate  that  number  of  links 
per  page  or  create  a  linked  list  to  store 


the  links.  The  use  of  an  array  results  in 
the  inefficient  use  of  memory.  If  you 
allocate  too  few  elements,  you  limit  the 
number  of  hot-links  per  page;  the  allo¬ 
cation  of  too  many  elements  wastes 
RAM.  The  use  of  link  lists  is  not  much 
better,  because  these  lists  require  the 
use  of  additional  routines  to  manage 
both  the  linked  lists  themselves,  and 
disk  I/O  to  and  from  the  linked  lists. 
What’s  more,  if  a  doubly  linked  list  is 
utilized,  then  each  node  requires  8  bytes 
just  for  list  pointers  —  and  8  bytes  is 
more  memory  than  each  hot-link  rec¬ 
ord  requires.  Either  way,  you  have  un¬ 
necessary  overhead. 

Another  disadvantage  with  the  ap¬ 
proach  just  described  is  that  you  have 
to  create  two  separate  editors  if  you 
want  the  system  to  be  fully  interactive. 
The  first  editor  allows  the  user  to  edit 
the  text  that  appears  on  each  page,  the 
second  would  be  used  to  allow  the 
user  to  manipulate  the  hot-link  data 
structures.  Moreover,  the  additional  com¬ 
plications  of  the  process  of  managing 
the  hot-link  data  itself  arise.  For  exam¬ 
ple,  should  the  hot-link  keywords  that 
appear  on  each  page  be  unique?  If  so, 
then  the  editor  must  be  able  to  prevent 
the  user  from  entering  duplicate  hot- 
link  keywords.  Eventually,  it  becomes 
apparent  that  there  must  be  a  simpler 
way  to  implement  the  system. 

The  answer?  What  if  there  were  a 
way  to  embed  the  hot-links  into  the 
text  itself?  If  this  were  possible,  then 
the  only  factor  limiting  the  number  of 
links  per  page  would  be  the  size  of  the 
page  itself.  Another  advantage  of  the 
technique  of  embedding  hot-links  into 
the  text  is  that  you  would  only  need 
one  editor.  The  only  requirement  of 
this  editor  would  be  that  it  must  be  able 
to  distinguish  hot-links  from  normal 
text.  Other  than  that,  a  simple  line  edi¬ 
tor  would  suffice .  (Just  wait,  you’ll  see.) 

The  inner  working  of  this  type  of 
system  is  so  simple  and  elegant  that  it’s 
almost  laughable.  The  entire  program  — 
support  routines  and  all  —  is  just  over 
500  lines  of  code.  It  just  goes  to  show 
you  that  the  best  solution  is  not  always 
the  most  difficult  to  produce. 

The  system  is  divisible  into  two  com¬ 
ponents,  each  of  which  is  incorporated 
into  a  unit  called  “HyprText.Pas”  (List¬ 
ing  One,  page  86).  The  first  component 
handles  all  of  the  user  interaction  re¬ 
quired  to  set  up  the  hyperdata  files;  this 
component  is  basically  a  screen  editor. 
The  second  component  is  called  a  “hy¬ 
pertext  engine,”  this  component  com¬ 
bines  the  information  from  the  hyperdata 
files  together  with  user  input  in  order 
to  navigate  the  pages  of  hypertext. 

Already  mentioned,  the  system  works 
by  combining  the  textual  data  that  ap- 


Help 


The  File  Menu  is  used  to|Open,||Close,||Save1and 
ICreatel  Files.  Files  may  be  selected  from  within  any 
available  Directory  or|Drive.[ 


Other  options  that  are  available  from  this  menu  are: 
[Change  Dir  j 


Directory! 


Related  topics: 


Other  Menus 


Help  on  Help 


Main  Index 


Const  ScreenWidth  =  60; 

LinesPerScreen  =  15; 

MaxHotLinks  =  25;  (Or  any  other  number  you  want) 

Type  (heres  a  place  to  store  the  screen  text) 

ScreenTextBuffer  =  Array!  1 . .ScreenWidth, 

1. .LinesPerScreen]  of  Char; 

HotLinkRecord  =  Record 

Startpos,  (col  pos  where  link  occurs) 

LineNum  :  Integer;  (row/line  number  where  link  occurs) 
LinkPage  :  Integer;  (page  number  to  activate  for  link) 

end; 

(now  put  it  all  together) 

OnePage  =  Record 

TheText  :  ScreenTextBuffer; 

TheLinks  ;  Array (1 ■ .MaxHotLinks]  of  HotLinkRecord; 

end; 
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(continued  from  page  24) 
pears  on  a  given  hypertext  page  with 
the  links  that  interconnect  one  page  to 
another.  An  example  of  how  it’s  done 
will  make  the  trick  obvious. 

Let’s  assume  that  the  user  has  typed 
the  lines  shown  in  Figure  2  for  a  given 
hypertext  page,  using  our  built-in  hy¬ 
pertext  editor.  The  characters  typed  by 
the  user  are  stored  in  the  Help_Record 
data  structure,  which  is  defined  as  listed 
in  Example  2. 

As  you  can  see,  the  Help_Record  data 
type  is  very  sparse;  in  fact,  it’s  an  array 
of  strings.  The  reason  for  using  a  rec¬ 
ord  structure  is  to  facilitate  disk  I/O, 
and  nothing  more. 

Here  comes  the  linking  trick.  Let’s 
presume  that  a  hypothetical  user  wants 
to  create  a  hot-link  for  the  term  “OS- 
Shell”  (Figure  2)  to  page  5  in  our  hy¬ 
perdata  file.  (Setting  and  removing  a 
link  is  accomplished  by  pressing  the  F2 
key.)  The  pseudocode  description  of 


the  algorithm  for  placing  a  link  is  shown 
in  Figure  3-  The  process  begins  by 
determining  if  the  cursor  is  currently 
positioned  on  a  valid  (non-space)  char¬ 
acter.  If  so,  then  the  next  step  is  to  find 
the  first  and  last  characters  in  the  cur¬ 
rent  phrase.  The  high  bit  of  each  char¬ 
acter  in  the  phrase  is  then  set,  by  add¬ 
ing  $80  to  the  value  of  each  character. 
The  last  step  is  to  add  a  “hot-link  token” 
to  the  end  of  the  phrase.  A  hot-link 
token  is  comprised  of  a  null  byte  fol¬ 
lowed  by  the  hot-link  page  number. 

Returning  to  our  example,  the  user 
has  decided  to  create  a  link  on  the 
phrase  “OS  Shell”  to  page  5  in  the 
hyperdata  file.  Before  the  link,  the  char¬ 
acters  on  line  8  look  like  those  shown 
in  Example  3-  After  the  link  is  per¬ 
formed,  the  high  bits  are  set,  and  the 
link  information  is  appended  to  the 
end  of  the  phrase,  line  8  looks  like  the 
code  in  Example  4. 

Notice  that  the  ordinal  value  of  each 


of  the  characters  in  the  phase  has  been 
incremented  by  $80.  Also,  notice  that 
a  hot-link  token  has  been  added  to  the 
end  of  the  phrase  ($00,  $05).  A  null 
($00)  value  is  used  as  a  delimiter,  and 
it  is  immediately  followed  by  a  byte 
that  contains  the  link  page  number. 
The  use  of  a  byte  to  store  the  page 
numbers  limits  the  system  to  a  maxi¬ 
mum  of  255  pages  of  help,  which  is 
equal  to  the  greatest  value  that  can  be 
stored  in  a  single  byte.  It  is  possible  to 
eliminate  this  limitation  by  promoting 
the  byte  to  a  word  or  a  longint,  as  long 
as  you  watch  out  for  nulls.  (Nulls  are 
used  as  the  unique  hot-link  delimiter.) 

You  may  be  wondering  why  the  sys¬ 
tem  both  adds  hot-link  tokens  and  sets 
the  high  bit  of  linked  terms.  There  are 
two  reasons.  First,  setting  the  high  bits 
simplifies  the  task  of  detecting  which 
words  are  linked  and  which  are  not. 
Second,  this  step  makes  the  process  of 
displaying  each  page  easier  to  do,  be¬ 
cause  the  display  routines  can  check 
for  the  presence  or  absence  of  the  high 
bit,  and  then  select  the  appropriate  dis¬ 
play  colors  accordingly. 

The  only  task  that  remains  to  be 
solved  is  the  step  of  unlinking  a  previ¬ 
ously  linked  phrase.  The  solution  is 
simple.  When  the  user  requests  a  link 
for  a  given  word,  the  system  first  deter¬ 
mines  if  the  word  has  already  been 
linked.  It  makes  this  determination  by 
comparing  the  ordinal  value  of  the  char¬ 
acter  that  is  currently  loaded  beneath 
the  cursor  (at  the  cursor  insert  position). 
If  the  value  of  the  current  character  is 
greater  than  $80,  then  the  character  must 
already  be  linked.  In  this  case,  the  pro¬ 
cess  just  described  is  reversed  —  the  high 
bit  of  each  character  in  the  phrase  is 
cleared,  returning  it  to  its  original  ASCII 
value.  Last  of  all,  the  hot-link  token  that 
was  previously  appended  to  the  end  of 
the  phrase  is  removed.  Voila  back  to  nor¬ 
mal! 

The  Hypertext  Editor 

The  hyperdata  file-editor  routines  ap¬ 
pear  in  the  HyprText  unit  (Listing  One) 
lines  77  -  288.  The  editor  provides  com¬ 
mon  routines  for  horizontal  and  verti¬ 
cal  cursor  movement,  backspace,  and 
character/line  deletion.  It’s  nothing  more 
than  a  simple,  screen-oriented  line  edi¬ 
tor  that  can  deal  with  both  embedded 
hot-link  tokens  and  characters  that  have 
their  high  bits  set. 

In  the  process  of  dealing  with  an 
ASCII  character  that  has  the  high  bit  set 
is  very  simple.  Because  the  only  data 
allowed  during  data  input  are  valid 
ASCII  characters,  we  can  be  sure  (cor¬ 
rupted  data  files  notwithstanding)  that 
any  character  with  an  ASCII  value 
greater  than  127  is  part  of  a  hot-linked 
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The  File  Menu  is  used  to  Open,  Close,  Save  and 
Create  Files.  Files  may  be  selected  from  within  any 
available  Directory  or  Drive. 

Other  options  that  are  available  from  this  menu  are: 
OS  Shell  Directory 

Change  Dir  Quit 

Related  topics: 

Other  Menus  Main  Index 

Help  on  Help 


Figure  2:  Sample  hypertext  screen 


Const  MaxLinesPerPage  =  15; 

MaxLineWidth  =  60; 

Type  Help_Record  =  Record 

Helplines  :  Array [1. .MaxLinesPerPage]  of  String[100];  (Leave  room 

for  links} 

end; 


Example  2:  Defining  the  Help_Record  data  structure 


If  Cursor  is  on  a  valid  alpha  character  ([Succ(  ‘  ’)..  ’}  ’])then 
Begin 

Start  :=  Find  1st  char  in  the  phrase: 

Stop  :=  Find  last  char  in  the  phrase; 

For  CurrentChar  :=  Start  to  Stop  do 
Set  Char[CurrentChar]  High-Bit; 

Attach  link 
end 


Figure  3- '  Pseudocode  description  of  the  algorithm  for  placing  a  link 


Helplines [8]  =  [ '  OS  Shell  Main  Index  ']  (As  a  string) 

=  (  $20, $20, $20, $20,  (As  Hex} 

$4F,  $53,  $20,  $53,  $68,  $6C,  $6C] 


Example  3:  Before  linking,  the  characters  on  line  8  look  like  this 
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(continued  from  page  26) 
phrase.  To  properly  display  this  data, 
all  that  is  required  is  to  reduce  the 
decimal  value  of  the  characters  in  ques¬ 
tion  by  $80.  The  routine  Show_HelpLine, 
and  its  ancillary  routine  Write_Char ; 
handle  that  task. 

Show_HelpLine  is  called  by  Show_ 
Help_Page  to  display  each  line  of  text. 
Show_HelpLine  performs  two  related 
tasks.  First,  it  determines  the  color  at¬ 
tribute  with  which  each  character  is 
displayed.  This  determination  gives  the 
system  the  capability  to  show  hot- 
linked  items  in  a  different  color  and/or 
intensity  than  the  color  or  intensity  of 
normal  text.  Second,  Show_HelpLine 
calls  Write_Char,  which  decodes  each 
ASCII  character  and  reduces  the  char¬ 
acter’s  value  by  $80  if  necessary  before 
displaying  that  character.  That’s  all  there 
is  to  it. 

To  understand  how  the  editor  deals 
with  embedded  hot-links,  consider  how 
a  line  editor  works.  Given  a  line  of 
ASCII  text,  the  editing  routine  enters  a 
loop.  The  user  is  permitted  to  enter 
valid  characters,  which  are  inserted  into 
the  line  at  the  current  cursor  position. 
Editing  commands  are  provided  to  al¬ 
low  the  user  to  quickly  alter  the  input 
data  via  such  steps  as  deleting  all  of  the 
characters  from  the  cursor  to  the  end 
of  the  line.  The  routine  normally  exits 
when  the  user  presses  a  valid  terminat¬ 
ing  keystroke,  which  is  often  just  a 
press  of  the  Return  key. 

The  editor  works  in  the  same  way. 
If  a  valid  character  is  entered  by  the 
user,  the  character  is  inserted  into  the 
line  at  the  cursor  position,  or  at  least 
at  what  appears  to  the  user  to  be  the 
cursor  position.  Remember  that  each 
line  may  contain  hot-link  tokens,  which 
consists  of  data  that  are  not  actually 
seen  by  the  user.  What  appears  to  the 
user  to  be  column  10  for  example,  might 
actually  be  character  16  or  character 
20  once  hot-link  tokens  are  taken  into 
account. 

Consider  Example  5.  Let’s  presume 
that  the  cursor  is  located  in  column  17, 
just  above  the  letter  “M”  in  the  word 
“Main  Index.”  Also,  presume  that  no 
hot-links  are  present  in  the  line.  In  this 


case,  the  actual  character  number  in 
the  string  is  the  same  as  the  column 
number  that  appears  to  the  user.  In  our 
example,  if  the  user  presses  any  valid 
character,  that  character  is  inserted  into 
the  line  at  column  17.  Now  let’s  say 
that  the  user  previously  linked  the 
phrase  “OS  Shell,”  and  that  the  cursor 
again  is  located  above  the  letter  “M,” 
as  shown  in  Example  6. 

Just  as  before,  the  cursor  appears  to 
the  user  to  be  located  in  column  17, 
but  the  editor  knows  better.  The  actual 
character  number  is  19;  the  difference 
is  due  to  the  fact  that  a  2-byte  hot-link 
token  has  been  inserted  into  the  line 
after  the  phrase  “OS  Shell.”  If  the  user 
presses  any  valid  character  at  this  point, 
then  the  character  is  inserted  into  the 
string  as  character  19-  From  the  user’s 
viewpoint,  the  result  is  identical  to  the 
process  just  described  for  the  case  where 
no  embedded  hot-links  are  present. 

Two  routines  worth  mentioning  are 
Determine_  Actual_Line_Pos and  Link_ 
Count.  Determine_Actual_Line_  Pos con¬ 
verts  the  visual  column  number  that 
appears  to  the  user  (and  is  tracked  by 
the  editor)  to  the  actual  column  posi¬ 
tion  just  described.  Link_Count returns 
the  number  of  hot-links  found  on  a 
given  line.  This  routine  works  by  count¬ 
ing  the  number  of  null  characters  — 
our  hot-link  token  delimiters  —  in  a 
line.  All  of  the  work  required  to  handle 
the  process  of  editing  text  that  contains 
embedded  hot-links  can  be  performed 
by  these  two  routines,  making  the  in¬ 
clusion  of  additional  editing  routines 
much  easier. 

The  editor  itself  is  called  and  man¬ 
aged  by  the  routine  Help_Editor ,  which 
provides  the  necessary  setup,  file-han¬ 
dling,  and  page-manipulation  routines 
required  by  the  editor  itself.  Help_Editor 
also  provides  a  simple  screen  display 
and  an  editing-command  help  window 
for  the  user  —  the  latter  is  an  excellent 
place  for  you  to  add  your  user-inter¬ 
face  touches. 

The  discussion  of  the  design  consid¬ 
erations  of  the  editor  brings  up  an  im¬ 
portant  point  not  only  with  respect  to 
our  hypertext  system,  but  to  user  inter¬ 
face  design  in  general.  It  doesn’t  make 


a  bit  of  difference  what  is  going  on 
beneath  the  surface,  as  long  as  that 
activity  does  not  interfere  with  the  user. 
Case  in  point:  Compare  word  process¬ 
ing  on  the  Macintosh  with  word  pro¬ 
cessing  on  the  PC.  On  the  Mac,  the 
user  never  explicitly  inserts  font  con¬ 
trols  into  a  document.  Instead,  the  user 
just  selects  the  font  they  want  from  a 
menu  and  the  rest  is  handled  by  the 
Mac  beneath  the  surface.  On  the  PC, 
the  user  practically  has  to  learn  a  for¬ 
eign  language  in  order  to  instruct  a 
word  processor  to  change  fonts  mid¬ 
paragraph. 

The  Hypertext  Engine 

A  hypertext  engine  is  a  collection  of 
routines  that  permit  a  user  to  access  the 
data  contained  in  hyperdata  files.  Func¬ 
tionally,  a  hypertext  engine  is  equiva¬ 
lent  to  a  random-access  file  browser;  it 
permits  the  user  to  scan  records  (or 
pages,  in  this  case)  in  any  order.  The 
only  difference  with  respect  to  a  hy¬ 
pertext  engine  is  that  the  user  never 
directly  specifies  a  record/page  num¬ 
ber.  Instead,  the  user  moves  from  one 
page  to  another  by  the  selection  of 
hot-links;  the  hot-links  contain  the  new 
page  numbers.  The  page  number  makes 
no  difference  whatsoever  to  the  user  — 
the  user  need  be  concerned  only  with 
the  context  of  the  hot-link  keywords 
and  the  user’s  own  interest  in  pursuing 
a  given  contextual  flow. 

The  hypertext  engine  itself  is  shown 
in  Listing  One  in  lines  290-319  and 
367  -  548.  Listed  first  are  the  I/O  rou¬ 
tines  that  read  and  write  the  hyperdata 
files  created  and  used  by  the  system. 
Because  these  routines  operate  on  sim¬ 
ple  binary  files,  and  because  binaiy  file 
I/O  is  both  easily  understood  and  well- 
documented  elsewhere,  a  discussion 
of  these  routines  is  omitted  here. 

The  main  task  performed  by  the  hy¬ 
pertext  engine  is  to  provide  a  user  in¬ 
terface  that  permits  the  user  to  navigate 
hyperdata  files.  The  engine  creates  the 
illusion  of  a  highlighted  selection  bar 
for  the  user.  A  related  task  performed 
by  the  hypertext  engine  is  to  track  the 
user’s  navigation  of  the  hyperdata  file. 
The  process  of  tracking  is  required  in 
order  to  allow  the  user  to  explore  any 
contextual  path  to  and  then  back  out 
of  that  path  to  the  original  starting  point. 
The  engine  handles  this  process  by 
maintaining  a  local  stack  that  tracks 
both  the  hypertext  pages  that  the  user 
visits  and  the  order  of  the  user’s  visit 
to  the  pages.  (The  Stack  data  structure 
is  shown  in  Listing  One,  lines  438  -  442 
and  444.) 

The  technique  of  tracking  the  user’s 
navigation  around  the  system  is  not 
(continued  on  page  31) 


Helplines  [8]  =  [ '  OS  Shell  Main  Index  ']; 

(Character  17) 

Example  5:  The  actual  character  number 
Example  4:  After  linking,  the  char-  in  the  string  is  the  same  as  the  column 
acters  on  line  8  look  like  this  number  that  the  user  sees 

HelpLines[8]  =  [ '  OS  Shell<xx>  Main  Index  ' ] ; 

(Hot  link)  (Character  19) 

Example  6:  The  phrase  “OS  Shell”  was  previously  linked;  cursor  is  on  the 
letter  “M” 


=  [  $20, $20, $20, $20, 

$CF,  $D3,  $A0,  $D3, 

$E8,  $EC,  $EC,  $00, $05) 
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( continued  from  page  28) 
very  difficult.  Once  the  user  selects  a 
hot-link,  the  page  number  contained 
in  the  hot-link  is  pushed  onto  the  local 
stack.  If  the  user  decides  to  back  out 
of  a  path  by  pressing  the  PgUp  key, 
then  each  preceding  page  number  is 
popped  off  the  local  stack  (which,  in 
effect,  reverses  the  user’s  path).  This 
process  continues  until  the  root  has 
been  found,  the  user  chooses  to  move 
down  another  path,  or  the  stack  is  empty. 

In  addition  to  engine’s  ability  to  track 
the  user’s  navigation  around  the  sys¬ 
tem,  another  very  useful  feature  is  pro¬ 
vided  by  the  engine  as  a  result  of  its 
local  stack.  The  programmer  can  spec¬ 
ify  a  starting  page  and  a  home  page, 
thereby  priming  the  local  stack.  This 
feature  allows  you  to  jump  into  the 
hyperdata  file  at  any  point  and  still 
permit  your  user  to  return  to  a  main 
index  or  a  home  page.  For  example, 
let’s  say  that  you  have  written  a  data¬ 
base  application  and  you’ve  used  this 
hypertext  system  as  the  basis  of  your 
pop-up  help  system.  Further,  let’s  say 
that  the  user  has  requested  help  on 
sorting  records.  As  the  programmer, 
you  want  the  help  system  to  first  show 
the  page  concerned  with  sorting.  This 
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step  is  accomplished  by  passing  a  valid 
page  number  to  the  hypertext  engine 
to  be  used  as  the  starting  page  on  the 
topic  of  sorting.  A  home  page,  usually 
used  for  a  main  index,  can  also  be 
specified  as  a  startup  parameter  for  the 
engine. 

One  last  point  of  interest  is  the 
method  used  to  find  embedded  hot- 
links  on  a  given  page.  The  technique 
used  for  embedding  hot-links  directly 
into  the  data  for  each  page  has  already 
been  discussed.  But  because  the  sys¬ 
tem  does  not  keep  master  hot-link  ta¬ 
bles,  the  links  must  be  decoded  at  run 
time.  Once  a  page  has  been  loaded 
into  memory  and  displayed,  the  recur¬ 
sive  routines  Find_Next_Link  and 
Find_Prev_Link  handle  the  decoding 
for  you.  Find_Next_Link  accepts  a  line 
and  column  number  for  the  current 
page,  and  then  searches  the  page  from 
that  coordinate  to  the  end,  looking  for 
an  embedded  link.  Find_Prev_Link. 
works  in  the  same  manner,  except  that 
it  starts  at  a  given  coordinate  and 
searches  backwards  toward  the  top  of 
the  page.  The  two  routines  allow  you 
to  start  at  any  point  on  the  screen,  and 
finding  the  next  or  the  previous  hot- 
link.  Once  the  new  hot-link  is  found, 


it’s  highlighted  by  the  selection  bar, 
and  can  be  invoked  by  a  press  of  the 
Return  key.  Pages  without  hot-links  ter¬ 
minate  the  current  contextual  path. 

The  Supporting  Cast 

The  other  routines  in  Listing  One  (see 
lines  32  -  75)  are  purely  to  provide  sup¬ 
port.  The  Make_String  procedure  cre¬ 
ates  a  string  of  a  given  length  from  any 
ASCII  character.  Draw_Box  draws  sin¬ 
gle  or  double-lined  boxes  using  ASCII 
line-drawing  characters  and  the  coor¬ 
dinates  provided  as  parameters.  (All 
simple  stuff.)  Read_KeyBoard  accepts 
user  input,  one  character  at  a  time,  and 
detects  when  the  user  presses  the  Ctrl 
and  Alt  keys. 

Using  the  HyprText  Unit 

The  code  in  Example  7  shows  how  easy 
it  is  to  use  the  HyprText  unit  in  your 
own  programs.  Line  9  shows  a  call  to 
the  editor,  Help_Editor,  that  passes  the 
name  of  the  hyperdata  file  to  be  used. 
Once  the  user  is  finished  editing  the  file, 
the  program  calls  the  procedure  Do_FIelp 
on  line  10,  and  passes  to  this  procedure 
the  name  of  the  hyperdata  file  to  be 
used.  The  other  parameters  passed  to 
Do_Help  specify  the  starting  and  home 
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(continued  from  page  3D 

page  numbers  used  to  prime  the  stack 

(as  described  earlier). 

If  you  want  to  use  this  system  for 
pop-up  help  inside  your  own  programs, 
you  may  want  to  add  routines  to  save  the 
text  screen  before  calling  Do_Hslp ,  and 
to  restore  the  text  screen  once  Do_Help 
terminates.  Also,  to  keep  the  length  of 
the  listing  to  a  minimum,  I  omitted  most 
of  the  error-checking  steps  that  a  com¬ 
mercial  application  should  have.  You  may 
want  to  add  more  error-checking  rou¬ 
tines  to  meet  your  own  needs. 


The  Epilog 

Well,  there  you  have  it  —  a  hypertext 
system  that  is  simple  to  program  and 
simple  to  use.  I  hope  that  this  system 
offers  a  useful  addition  to  your  pro¬ 
gramming  toolbox. 

I  am  sure  that  you  can  think  of  addi¬ 
tional  uses  and  enhancements  to  this 
system.  What  about  converting  this  sys¬ 
tem  to  a  graphics-oriented  environment, 
such  as  the  BGI?  What  about  adding 
sound  hot-links?  Or  adding  a  utility 
that  reads  text  files,  searches  for  key¬ 
words,  builds  an  index,  and  then  auto¬ 


matically  builds  hyperdata  files?  You 
could  also  add  compression  routines 
to  reduce  the  storage  requirements  of 
hyperdata  files. 

Nobody  ever  said  that  programming 
the  PC  was  supposed  to  be  dull! 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr  Dobb's Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listing  begins  on  page  86.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  2. 


1  Program  HelpTest; 

2  Uses  Crt, HyprHelp; 

3  Var  FileName  :  String[80]; 

4  Begin 

5  ClrScr; 

6  {If  you  want  to  save  the  current  text  screen,  do  it  here.} 

7  Write (TEnter  the  file  name:  U) ; 

8  Readln (FileName) ; 

9  Help_Editor (  FileName  ) ; 

10  Dojtelp  (  FileName,  1,1); 

11  {  Restore  the  text  screen  here,  if  you  saved  it  before  } 

12  end. 


Example  7:  Code  to  incorporate  the  HyprText  unit  in  other  programs 
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A  Self-Referential 

Hypertext  Engine 

A  simple  engine  for  context-sensitive  help 


Todd  King 


. he  history  of  the  idea  of  hy¬ 
pertext  systems  dates  back  as 
I  far  as  1945.  The  first  true  imple¬ 
mentations  didn’t  emerge  until 
JL  about  20  years  later  and  hypertext 
systems  have  evolved  continually  ever 
since.  Hypertext-related  concepts  have 
found  their  way  into  a  variety  of  appli¬ 
cations  ranging  from  context-sensitive 
help  to  document-management  systems 
to  user-programmable  systems  such  as 
Apple’s  HyperCard.  Even  multimedia 
hypertext  systems  (which  are  the  pur¬ 
est  form  of  hypertext)  are  now  within 
our  reach. 

In  this  article,  I'll  discuss  how  you 
can  build  a  hypertext  system  that  can 
be  used  for  the  development  of  a  con¬ 
text-sensitive  help  system  or  for  the 
display  of  hypertext  documents.  The 
type  of  hypertext  system  presented  is 
a  “text-based”  (no  graphics  or  sound) 
system.  This  type  of  system  is  sufficient 
for  many  applications,  and  is  easy  to 
implement. 

At  the  level  of  plain  text,  a  hypertext 
document  differs  from  an  ordinary  docu¬ 
ment  in  that  links  in  a  hypertext  docu¬ 
ment  are  established  between  various 
parts  of  the  document.  These  links  al¬ 
low  you  to  reposition  yourself  within 
the  document  by  navigating  along  the 
links.  In  some  ways,  a  link  is  an  iconic 


Todd  is  a  programmer/analyst  with  the 
Institute  of  Geophysics  and  Planetary 
Physics  at  UCLA  where  he  works  on 
various  software  projects.  He  is  writing 
a  book,  Dynamic  Data  Structures,  which 
will  be  published  by  Academic  Press, 
late  in  1990.  Todd  can  be  reached  at 
1104  N.  Orchard,  Burbank,  CA  91506. 


bookmark  to  which  you  can  move  at 
any  time.  In  the  case  of  a  graphical  or 
multimedia  hypertext  system,  other  ac¬ 
tions  may  also  be  associated  with  a 
link.  For  example,  a  link  may  display 
a  particular  photograph,  or  even  pro¬ 
duce  music. 

Just  as  a  variety  of  hypertext  systems 
exist,  a  variety  of  methods  for  estab¬ 
lishing  the  links  within  a  hypertext  docu¬ 
ment  also  exist.  In  the  application  pre¬ 
sented  here,  I  establish  the  links  at  the 
time  when  the  document  is  displayed. 
This  step  is  accomplished  as  follows: 
Each  topic  in  the  hypertext  document 
has  a  phrase  associated  with  it.  This 
phrase  serves  as  a  tag  which,  if  refer¬ 
enced  in  another  topic,  automatically 
establishes  a  link.  This  type  of  approach 


allows  you  to  build  up  your  hypertext 
document  either  by  adding  topics  when 
you  need  them  or  when  you  find  that 
certain  words  or  phrases  require  eluci¬ 
dation.  Because  the  new  topics  will 
automatically  be  linked  to  all  other  top¬ 
ics  that  reference  them,  you  don’t  have 
to  spend  time  managing  the  links  —  all 
you  do  is  write  the  document. 

The  Code 

The  code  for  the  hypertext  document 
display  program  (which  I  call  hyper_d) 
is  presented  in  Listing  One,  page  92. 
hyper_d  is  invoked  without  any  com¬ 
mand-line  arguments  (for  the  sake  of 
simplicity).  When  the  program  is  in¬ 
voked  it  first  opens  the  document  file 
called  “F1YPER.TXT.  ”  hyper_d then  calls 
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C continued  from  page  34) 
the  function  build_hyperbase(  ).  This 
function  builds  an  index  of  topic  tags 
for  all  of  the  topics  in  the  file,  and 
stores  the  location  of  the  beginning  of 
each  topic  within  the  file.  This  tag  data 
base,  called  “Hyperbase,”  is  used  by 
the  display  and  navigation  routines  to 
establish  links  and  to  move  within  the 
document.  The  definition  for  the  Hy- 

A  variety  of  methods 
can  he  used  to  establish 
the  links  within  a 
hypertext  document 


perbase  structure,  as  well  as  other  defi¬ 
nitions,  can  be  found  in  Listing  Two, 
page  94. 

The  next  function  called  by  hyper_d 
is  enter_text(  ).  This  function  references 
a  given  topic  by  its  tag,  vectors  to  that 
topic  in  the  document,  and  then  allows 
navigation  within  the  document,  en- 
ter_text(  )  returns  each  time  a  tag  is 
selected  within  a  document,  and  then 
evaluates  to  the  index  in  Hyperbase  of 
the  selected  tag.  As  long  as  the  Esc  key 
is  not  pressed  (which  returns  a  special 
tag  ID  of  -1),  enter_text(  )  is  called  with 
the  tag  that  represents  the  current  se¬ 
lection.  This  step  repositions  you  in  the 
document  and  begins  the  entire  cycle 
again.  If  the  Esc  key  is  pressed,  the 
application  performs  some  cleanup  op¬ 
erations  and  then  exits. 

enter_text( )  could  also  have  been 
implemented  as  a  recursive  call,  rather 
than  placing  it  in  a  while!  )  loop.  This 
function  was  placed  in  a  while!  )  loop 
because  this  approach  minimizes  the 
demands  for  stack  space.  Imagine  the 
results  of  making  each  topic  a  separate 
function,  or  calling  enter_text(  )  as  the 
navigational  step  rather  than  using  loop¬ 
ing.  You  are  free  to  navigate  through 
the  document  and  jump  along  links  as 
many  times  as  you  like,  so  at  some  point 
a  recursive  implementation  would  ex¬ 
ceed  the  limits  of  the  application’s  stack. 

Several  other  functions  and  struc¬ 
tures  are  used  in  the  application.  Rather 
than  describe  each  one  here,  I  created 
a  hypertext  document  that  describes 
the  entire  application.  The  text  for  this 
document  is  contained  in  Listing  Three, 
page  94.  The  structure  of  the  hypertext 
documents  used  by  this  system  is  very 
similar  to  the  structure  of  a  conven¬ 
tional  document.  The  listing  is  quite 


readable  without  using  hyper_d,  but 
the  use  of  hyper_d  makes  tlte  process 
of  reading  the  listing  more  efficient  and 
more  fun. 

Using  the  System 

When  you’ve  created  a  hypertext  docu¬ 
ment  that  you’d  like  to  view,  simply 
place  the  document  in  a  file  called 
“HYPER.TXT”  and  run  hyper_d.  Pro¬ 
vided  that  your  document  is  structured 
properly,  you  will  be  placed  at  the  first 
item  in  the  first  topic,  and  then  set  free 
to  navigate  through  the  document.  Each 
link  to  another  topic  is  displayed  as 
bold  type  on  monochrome  screens,  and 
as  yellow  type  on  color  screens.  The 
currently  selected  item  is  displayed  in 
inverse  video..  To  move  the  highlight 
around  within  the  document,  press 
either  the  left  or  the  right  cursor  key. 
This  step  will  move  you  either  back¬ 
ward  one  item  (left  cursor)  or  forward 
one  item  (right  cursor).  Once  you’ve 
highlighted  a  tag  of  a  topic  to  which 
you’d  like  to  move,  press  the  Enter  key. 

To  create  a  new  document,  you  have 
to  follow  some  simple  rules  so  that 
byper_d  can  locate  each  topic.  A  topic 
begins  with  a  line  that  consists  of  a 
form  feed  that  is  followed  by  a  new 
line.  The  next  line  that  follows  is  the 
tag  string  for  the  topic.  Everything  that 
follows  the  tag  line  is  text  for  the  topic. 
You  can  insert  any  characters  into  the 
text  portion  of  a  topic,  including  the 
graphic  characters  in  the  PC’s  character 
set.  Graphic  characters  are  handy  be¬ 
cause  they  give  the  appearance  of  be¬ 
ing  graphically  based,  when  in  fact 
they’re  only  character  based. 

The  way  in  which  you  embed  a  form 
feed  into  your  document  differs  from 
editor  to  editor.  Here’s  how  to  do  it 
using  a  few  of  the  editors  that  I  use 
regularly.  In  Turbo  C,  press  Ctrl-P  and 
then  press  Ctrl-L.  In  vi,  press  Ctrl-L 
while  the  program  is  in  insert  mode. 
In  Microsoft  Word,  insert  a  page  break 
by  pressing  Shift-Ctrl-Return. 

Extensions 

Many  obvious  improvements  could  be 
made  to  hyper_d.  Only  a  minimal  set 
of  functions  has  been  implemented  in 
order  to  present  the  elements  of  a  hy¬ 
pertext  system  in  the  clearest  possible 
way.  One  obvious  improvement  would 
be  to  add  support  for  a  full  range  of 
navigational  keystrokes,  such  as  the 
up  and  down  cursor  motions.  Another 
improvement  would  be  to  “compile” 
the  text,  rather  than  take  the  “interpreter” 
approach  that  was  done  in  this  article. 
This  technique  would  involve  the  pro¬ 
cess  of  calculating  the  links  (as  per¬ 
formed  by  build_hyperbase(  ))  and  then 
recording  the  calculation  in  some  way 
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(continued  from  page  36) 
so  that  navigation  can  begin  immedi¬ 
ately  when  the  document  is  called. 

Some  features  of  more  powerful  hy¬ 
pertext  systems  include  navigation  his¬ 
tory  lists,  which  allow  you  to  retrace 
your  steps  through  a  document;  the 
possibility  of  integrated  text  and  graph¬ 
ics;  and  scrollable  windows.  Even 
though  these  features  (and  many  more) 
are  expected  of  hypertext  systems  to¬ 
day,  applications  for  text-only  hypertext 
still  exist.  The  hypertext  system  for  the 
documentation  of  the  source  code  pre¬ 
sented  in  this  article  is  one  example. 

Conclusion 

I  think  Apple  will  be  remembered  fondly 
for  bringing  hypertext  systems  into  the 
hands  of  the  average  person  —  not  so 
much  because  the  company  developed 
HyperCard,  but  because  Apple  gave  it 
away  for  free,  bundled  with  every  Mac. 
Even  though  a  PC  is  just  as  capable  of 
running  hypertext  systems  as  a  Mac, 
there  isn’t  a  single  (as  far  as  I  know) 
PC-based  hypertext  development  sys¬ 
tem  that  is  given  away  free  or  almost 
free.  The  PC-based  application  pre¬ 
sented  in  this  article  is  available  for 
anyone  to  use,  free  of  charge.  You  are 
also  welcome  to  use  it  as  a  seed  for  the 
development  of  a  more  fully  featured 
display  system.  If  you  do  expand  this 
code  directly,  please  keep  the  results 
in  the  public  domain. 

This  code  was  developed  and  tested 
using  Turbo  C  2.0.  It  also  uses  certain 
library  functions  that  are  unique  to 
Turbo  C  and  are  related  to  screen  out¬ 
put.  These  functions  are:  clrscr( ), 
cputs( ),  gotoxy( ),  textbackground( ), 
and  textcolor(). 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  92.) 

Vote  tor  your  favorite  feature/article. 

Circle  Reader  Service  No.  3. 
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Building  an  Efficient 

Help  System 

Knowing  how  help  files  and  the  hypertext  engine 
interact  is  essential 


Leo  Notenboom  and  Michael  Vose 


On-screen  documentation  has 
become  ubiquitous  in  con¬ 
temporary  software,  from  busi¬ 
ness  applications  to  program¬ 
ming  tools.  Like  anything 
else,  the  quality  and  usefulness  of  this 
aid  varies  from  package  to  package. 
The  technology  of  hypertext,  however, 
promises  to  solve  many  of  the  organiza¬ 
tional  and  speed  problems  currently 
found  in  some  on-screen  help  systems. 

On-screen  documentation  is  useless 
unless  it  makes  finding  information  easy, 
provides  that  information  quickly,  and 
delivers  all  the  information  users  need. 
Some  kinds  of  information  —  command 
references,  API  references,  example 
code,  and  the  like  —  lend  themselves 
more  readily  to  on-screen  help  than 
do  others.  Hypertext  can  equip  a  help- 
system  programmer  with  the  tools 
needed  to  create  on-screen  documen¬ 
tation  that  is  fast,  easy  to  navigate  (even 
through  voluminous  text),  and  compre¬ 
hensive.  Hypertext  isn’t  magic;  it’s  actu¬ 
ally  quite  a  simple  idea.  In  a  help  sys¬ 
tem,  it’s  the  association  of  a  programmed 
action  with  an  area  of  viewed  text. 

This  article  explains  how  help  files 
and  the  hypertext  help  engine  of  a 
typical  hypertext-based  on-screen  help 
system  fit  together,  using  the  Microsoft 
Advisor  as  the  example.  With  an  under¬ 


let),  a  software  development  engineer 
and  manager  for  Microsoft,  is  the  de¬ 
signer  of  the  Microsoft  Advisor.  Michael 
is  a  coeditor  of  OS/2  Report  newsletter. 
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standing  of  how  this  technology  works, 
you  can  use  it  and  associated  tools  to 
add  on-screen  documentation  to  your 
libraries  and  programs  or  access  on¬ 
screen  help  provided  by  any  other  pro¬ 
gram  that  uses  similar  technologies. 

Hypertext  in  Context 

As  already  defined,  hypertext  is  simply 
the  association  of  an  action  with  an 
area  on  the  screen.  Thus  a  “button,” 
which  is  just  a  visible  region  on  a  screen, 
might  have  associated  with  it  the  action 
of  looking  up  help  text  on  a  predefined 
string  of  characters.  When  a  user  se¬ 


lects  the  button,  the  associated  help 
text  is  located  and  displayed. 

In  practice,  this  movement  between 
help  screens  via  buttons  or  an  action 
such  as  pressing  a  help  key  is  generally 
referred  to  as  a  link  or  cross-reference. 
There  are  two  primary  types  of  links: 

•  Implicit  Links  When  a  user  selects 
a  word  on  the  screen  and  requests  help 
by  pressing  FI  or  clicking  a  mouse,  the 
application  looks  up  help  on  that  word 
and  displays  the  resulting  help  text. 
Within  the  help  text  itself,  a  user  can 
place  the  cursor  on  any  word  within 
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( continued  from  page  40) 
the  help  text  and  press  FI  again  to  get 
further  help.  This  second  lookup  op¬ 
eration  is  made  possible  by  implicit  links. 
•  Explicit  Links  Encoded  by  the  help 
file  author,  explicit  links  specify  a  re¬ 
gion  within  the  text  (often  represented 
by  a  button)  and  the  help  text  to  which 
that  region  refers.  For  example,  a  help 
screen  may  present  an  area  labeled 
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<Example  Code>  that  was  defined  by 
the  help  author  to  be  linked  to  the 
phrase  abs. example.  When  the  user  se¬ 
lects  that  button,  the  application  looks 
up  the  phrase  abs.example,  and  dis¬ 
plays  the  resulting  help  screen. 

Explicit  links  come  in  two  flavors  — 
normal  and  local.  Normal  explicit  links 
operate  exactly  as  in  the  previous  ex¬ 


ample.  They  differ  from  local  explicit 
links  in  that  they  can  reference  differ¬ 
ent  help  files  from  the  one  actually 
containing  the  button.  Local  explicit 
links,  on  the  other  hand,  are  restricted 
to  linking  to  help  text  present  in  the 
same  help  file  as  that  containing  the 
button.  As  we’ll  see  later,  local  links 
have  advantages  and  disadvantages. 

To  implement  these  hypertext  links 


Turning  the  Tables 


The  tables  that  connect  the  different 
parts  of  a  help  database  are  created 
by  the  HELPMAKE  utility  and  are 
stored  along  with  a  header  at  the  be¬ 
ginning  of  every  help  file  (see  Figure 
3).  Every  help  file  has  the  following 
structure:  A  header  that  contains  the 
identifier  and  version  of  the  file,  loca¬ 
tion  of  the  subsequent  tables,  and 
some  additional  information;  the  topic 
map,  an  array  of  file  positions  of  each 
of  the  topics  in  the  help  file,  plus  an 
extra  entry  to  mark  the  end  of  the  file; 
the  context  map,  which  matches  a 
context  number  to  a  topic  number; 
the  context  string  table,  which  de¬ 
fines  the  strings  when  help  exists  and 
determines  their  context  numbers;  op¬ 
tional  keyword  compression  table, 
which  contains  the  keywords  removed 
from  the  topic  text  during  compres¬ 
sion;  an  optional  Huffman  compres¬ 
sion  table,  which  contains  the  decode 
tree  created  during  compression;  and 
topic  text. 

Topic  text  itself  contains  more  than 
just  the  displayed  text — it  also  car¬ 
ries  control,  color,  and  cross-refer¬ 
ence  data.  The  control  information 
includes  a  number  representing  the 
size  of  the  uncompressed  topic  in 
bytes.  Each  subsequent  line  of  text 
consists  of  the  ASCII  text  to  be  dis¬ 
played;  attribute/color  information, 
such  as  bold  or  underline,  that  an 
application  can  then  map  to  colors  if 
desired;  and  explicit  link  information, 
which  specifies  the  areas  within  the 
line  that  are  hot  spots,  and  the  string 
local  context  number  with  which  the 
explicit  links  cross-reference. 

When  a  help  file  is  compiled,  the 
HELPMAKE  utility  makes  three  com¬ 
pression  passes  on  the  topic  text.  Run- 
length,  keyword,  and  Huffman  com¬ 
pression  are  each  applied  to  the  text 
in  turn. 

Run-length  encoding  is  the  replace¬ 
ment  of  runs  of  characters  (three  or 
more  of  the  same  character)  with  a 


special  token  signifying  the  run,  the 
character  that  is  to  be  repeated,  and 
the  number  of  times  it  is  to  be  re¬ 
peated.  Encoded  this  way,  any  run 
of  4  to  255  characters  can  be  replaced 
by  3- 

Keyword  encoding  is  the  replace¬ 
ment  of  commonly  occurring  words 
or  phrases  with  a  2-byte  token.  The 
text  is  analyzed  for  the  words  occur¬ 
ring  most  frequently,  and  the  most 
frequent  words  are  collected  into  a 
key-phrase  table.  Occurrences  of  these 
words  in  the  text  are  then  replaced 
by  a  token  whose  value  is  an  index 
into  this  key-phrase  table.  For  exam¬ 
ple  the  word  "the”  is  used  frequently 
in  normal  English  text.  If  you  remove 
this  word  and  replace  it  with  a  2-byte 
token,  the  savings  of  1  byte  per  oc¬ 
currence  adds  up  quickly. 

Huffman  encoding  is  simply  a  bit-for- 
byte  replacement.  The  text  is  again 


analyzed  for  frequently  occurring 
bytes,  and  the  most  frequent  bytes 
are  replaced  with  a  shorter  bit  pat¬ 
tern.  For  example,  if  you  can  replace 
1000  8-bit  bytes  with  a  2-bit  pattern, 
you  save  6 000  bits,  or  750  bytes.  To 
restore  a  Huffman-compressed  file  re¬ 
quires  a  table  that  a  decompression 
routine  can  use  to  restore  the  2-bit 
pattern  to  its  original  8-bit  value.  The 
side  effect  of  Huffman  compression 
is  that  less  frequently  occurring  bytes 
often  get  replaced  by  a  bit  pattern 
longer  than  8  bits.  However,  the  net 
gain  due  to  the  frequency  of  the 
smaller  bit  patterns  quickly  outweighs 
the  loss  due  to  the  growth  of  the 
longer  ones. 

Microsoft  offers  a  “Programmer’s 
Workbench  Toolkit”  that  contains  the 
Advisor  API  Library  and  Documenta¬ 
tion.  Call  1-800-426-9400  to  obtain  de¬ 
tails.  —  L.N.,M.V. 


Header 

Identifier,  version  number,  location  of  tables  information 

Topic  map 

An  array  of  file  positions  of  topics  plus  an  entry  to  mark  the  end  of  the  file 

Context  map 

A  table  to  match  a  context  number  to  a  topic  number 

Context  string  table 

A  table  that  defines  the  strings  for  which  it  exists 

Keyword  compression  table 

Contains  the  key  words  removed  from  the  text  during  compression 

Huffman  compression  table 

Contains  the  decode  tree  created  during  compression 

Topic  text 

Figure  3:  The  components  of  a  help  database 
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(continued  from  page  42) 
to  assist  users  in  navigating  help  text, 
a  help-system  author  can  benefit  from 
understanding  the  data  structure  known 
as  a  help  database. 

Help  Files  and  Databases 

To  make  on-line  help  fast  requires  a 
way  to  quickly  map  individual  words 
or  phrases  to  some  textual  or  graphic 
information.  Associating  the  explana¬ 
tory  text  or  graphic  information  with 
more  than  one  word  or  phrase  may 
also  be  necessary.  The  help  file  con¬ 
tains  the  information  that  allows  help 
retrieval  to  be  both  fast  and  flexible.  A 
help  file  comprises  one  or  more  help 
databases.  A  help  database  contains  the 
words  that  help  is  available  for  and  the 
information  associated  with  those  words. 

The  words  and  phrases  for  which 
help  can  be  requested,  called  “context 
strings,”  and  their  associated  help  text, 
referred  to  as  “topic  text,”  are  authored 
using  a  text  editor  or  word  processor 
and  are  compiled  into  help  files  using 
the  HELPMAKE  utility.  HELPMAKE  cre¬ 
ates  the  links  between  the  context  strings 
and  topic  text  and  also  compresses  the 
topic  text.  HELPMAKE  can  also  decom¬ 
press,  or  “uncompile,”  an  entire  help 
file  into  its  original,  editable  form.  (See 
the  accompanying  text  box,  “Turning 
the  Tables”  for  information  about  the 
structure  of  a  help  database  and  the 
techniques  used  to  compress  it.) 

During  help-file  compilation,  the  ac¬ 
tual  connections  between  context  strings 
and  topic  text  are  made  through  a  se¬ 
ries  of  three  lookup  tables  used  by  the 
Advisor  when  a  help  request  is  made 
(see  Figure  1).  The  context  strings  sup¬ 
ported  by  the  help  file  are  stored  as  a 
simple  array  in  the  first  table,  and  the 
help  text  contained  in  the  file  can  also 
be  viewed  as  an  array  of  topics.  The 
job  at  lookup  time,  then,  is  to  map  the 
given  context  string  to  the  correct  piece 


of  topic  text  to  which  it  refers. 

The  first  table,  the  context-string  ta¬ 
ble,  is  just  a  simple  array  of  context 
strings.  The  index  of  a  string  in  this 
table  becomes  its  “context  number.” 
The  second  table  maps  the  context  num¬ 
ber  to  its  corresponding  topic.  The  en¬ 
try  indexed  by  the  context  number  in 
this  “context  map”  contains  the  corre¬ 
sponding  “topic  number.”  The  last  ta¬ 
ble  maps  the  topic  number  to  the  ac¬ 
tual  position  within  the  help  file  that 
contains  the  topic  text.  From  this  last 
table,  the  compressed  size  of  the  topic 
can  be  calculated  (the  difference  be¬ 
tween  two  successive  file  offsets;  this 
number  can  then  be  used  for  memory 
allocation)  along  with  the  predicted 
end  of  the  help  file  (the  file  offset  of  the 
last-plus-one  help  topic  used  for  con¬ 
catenated  help  files,  described  later). 

The  Advisor  optimizes  this  lookup 
process  by  loading  the  mapping  tables 
(and  the  decompression  tables  de¬ 
scribed  in  the  text  box)  into  memory 
once,  wherever  possible,  and  leaving 
them  there  until  the  application  instructs 
it  to  discard  them. 

Because  a  context  string  is  trans¬ 
formed  into  a  number  representing  its 
position  in  the  context-string  table,  an 
application  can  discard  this  string  once 
the  transformation  has  been  made.  In 
fact,  this  context  number  is  returned 
to  the  application  in  a  form  that  also 
identifies  the  specific  help  database  to 
which  it  applies  when  more  than  one 
help  database  is  being  used.  This  con¬ 
text  number  can  be  used  to  map  back¬ 
ward  if  necessary  to  determine  what 
string  was  originally  looked  up  and 
what  database  it  came  from. 

One  special  type  of  context  number 
provided  by  the  Advisor  for  the  appli¬ 
cation  is  called  a  “local  context  num¬ 
ber,”  or  simply  “local  context.”  Local 
contexts  are  not  associated  with  a  con- 
(continued  on  page  47) 
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Figure  1:  The  look-up  tables  for  mapping  context  strings  to  topic  text.  Note 
that  three  related  context  strings  can  map  to  the  same  topic  text 
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(continued  from  page  44) 
text  string;  rather,  they  are  directly  en¬ 
coded  with  the  desired  topic  number. 

Local  contexts  are  identified  by  the 
help-file  autnor  at  the  time  the  file  is 
written  and  are  compiled  specially  by 
the  HELPMAKE  utility.  Explicit  links 
often  use  local  contexts  instead  of  nor¬ 
mal  contexts  because  the  2-byte  topic 
number  with  which  a  local  context  is 
encoded  is  much  smaller  than  the  string 
normally  coded  into  an  explicit  link. 
The  only  restriction  on  local  contexts 
is  that  explicit  links  that  reference  local 
contexts  must  have  the  topic  text  asso¬ 
ciated  with  each  local  context  present 
in  the  same  help  database. 

Multiple  help  databases  can  be  con¬ 
catenated  to  form  a  single  help  file  for 
a  given  application.  When  a  help  file 
is  opened,  the  hypertext  system,  using 
the  three  tables  previously  mentioned, 
examines  what  should  be  the  end  of 
the  database  in  that  file.  If  instead  it 
finds  the  beginning  of  another  help 
database,  it  opens  that  as  well  and  re¬ 
peats  the  end-of-database  examination. 
By  repeating  this  operation,  multiple 
help  data  files  can  be  combined  simply 
by  using  the  MS-DOS  Copy  command, 
and  even  applications  that  support  only 


one  help  file  can  be  “fooled”  into  using 
several  help  files  disguised  as  one. 

The  Help  Engine 

The  help  engine  is  nothing  more  than 
a  data  retrieval  tool.  The  engine  takes 
a  string  and  maps  it  to  the  appropriate 
topic  text.  It  simply  searches  the  data 
structure  that  is  a  help  file  and  makes 
the  desired  information  available  to  an 
application. 

The  Advisor  help  engine  knows  very 
little  about  its  environment  —  except 
for  the  OS/2  version,  which  does  make 
some  assumptions  about  memory  man¬ 
agement  and  file  I/O.  The  MS-DOS  ver¬ 
sion  of  the  help  engine  relies  on  the 
application  to  handle  memory  man¬ 
agement  and  file  I/O. 

The  engine  enforces  the  help-file  for¬ 
mat  and  its  data  structures  but  leaves 
determinations  about  how  to  use  re¬ 
trieved  data  to  an  application.  The  help 
engine  has  to  be  told  what  help  files 
to  deal  with,  and  an  application  can 
specify  multiple  help  files. 

In  addition  to  routines  to  query  for 
and  retrieve  help  text,  the  help  engine 
provides  routines  that  the  application 
must  use  to  perform  decompression 
after  the  topic  text  has  been  located. 


The  help  engine  also  has  routines  that 
an  application  can  query  to  discover  if 
a  topic  has  cross-references  or  to  read 
only  the  color  or  control  information 
in  a  topic. 

The  help  engine  uses  application- 
provided  handles  for  memory  manage¬ 
ment  and  for  file  I/O  and  can  therefore 
deal  with  many  different  memory  and 
I/O  schemes. 

The  Application's  Job 

The  application  program  that  uses  the 
help  system  must  perform  several  im¬ 
portant  functions  of  its  own  (see  Figure 
2),  including  providing  the  user  inter¬ 
face  to  the  help  system  and  supplying 
the  interface  to  its  environment. 

The  most  important  of  these  func¬ 
tions  is  the  user  interface  for  displaying 
help  information  and  interacting  with 
the  user  and  the  help  screens.  The  ap¬ 
plication  defines  what  text  gets  parsed 
into  a  context  string  when  a  help  re¬ 
quest  is  made,  and  it  then  passes  that 
string  to  the  help  engine,  which  mounts 
the  search  for  that  string.  For  example, 
if  the  cursor  resides  on  a  menu  or  an 
open  dialog  box,  the  application’s  parser 
must  be  able  to  decide  if  help  is  appro¬ 
priate  for  that  object.  The  application 
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Figure  2:  The  help  engine’s  place  within  the  hierarchy  of  an  application 


also  interprets  all  control  and  cross- 
reference  commands,  as  well  as  han¬ 
dling  multiple  help  files.  For  example, 
if  an  application  has  five  open  help 
files  and  a  user  asks  for  help  on  a 
string,  the  application  must  use  the  Ad¬ 
visor  to  query  each  help  file  in  turn  to 
find  the  desired  string  match. 

The  application  must  also  handle  fail¬ 
ures  and  be  able  to  display  a  message 
or  beep  the  speaker  when  no  help  is 
available.  Conversely,  the  application 
must>  determine  what  action  to  take  if 
there  is  help  on  the  same  context  string 
in  more  than  one  help  database. 

In  addition,  the  application  must  pro¬ 
cess  control  information.  The  Advisor 
offers  a  history  function  that  lets  a  user 
move  backward  through  the  20  most 
recently  viewed  help  screens.  Because 
the  context  numbers  returned  by  the 
hypertext  system  uniquely  identify  each 
help  database  and  context  string,  the 
history  function  simply  keeps  a  circular 
queue  of  the  20  most  recently  accessed 
context  numbers.  The  application  must 
provide  a  keystroke  or  clickable  screen 
button  to  engage  this  history  function. 
The  application  parses  a  history  request 
and  then  calls  the  help  engine’s  history 
function  to  retrieve  and  display  previ¬ 
ous  help  screens. 

Under  MS-DOS,  the  application  must 
also  provide  the  interface  between  the 
Advisor  and  its  environment,  including 
memory  management  and  all  direct  file 
I/O  support. 


Taking  Advantage 

The  hypertext  technology  described 
here  can  be  leveraged  in  two  ways:  By 
supplying  supplemental  help  files  for 
use  by  applications  using  the  hypertext 
system  and  by  incorporating  the  sys¬ 
tem  into  new  applications.  Supplemen¬ 
tal  help  files  offer  the  ability  to  custom¬ 
ize  and  expand  on-line  help  to  fill  a 
variety  of  needs.  New  applications  be¬ 
ing  written  can  benefit  from  the  en¬ 
forced  consistency  in  file  format  in  that 
all  help  files  can  be  used  by  any  appli¬ 
cation  that  also  uses  the  Advisor.  This 
technology  also  provides  a  simple  frame¬ 
work  for  implementing  hypertext  in 
any  application  and  provides  a  pain¬ 
less  way  to  compress  text  without  any 
significant  access-speed  penalties. 

Searching  for  information  was  the 
primary  application  of  computers  from 
the  beginning.  Today’s  hypertext-based 
on-screen  help  systems  can  begin  to 
make  the  information  that  people  need 
the  most  more  readily  accessible  than 
ever  before. 
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Writing  a  base  class  is  the  key  to  programming  with 
an  object-oriented  language 


Kevin  Weeks 


A  few  months  ago  I  wrote  a 
database  program  for  a  cli¬ 
ent  and  found  myself  ma¬ 
nipulating  multiple  files  in 
multiple  directories  on  mul¬ 
tiple  drives  using  multiple  devices.  Al¬ 
though  I’d  run  into  this  sort  of  chal¬ 
lenge  many  times  before,  this  particu¬ 
lar  program  involved  some  variations 
on  the  theme  that  didn’t  quite  fit  my 
previous  work.  Nevertheless,  I  went 
ahead  and  wrote  the  program  in  C, 
rewriting  file  access/handling  routines 
I’d  developed  before. 

As  an  afterthought,  I  decided  to  use 
C++  to  design  a  basic  object  or  objects 
that  would  at  least  minimize  some  of 
these  problems  in  the  future.  Although 
there  are  a  number  of  examples  of 
file-type  objects  around,  I  haven’t  run 
across  any  that  are  capable  of  taking  a 
partial  file  specification,  such  as  TEMP- 
FILE. DAT,  and  completing  it  by  adding 
the  drive  and  path  components.  Fail¬ 
ure  to  do  so  can  result  in  unpredictable 
references.  For  instance,  A:TEMP- 
FILE.DAT  obviously  refers  to  a  file  on 
drive  A  in  the  current  subdirectory.  But 
what  is  the  current  subdirectory?  Is  it 
what  the  user  intended?  I  came  to  the 
conclusion  that  a  file  object  starts  too 
high  up  the  tree.  The  first  step  is  creat¬ 
ing  the  file  specification,  the  second  is 
handling  the  file. 


Kevin  had  been  coding  in  C  for  six 
years.  He  is  working  for  Computational 
Systems,  a  vibration  analysis  company 
in  Knoxville,  Term.  Kevin  can  be 
reached  at  508  Valparaiso  Rd.,  Oak 
Ridge,  m 378J0. 


Creating  a  good  base  class  is  like 
sculpting,  start  with  a  block  of  marble 
and  then  chip  away  everything  that 
doesn’t  look  like  a  statue.  This  took  a 
while  but  the  result  was  class  File_Spec. 

Fi/e_Spec 

Although  the  code  that  defines  the 
File_Spec  class  is  large,  it  contains  noth¬ 
ing  that  isn’t  specific  to  the  creation 
and  maintenance  of  a  DOS/Unix-style 
file  specification.  Each  component  can 
be  retrieved  or  modified,  an  incom¬ 
plete  file  specification  can  be  completed, 
and  the  object’s  current  status  is  main¬ 
tained  and  made  available  to  clients. 
Of  course,  not  all  the  methods  have  to 
be  included  in  a  given  application.  I 
have  provided  a  single  File_Spec  mod¬ 
ule  (FILESPEC.CPP,  Listing  Two.  page 
96)  for  simplicity’s  sake.  If  the  individ¬ 
ual  methods  are  compiled  separately 
and  placed  in  a  library,  however,  then 


only  those  methods  actually  used  by  a 
program  will  be  included. 

If  you  look  at  Listing  One  (FILE- 
SPEC.HPP,  page  96)  you'll  see  first  that 
I  named  the  fields  (attributes  in  OOP- 
speak)  device ,  prefix,  name,  and  suf¬ 
fix.  The  idea  behind  these  labels  is  to 
provide  some  degree  of  abstraction  in 
case  the  object  is  ported  to  a  system 
where  the  device  doesn’t  have  to  be  a 
disk  drive,  or  the  prefix  a  DOS/Unix- 
style  path.  (For  instance,  I’ve  recently 
been  coding  on  a  Prime  Series  50  ma¬ 
chine  where  the  device  names  are  logi¬ 
cal  drives  enclosed  in  <...>.)  Next 
you  should  notice  that  the  device,  name, 
and  suffix  are  implemented  as  arrays. 

C++  books  are  big  on  the  new  op¬ 
erator  and  seem  to  use  it  at  the  drop 
of  a  class  bat.  I’ve  gotten  burned  by 
poor  malloct )  implementations  a  time 
or  two,  where  memory  ended  up  so 
fragmented  that  mallocf  )  lost  all  con- 
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(continued  from  page  50) 
ception  of  order.  Because  there  is  no 
specification  for  memory  management 
in  C++,  it  seems  wise  to  limit  the  poten¬ 
tial  for  such  problems  when  objects  are 
potentially  volatile. 

device,  name,  and  suffix  are  all  rela¬ 
tively  short;  any  waste  space  is  mini¬ 
mized,  reducing  both  the  code  and  the 
time  required  to  change  them  with  the 
change_XXXX( )  methods.  The  excep¬ 
tions  are  prefix  (the  path)  and  request. 
Because  these  may  vary  in  length  from 

Creating  a  good  base 
class  is  like  sculpting, 
start  with  a  block  of 
marble  and  then  chip 
away  everything  that 
doesn’t  look  like  a  statue 


one  character  to  as  many  as  78  charac¬ 
ters,  it  seemed  more  reasonable  to  swal¬ 
low  the  overhead  and  reduce  RAM  re¬ 
quirements  in  their  case.  If  you’re  won¬ 
dering  what  the  request  attribute  ac¬ 
complishes,  it  forces  me  to  look  and 
not  touch. 

All  strings  that  have  to  be  returned 
are  returned  as  a  pointer  to  request, 
which  is  allocated  as  needed.  Obvi¬ 
ously  I  could  reduce  code  and  execu¬ 
tion  overhead  even  more  if,  instead  of 
copying  the  device,  name,  and  so  on 
to  another  string  and  returning  it,  I 
simply  returned  pointers  to  the  respec¬ 
tive  attributes.  I  must  confess,  how¬ 
ever,  that  I  might  be  tempted  at  some 
point  to  modify  the  attributes  directly 
by  using  an  alias,  instead  of  playing 
by  the  rules.  What  can  I  say?  I’m  weak. 
Because  I  can’t  depend  on  self-disci¬ 
pline,  I’m  better  off  returning  some¬ 
thing  that  can’t  modify  the  originals. 
Besides,  I  have  to  create  another  string 
to  return  the  complete  file  specification 
to  clients  anyway.  Why  not  let  the  caller 
pass  a  string  pointer  for  the  method  to 
fill?  Two  reason:  First,  without  bounds 
checking  there’s  no  way  to  be  sure  the 
passed  string  is  big  enough,  and  sec¬ 
ond,  this  adds  to  the  complexity  of 
using  the  class  methods,  without  really 
buying  anything. 

Making  If 

The  first  four  methods  in  Listing  Two 
are  the  constructors  and  the  destructor. 
Constructors  constitute  a  built-in  setup 
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or  initialization  routine  for  an  object. 
All  you  have  to  do  is  declare  the  object, 
and  the  compiler  automatically  calls 
the  appropriate  constructor.  C++  also 
allows  you  to  have  more  than  one  con- 
stmctor  (or  method)  with  the  same  name 
(hence  multiple  constructors).  Depend¬ 
ing  on  the  number  and  type  of  parame¬ 
ters  passed,  the  compiler  determines 
just  which  method  you  need.  This  is 
called  “overloading”  and  is  an  exam¬ 
ple  of  polymorphism.  More  on  this  later. 

There  is  a  drawback  to  constructors: 
They  always  return  a  reference  to  the 
object  created.  If  problems  occurred, 
you’ll  have  a  malformed  object.  There’s 
no  such  thing  as  an  error  or  even  a 
NULL  return.  Consequently,  you  should 
check  the  status  (see  status( )  later) 
prior  to  using  the  object  (see  Class  File 
for  examples)  and  check  errno  for  mem¬ 
ory  allocation  errors  following  the  ob¬ 
ject’s  creation.  This  necessity  is  irri¬ 
tating  and  unrefined,  but  we’re  stuck 
with  it.  On  the  positive  side,  because 
both  of  the  objects  presented  here  are 
aware  of  their  own  status,  they  won’t 
misbehave  if  asked  to  do  the  impos¬ 
sible  —  they’ll  simply  report  an  error 
back  to  the  caller.  Ideally,  incorporat¬ 
ing  a  reference  to  a  separate  Error  class 
would  enable  you  to  use  the  objects 
without  worries. 

The  first  constructor  simply  creates 
an  empty  object  that  can  later  be  filled 
by  using  the  other  class  methods.  The 
second  constructor  accepts  a  reference 
(pointer)  to  another  File_Spec  object 
and  makes  a  copy  of  it.  These  two  are 
pretty  straightforward.  The  constructor 
that  accepts  a  character  string,  how¬ 
ever,  isn’t  quite  so  obvious. 

Following  initialization  of  the  vari¬ 
ous  attributes,  the  ( char*string )  con¬ 
structor  uses  a  finite  state  machine  to 
parse  the  string  passed  to  it.  This  string 
may  consist  of  any  or  all  combinations 
of  a  device,  prefix  (path),  name,  and / 
or  suffix  (extension.)  The  prefix  may 
be  a  full  or  partial  path,  but  must  end 
with  a  backslash  to  be  properly  recog¬ 
nized.  Once  the  string  has  been  parsed, 
checks  are  made  both  to  see  which 
components  are  missing  and  for  valid 
file  characters. 

You  indicate  to  C++  that  a  method 
is  a  destructor  by  prepending  a  tilde 
(~)  to  the  class  name.  This  message  is 
automatically  passed  to  an  object  when¬ 
ever  the  object  passes  out  of  scope  and 
is  meant  to  perform  any  necessary 
cleanup.  In  the  case  of  File_Spec  this 
means  deallocating  any  memory  as¬ 
signed  to  prefix  or  request. 

The  Rest  of  FHe_Spec 

Status( )  returns  the  condition  of  the 
file  spec.  A  non-zero  return  value  indi- 
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cates  a  problem  of  some  sort.  Exactly 
what  the  problem  is  can  be  determined 
by  examining  the  value.  The  low  nib¬ 
ble  of  the  low  byte  of  the  status  word 
indicates  whether  or  not  the  spec  is 
complete;  the  high  nibble  of  the  low 
byte  of  the  status  word  indicates  inva¬ 
lid  file  characters.  Next  is,  in  my  opin¬ 
ion,  one  of  the  most  exciting  aspect  of 
object-oriented  programming  —  opera¬ 
tor  overloading  or  polymorphism. 

C  allows  you  to  create  new  types 
with  the  typedef  operator.  What  it 
doesn’t  do  is  redefine  operators  to  han¬ 
dle  the  new  types.  With  C++,  you  can. 
This  provides  genuine  language  exten¬ 
sibility,  which  is  one  of  the  things  that 
gets  Forth  programmers  so  excited  (even 
if  they  can’t  figure  out  what  they  did  a 
week  later).  Most  of  the  C  operators 
can  be  overloaded,  and  early  versions 
of  File_Spec  got  rather  carried  away 
with  this  capability.  By  dint  of  much 
pruning,  we  are  left  with  the  equal  sign 
(=).  In  this  incarnation,  File_Spec= 
doesn’t  even  do  much,  it  just  calls 
c°py( ),  a  private  method.  Operator  over¬ 
loading  is  a  powerful  capability,  and 
everyone  will  tell  you  it  can  be  abused. 
They’re  right,  but  go  ahead  and  abuse. 
Get  it  out  of  your  system.  I  did.  Now 
back  to  earth. 

The  get_XXXX(  )  and  cbange_XXXX 
( )  methods  should  be  readily  under¬ 
standable.  Because  both,  request  and 
prefix ,  have  lengths  associated  with 
them,  they  are  only  reallocated  if  they 
aren’t  long  enough.  (I  know.  If  I’m 
concerned  enough  about  storage  to 
make  them  dynamic  to  begin  with,  why 
don’t  I  shorten  them  when  possible. 
What  can  I  say?  GIGO  is  one  thing,  but 
someone  has  to  pick  up  the  garbage.) 
The  change  methods  also  keep  the  con¬ 
dition  flags  up  to  date.  The  read_only( ) 
method  is  to  prevent  the  change  meth¬ 
ods  from  working  at  inconvenient  times, 
such  as  when  the  file  is  open. 
Check_prefix( )  determines  whether  or 
not  a  path  is  complete.  It  does  this  by 
checking  for  a  backslash  as  the  first 
character.  If  there  is  no  backslash,  the 
path  is  relative  to  the  current  working 
directory.  Next  it  looks  for  a  period  (.) 
followed  by  backslashes  or  another  pe¬ 
riod.  This  refers  either  to  the  current 
directory  or  to  the  parent  directory. 
The  last  step  is  to  make  sure  the  prefix 
ends  with  a  backslash. 

One  of  the  principles  of  object-ori¬ 
ented  programming  is  late  binding.  With¬ 
out  getting  into  details  or  specifics,  this 
means  that  decisions  concerning  which 
functions  to  call  or  what  parameters  to 
pass  can  be  delayed  until  run  time, 
thus  making  a  virtue  of  procrastina¬ 
tion.  The  advantage  is  an  increase  in 
the  flexibility  of  the  program.  In  keep¬ 


ing  with  this  principle,  File_Spec  ob¬ 
jects  do  not  attempt  to  automatically 
complete  themselves  until  specifically 
requested  to  do  so.  This  means  that  a 
partial  File_Spec  can  be  instantiated, 
passed  around,  copied,  and  modified 
without  worrying  about  the  validity  or 
presence  of  a  drive  or  path  until  those 
elements  are  necessary. 

Complete( )  attempts  to  resolve  an 

C  allows  you  to  create 
new  types  with  the 
typedef  operator.  What 
it  doesn ’t  do  is  redefine 
operators  to  handle  the 
new  types.  With  C++, 
you  can 


incomplete  file  specification.  If  a  name 
was  not  specified  or  if  any  of  the  attrib¬ 
utes  have  invalid  characters,  complete( ) 
immediately  returns  a  FALSE.  If  com- 
plete( )  passes  those  tests,  it  checks  for 
a  device  specification  and,  if  one  isn’t 
found,  calls  DOS  for  the  current  drive 
using  ll_get_drive( ).  I  wrote  the  assembly 
language  module  (LOWIO.ASM,  Listing 
Five,  page  111)  to  provide  three  func¬ 
tions.  First,  I  needed  a  routine  for  get¬ 
ting  just  the  current  drive  (without  the 
current  working  directory).  Second,  I 
needed  to  be  able  to  get  the  current 
working  directory  of  another  drive.  Third, 
I  wanted  a  routine  to  tmncate  a  file  at  a 
position  other  than  its  beginning. 

The  last  step  is  to  check  for  and,  if 
necessary,  complete  the  prefix.  If  the 
prefix  is  incomplete  then  parse _prefix( ) 
is  called.  Space  is  allocated  for  a  path 
name,  and  then  DOS  is  called  for  the 
current  working  directory  for  the  speci¬ 
fied  device  via  ll_get_cwd( ).  Again,  as 
in  the  constructor,  a  finite  state  ma¬ 
chine  is  used  to  build  the  prefix.  Rela¬ 
tive  references  (.  A  and  A)  are  treated 
as  DOS  would.  This  routine,  though, 
is  a  bit  smarter,  or  takes  a  bit  more  for 
granted,  than  DOS.  Multiple  backslashes 
are  ignored.  For  instance,  \\  subdir\  is 
treated  as  \  subdir\  .  More  than  two 
periods  in  a  row  are  treated  as  two 
periods  in  a  row:  .  .  A  subdir  \  =  .  A 
subdir  \  .  And  two  or  more  periods  in 
a  row  without  a  backslash  are  treated 
as  two  periods  with  a  backslash:  .  .  sub¬ 
dir  =  .  A  subdir.  Obviously  these  fixes 


are  not  guaranteed  to  produce  what 
you  and/or  your  user  had  in  mind,  but 
the  chance  of  possible  harm  seems  mini¬ 
mal. 

Class  File 

Class  File  (see  FILE.HPP,  Listing  Three 
page  106  and  FILE.CPP,  Listing  Four 
page  108)  is  the  first  derived  class  of 
File_Spec.  Its  purpose  is  to  bundle  the 
basic  file  operations  such  as  create, 
read,  rename,  and  so  on  into  a  single 
object.  File  is  defined  as  a  public  de¬ 
scendant  of  File__Spec  so  that  all  of  the 
File_Spec  methods  are  available  to  File 
and  its  clients. 

The  first  File  constructor  is  defined 
like  this: 

File::File(char  “name,  int  open_flag 
=  FALSE): (char  "name) 

The  phrase  int  open_flag  =  FALSE  is 
one  of  two  points  worthy  of  comment. 
This  phrase  defines  a  pass  parameter, 
open_flag,  and  states  that  if  none  is 
provided  to  default  to  FALSE.  Default 
parameters  are  sexy.  They’re  a  kind  of 
“just  give  me  the  usual”  to  the  com¬ 
piler.  The  other  point  worth  noting  here 
is  the  phrase  .  .  .  .  (char  *name).  This 
is  a  call  to  the  parent’s  class  construc¬ 
tor.  As  you  can  see,  the  File  class  doesn’t 
use  the  name  parameter  itself  but  in¬ 
stead  passes  it  on  to  its  parent,  File_Spec. 
Although  a  child  constructor  does  not 
automatically  call  its  parent  construc¬ 
tor,  the  parent  destructor  is  automati¬ 
cally  called. 

Next,  exists( )  reports  to  its  client  on 
the  existence  of  the  file  specified.  In 
addition  to  reporting  to  clients,  the 
exists( /method  is  used  by  the  File  meth¬ 
ods  open( )  and  create( ).  With  these 
two  we  come  to  a  somewhat  peculiar 
function  call: 

::close(tmp_handle); 

C++  defines  an  “overload”  directive 
that  is  intended  to  allow  the  programmer 
to  use  the  same  name  for  multiple  func¬ 
tions  and  which,  according  to  the  books, 
should  work  like  this: 

overload  foo; 

int  foo(char  *); 

int  foo(unsigned  int); 

Following  this  declaration,  you  should 
be  able  to  issue  calls  to  foo(.  .  .)  and 
depending  on  the  type  and  number  of 
parameters  passed,  the  compiler  will  se¬ 
lect  the  appropriate  function.  Unfortu¬ 
nately,  there  is  a  bug  in  Zortech’s  1.0 
implementation  and  explicit  overload¬ 
ing  doesn’t  work  properly.  When  I  spoke 
to  Zortech’s  tech  support  people  about 
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this  they  recommended  using  the  ::  op¬ 
erator  as  a  workaround.  This  operator 
is  a  scope  qualifier  (notice  its  use  in  all 
the  method  definitions  to  restrict  their 
scope  to  their  class).  When  used  with¬ 
out  a  class  name  it  is  a  global  reference 
and  enables  me  to  access  the  standard 
C  close( )  function.  I  also  use  the  ::  op¬ 
erator  to  access  the  library  versions  of 
open( ),  read( ),  and  rename( ). 

As  for  read( )  and  write( ),  under 
DOS,  Unix,  and  many  other  operating 
systems,  the  file  pointer  is  automati¬ 
cally  advanced  whenever  a  read  or  write 
operation  is  performed.  While  this  is 
convenient  in  the  case  of  a  sequential 
file,  most  of  the  time  it  constitutes  an 
undesired  side  effect  (certainly  when 
you’re  writing  a  random  access  data¬ 
base  program).  For  this  reason  I  added 
an  auto-advance  file  attribute,  which 
is  set  when  the  object  is  opened  or 
created  by  ORing  F_ADVANCE  with 
the  other  file  attributes.  Consequently, 
if  a  File  is  opened  or  created  with  the 
F_ADVANCE  flag  it  behaves  just  as  you 
would  expect  it  to.  Without  this  flag, 
however,  reads  and  writes  don’t  lose 
their  position  in  the  file.  Now  just  imag¬ 
ine  a  (descendant)  database  class  us¬ 
ing  methods  such  as  retrieve( )  and 
replace( )  instead  of  lseek( ),  read( ), 
lseek( ),  ivrite( ).  Seems  just  a  hair  more 
elegant,  doesn’t  it. 

TruncateC )  is  a  routine  that  has  been 
part  of  my  standard  library  for  some 
time.  When  DOS  is  called  to  write  a  file 
and  the  number  of  bytes  specified  is 
zero,  DOS  truncates  the  file  at  that  point. 
For  reasons  of  safety  and  history,  the 
C  write()  routines  doesn’t  do  this;  it 
returns  zero  bytes  written.  I  can’t  really 
argue  with  that  philosophy,  but  some¬ 
times  you  must  truncate  a  file.  In  the 
case  of  the  File  class,  the  write(  /method 
continues  to  behave  as  expected  and 
returns  immediately,  with  no  effect,  if 
zero  bytes  are  written.  An  explicit  mes¬ 
sage  to  a  File  object  to  truncate  though, 
uses  DOS  to  actually  chop  off  the  file 
at  the  current  file  pointer  location. 

Set_  position(  )  and  get_  position( )  al¬ 
low  a  File  client  to  specify  where  the 
file  pointer  should  be.  Size( ),  rename( ), 
erase( ),  and  copyC )  do  what  their  names 
suggest.  Notice  that  both  copy( )  and 
rename( )  operate  whether  the  file  is 
open  or  not.  They  both  preserve  the 
current  condition,  restore  upon  com¬ 
pletion,  and,  aside  from  the  long-winded 
error-testing  stuff,  they’re  all  simple. 

Epilogue 

An  obvious  heir  of  File  is  class  BnJ'_File 
that  would  provide  buffered  I/O.  This 
would  be  very  easily  accomplished  by 
descending  publicly  from  class  File  and 
writing  new  read( )  and  ivrite( )  meth¬ 


ods.  Nothing  else  is  required.  A  class 
Text_File  might  in  turn  descend  from 
Buf_File.  A  Directory  class  could  de¬ 
scend  directly  from  File_Spec.  C++  2.0 
offers  multiple  inheritance  and  the  pos¬ 
sibilities  boggle  the  mind. 

I  chose  C++  for  my  OOP  explora¬ 
tions  thinking  that  my  familiarity  with 
C  would  enable  me  to  clearly  see  what 
OOP  was  against  —  the  backdrop  of  a 
known  language.  In  retrospect  I  think 
it  had  the  opposite  effect. 

In  many  ways  object-oriented  pro¬ 
gramming  is  like  writing  several  mini¬ 
programs.  This  has  the  advantage  of  re¬ 
stricting  the  problem  domain  at  any  given 
point  to  a  more  easily  managed  size.  I 
also  found  that  if  one  thinks  of  objects 
in  this  way  they  are  easier  to  define.  For 
a  lucid  description  of  the  concepts  of 
OOP,  I  highly  recommend  Bertrand 
Meyer’s  book,  Object-oriented  Software 
Construction  (Prentice  Hall,  1988),  which 
does  an  outstanding  job  of  describing 
what  OOP  is  and  isn’t  and,  although  the 
book  uses  Eiffel  (which  Meyer  wrote), 
it  helped  my  C++  programming  im¬ 
mensely.  C++  in  turn  is  having  an  impact 
on  my  C  programming. 

OOP’s  promise  is  to  bring  us  a  bit 
closer  to  component  level  design  and 
implementation.  I  think  OOP  does  have 
the  potential  to  accomplish  this.  The 
cost  is  another  layer  of  code  between 
you  and  the  machine.  This  means 
slower  and  larger  programs,  in  other 
words,  less  efficient  use  of  computer 
resources.  On  the  other  hand,  the  extra 
layer  of  abstraction  will  mean  more  effi¬ 
cient  use  of  the  programmer.  No  lan¬ 
guage  can  decide  this  swap-off  for  us. 
There  will  always  be  a  need  and  a  time 
for  assembler,  just  as  there  will  always 
be  a  need  and  a  time  for  dBase  IV. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  96.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  5. 


Dr  Dobb’s  Journal,  June  1990 

510 


A  Pixel  Ordering 
Algorithm 

A  shortcut  for  interactive  development 


Norton  T.  Allen 


ersonal  computers  can  gener¬ 
ate  and  display  some  very  inter¬ 
esting  graphics.  Unfortunately, 
some  of  the  most  interesting  pro¬ 
grams  require  hours  to  produce 
a  single  graphics  screen.  Mandelbrot 
sets  and  ray-tracing  programs  do  ex¬ 
tensive  floating-point  calculations  for 
each  pixel  of  the  final  display.  The 
iterations  can  be  painfully  slow  if  the 
resulting  image  needs  touching  up. 
Often,  a  general  idea  of  how  the  final 
image  will  look  is  enough  to  act  on, 
but  the  standard  linear  approach  to 
drawing  the  screen  can  mean  a  long 
wait  just  to  find  out  what’s  going  on  in 
the  lower  right-hand  corner. 

For  programs  that  produce  graphics 
one  pixel  at  a  time,  a  better  method  of 
pixel  ordering  provides  a  shortcut  dur¬ 
ing  interactive  development.  By  select¬ 
ing  pixels  that  are  always,  evenly  dis¬ 
tributed  on  the  screen,  the  general  char¬ 
acter  of  the  final  image  can  be  seen 
early  on.  Subsequent  calculations  con¬ 
tinuously  improve  the  focus  until  full 
resolution  is  achieved.  This  makes  it 
possible  to  jump  in  early  and  adjust 
colors,  move  objects,  or  zoom  in  on  a 
particular  area  of  interest.  I  have  imple¬ 
mented  this  algorithm  for  viewing  the 
Mandelbrot  set,  but  it  also  applies  as 
well  to  ray-tracing  or  any  other  pixel-by- 
pixel  task. 

Reversing  Bit  Order 

Part  of  my  job  is  writing  software  to 
receive  data  transmitted  from  high- 


Norton  is  a  systems  analyst/program¬ 
mer  with  the  Harvard  University  At¬ 
mospheric  Research  Project  and  can 
he  reached  at  202  Ridge  St.,  Winches¬ 
ter,  MA  01890. 


altitude  research  balloons.  Information 
from  many  different  sensors  is  collected 
on  the  balloon,  sorted  into  a  standard 
data  structure,  and  then  broadcast  as  a 
serial  bit  stream.  On  the  ground,  the 
process  is  reversed.  Bits  are  collected 
into  bytes,  and  the  bytes  become  mem¬ 
bers  of  structures.  To  help  sort  things 
out,  we  use  a  frame  counter  in  the  data 


Z  bit-reversed  pixel  #  Pattern 
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Figure  1:  Bit-reversed  numbers  can 
be  used  to  address  pixels  in  a  row 


indices  in  a  single  counter  by  interleav¬ 
ing  the  bits  of  their  binary  represent¬ 
ations  in  reverse  order 


stream.  This  is  a  1-  or  2-byte  integer 
that  increments  every  time  it  is  trans¬ 
mitted.  Once  we  successfully  locked 
onto  a  data  stream,  but  the  frame 
counter  readout  showed  no  apparent 
pattern.  By  changing  the  display  to  bi¬ 
nary,  the  problem  became  obvious  — 
the  normal  bit  order  (MSB  -  >LSB)  was 
reversed  (LSB  -  >MSB  in  our  case). 

In  that  case,  bit-reversal  was  the  root 
of  the  problem.  When  I  began  thinking 
about  generating  pixel-oriented  graph¬ 
ics,  however,  bit-reversal  was  the  key 
to  a  solution.  When  counting  the  bi¬ 
nary  integers  from  0002  to  111^  the 
most  significant  bit  on  the  left  is  not  set 
until  the  halfway  point  at  1002.  If  the 
bits  are  reversed,  the  least  significant 
bit  is  not  set  until  halfway  through,  and 
all  bit-reversed  numbers  up  to  that  point 
are  even.  As  Figure  1  shows,  these 
bit-reversed  numbers  can  be  used  to 
address  a  row  of  pixels.  Only  even 
pixels  are  addressed  until  Z=1002.  At 
each  step,  the  distribution  of  filled  and 
unfilled  pixels  is  as  uniform  as  possible. 

This  is  fine  for  addressing  a  single 
row  of  pixels,  but  both  rows  and  col¬ 
umns  need  to  be  addressed.  Two  inde¬ 
pendent  counters  in  a  nested  loop  could 
be  used,  but  this  would  not  give  the 
desired  result.  The  inside  loop  would 
completely  fill  one  row  before  the  next 
evenly-spaced  row  was  selected. 

The  following  algorithm  combines 
both  indices/coordinates  (X,  Y)  in  a  sin¬ 
gle  counter,  Z,  by  interleaving  the  bits 
of  their  binary  representations  in  re¬ 
verse  order.  The  variable  map  (shown 
in  Figure  2)  keeps  track  of  which  bits 
correspond  to  which  coordinate  ( X  or 
Y).  Bits  in  Z,  which  correspond  to  zero 
bits  in  the  map  are  part  of  the  X  coordi¬ 
nate.  Bits  corresponding  to  one  are 
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part  of  the  ^coordinate.  The  results  are 
demonstrated  in  a  4  x  4  region  in  Fig¬ 
ure  2. 

This  is  close  to  the  desired  result, 
but  the  distribution  at  the  halfway  point 
(shown  in  the  second  pattern  in  Figure 
2)  could  be  more  uniform.  Half  the 
rows  are  completely  filled  in,  while  the 
other  half  haven’t  been  filled  in  at  all. 
This  problem  can  be  seen  in  a  2  x  2 
example.  The  algorithm  described  pro¬ 
duces  X,  Fpairs  in  the  order  (0,0),  (1,  0), 
(0,  1),  (1,  1),  which  can  be  represented: 


0  1 
2  3 


A  more  desirable  X,  Y  pair  ordering  is 
(0,0),  (1,1),  (0,1),  (1,0),  or: 


0  3 
2  1 


The  X  coordinates  for  both  orders  are 
the  same,  but  the  Y  coordinates  are 
different.  The  following  inset  shows  a 
truth  table  comparing  the  original  or¬ 
der  (Xz,  Yz),  and  the  new  order  (Xz,  Y’z). 


V* 

0  1 

0 

0  1 

1 

1  0 

The  truth  table  shows  that  Y’z  =  Xz 
©  Yz.  ©  designates  the  exclusive-OR 
operation.  Once  Xz  and  Yz  are  cal¬ 
culated,  it  is  easy  to  generate  Y’z,  and 
report  the  new  point  (Xz ,  Y’).  Figure 
3  shows  how  this  works  in  a  4” x  4  case. 

I  have  implemented  this 
algorithm  for  viewing 
the  Mandelbrot  set,  but 
it  would  apply  as  well 
to  ray-tracing  or  any 
other  pixel-by-pixel  task 


There  are  a  few  rough  edges  dealing 
with  arbitrary  rectangular  regions.  First, 
the  ranges  may  not  be  even  powers  of 
two.  This  is  handled  by  rounding  up 
to  the  next  even  power  of  two  and  then 
discarding  any  points  outside  of  the 
rectangular  region.  Second,  even  after 
rounding,  the  regions  may  not  be 
square.  One  coordinate  may  have  more 
bits  than  the  other.  This  is  handled  by 


storing  the  extra  bits  on  the  LSB  end 
of  map.  If  A  has  2  bits  and  Fhas  4  bits, 
map  =  101011 z  The  exclusive-OR  op¬ 
eration  imposes  an  additional  compli¬ 
cation.  The  Y  range  must  be  at  least  as 
large  as  the  X  range.  This  is  handled 
by  reversing  the  roles  of  the  two  coor¬ 
dinates,  if  the  X  range  is  larger. 


Compilation 

I  have  implemented  a  Mandelbrot  set 
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Figure  3:  Y’z  is  generated  and  the  new 
point  (Xz,  Y’z)  is  reported  as  shown 
in  this  4x4  matrix 
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(continued  from  page  58) 
example  using  grafix.lib  —  Kent  Por¬ 
ter’s  graphics  library  (see  DDf  Febru¬ 
ary  1989  through  August  1989).  This 
library  is  compatible  with  Microsoft  C 
5.1  and  Turbo  C  2.0.  I  compiled  this 
project  using  Lattice  C,  Version  3.41, 
and  some  minor  modifications  were 
necessary.  Lattice  did  not  support  mixed 
mode  programming  before  Version  6.0. 
Grafix.lib  contains  explicit  “far”  desig¬ 
nations.  These  designations  are  redun¬ 
dant  when  programming  in  the  large 
model,  and  problematic  when  program¬ 
ming  in  the  small  model.  Because  my 
program  is  small,  I  removed  the  ex¬ 
plicit  declarations.  I  also  ran  into  syn¬ 
tax  difficulties  using  Kent’s  #define  byte 
unsigned  char,  which  vanished  when 
I  used  typedef  unsigned  char  byte. 

On  the  assembly  side,  I  modified  the 
initializations  to  use  the  Lattice  assem¬ 
bly  macros  to  provide  model-sensitive 
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procedure  definitions.  I  also  followed 
Lattice’s  recommendation  and  saved  ES 
when  that  register  was  used.  Finally, 
Lattice  function  and  data  names  are 
not  prefaced  with  an  underscore  in 
assembly  modules. 

The  Code 

The  file  points. c  (Listing  One,  page 
116)  contains  two  routines:  init _points(  ) 
and  next jpoint( ).  The  X  and  Y  limits 
are  passed  to  init _j>oints(  ),  which  initial¬ 
izes  the  map  variable,  next _point(  )  de¬ 
fines  the  coordinates  of  each  succes¬ 
sive  pixel  through  pointer  arguments, 
returning  a  non-zero  value  when  the 
area  has  been  completely  filled. 

Mandel.c  (Listing  Two,  page  1 16)  pro¬ 
vides  functions  particular  to  the  Man¬ 
delbrot  example.  The  function  set_ 
range( )  creates  a  virtual  coordinate  sys¬ 
tem.  This  function  is  similar  to  grafix’ 
setcoords( ),  with  two  major  differences: 


The  function  set_range( )  guarantees 
that  the  new  coordinates  preserve  the 
aspect  ratio  of  the  screen.  One  inch 
on  the  screen  should  represent  the  same 
number  of  units  in  either  the  X  or  the 
Y direction.  If  one  range  is  proportion¬ 
ately  smaller  than  the  other,  the  coordi¬ 
nates  are  extended  to  place  that  range 
in  the  center  of  the  screen.  The  func- 

The  pixel  ordering 
presented  here 
is  very  closely 
related  to  dither 
matrices  used  for 
generating  gray 
shading  on 
monochrome  monitors 


tion  setcoords( )  only  provides  func¬ 
tions  to  convert  from  virtual  coordinates 
to  device  coordinates,  but  in  this  pro¬ 
gram  we  need  to  do  the  reverse,  man- 
del_color( )  contains  the  Mandelbrot 
calculations  to  determine  the  color  of 
a  particular  pixel. 

Generate. c  (Listing  Three,  page  116) 
provides  the  operational  framework  for 
the  demonstration  program  and  point. h 
(Listing  Four,  page  118)  is  the  include 
file.  generate( )  calls  next _point( )  to 
step  through  the  pixels,  and  calls  man- 
del_color()  to  determine  their  color. 
menu( )  is  called  any  time  a  key  is 
pressed.  menu( )  lets  the  user  move 
and  scale  a  rectangular  box  on  the 
screen  to  identify  a  region  for  closer 
examination.  The  area  in  the  rectangu¬ 
lar  box  can  be  focused  or  zoomed  on. 
Focusing  confines  subsequent  calcula¬ 
tions  to  the  bounds  of  the  box.  This 
gives  a  sharper  look  at  a  small  area,  in 
the  context  of  the  larger  screen.  Zoom¬ 
ing  in  rescales  the  virtual  coordinates  of 
the  screen  to  the  coordinates  of  the  box. 

This  example  demonstrates  the  ad¬ 
vantages  of  this  algorithm.  A  small  re¬ 
gion  can  be  zoomed  in  without  waiting 
for  the  completion  of  intermediate 
views.  By  displaying  the  full  scale  im¬ 
age  at  low  resolution,  the  zooming  can 
be  accurately  selected.  Focusing  can 
be  used  to  choose  from  different  re¬ 
gions.  The  beauty  of  this  algorithm  is 
that  the  same  amount  of  detail  is  pro¬ 
vided  in  the  same  amount  of  time,  re- 
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gardless  of  whether  the  image  is  zoomed 
or  focused.  If  you  zoom,  a  longer  wait 
will  produce  even  more  detail. 

XOR 

To  overlay  a  movable  box  on  the  graph¬ 
ics  display,  a  significant  addition  was 
made  to  the  library.  I  added  the  ability 
to  draw  pixels  on  the  screen  by  calcu¬ 
lating  the  exclusive-OR  (XOR)  of  the 
current  foreground  color  and  the  color 
already  on  the  screen.  XOR  is  very 
useful  for  three  reasons.  If  you  XOR  a 
bit  pattern  with  a  pattern  of  ones  you 
get  the  ones  complement  of  the  origi¬ 
nal  bit  pattern.  Whether  writing  to  a 
black  or  a  white  background,  a  change 
is  visible.  XORing  a  bit  pattern  with 
zeros  has  no  effect.  If  a  bit  pattern  is 
XORed  with  itself,  the  result  is  zero. 
XOR  is  associative.  If  bit  pattern  X  is 
XORed  with  non-zero  mask  M,  a  result 
will  be  seen.  If  the  result  is  XORed  with 
M  again,  the  result  is  (X  ffi  M)  ®  M. 
This  is  equal  to  X  ©  (M  ©  M),  which  is 
equal  to  X  ffi  0,  which  is  equal  to  X. 

XOR  allows  an  image  to  be  put  on 
and  removed  from  the  screen  quickly 
without  destroying  the  image  being  writ¬ 
ten  over.  This  is  very  useful  for  interac¬ 
tive  applications.  Not  only  does  it  allow 
the  cursor  to  move  around  a  graphics 
screen,  but  it  also  enables  experimen¬ 
tation  with  the  placement  of  objects  be¬ 
fore  committing  them  to  an  image. 

This  is  so  useful  that  it  is  implemented 
in  the  hardware  of  the  EGA  adapter.  The 
write  function  register  can  be  set  to  re¬ 
place  the  stored  value,  or  to  perform 
OR,  AND,  or  XOR  functions  between 
the  stored  value  and  the  value  being 
written.  In  this  case,  I  want  to  move  a 
rectangular  box.  The  function  to  draw 
the  box  is  draw_rect( ).  This  function 
calls  draw_line(  ),  which  calls  draw_ 
point(  ).  Adding  a  XOR  mode  to  draw_ 
point( )  allows  the  box  to  be  moved. 
Listing  Five,  page  118,  contains  defini¬ 
tions  to  be  included  in  grafix.h,  and 
Listing  Six,  page  118,  contains  wmode.c, 
which  defines  the  function  set_write_ 
mode( ).  This  module  should  be  com¬ 
piled  and  included  in  grafix.lib  by  us¬ 
ing  the  LIB  grafix  +wmode;  command. 

Two  changes  need  to  be  made  in 
drawpt.asm.  Below  line  14,  where  the 
vuport  pointer  is  declared,  add  the  line: 
EXTRN  _write_mode  :  BYTE.  Also 
change  line  78  from:  xorah,  ah  to:  mov 
ah,  _write_mode.  Assemble  drawpt , 
then  replace  it  in  the  library  with  the 
command:  LIB  grafix  -+ drawpt.  A  simi¬ 
lar  change  can  be  made  to  hline.asm 
by  adding  the  declaration  after  line  14, 
and  changing  line  106. 

Other  Applications 

To  use  this  algorithm  in  a  ray-tracing 


study,  replace  the  functions  in  man- 
del. c  with  the  ray-tracing  code  and 
change  the  calls  in  generate( )  accord¬ 
ingly.  Another  application  of  this  algo¬ 
rithm  is  for  demo  programs,  where  one 
graphics  image  facies  into  another.  Run¬ 
ning  the  fade  one  pixel  at  a  time  is 
much  too  slow.  Divide  the  image  into 
small  rectangles,  use  this  algorithm  to 
index  the  rectangles,  and  use  a  bitblt 
routine  to  copy  the  rectangles. 

The  pixel  ordering  presented  here 
is  closely  related  to  dither  matrices  used 
for  generating  gray  shading  on  mono¬ 
chrome  monitors.  For  16  shades  of  gray, 
the  screen  is  tiled  with  imaginary  4x4 
pixel  blocks.  Each  pixel  is  numbered 
from  0  to  15,  according  to  its  position 
in  the  order.  When  the  user  wishes  to 
color  an  area  with  a  certain  gray  level, 
only  those  pixels  with  numbers  less 
than  that  level  are  turned  on. 

Tradeoffs 

This  algorithm  does  much  bit  twid¬ 
dling  to  calculate  each  set  of  coordi¬ 
nates.  This  adds  CPU  processing  time. 
On  the  4.77-MHz  XT,  this  algorithm 
took  15  minutes  longer  to  fill  the  screen 
than  a  simple  nested  loop.  If  the  exact 
calculations  for  drawing  an  image  are 
already  known,  it  is  preferable  not  to 
use  this  algorithm.  When  a  lot  of  CPU 
time  is  being  used,  however,  it’s  nice 
to  know  if  the  right  picture  is  being 
generated.  Seeing  only  the  left  quarter 
of  the  screen  won’t  help,  but  one  quar¬ 
ter  resolution  across  the  entire  display 
is  enough  to  see  considerable  detail. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 


DDJ 
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Instant-C  is  an  interactive  C  com¬ 
piler  and  integrated  development 
environment  from  Rational  Systems, 
based  on  Rational’s  DOS/16M,  a 
protected-mode  DOS  extender  for 
Intel  80286-  and  80386-based  PC  com¬ 
patibles.  DOS/16M  is  also  used  in  such 
products  as  Lotus  1-2-3,  Release  3, 
AutoCAD,  Release  10.0,  and  the  DOS 
version  of  the  Glockenspiel  C++  com¬ 
piler. 

Instant-C  (IC)  provides  interactive  exe¬ 
cution,  linking,  editing,  and  debugging 
of  C  code.  In  addition  to  loading  .C 
files,  C  expressions  can  be  typed  in  at 
IC’s  #  prompt  for  immediate  evaluation. 

Figure  1  shows  a  sample  session  with 
IC.  First,  a  buffer  is  allocated  with  mal- 
loc( ).  This  buffer  happens  to  reside  in 
extended  memory,  as  shown  by  a  call 
to  the  DOS/16M  function  D16AbsAd- 
dressQ.  As  with  any  product  based 
on  a  DOS  extender  such  as  DOS/16M, 
however,  the  distinction  between  ex¬ 
tended  and  conventional  memory  is 
largely  unimportant:  In  protected  mode, 
it’s  all  just  memory. 

Next,  the  low-level  Microsoft  C 
dos_open( )  function  is  used  to  open  a 
file,  and  dos_read( )  is  used  to  read  the 
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file  into  our  buffer.  We  could  just  as 
easily  use  the  C  standard  library  func¬ 
tions  fopen( )  and  fread( ),  but  using 
these  DOS-specific  routines  in  conjunc¬ 
tion  with  the  extended-memory  buffer 
shows  how  a  DOS  extender  transpar¬ 
ently  manages  the  interface  between 
MS-DOS  and  protected  mode. 

Note  how  C  statements,  declarations, 
and  preprocessor  statements  can  be 
freely  mixed  at  the  #  prompt,  some¬ 
what  like  mixing  statements  and  decla¬ 
rations  in  C++.  In  this  “immediate 
mode,”  leaving  the  semicolon  off  a  state- 


#  char  *p; 

##include  <malloc.h> 

MALLOC.H  included 

#  p  =  malloc(10240) 

address  03B8:01A6:‘‘  ’’ 

##include  “dos16.h" 

DOS16.H  included 

#  D16AbsAddress(p) 

2940246  (0X2CDD56) 

#  include  <dos.h> 

DOS.H  included 

#  int  handle; 

#_dos„open(“\\msc\\inc\\dos.h'',  0,  &handle) 
0 

#  handle 

7 

#  unsigned  bytes; 

#  _dos_read(handle  p,  10240,  &bytes) 

0 

#  bytes 

5917  (0x1 71 D) 

#  _dos_close(handle) 

0 

#  printf(“%s\n”,  p)  //  display  file 


Figure  1:  A  sample  session  with 
Instant-C 


ment  tells  IC  to  print  its  value.  This  is 
one  way  that  interactive  C  differs  from 
“normal”  C.  In  Figure  1, 1  displayed  the 
value  of  the  variable  bytes  simply  by 
typing  its  name. 

IC  provides  a  command  language  in 
the  form  of  preprocessor  statements. 
To  compile  a  file  FOO.C,  for  example, 
you  could  type  #load  foo.c  at  the  IC 
prompt.  The  command  language  can 
also  be  used  under  program  control: 

if  (x  >  1) 

_interpret(“#load  foo.c”); 

Working  with  a  “quick”  environment 
raises  the  issue  of  compatibility  with 
production  compilers.  IC  has  a  stan¬ 
dard  library,  but  for  using  the  Microsoft 
C  library  instead,  for  example,  IC  comes 
with  scripts  to  load  MSC  5.1’s  real¬ 
mode  large-model  LLIBCE.LIB,  load  IC- 
supplied  .LIB  modules  to  replace  the 
few  Microsoft  functions  that  won’t  work 
in  protected  mode,  #include\he  Micro¬ 
soft  header  files  into  IC,  and  then  write 
out  a  new,  large  model,  MSC-compat- 
ible  IC.  The  new  executable  not  only 
runs  your  C  programs  in  protected  mode 
under  MS-DOS:  It  executes  the  Micro¬ 
soft  C  library  in  protected  mode  as 
well.  It  seems  like  quite  an  accomplish¬ 
ment  to  load  real-mode  object  code 
and  execute  it  in  protected  mode,  but 
this  is  standard  procedure  for  DOS  ex¬ 
tenders. 

IC  gives  C  the  interactive  style  of 
languages  such  as  Forth  and  Lisp.  Con¬ 
trary  to  the  stereotype  of  an  interpreter, 
IC  uses  native  object  code.  In  fact,  IC 
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(continued  from  page  62) 
can  dynamically  load  and  link  .OBJ 
and  .LIB  files,  and  can  write  out  stand¬ 
alone  .EXE  files.  Such  stand-alone  execut¬ 
ables  include  a  built-in  protected-mode 
DOS  extender. 

The  two  major  benefits  of  protected 
mode  —  memory  protection  and  a  large 
address  space  —  mesh  with  the  needs 
of  a  C  development  environment.  The 
large  address  space  (up  to  16  Mbytes 
of  memory)  means  that  even  very  large 
C  programs  can  be  developed  interac¬ 
tively.  Hardware-based  memory  pro¬ 
tection  also  helps  insulate  IC  from  bugs 
in  user  code  and  assists  IC  in  finding 
bugs.  An  interpreter  running  in  pro¬ 
tected  mode  can  off-load  some  of  its 
type-checking  onto  the  CPU. 

IC  is  not  only  a  product  built  using 
a  DOS  extender,  it  is  an  example  of 
why  “EXTDOS”  is  necessary  in  the  first 
place.  IC  has  been  in  existence  since 
1984.  As  more  and  more  features  were 
added  to  the  product,  it  began  to  strain 
against  the  artificial  640K  “Berlin  Wall” 


Figure  2:  Detecting  a  protection  violation 


of  real-mode  MS-DOS.  Rational  Sys¬ 
tems  developed  DOS/16M  for  IC  to 
cope  with  its  expanding  features  and 
resulting  expanding  memory  consump¬ 
tion.  Thus,  DOS/16M  is  based  on  IC, 
as  much  as  IC  is  based  on  DOS/16M. 
For  a  short  time,  Rational  Systems  mar¬ 
keted  a  separate  protected-mode  IC/ 
16M  alongside  real-mode  IC.  In  Octo¬ 
ber  1989,  with  IC  Version  4.0,  Rational 
discontinued  the  real-mode  version. 

Using  Protection 

A  protected-mode  interpreter  must  al¬ 
low  the  user  to  violate  the  CPU’s  pro¬ 
tection  model  without  causing  the  in¬ 
terpreter  itself  to  be  shut  down.  I  have 
discussed  this  issue  at  length  in  my 
two-part  article,  “Stalking  GP  Faults” 
(DDf  January  1990  and  February  1990). 
In  IC  we  can  freely  type  protection 
violations  at  the  #  prompt,  as  shown 
in  Figure  2,  because  IC  installs  its  own 
general-protection  violation  (GP  fault) 
handler. 

In  addition  to  helping  find  bugs  dur¬ 


ing  development,  the  hardware-based 
memory  protection  of  the  Intel  proces¬ 
sors  also  can  be  put  to  work  in  the 
deliverable  version  of  a  product. 

For  example,  functions  often  per¬ 
form  their  own  range  checking.  Each 
time  the  function  is  called,  its  parame¬ 
ters  are  checked  against  the  size  of  the 
target  object.  But  because  the  hard¬ 
ware  does  range  and  type  checking  in 
protected  mode  anyway,  and  because 
we  pay  a  performance  penalty  for  this 
checking,  we  should  get  the  hardware 
to  do  our  checking  as  well. 

This  requires  devoting  a  separate  se¬ 
lector  to  each  object  for  which  you 
want  hardware-assisted  checking.  To 
see  why,  let’s  overstep  the  bounds  of 
an  array  and  see  whether  the  Intel  pro¬ 
cessor  detects  an  off-by-one  fencepost 
error.  In  Figure  3,  the  pointer  p  points 
to  a  block  of  2013  bytes,  numbered  0 
through  2012,  so  p[2013]  clearly  over¬ 
steps  its  bounds.  If  protected  mode  is 
all  it’s  cracked  up  to  be,  the  CPU  should 
have  complained,  right?  Why  didn’t  it? 

The  reason  is  that  mallocO  and  other 
high-level-language  memory  allocators 
suballocate  out  of  pools  of  storage. 
They  do  not  ask  the  operating  system 
for  memory  each  time  you  ask  them 
for  memory,  nor  would  you  want  them 
to.  From  one  segment,  malloc( )  may 


#  char  *s;  //  oops:  forgot  to  initialize 

#  atoi(s) 

## 492:  Invalid  address  0AA8:4582  at  _CATOX+OOOE 

#  #reset 
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( continued  from  page  64) 
allocate  several  different  objects.  While 
we  think  of  the  object  p  as  containing 
2013  bytes,  the  processor  sees  a  con¬ 
siderably  larger  object:  The  block  of 
memory  mallocC )  received  the  last  time 
it  asked  DOS  for  memory.  What  size  is 
the  object  the  CPU  sees? 

#  Dl6SegLimit(p) 

24575 (0x5FFF) 

If  this  explanation  is  correct,  trying 
to  poke  p[0x5FFF]  ought  to  cause  a 
GP  fault: 

#  p[0x5fffl  =  ‘x’ 

##  492:  Invalid  address  0BF8:002A 

Now,  we  still  need  a  way  to  make 
the  CPU  see  things  our  way.  Because 
80286  memory  protection  is  based  on 
segmentation,  we  must  devote  a  sepa¬ 
rate  selector  to  each  object  for  which 
we  want  hardware-assisted  checking. 
Notice  I  said  “selector”  and  not  “seg¬ 
ment.”  We  can  continue  to  use  mal- 
loc( )  to  allocate  objects,  but  when  we 
want  the  CPU  to  know  how  big  we 
think  the  object  is,  we  provide  an  “alias” 
in  the  form  of  another  selector  that 
points  at  the  same  physical  memory 
but  whose  limit  is  smaller.  The  seg¬ 
ment  limit  indicates  the  highest  legal 
offset  within  a  block  of  memory  and  is 
checked  by  the  CPU  for  each  memory 
access. 

To  create  an  alias  q  for  the  pointer  p, 
where  qfs  limit  is  equivalent  to  the  ar¬ 
ray  bounds,  we  can  use  two  other  DOS/ 
16M  functions,  as  shown  in  Figure  4. 
This  takes  a  physical  address  returned 
by  Dl6AbsAddress( ),  together  with  the 
limit  we’re  imposing  for  access  to  this 
memory,  and  passes  them  to  Dl6Seg- 
AbsoluteC ),  which  constructs  a  pro- 
tected-mode  selector  for  the  same  ab¬ 
solute  physical  address  but  with  a  dif¬ 
ferent  limit. 

In  Figure  5,  we  verify  that  this  worked. 
Attempting  even  to  read  from  this  inva¬ 
lid  array  index  now  causes  a  GP  fault. 

So  we  can  dispense  with  explicit 


#  char  *p; 

#p  =  malloc(2013) 

address  03B8:01A6:  “ 

#  p[2013]  =  ‘x’ 

‘x'  (0x78) 

Figure  3-'  This  ojf-by-one  error 
violate  protection 

doesn  7 

#char*q; 

!  #  q  =  D16SegAbsolute(D16AbsAddress(p), 

2013); 

0008:0000 

Figure  4:  Creating  an  alias  with  a 
shorter  limit 
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bounds  checking:  The  CPU  will  check 
for  us.  To  control  the  error  message 
displayed  when  a  GP  fault  occurs,  we 
could  write  our  own  INT  OD  handler 
and  install  it  using  the  DOS  set-vector 
function  (INT  21  AH=25).  Thus,  in¬ 
stead  of  littering  error  checking  through¬ 
out  our  code,  protected  mode  allows 
us  to  centralize  it  inside  an  interrupt 
handler.  Errors  can  be  handled  after 
the  fact,  rather  than  up  front.  In  a  way, 
this  resembles  ON  ERROR,  one  of  the 
more  powerful  concepts  in  Basic  (which 
got  it  from  PL/I). 

This  meshes  with  the  advice  given 
by  advocates  of  object-oriented  pro¬ 
gramming:  “If  you  are  expecting  a  ser¬ 
mon  telling  you  to  improve  your  soft¬ 
ware’s  reliability  by  adding  a  lot  of 
consistency  checks,  you  are  in  for  a 
few  surprises.  I  suggest  that  one  should 
usually  check  less.  .  .  .  ‘Defensive  pro¬ 
gramming’  is  a  dangerous  practice  that 
defeats  the  very  purpose  it  tries  to 
achieve”  (Bertrand  Meyer,  “Writing  Cor¬ 
rect  Software,”  Dr.  Dobb’s Journal ,  De¬ 
cember  1989). 

By  using  protection,  you  may  be  able 
to  make  an  application  run  faster  in 
protected  mode  than  under  real  mode, 
because  a  lot  of  error-checking  and 
“paranoia”  code  can  now  be  made  un¬ 
necessary. 


When  finished  with  the  pointer  p ,  it 
is  important  not  only  to  free(p)  but  to 
release  the  alias  in  q.  Don’t  use  free( ) 
to  release  this  selector,  though:  The  C 
malloc( )  manager  doesn’t  know  any¬ 
thing  about  q ,  which  is  just  an  alias,  a 
slot  in  a  protected-mode  descriptor  ta¬ 
ble.  We  need  to  free  this  slot  because 
the  number  of  selectors  available  in 
protected  mode  is  quite  limited: 

#  free(p) 

#  Dl6SegCancel(q) 

In  moving  from  real  to  protected 
mode,  programmers  may  regret  that 
segment  arithmetic  is  so  restricted.  But 
the  ability  to  create  aliases,  different 
views  of  the  same  block  of  physical 
memory,  means  that  protected-mode 
selector  manipulation  is  actually  far 


Figure  5:  Now  the  off-by-one  error  does 


more  versatile  than  real-mode  segment 
arithmetic. 

The  Intel  286  Protected- Mode  Instructions 

Transparency  is  a  major  goal  of  DOS 
extenders.  But  sometimes  it  is  useful 
not  to  be  so  transparent.  For  example, 
DOS  extender  diagnostic  programs  and 
DOS  extender  utilities  will  generally 
be  nonportable,  hyper- aware  that  they 
are  running  in  protected  mode. 

The  80286,  and  also  the  286-compat- 
ible  386  and  486  chips,  have  a  number 
of  instructions  that  Intel  provides  pri¬ 
marily  for  use  by  protected-mode  op¬ 
erating  systems  but  which  are  also  use¬ 
ful  for  utilities  and  diagnostic  programs. 
Some  of  these  are  listed  in  Figure  6. 

For  example,  in  the  last  section  we 
called  Dl6SegLimit( )  to  find  the  size 
of  the  segments  pointed  to  by  p  and  q. 


violate  protection 


#  q[2013] 

##  492:  Invalid  address  0BF8:002A  in  command  line 

#  D16AbsAddress(p)  =  =  D16AbsAddress(q) 

1 

#  D16SegLimit(p)  =  =  D16SegLimit(q) 

n 

#  D16SegLimit(p) 

24575  (0x5FFF) 

#  D16SegLimit(q) 

2012  (0x7DC) 
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In  operation  (though  not  in  implemen¬ 
tation),  D16SegLimit(  )  corresponds  to 
the  LSL  instruction,  which  takes  a  se¬ 
lector  in  the  source  operand  and,  if  the 
selector  is  valid,  returns  its  limit  (size  -1) 

The  two  major  benefits 
of  protected  mode — 
memory  protection  and 
a  large  address  space — 
mesh  with  the  needs 
of  a  C  development 
environment 


in  the  destination  operand.  For  example: 

lsl  ax,  [bp+6] 

Similarly,  the  LAR  instruction  will  load 
the  destination  operand  with  the  “ac¬ 
cess  rights”  of  the  selector  in  the  source 
operand  if  it  contains  a  valid  selector: 

lar  ax,  [bp+6] 

The  instructions  LSL,  LAR,  VERR,  and 
VERW  are  special  because,  even  if  the 
selector  in  the  source  operand  is  not 
valid,  the  instructions  don't  GP  fault; 
instead,  the  zero  flag  is  cleared.  There¬ 
fore,  if  these  instructions  were  avail¬ 
able  in  a  high-level  language,  we  could 
construct  protected-mode  memory 
browsers  and  other  utilities  simply  by 
looping  over  all  possible  selectors.  This 
is  an  odd  form  of  segment  arithmetic: 

for  (i=0;  i<0xFFFF;  i++) 
if  lar(i)  is  valid 
print_selector(i) 

It  is  easy  to  make  the  Intel  protected- 
mode  instructions  available  to  C  and 
other  high-level  languages,  and  they 
can  be  used  interactively  in  IC. 
PROTMODE.ASM  (Listing  One,  page 
120)  is  a  small  library  of  functions,  in¬ 
cluding  lsl( )  and  lar( ),  that  can  be 


Figure  6:  Some  Intel  protected-mode 
instructions 


assembled  into  PROTMODE.OBJ  by  us¬ 
ing  either  the  Microsoft  Assembler  (Ver¬ 
sion  5.0  and  later)  or  Turbo  Assembler. 

PROTMODE.ASM  uses  the  DOSSEG 
directive,  which  simplifies  writing  as¬ 
sembly-language  subroutines  and  uses 
the  ENTER  and  LEAVE  instructions  pro¬ 
vided  on  the  80286  and  higher  for  work¬ 
ing  with  high-level-language  stack 
frames.  These  execute  a  little  slower 
than  the  standard  BP-SP  prolog/epilog 
but  create  compact  source  code. 

PROTMODE.ASM  provides  nothing 
more  than  a  functional  interface  to  the 
Intel  protected-mode  instructions.  While 
completely  nonportable  with  real  mode, 
this  module  is  highly  portable  among 
16-bit  protected-mode  systems  (it  would 
require  some  modification  for  use  with 
a  32-bit  DOS  extender).  Once  assem¬ 
bled  into  PROTMODE.OBJ,  it  can  be 
linked  into  any  16-bit  protected-mode 
program,  including  an  OS/2  program. 
It  can  be  loaded  into  IC: 

#loadobj  “protmode.obj” 

You  need  to  supply  stub  definitions 
for  the  individual  routines  in  an  object 
module  loaded  into  IC.  These  look  al¬ 
most  like  declarations  or  function  pro¬ 
totypes,  except  that  they  are  followed 
by  the  construct  (extern;!.  PROT- 
MODE.H  (Listing  Two,  page  120)  is  a 
C  #include  file  that  contains  function 
prototypes  for  use  with  IC  (#ifdef  ln- 
stantC )  or  with  any  other  1 6-bit  pro¬ 
tected-mode  environment. 

Now  it’s  time  to  test  the  functions. 
Let’s  allocate  a  10K  segment,  and  see 
what  limit  lsl( )  returns.  Figure  7  uses 
the  FP_SEG( )  macro  from  Microsoft’s 
dos.h  to  extract  the  selector  from  the 
pointer  p ,  and  passes  this  to  lsl( );  lsl(  ) 
returns  10,239,  which  is  clearly  the  last 
legal  offset  within  a  10K  segment,  so 
lsl(  )  seems  to  work.  (Actually,  there  is 
an  extremely  obscure  bug  in  lsl( ).  You 
should  be  able  to  spot  it  by  looking 
back  over  Listing  One.) 

The  verw( )  function,  like  the  VERW 
instruction,  returns  TRUE  if  a  selector 
can  be  written  to,  or  FALSE  if  the  selec¬ 
tor  is  read-only: 

#  verw(FP_SEG(p)) 

1 


Figure  7:  Verify  that  lsl(  ) 
works 


LSL  (load  segment  limit)  — size  of  a  segment 
LAR  (load  access  rights)  — access  rights  of  segment 
VERR  (verify  read)  — can  segment  be  peeked? 

VERW  (verify  write)  — can  segment  be  poked? 

SGDT  (store  GDT)  — base  address  and  size  of  GDT 
SIDT  (store  IDT)  — base  addr  and  size  of  IDT 
SLDT  (store  LDT)  — selector  to  LDT 


#  char  *p; 

#  p  =  D16MemAlloc(10240) 

address  0008:0000 

#  lsl(FP_SEG(p)) 

10239  (0x27FF) 
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We  can  use  a  DOS/16M  function  to 
mark  this  segment  as  read-only  and 
then  see  if  verw( )  has  picked  up  on  the 
change  in  the  selector  attributes: 

#  Dl6SegProtect(p,  1) 

0 

#  verw(FP_SEG(p)) 

0 

The  read-only  attribute,  like  other 
aspects  of  the  protected-mode  “access 
rights,”  applies  to  a  selector,  not  to  the 
underlying  block  of  memory.  One  se¬ 
lector  can  be  read-only  and  another 
read/write,  while  both  correspond  to 
the  same  physical  memory. 

Having  tested  the  PROTMODE.OBJ 
routines  we  can,  as  promised,  write  a 
simple  loop  to  display  all  valid  selec¬ 
tors  within  our  program.  In  IC,  of  course, 

Instant-C  gives  C  the 
interactive  style  of 
languages  such  as  Forth 
and  Lisp 


we  can  just  type  this  in  at  the  *  prompt, 
as  shown  in  Figure  8. 

This  will  display  all  valid  selectors 
within  a  protected-mode  program  (not 
just  a  DOS/16M  program).  But  to  be 
genuinely  useful  we  need  to  print  out 
some  additional  information  about  the 
selectors.  In  addition  to  using  several 
of  the  functions  in  PROTMODE.ASM, 
the  code  in  BROWSE. C  (Listing  Three, 
page  120)  also  performs  some  manipu¬ 
lations  on  the  selector  number  itself: 
The  bottom  two  bits  are  extracted  with 
the  expression  i  &  3,  and  the  third  bit 
is  extracted  with  the  expression  i  &  4. 

What?!  A  protected-mode  selector, 
unlike  a  real-mode  segment  number, 
has  no  necessary  relation  to  the  seg¬ 
ment’s  physical  location  in  memory.  A 
protected-mode  selector  closely  resem¬ 
bles  a  file  handle.  It  is  almost  a  “magic 
cookie,”  but  not  exactly,  in  that  the 
number  itself  actually  has  semantic  mean¬ 
ing:  A  selector  is  a  record  comprised 
of  three  fields.  The  bottom  two  bits 
contain  a  protection  level,  zero  (most 
privileged)  through  three  (least  privi¬ 
leged).  The  third  bit  from  the  right  con¬ 
tains  a  “table  indicator”  —  zero  means 
the  selector  belongs  to  the  Global  De¬ 
scriptor  Table  (GDT),  and  one  means 
it  belongs  to  the  Local  Descriptor  Table 
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(continued  from  page  70) 

(LDT)  —  and  the  remaining  13  bits  form 
an  index  into  this  table.  Thus,  when 
applied  to  a  protected-mode  selector  i, 
i  &  3  extracts  the  selector’s  protection 
level,  and  i  &  4  tells  whether  the  selec¬ 
tor  is  located  in  the  GDT  or  LDT. 

Running  under  IC,  a  small  part  of  the 
output  from  BROWSE. C  is  shown  in 
Figure  9.  The  list  runs  on  and  on  for 
quite  a  while.  What  is  the  value  of  this? 

In  contrast  to  real  mode  where  every 
address  you  can  form  points  some¬ 
where,  protected-mode  memory  is  a 
sparse  matrix.  At  any  given  time,  most 
segment:  offset  combinations  are  not 
valid  addresses:  Dereferencing  them 
causes  a  protection  violation.  Produc¬ 
ing  a  list  like  this  gives  us  an  idea  of  the 
memory  organization  of  a  DOS  exten¬ 
der  program. 

From  this  list,  we  can  see  that  while 
protected-mode  memory  is  a  sparse 
matrix,  it’s  not  so  sparse  under  DOS/ 
16M  as  under  OS/2.  We  can  also  see 
that  all  the  entries  are  marked  PL=00, 
indicating  that  everything  is  running  at 
Ring  0.  To  double-check  that  this  is  so, 


the  loop  in  Figure  10  represents  the 
query,  “Are  any  segments  not  at  Ring 
0?”.  Under  IC,  this  produces  no  output: 
Everything  is  running  at  the  most  privi¬ 
leged  protection  level.  But  in  OS/2,  most 
of  an  application  program’s  selectors 
would  be  displayed  by  this  loop.  This 
is  one  of  the  differences  between  DOS/ 
16M  and  a  full-blown  protected-mode 
operating  system  such  as  OS/2.  Be¬ 
cause  DOS/16M  is  just  a  shell  to  sup¬ 
port  one  program  at  a  time  in  protected 
mode,  Rational  Systems  chose  not  to 
establish  different  protection  levels. 

Along  the  same  lines,  the  selectors 
you'll  use  in  IC  or  in  DOS/16M  actually 
refer  not  to  your  program’s  LDT,  but 
to  the  GDT.  Because  there  is  only  one 
program  running,  the  distinction  be¬ 
tween  GDT  and  LDT,  while  crucial  in 
a  multitasking  operating  system  such 
as  OS/2,  is  fairly  artificial  in  the  “one 
program  at  a  time”  world  of  DOS/16M. 

On  the  other  hand,  another  DOS 
extender,  Eclipse  Computer  Solution’s 
OS/286,  while  sharing  many  of  the  same 
goals  as  DOS/16M,  makes  a  sharper 
distinction  between  the  kernel  (the  OS/ 


unsigned  i; 

for  (i=0;  i<0xFFFF;  i++) 

//  for  all  possible  selectors 

if  (lar(i)) 

//  if  a  valid  selector 

printf("%04X  \  n",  i); 

//  print  selector 

Figure  8:  Display  all  valid  selectors 
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LSL=FFFF 

PL=00 

VERR 

VERW 

GDT 

003C 
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LSL=FFFF 
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VERW 

LDT 

0040 
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LSL=0FFF 
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VERW 

GDT  TRANS 
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LSL=FFFF 

PL=00 

VERR 

VERW 

LDT 
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110010 

LAR=93 
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GDT 

0054 

110010 

LAR=93 

LSL=200F 

PL=00 

VERR 

VERW 

LDT 
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LAR=81 

LSL=0067 

PL=00 

GDT 

005C 

032050 

LAR=81 

LSL=0067 

PL=00 

LDT 
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FAOOOO 

LAR=93 

LSL=FFFF 

PL=00 

VERR 

VERW 

GDT 

0064 

FA0000 

LAR=93 

LSL=FFFF 

PL=00 

VERR 

VERW 

LDT 

0068 

100010 

LAR=82 

LSL=FFF8 

PL=00 

GDT 

Figure  9:  Output from  BROWSE.  C 


for  (i=0;  i<0xFFFF;  i++) 
if  (lar(i)  &&  (i  &  3)) 
printf(“%04X  PL=%02X\n”,  i,  i  &  3); 


Figure  10:  Are  any  selectors  not 
at  Ring  OF 


for  (i=0;  icOxFFFF;  i++) 

if  (lar(i)  &&  (i  ==  D16Abs  Address 

(MK_FP(i,0))  »  4)) 
printf(“%04X  ”,  i); 

Figure  11:  Are  any  selectors 
transparent F 


#  GDTR  g; 

#  sgdt(&g) 

typedef  struct  { 

#g 

unsigned  limit,  lo; 

struct  at2F1C{ 

unsigned  char  hi,  reserved; 

limit  =  65528  (0xFFF8); 

}  GDTR; 

lo  =  16  (0x10); 
hi  =  ’\020’  (0x10); 
reserved  =  ’\0’;} 

Figure  12:  The  GDTR  represented  Figure  13:  Finding  the  location  and 
in  C  size  of  the  GDT 


286  DOS  extender  itself)  and  the  pro¬ 
gram  supported  by  the  DOS  extender. 
OS/286  programs  run  at  Ring  3,  while 
OS/286  itself  runs  at  Ring  0.  This  just 
shows  that  there  are  few  fixed  rules 
about  how  a  DOS  extender  must  be 
organized.  Protected  mode  allows  for 
a  wide  variety  of  styles  in  operating 
environments. 

IC  requires  a  large  GDT  partially  to 
support  many  “transparent”  selectors. 
For  example,  selector  0x40  has  a  physi¬ 
cal  base  address  of  0x400,  correspond¬ 
ing  to  the  BIOS  data  area.  Using  the 
same  code  from  PROTMODE.ASM,  it 
is  trivial  to  form  the  query,  “Which 
selectors  are  transparent?”  (Figure  11.) 

Examining  the  Protected-Mode 
Descriptor  Tables 

We  have  already  used  an  indirect 
method  to  examine  the  DOS/16M  mem¬ 
ory  map:  Loop  over  all  possible  selec¬ 
tors  and  see  if  they’re  legal.  We  can 
also  directly  examine  the  GDT,  IDT, 
and  LDT. 

PROTMODE.ASM  contains  a  func¬ 
tional  interface  to  the  SGDT  instruc¬ 
tion.  SGDT  expects  a  pointer  to  6  bytes 
of  storage  (a  FWORD  PTR),  into  which 
it  copies  the  contents  of  the  CPU’s  GDT 
register  (GDTR).  The  GDTR  holds  the 
24-bit  physical  base  address  and  16-bit 
limit  of  the  GDT,  corresponding  to  the 
C  structure  in  Figure  12.  (Note  that  this, 
like  most  structures  in  this  article,  re¬ 
quires  byte  alignment;  in  IC,  _struct 
_alignment  =  1\  in  batch  compilers 
such  as  Microsoft  C,  use  #pragma pack 
(1).)  This  structure,  along  with  sgdt( ), 
is  used  in  Figure  13  to  get  the  physical 
base  address  (0x100010)  and  limit 
(0xFFF8)  of  the  GDT. 

Now  we  need  to  map  this  into  our 
address  space.  A  protected-mode  de¬ 
scriptor  table  is  an  array  of  8-byte  seg¬ 
ment  descriptors.  Each  descriptor  con¬ 
tains  the  24-bit  physical  base  address 
and  1 6-bit  limit  for  the  segment,  as 
well  as  an  access-rights  byte.  There  is 
also  a  2-byte  field  used  in  32-bit  pro¬ 
tected  mode  on  the  386.  All  this  can 
be  expressed  in  C,  as  shown  in  Figure 
14.  After  typing  or  loading  this  struc¬ 
ture  definition  into  IC,  we  can  create  a 
pointer  to  the  GDT  (Figure  15). 

Now  that  we  have  a  pointer  to  the 
GDT,  let’s  make  it  read-only  to  make 
sure  we  don’t  mess  anything  up 
(though,  if  you  were  working  in  a  pro¬ 
tected-mode  environment  that  didn’t 
have  convenient  functions  for  chang¬ 
ing  selector  attributes,  you  might  actu¬ 
ally  want  to  write  to  the  GDT!): 

#  Dl6SegProtect(gdt,  1); 

If  bit  3  of  a  selector  indicates  that  it 
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(continued  from  page  72) 
belongs  to  the  GDT,  then  the  top  13 
bits  of  the  selector  can  be  used  as  an 
index  into  the  GDT.  Take  the  example 
of  the  GDT  pointer  itself.  In  Figure  16, 
we  locate  our  new  descriptor  for  the 
GDT  within  the  GDT.  (Got  it?) 

Figure  16  confirms  what  we  already 
know  about  the  GDT :  Its  physical  base 
address  is  0x100010  and  its  limit  is 
0xFFF7.  We  could  now  dispense  with 
D16SegAbsolute(  )  and  Dl6SegLimit(  ), 
and  write  portable  protected-mode 
code. 

To  get  a  pointer  to  the  GDT  gener¬ 
ally  requires  that  you  use  some  special 
facility  within  your  protected-mode  en¬ 
vironment.  We  used  Dl6SegAbsolute( ) 
here,  which  obviously  won’t  work  out¬ 
side  DOS/16M.  However,  once  you  do 
have  a  pointer  to  the  GDT,  you  can 
write  completely  portable  protected- 
mode  code.  For  example,  I  will  snarf  a 
lot  of  this  code  for  a  forthcoming  DDJ 
article  that  features  a  GDT  browser  for 
OS/2. 

What  about  the  “access  rights”  value 
that  the  CPU  in  protected  mode  uses 
to  ensure  proper  use  of  selector  0x0C08? 
We  can  use  the  C  bitfield  in  Figure  17 


to  display  the  individual  fields  that  make 
up  the  access-rights  value  0x91.  The  C 
bit  field  structure  is  wonderfully  non¬ 
portable,  so  if  using  the  structure  in 
Figure  17,  you  should  check  your  com¬ 
piler’s  ordering  of  bit  fields  and  make 
sure  the  stucture  is  byte  aligned. 

While  DOS/16M  (and,  consequently, 
IC)  doesn’t  make  much  use  of  the  LDT, 
this  table  is  crucial  in  other  protected- 
mode  environments.  Getting  the  LDT 
selector  is  simple: 

DESCRIPTOR  far  *ldt; 

ldt  =  MK_FP(sldt(),  0); 

If  this  pointer  is  not  valid  within  your 
address  space  ( !verr(sldt( ))),  you  can 
instead  look  up  your  LDT’s  descriptor 
within  the  GDT : 

gdt[sldt(  )  »  31 

and  then  map  the  absolute  address  you 
find  there  into  your  address  space. 

Now  that  we  have  these  structures, 
we  can  write  a  function,  sel( ),  to  dis¬ 
play  selector  attributes.  Note  that  in 
Listing  Four,  page  120,  (SEL.C)  con¬ 
tains  no  references  to  DOS/16M-  sel( ) 
can  be  used  to  examine  the  selector  for 
any  pointer,  such  as  sel( )s  own  func¬ 


tion  pointer.  The  attributes  display  in¬ 
dicates  that  this  is  readable  code  run¬ 
ning  at  protection  level  zero: 

#  sel(sel) 

SEL=0A68  ADDR=472BB0 

LIMIT=43FF  ACCESS=0ar-c-p 

All  these  data  structures  are  described 
in  the  Intel  literature  on  286  and  386 
protected  mode.  Seeing  them  come  to 
life  in  IC,  though,  is  a  great  aid  to 
understanding  protected  mode. 

One  of  the  tricks  of  protected-mode 
programming  is  to  acquire  an  in-depth 
knowledge  of  these  data  structures  and 
then,  when  programming,  to  forget 
about  them.  The  operating  environ¬ 
ment  takes  care  of  maintaining  the  GDT, 
the  descriptors  within  the  GDT,  and 
the  access-rights  bytes  within  the  de¬ 
scriptors.  The  CPU  will  take  care  of 
using  these  data  structures  to  maintain 
the  integrity  of  the  system.  You’re  bet¬ 
ter  off  not  thinking  too  closely  about 
them,  but  it  does  seem  to  help  to  have 
been  familiar  with  them  at  some  point 
or  other.  Having  an  interactive  envi¬ 
ronment  like  IC  is  a  great  aid  to  gaining 
this  familiarity. 


Product  Information 

instant-C 

Rational  Systems  Inc. 

220  N.  Main  St. 

Natick,  MA  01760 
508-653-6006 

Requires  DOS  2.0  or  above 
an  80286  or  80386  CPU 
and  at  least  1  Mbyte  of  memory. 
Works  with  medium  and 
large  memory  models. 

Price:  $795 


Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  120.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  7. 


typedef  struct  { 

unsigned 

limit; 

//  size  minus  1 

unsigned 

addrjo; 

//  physical  base  addr  -  paragraph. byte 

unsigned  char 

addr  hi; 

//  physical  base  addr  -  megabyte 

unsigned  char 

access; 

//see  ACCESS  RIGHTS  below 

unsigned 
}  DESCRIPTOR; 

reserved; 

//  for  386  (32-bit) 

Figure  14:  The  protected-mode  descriptor  represented  in  C 


#  gdt[FP_SEG(gdt)  »  3] 
struct  at  0C08:0C08  { 
limit  =  65527  (0xFFF7); 
addrjo  =  16  (0x10); 
addr_hi  =  ’\020’  (0x10); 
access  =  'Q'  (0x91); 
reserved  =  0;} 

Figure  15:  Mapping  the  GDT  into  our  Figure  16:  Finding  the  GDT 

address  space  selector  within  the  GDT 


typedef  struct  access  { 

unsigned  accessed  :  1 

//  has  segment  been  accessed? 

unsigned  read  write  :  1 

//  if  data  1  =write;  if  code  1  =read 

unsigned  conjexp  :  1 

//  expansion  direction 

unsigned  code  data  :  1 

1/0  =  data,  1  =  code 

unsigned  xsystem  :  1 

//  0  =  system  descriptor 

unsigned  dpi  :  2 

//protection  level:  0..3 

unsigned  present  :  1 

//  is  segment  in  memory? 

)  ACCESS  J3IGHTS; 

#  *((ACCESS_RIGHTS 

)  &gdt[FP_SEG(gdt)  »3]. access) 

struct  access  at  0C08:0C0D  { 

accessed  :  1  =  1 ; 

//  it's  been  used 

read  write  :  1  =  0; 

//  it’s  read-only 

conf  exp  :  1  =  0; 

//  it's  not  a  stack 

code  data  :  1  =  0; 

//  it's  data 

xsystem  :  1  =  1 ; 

//  it’s  not  a  system  descriptor 

dpi :  2  =  0; 

//  protection  level  0 

present :  1  =  1 ;} 

//  it's  present  in  memory 

Figure  1 7:  The  protected-mode  access-rights  byte  in  C 


#  DESCRIPTOR  *gdt;  //  GDT  is  array  of  DESCRIPTOR 

#  gdt  =  D16SegAbsolute((long)  MK_FP(g.hi,  g.lo),  g.limit  +  1) 

address  0C08:0000 


74 

522 


Dr.  Dobb’s  Journal,  June  1990 


P  R  OGRAMMER'S  W  ORKBENCH 


Accessing  Hardware  from  80386 
Protected  Mode  Part  II 

A  4 -gigabyte  memory  model  and  features  that 
control  80386  paging  make  FAR  pointers  obsolete 


Stephen  Fried 


Last  month,  in  Part  I,  we  saw  that 
with  a  few  tricks  such  as  tiling  a 
huge  model,  and  the  use  of  FAR 
pointers  we  could  address  up  to 
64  terabytes.  However,  I  hope 
to  convince  you  by  the  end  of  this 
article  that  the  only  use  for  FAR  point¬ 
ers  in  80386  code  is  in  operating  sys¬ 
tem  kernels.  As  a  starting  point,  let’s 
take  a  look  at  ports  and  interrupts. 

The  80386  supports  ports  and  inter¬ 
rupts  in  the  same  manner  as  the  8086, 
with  the  exception  that  interrupt  vec¬ 
tors  are  only  stored  in  the  first  1024 
bytes  in  real  mode,  while  port  reads 
and  writes  can  result  in  exceptions  if 
the  user’s  code  does  not  have  the  re¬ 
quired  protection  level.  From  a  practi¬ 
cal  standpoint,  what  this  means  in  32- 
bit  protected  mode  is  that  the  proces¬ 
sor  looks  into  the  interrupt  descriptor 
table  (IDT)  instead  of  the  first  kilobyte 
anytime  an  interrupt  happens. 

These  two  features  make  it  possible 
for  an  operating  system  or  environ¬ 
ment  to  control  what  happens  when  a 
protected-mode  program  hits  either  an 
interrupt  or  attempts  to  write  a  port. 
This  type  of  facility  makes  it  possible  to 
run  DOS  applications  in  “compatibility 
boxes”  that  simulate  MS-DOS.  In  the 
case  of  DOS  extenders,  what  happens 
during  I/O  operations  is  that  port  reads 


Stephen  is  the  vice  president  of  Micro- 
Way’s  R&D.  He  is  well  known  in  the 
field for  his  PC  numeric  and  HF  chemi¬ 
cal  laser  contributions.  You  can  reach 
him  at  Micro  Way  Inc.,  P.O.  Box  79, 
Kingston,  MA  02364. 


and  writes  are  passed  through,  while 
interrupts  get  translated  into  MS-DOS 
compatible  operations.  These  MS-DOS 
compatible  operations  are  performed  by 
DOS  itself,  which  is  activated  by  return¬ 
ing  to  real  mode  and  examining  a  buffer 
area  in  the  first  640K  that  has  been  left 
behind  by  the  protected-mode  portion 
of  the  DOS  extender. 

Interrupts 

To  place  interrupts  in  context,  let’s  ex¬ 
amine  how  to  write  a  short  sequence 
that  writes  to  the  system  diskette  using 
the  ROM  BIOS  INT  13H  entry  point. 
Digging  out  an  eight-year-old  copy  of 
the  IBM  technical  user’s  manual,  we 
examine  the  parameters  that  have  to 
be  passed  to  the  routine  in  the  registers 
al,  ah,  cl,  ch,  dl,  dh,  and  es.bx.  Figure 
1  shows  the  equivalent  8086  and  80386 
versions  of  a  section  of  a  program  that 
writes  eight  sectors  at  a  time  to  a  disk¬ 
ette. 

Of  course,  if  we  were  writing  this 


code  in  C,  we  would  have  used  the 
NDP  C  version  of  int86  or  int386,  or 
the  register-aliased  variables  introduced 
later,  in  conjunction  with  an  asm  state¬ 
ment.  We  chose  the  diskette  routine  as 
an  example  because  it  requires  that  a 
pointer  to  a  buffer  is  passed  to  the 
ROM  BIOS.  Examining  the  code,  we 
discover  that  both  pieces  of  code  are 
identical,  except  for  the  buffer  point¬ 
ers.  In  the  protected-mode  example, 
we  use  the  pointer  es:ebx  instead  of 
es.  bx.  To  understand  how  the  interface 
becomes  32-bit  knowledgeable,  it  is  nec¬ 
essary  to  examine  what  happens  when 
an  int  /^//executes  in  protected  mode. 

The  DOS  extender  has  set  up  the 
IDT,  so  that  when  an  int  13H  occurs, 
the  DOS  extender  gets  interrupted  and 
takes  over.  The  extender  first  looks  at 
the  interrupt  number,  and  if  it  employs 
a  pointer  of  the  type  es-.bx,  it  enters  a 
special  mode  in  which  it  moves  the 
data  pointed  to  by  es.ebx  into  a  buffer 
area  it  has  reserved  for  itself  in  real 


Real  mode  32-bit  protected  mode 


mov 

ax,ds 

mov 

ax,ds 

set  up  es:bx 

mov 

es,ax 

mov 

es,ax 

es  =  ds 

mov 

bx,  buffer 

mov 

ebx, buffer 

point  at  buffer 

mov 

al,8 

mov 

al,8 

#  of  sectors 

mov 

ah, 3 

mov 

ah, 3 

write  to  diskette 

mov 

cl, 8 

mov 

cl, 8 

sector  #  1 

mov 

ch,39 

mov 

ch,39 

track  number  39 

mov 

dl,2 

mov 

dl,2 

drive  #  2 

mov 

dh,1 

mov 

dh,1 

head  #1 

int 

13H 

int 

13H 

call  the  ROM  BIOS 

Figure  1:  8086  and  80386  versions  of  a  program  fragment  that  write  eight 
sectors  at  a  time  to  a  diskette 
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(continued  from  page  78) 
memory.  This  makes  it  possible  to  lo¬ 
cate  our  protected-mode  track  buffer 
anywhere  in  the  32-bit  segment  being 
addressed  by  ebx,  and  to  use  buffers 
larger  than  64K.  The  extender  then  cop¬ 
ies  the  first  64K  from  the  protected 
buffer  into  the  real  buffer,  sets  es.bx  so 
that  it  points  at  the  real  buffer,  restores 
all  the  other  registers  so  that  they  were 
the  same  as  when  the  interrupt  was 

Another  benefit  of  this 
technique  is  that  it 
works  up  to  20  percent 
faster  in  an  80486 
system  than  techniques 
that  use  intrasegment 
methods 


invoked  in  protected  mode,  enters  real 
mode  and,  finally,  issues  an  int  1JH  to 
invoke  the  ROM  BIOS  diskette  routine. 

This  technique  works  fine  for  buff¬ 
ers  that  are  up  to  64K  in  size.  For  buff¬ 
ers  larger  than  64K,  the  extender  is 
forced  to  make  multiple  transfers.  As  a 
result,  there  is  little  benefit  in  using 
buffers  larger  than  64K  when  calling 
either  a  ROM  BIOS  or  MS-DOS  entry 
point  from  protected  mode.  In  the  pro¬ 
cess  of  benchmarking  the  NDP  C  and 
Fortran  I/O  run-time  systems,  we  dis¬ 
covered  that  MS-DOS  is  the  primary 
I/O  bottleneck,  and  that  a  buffer  size 
of  8- Kbytes  gave  excellent  performance. 

FAR  Pointers 

Two  years  ago,  when  we  introduced 
NDP  Fortran,  the  block  move  technique 
just  described  was  the  main  technique 
used  for  accessing  real  mode  memory 
from  protected  mode.  We  made  this 
facility  available  to  users  with  functions 


whose  arguments  included  the  selector 
of  the  destination  segment.  This  worked 
fine,  just  as  long  as  the  memory  being 
accessed  was  recognized  and  had  a 
selector  set  up  for  it  by  Phar  Lap.  How¬ 
ever,  as  our  users  became  more  sophis¬ 
ticated,  this  technique  started  to  break 
down.  More  and  more  users  wanted  to 
access  new  memory-mapped  gadgets 
no  one  had  ever  heard  of  before. 

At  about  the  same  time,  a  number 
of  people  started  talking  about  adopt¬ 
ing  FAR  pointers  to  the  80386,  but  when 
we  examined  the  problem  we  discov¬ 
ered  that  adding  more  segments  was 
not  a  solution  because  it  did  not  ad¬ 
dress  the  problem  of  how  to  create 
new  segments  to  map  in  new  devices. 

About  this  time,  Phar  Lap  added  some 
calls  that  made  it  possible  to  control 
system  paging.  With  these  calls  in  hand, 
we  developed  a  routine  that  enabled 
us  to  extend  the  size  of  a  user’s  data 
segment  while  simultaneously  mapping 
this  new  extension  to  any  arbitrary, 
physical  address. 

To  gain  some  perspective,  imagine 
you  have  just  bought  a  digitizer  which 
is  memory  mapped  and  has  a  resolu¬ 
tion  of  1000  x  1000  pixels  (that  is,  it 
takes  up  a  megabyte  of  physical  ad¬ 
dress  space  in  your  386  AT’s  I/O  chan¬ 
nel).  The  ideal  way  to  obtain  access  to 
this  device  is  to  pass  its  size  and  physi¬ 
cal  location  to  the  operating  system 
and  to  get  back  a  32-bit  pointer  to  the 
device  in  the  address  space  of  the  pro¬ 
gram.  This  is  exactly  what  mapdev( ) 
does.  The  pointer  that  mapdevO  re¬ 
turns  is  an  ordinary  32-bit  pointer  to  a 
piece  of  your  program’s  data  segment 
that  was  just  magically  created.  It  doesn’t 
require  the  use  of  intrasegment  trans¬ 
fers  or  FAR  pointers,  and  you  don’t 
have  to  worry  about  using  a  block  move 
to  access  the  device  or  memory  that 
was  mapped  in. 

Another  benefit  of  this  technique  is 
that  it  works  up  to  20  percent  faster  in 
an  80486  system  than  techniques  that 
use  intrasegment  methods.  The  reason 
is  that  the  80486  has  a  preferred  seg¬ 
ment  register,  ds,  for  accessing  data, 
and  all  NDP  data  accesses  (by  default) 


char  *mapdev ( ) ; 
main  ( ) 

{ 

int  j count  =  0; 
char  *scr_ptr; 

/*  map  the  screen  into  the  data  segment  */ 
scr_ptr  =  mapdev (0xb8000, 4096) ; 
while  (jcount  <  4096) 

{ 

*(scr_ptr  +  ( jcount ++))  =  0x20;  /*  write  space*/ 
*(scr_ptr  +  ( jcount ++))  =  0x7c;  /*  and  attribute*/ 


Example  1:  Using  mapdev(  )  to  map  the  screen  into  the  protected  data 
segment 


80 

524 


Dr.  Dobb’s Journal,  June  1990 


PROGRAMMER'S  WORKBENCH 


( continued  from  page  80) 
are  made  by  using  ds. 

The  choice  of  segment  registers  be¬ 
comes  a  crucial  issue  when  it  comes 
to  Weitek.  The  default  technique  used 
by  NDP  compilers  for  accessing  Weitek 
is  to  pass  the  selector  3C  into  the  seg¬ 
ment  register  fs  and  to  access  Weitek 
through  fs.  Our  research  to  date  indi¬ 
cates  that  mapping  Weitek,  and  every¬ 
thing  else  into  ds,  pays  off  with  big 
dividends.  Altogether,  it  is  possible  to 
make  a  15-50  percent  improvement 
in  486/Weitek  speed  by  correctly  align¬ 
ing  and  mapping  486  code. 

The  80486  and  mapdev( )  put  the 
final  nails  in  the  FAR  pointer  coffin. 
The  next  question  is,  “How  do  you 
port  a  1 6-bit  C  application  that  uses 
FAR  pointers  to  386  protected  mode?” 
FAR  pointers  are  used  in  two  different 
ways  by  16-bit  C  programs:  To  identify 
20-bit  pointers  when  the  program  is 
using  16-bit  pointers  by  default,  and 
to  access  physical  locations  in  the  20- 
bit  8086  address  space.  The  first  use, 
increasing  pointer  size,  does  not  have 
a  corresponding  feature  in  the  small 
memory  model  employed  by  any  of 
the  operating  systems  currently  in  use. 
As  a  result,  this  type  of  FAR  pointer 
gets  translated  by  the  statement 
define  FAR 

This  statement  converts  occurrences 
of  FAR  into  a  null  string.  When  FAR 
pointers  are  used  to  access  physical 
devices  in  the  20-bit  address  space  of 
the  8086,  the  easiest  solution  is  to  use 
mapdev( )  to  map  the  device  into  the 
protected  data  segment  and  use  the 
resulting  pointer  instead.  For  instance, 
consider  the  program  in  Example  1  to 
clear  the  screen. 

For  chores  such  as  addressing  the 
screen,  note  that  mapdev( )  is  a  much 
better  solution  than  the  block  move 
we  introduced  earlier.  It  makes  it  pos¬ 
sible  to  read  or  write  any  region  of 
physical  memory  by  using  32-bit  point¬ 
ers  created  by  the  operating  system, 
without  invoking  special  functions  or 
creating  buffers  that  have  to  be  moved 
in  bulk. 

At  this  point,  you  should  have  a  good 
feel  for  what  memory  looks  like.  Figure 
2  shows  a  map  of  a  system  running  in 
protected  mode  under  a  DOS  extender 
without  virtual  memory  running  (the 
virtual  map  is  different). 

The  lowest  megabyte  looks  just  like 
any  other  real  map  with  the  exception 
that  an  area  of  the  map  between  the 
DOS  extender  and  its  I/O  buffer  have 
been  made  available  for  protected- 
mode  code  and  data  if  paging  is  en¬ 
abled  (the  default).  To  simplify  the  map, 
we  have  drawn  it  with  paging  disabled, 
which  places  the  start  of  the  protected 


code  and  data  segment  at  the  bottom 
of  the  first  megabyte.  Note  that  the 
code  and  data  of  the  protected-mode 
program  itself  looks  very  similar  to  an 
ordinary  small  model  program  with  the 
exception  that  this  segment  can  grow 
on  the  top.  Just  above  the  code  and 
data  is  an  area  identified  for  expansion 
of  the  address  space  using  the  mapdev 
function,  which  also  causes  selectors 
OCH  and  14H  to  grow.  Finally,  at  the 
top  of  the  map  we  find  the  Weitek 
segment. 

Register-Aliased  Variables 

At  this  point,  we  have  just  about  intro¬ 
duced  all  the  interface  tricks  except 
those  that  let  programs  running  in  real 
mode  access  protected-mode  programs, 
and  vice  versa.  These  types  of  accesses 
involve  writing  TSRs  and  passing  data 
back  and  forth  between  real  and  pro¬ 
tected  mode,  using  real  mode  buffers. 
Phar  Lap  does  a  good  job  of  explaining 
how  to  write  these  types  of  interfaces. 
Because  of  popular  demand,  we  have 
written  interfaces  between  the  NDP  run¬ 
time  environment  and  Media  Cybernet¬ 
ics’  Halo  and  Novell’s  BTrieve.  How¬ 
ever,  we  have  still  not  introduced  the 
piece  de  resistance  of  interface  tricks  — 


register-aliased  variables. 

Functions  such  as  int86,  int386,  outp, 
outpw,  inp,  and  inpw,  are  fine  for  pro¬ 
totyping  I/O  routines  that  interface  de¬ 
vices  directly  but,  in  the  end,  any  de¬ 
veloper  that  is  worth  their  salt  will 
choose  to  rewrite  these  routines  in  as¬ 
sembly  language.  The  reason  is  clear: 
Functions  such  as  int86  involve  the 
use  of  bulky  structures  and  have  to 
pass  through  as  many  as  40  lines  of 
code  every  time  they  are  called. 

In  searching  for  a  technique  to  speed 
up  this  operation,  we  chose  to  make 
two  simple  extensions  to  the  language: 

1.  Make  it  possible  to  specify  which 
register  a  register  variable  is  stored 
in. 

2.  Notify  the  asm  statement  about  which 
variables  were  read  and  written  on 
each  “call”  to  asm. 

These  two  tricks  make  it  possible  to 
declare  8-,  16-  and  32-bit  C  variables 
that  are  stored  in  particular  80386  regis¬ 
ters.  To  invoke  an  interrupt  by  using 
register-aliased  variables,  use  C  assign¬ 
ments  to  set  up  the  registers  and  then 
kick  off  the  function  with  an  asm  state¬ 
ment  that  contains  the  interrupt  being 
used. 


10000000:0  Top  of  address  space 


Mapdev  grows  segment 
as  necessary  above 
the  stack.  Uses 
paging  to  map  any 
physical  address 
into  program  segment 

Start  of  protected 
programs  when  paging 
is  disabled 
.  Paging  is  enabled  <*■ — - 


(640K) 

Available  for 
protected  programs, 
paging  is  enabled 


Figure  2:  Memory  map  of  a  system  running  in  protected  mode  under  a  DOS 
extender  without  virtual  memory  running 
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As  we  will  see,  what  results  is  pure 
poetry  and,  frequently,  much  better 
code  than  can  be  produced  by  an  ex¬ 
pert  assembly  language  programmer. 
A  person  writing  an  assembly  routine 
does  not  know  the  state  of  all  the  regis¬ 
ters  (that  is,  which  are  free  when  a 
procedure  is  called)  when  the  routine 
they  are  writing  is  called.  As  a  result, 
they  must  save  and  restore  all  registers 
used  (something  the  compiler  does  not 
have  to  do  as  the  compiler  has  a  com¬ 
plete  knowledge,  at  all  points  in  the 
program,  of  the  machine  for  which  it 
is  generating  code).  In  addition,  the 
assembly  routine  must  be  called,  possi¬ 
bly  getting  parameters  off  a  stack,  while 
the  register-aliased  routine  appears  in¬ 
line.  And,  as  you  know,  the  fastest  call 
is  no  call  at  all. 

The  ideal  use  of  register-aliased  vari¬ 
ables  is  in  advanced  graphics  adapter 
drivers  in  which  register  ports  must  be 
accessed  inline  and  in  sequence  with 
reads  and  writes  to  the  screen  buffer. 
The  difference  between  inline  code  and 
prototypes  that  use  C  to  access  the 
ports  is  very  noticeable. 

A  Sound  Generator 

The  example  presented  shortly  demon¬ 
strates  the  principles  and  provides  a 
sound( )  function  that  I  will  use  as  the 


basis  for  a  Basic-like  music  interpreter. 
The  program  in  Listing  One  (page  122) 
contains  a  general-purpose  sound  rou¬ 
tine  called  note( )  that  can  be  called 
with  a  pitch  and  duration.  The  pro¬ 
gram  works  by  controlling  the  8255 
timer  on  the  system  motherboard  and 
is  similar  to  the  program  in  the  IBM-PC 
ROM  BIOS.  The  traditional  Microsoft 
C  version  of  the  program  demonstrates 
the  principles  we  have  developed  ear¬ 
lier,  except  for  mapdev(  ). 

The  register-aliased  version  of  the 
same  program  is  shown  in  Listing  Two 
(page  122).  Note  that  we  have  defined 
a  couple  of  macros  at  the  head  which 
convert  outp( )  from  a  function  to  a 
macro,  and  that  we  have  created  a  new 
form  of  inp(  )  that  is  also  a  macro.  The 
benefit  of  these  macros  (over  the  func¬ 
tions)  is  that  they  are  almost  identical 
in  form  to  those  used  by  MS  C,  take 
up  much  less  space  than  function  calls 
in  the  generated  code,  and  execute 
inline  without  the  costly  overhead  of  a 
call  and  return. 

In  examining  the  code,  note  that  the 
source  is  virtually  identical  to  Listing 
One,  and  that  the  only  source  lines 
that  have  in  fact  changed  are  those  that 
invoke  the  two  interrupts  and  port  reads. 
The  technique  used  to  force  a  variable 
into  a  particular  register  is  a  simple 


extension  of  the  reg keyword,  followed 
by  the  register  to  be  used.  To  use  an 
8-  or  16-bit  section  of  a  32-bit  register, 
use  the  32-bit  register  name,  followed 
by  short  or  char ;  using  unsigned  as 
necessary.  Variables  that  have  the  same 
name  as  the  register  in  which  they  re¬ 
side  are  called  “register  aliased.” 

It  is  possible,  however,  to  overload 
variables,  and  in  this  demonstration  I 
have  deliberately  overloaded  eax,  de¬ 
claring  three  variables  ( al ,  x,  and  y)  to 
be  stored  in  al,  another  in  ax,  and 
another  in  ah.  (Note  that  ah  is  speci¬ 
fied  in  a  slightly  different  manner.)  None 
of  these  five  eax  components  are  ac¬ 
tive  at  the  same  time.  If  a  conflict  exists, 
the  compiler  spills  temporaries  to  the 
stack,  thus  signaling  us  to  change  our 
usage,  if  possible. 

Listing  Three  (page  122)  is  the  assem¬ 
bly  language  produced  by  the  com¬ 
piler  for  the  procedure  note( ).  The  code 
demonstrates  the  level  of  integration 
produced  by  the  use  of  register-aliased 
variables.  The  register  allocation  sum¬ 
mary  at  the  bottom  shows  that  all  of  the 
variables  in  the  program,  including  the 
register-aliased  variables,  are  allocated 
to  registers.  In  addition,  notice  that  the 
register-coloring  algorithm  used  by  the 
allocator  placed  six  variables  in  eax 
(this  includes  the  use  of  its  compo- 
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nents  al ,  ah,  and  ax),  in  addition  to 
using  eax  as  an  accumulator  in  three 
other  locations.  The  inline  assembly  is 
integrated  with  the  surrounding  C  code 
without  a  single  push  or  pop,  and  does 
not  require  the  use  of  structures  or  calls 
and  returns  to  handle  interrupts  and 
port  I/O. 


a . .  g[#,+,- 

,.,n]  the  notes  with  optional  extenders 

o  . .  0  n 

octave,  n  =  0  .  .  6 

> 

one  octave 

< 

go  down  an  octave 

1 .  .  Ln 

set  note  length  n  =  1  .  .  64 

p,P,r,R  n 

rests  of  length  n  =  1  .  .  64 

t,T  n 

set  tempo  n  =  32  .  .  255 

Table  1:  The  syntax  supported  by  the 
C  version  of  the  PLAY function 


In  particular,  examine  the  block  that 
starts  at  label  L13.  This  block  is  the  one 
that  polls  the  timer  until  it  is  time  to 
turn  off  the  note.  The  block  starts  off 
with  ax  being  used  as  an  argument  for 
the  timer  service  routine  01AH;  the  eax 
register  is  then  used  by  the  compiler 
as  a  temporary  accumulator,  which  is 
followed  by  al  being  used  to  service 
both  input  and  output  operations.  Of 
course,  ecx,  edx,  esi,  and  edi  (or  their 
components)  are  also  used  throughout 
the  12  lines  of  code.  In  fact,  the  only 
register  that  does  not  find  its  way  into 
this  sequence  is  ebx. 

The  resulting  code  is  about  one- 
third  the  size  of  a  similar  routine  that 
uses  calls.  However,  it  executes  sub¬ 


stantially  faster  than  the  mere  size  dif¬ 
ference  would  indicate,  as  most  of  the 
instructions  are  self-contained  in  the 
processor’s  registers.  The  issue  of  keep¬ 
ing  things  in  registers  becomes  even 
more  important  with  the  80486  which, 
even  though  it  has  a  built-in  cache,  has 
been  RISCed  to  execute  many  register- 
register  instructions  in  a  single  cycle. 
Taking  advantage  of  these  single  cycle 
operations  becomes  a  key  issue  with 
generating  80486  code.  In  addition,  fu¬ 
ture  generations  of  486  systems  will 
probably  increase  the  importance  of 
register  allocation  as  improved  proces¬ 
sor  speeds  (50  to  100  MHz)  outstrip  the 
ability  of  inexpensive  DRAM  memory 
to  keep  up  with  the  CPU. 

Conclusion 

To  wrap  things  up,  Listing  Four  (page 
122)  presents  the  play()  function.  The 
program  calls  note( ),  using  a  case  state¬ 
ment  to  parse  the  note  being  played 
or  the  command  being  executed.  The 
syntax  chosen  was  that  in  the  IBM  2.0 
Basic  manual.  The  elements  of  the  syn¬ 
tax  supported  are  shown  in  Table  1. 

The  command  is  only  a  partial  im¬ 
plementation  of  the  Basic  version.  Be¬ 
cause  the  current  implementation  of 
note( )  polls  the  timer,  play( )  will  not 
run  in  the  background.  If  you  plan  to 
use  this  function  as  part  of  a  game,  I 
recommend  that  you  turn  the  routine 
into  a  compiler  that  generates  a  list  of 
pitches  and  durations  that  get  fed  to  a 
TSR  interpreter  that  uses  the  timer  tick 
to  control  duration. 

One  final  problem  is  the  fact  that  C 
does  not  support  strings  in  strings.  The 
addition  of  legato  or  staccato  is  left  as 
a  reader  exercise. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 


(Listings  begin  on  page  122.) 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  8. 
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Listing  One  (Text  begins  on  page  22.) 

1 

{ $V- }  ( $F+]  {$0+}  {  Written  By:  Rick  Gessner,  1989.  } 

113! 

Inc(i)  else  Inc ( j , 2 ) ; 

2 

113: 

Inc  ( j) ; 

3 

Unit  HyprText; 

1141 

end; 

4 

{ - }  interface  { - } 

115: 

Determine  Actual  Line  Pos:=J; 

5 

ii6: 

end;  (Determine  actual  line  pos) 

6 

PROCEDURE  Help  Editor (FileName:  String); 

ii7: 

7 

PROCEDURE  Do  help (FileName :  String;  GoPage, HomePage:  Word); 

ns: 

t - 1 

8 

{ - }  Implementation  ( - } 

119: 

FUNCTION  Link  Count (Var  Line:  String):  Integer; 

9 

Uses  Crt; 

120 : 

Var  I, Count:  Integer;  (  Returns  2*#nulls  in  line,  used  to  convert  ) 

10 

121 : 

Begin  (  from  actual  byte  pos.  to  visual  byte  pos.,  ) 

11 

CONST  HelpColor  :  Array [False. .true]  of  Byte  = 

122: 

Count :=0;  (  during  data  input.  ) 

12 

(  Black*16+White,  (  for  normal  text) 

123: 

For  I:=l  to  Length (Line)  do 

13 

Magenta*16+Yellow) ;  {  for  hot-link  text.) 

124: 

If  Line[i]=Null  then  Inc (Count, 2) ; 

14 

NormalColor  :  Byte  =  Black*16+White;  {  draw  screen  info.) 

125: 

Link  Count : Count; 

15 

BoldColor  :  Byte  =  White*16+Black-Blink;  {  for  select  bar.) 

126: 

end;  (Link  count) 

16 

Header  :  String [50]  =  '  HyperText  System  [1.0]  '; 

127: 

1 - - - 1 

17 

MaxLinesPerPage  =  15; 

128: 

FUNCTION  Input  HelpPage (X, Y :  Byte;  Var  AHelpRec :  HelpRecord):  Char; 

18 

MaxLineWidth  =  57; 

129: 

Var  Ch  :  Char;  (  Main  editing  routine  in  this  system.  ) 

19 

130 : 

PageNum  :  Byte;  {  It  is  really  just  a  page-oriented  line  ) 

20 

PGUP  =  'I';  PGDN  =  'Q';  UpArrow  =  'H' ;  [Edit  keys] 

131 ; 

I,j,  (  editor  knows  how  to  jump  over  2-byte  ) 

21 

DnArrow  =  'P';  LArrow  =  'K' ;  RArrow  =  'M' ; 

132: 

LinePos,  (  hot-links.  ) 

22 

ESC  =  #27;  HomeKey  =  'G';  EndKey  =  'O'; 

133: 

RealLinePos,  (  If  you  add  editing  options,  take  ) 

23 

RETURN  =  AM;  BkSpc  =  #8;  NULL  =  #0; 

134: 

LineNum  :  Integer; (  the  embedded  hot-links  into  account!  ) 

24 

Tab  =  #9;  F2  =  '<';  DelKey  =  'S'; 

135: 

25 

Type  HelpRecord  =  Record  (The  main  structure  for  our  hypertext  files) 

136: 

PROCEDURE  Delete  Linked  Char (Var  Line:  String;  LinePos:  Integer); 

26 

HelpLines  :  Array [1 . .MaxLinesPerPage]  of  String [100]; 

137! 

Var  I, J:  Integer; 

27 

end;  (String  length  MUST  be  >  than  MaxLineWidth  to  store  hot-links!) 

138: 

Begin 

28 

Var  HelpRec  :  HelpRecord; 

139: 

LinePos :=Pred (Determine  Actual  Line  Pos (Line, LinePos) ) ; 

29 

HelpFile  :  File  of  HelpRecord; 

140 : 

f  Ord (Line [LinePos] ) >127  then  (Were  on  a  linked  item) 

30 

Alt, Ctrl, CommandKey  :  Boolean; 

141 

egin 

31 

i — - - - — i 

142: 

I :=LinePos; 

32 

FUNCTION  Make  String (Ch  :  Char;  Size  :  Integer)  :  String; 

143: 

While  ( (Ord (Line [ 1-1 ] ) >127)  and  (I>1) )  do  Dec(i); 

33 

Var  S:  string; 

144: 

J:=LinePos;  (Next  find  end  of  link) 

34 

Begin 

145: 

While  ( (Ord (Line [J+l] ) >127)  and  (I<Length (Line) ) )  do  Inc ( J) ; 

35 

S[0]  :=  Chr(Size);  (  Set  length  byte  =  SIZE.  ) 

146; 

Delete (Line, LinePos,  (Delete  all  of  item  +  link  if  necc.) 

36 

FillChar (S [1] , Size, Ch) ;  {  Fill  the  string  with  chr(CH).  ) 

147: 

1+ (2*Ord(J=I) ) ) ; 

37 

Make  String :=  S;  (  and  return  the  string  as  function) 

148: 

end; 

38 

end;  (Make  String  )  {  value.  ) 

i- - - - - 1 

149: 

end;  (Delete  linked  char) 

39 

150 : 

Begin 

40 

PROCEDURE  Draw  Box (topx, topy, botx, boty :  Byte;  Color, Width:  byte); 

151: 

Show  Help  Page (X, Y, AHelpRec) ;  (Display  this  page  ) 

41 

Type  BoxPos  =  (TopL, TopR, BotL, BotR, Top, Bot, LSide, RSide) ; 

152: 

LinePos :=1;  RealLinePos :=1;  (Now  do  a  little  init  stuff.) 

42 

Var  Y  :  Integer; 

153: 

LineNum :=1; 

43 

Const  Boxchar  :  Array [1 . .2, TopL. .RSide]  of  char  = 

154: 

With  AHelpRec  do  (Now  enter  main  edit  loop...) 

44 

((  'Z','?','@','Y','D','D','3','3'),  (ASCII  chars,  single  line  box  ) 

155: 

Repeat 

45 

(  ' I H M' ,' M' ;  (ASCII  chars,  double  line  box  } 

156: 

Show  HelpLine (X, Y+LineNum, 0, 0, HelpLines [LineNum] ) ; 

46 

Begin 

157: 

Gotoxy (X+LinePos-1, Y+LineNum) ; 

47 

TextAttr:=Color; 

158: 

Repeat  Ch:=Read  KeyBoard  Until  Ch  <>  Null; 

48 

If  Not  (Width  in  [1,2])  then  Width:=l;  (  Sure  width  value  is  OK?  } 

159: 

If  CommandKey  then 

49 

Gotoxy (TopX,TopY) ;  (  First,  draw  the  top  line  of  the  box...) 

160: 

Case  Ch  of 

50 

Write (  BoxChar (Width, TopL] +Make  String (BoxChar [width, top] , 

161 

AY  :  If  RealLinePos<=Length (HelpLines [LineNum] )  then 

51 

BotX-TopX-1) +BoxChar [Width, TopR] ) ; 

162: 

Begin  (  '"L  =  Delete  to  end  of  line.  } 

52 

For  Y:=TopY+l  to  BotY-1  do 

163: 

If  (RealLinePos=l)  then  HelpLines [LineNum] :=' ' 

53 

Begin  (  Second,  draw  the  middle  lines  of  the  box...} 

164: 

else 

54 

Gotoxy (TopX, Y) ; 

165: 

Begin 

55 

Write (  BoxChar [Width, LSide] , BoxChar [Width, RSide] : BotX-TopX) ; 

166: 

While  HelpLines [LineNum, RealLinePos] ONull  do 

56 

end; 

167: 

Delete (HelpLines [LineNum] , RealLinePos, 1) ; 

57 

GotoXY (TopX, BotY) ;  {  Third,  draw  the  bottom  line  of  the  box.  1 

168: 

If  HelpLines [LineNum, RealLinePos] =Null  then 

58 

Write  (  BoxChar [Width, BotL] +Make  String (BoxChar [width, top] , BotX-TopX-1)  + 

169: 

Delete (HelpLines [LineNum] , RealLinePos+2, 255) 

59 

BoxChar [Width, BotR] ) 

170 : 

end 

60 

end;  (Draw  Box) 

m : 

end; 

61 

i . — - - - - . . . . ) 

172: 

F2  :  Begin  {  F2  =  Add/Remove  hot-link.) 

62 

FUNCTION  Read  KeyBoard:  Char;  (Routine  to  get  keystrokes  from  user) 

173: 

J:=RealLinePos; 

63 

Const  CtrlMask  =  $04; 

174: 

While  (j>0)  and  (HelpLines [LineNum, j]<>'  ') 

64 

AltMask  =  $08; 

175: 

do  Dec( j) ; 

65 

Var  KBDFlag  :  Byte  Absolute  $0040 : $0017 ; 

176: 

Inc ( j) ; 

66 

Begin 

177: 

If  Ord (HelpLines [Linenum, j ] )  in  [28.. 127]  then 

67 

Read  KeyBoard :=ReadKey; 

178: 

Repeat  (Now  get  a  valid  page  #  to  jump  to...) 

68 

CommandKey  := ( (KBDFlag  AND  AltMask) <>0)  or  ((KBDFlag  AND  CtrlMask) <>0) ; 

179: 

Gotoxy (3, 24) ;  Write ('Link  Page:  '); 

69 

ALT  := (KBDFlag  AND  AltMask) <>0;  CTRL  :=  (KBDFlag  AND  CtrlMask) <>0; 

iso: 

Readln (PageNum) ; 

70 

If  KeyPressed  Then 

181 

Gotoxy (3, 24) ;  ClrEOL; 

71 

Begin 

182: 

Until  (PageNum>0)  and  (PageNum<256) ; 

72 

Read  Keyboard  :=  ReadKey;  (Just  in  case  user  pressed  modified  key) 

183: 

While  (HelpLines [LineNum, j ] <>'  ')  and 

73 

CommandKey  :=  True; 

184: 

( j<=Length (HelpLines [ LineNum] ) )  and 

74 

end; 

185: 

(HelpLines [LineNum, j]<>Null)  do 

75 

end;  (Read  Keyboard) 

186: 

Begin 

76 

i - - - - - 1 

187: 

HelpLines [ LineNum, j ] : =Chr (Ord (HelpLines 

77 

PROCEDURE  Show  HelpLine (X, Y, StartBold, EndBold:  Integer;  Var  Line:  String); 

188: 

[LineNum, j] ) +128) ; 

78 

Var  I , J :  Integer; 

189: 

Inc ( j) ; 

79 

PROCEDURE  Write  Char(Ch:  Char); 

190 : 

end; 

80 

Begin 

191 : 

If  Ord (HelpLines [LineNum, J-l ] )  in  [28.. 127]  then 

81 

If  Ord(Ch)>127  then  Ch:»Chr (Ord (Ch) -128) ;  (Clear  high  bit) 

192: 

Delete (HelpLines [LineNum] , J, 2)  else 

82 

If  Ord(Ch)>27  then  Write (Ch)  else  Inc(i); 

193: 

Insert (Null+Chr (PageNum) , HelpLines [LineNum] , j) ; 

83 

end; 

194: 

end; 

84 

Begin 

195: 

LArrow  :  If  RealLinePos>l  then  (Move  cursor  left  1  char) 

85 

TextAttr :=HelpColor [False] ; 

196: 

Begin 

86 

Window (X,Y, 59, Y) ;  ClrEOL;  Window(l, 1,80,25) ;  (Prepare  for  output) 

197: 

Dec (linePos) ; 

87 

Gotoxy (X,Y);  I:=l; 

198: 

RealLinePos :=Pred (Determine  Actual  Line  Pos 

88 

While  I<=Length (Line)  do  (Do  each  char  in  line) 

199: 

(HelpLines [LineNum] , LinePos) ) ; 

89 

Begin 

200: 

end; 

90 

TextAttr:=HelpColor [Ord(Line[i] ) >128 ] ;  (Set  proper  color) 

201: 

RArrow  :  If  RealLinePos<=Length (HelpLines [ LineNum] )  then 

91 

If  I  in  [StartBold. .EndBold]  then  TextAttr :=BoldColor; 

202: 

Begin  (Move  cursor  right  1  char) 

92 

Write  Char (Line [i] ) ; 

203: 

Inc (LinePos) ; 

93 

Inc (i) ; 

204: 

If  RealLinePos<Length (HelpLines [LineNum] )  then 

94 

end; 

205: 

Inc  (RealLinePos, 

95 

end;  (Show  helpline) 

206: 

1+Ord (HelpLines [LineNum, RealLinePos+1] =Null) *2) 

96 

, - ) 

207: 

else  Inc (realLinePos) 

97 

PROCEDURE  Show  Help  Page(X,Y:  Integer;  Var  HelpRec:  HelpRecord); 

208: 

end; 

98 

Var  I:  Integer; 

209: 

DnArrow:  If  LineNum<MaxLinesPerPage  then 

99 

Begin 

210: 

Begin  (Move  down  1  line.) 

100 

Window (X+l, Y+l, X+56, Y+MaxLinesPerPage+1) ;  ClrScr;  Window(l, 1,80,25) ; 

211: 

Inc (LineNum) ; 

101 

For  I:=l  to  MaxLinesPerPage  do 

212: 

If  LinePos<=Length (HelpLines [LineNum] )  then 

102 

Show  HelpLine (X, Y+I, 0, 0, HelpRec . HelpLines [ I ] ) ; 

213: 

RealLinePos :=Pred (Determine  Actual  Line  Pos 

103 

end;  (Show  help  page) 

214: 

(HelpLines [LineNum] , LinePos) ) 

104 

, - 1 

215: 

else 

105 

FUNCTION  Determine  Actual  Line  Pos(Var  Line:  String;  LinePos: 

216: 

Begin 

106 

Integer) :  Integer; 

217: 

RealLinePos :=Succ (Length (HelpLines [LineNum] ) )  ; 

107 

Var  I,J:  Integer;  (Convert  visual  edit  column  to  char,  position,) 

218 : 

LinePos :=RealLinePos-Link  Count (HelpLines [LineNum] ) ; 

108 

Begin  (by  skipping  over  embedded  hot  links.) 

219: 

end; 

109 

I : =0 ;  J:=l; 

220: 

end; 

110 

111 

While  ( J<=Length  (Line) )  and  (ioLinePos)  do 

Begin 

(Listing  continued  on  page  88) 

86 
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Listing  One  (Listing  continued,  text  begins  on  page  22.) 

221!  UpArrow:  If  LineNum>l  then  (Move  up  1  line.} 

222!  Begin 

223!  Dec (LineNum) ; 

224!  If  LinePos<=Length (HelpLines [LineNum] )  then 

225 !  RealLinePos :=Pred (Determine_Actual_Line_Pos 

226 !  (HelpLines [LineNum] , LinePos) ) 

227!  else 

228!  Begin 

229 !  RealLinePos :=Succ (Length (HelpLines [LineNum] ) ) ; 

230!  LinePos :=RealLinePos-Link_Count (HelpLines [LineNum] ) ; 

231!  end; 

232 !  end; 

233!  HomeKey:  Begin  (Move  to  1  char,  in  line.} 

234!  LinePos :=1; 

235!  RealLinePos :=LinePos; 

236!  end; 

237!  EndKey  :  Begin  (Move  to  end  of  line.) 

238 !  RealLinePos :=Succ (Length (HelpLines [LineNum] ) ) ; 

239!  LinePos :=RealLinePos-Link  Count (HelpLines [LineNum] ) ; 

240!  end; 

241!  DelKey  :  If  (RealLinePos<=Length (HelpLines [LineNum] ) )  then 

242!  Begin  (Delete  a  character.} 

243!  If  (HelpLines [LineNum, RealLinePos] )  in  ['  '..'l'] 

244!  then  Delete (HelpLines [LineNum] , RealLinePos, 1)  else 

245 !  Delete_Linked_Char (HelpLines [LineNum] , LinePos) ; 

246!  RealLinePos : =Pred (Determine_Actual_Line_Pos 

247 !  (HelpLines [LineNum] , LinePos) ) ; 

248!  end; 

249 !  end  else 

250!  Case  Ch  of 

251!  Return:  If  LineNum<MaxLinesPerPage  then  (Move  down  1  line.} 

252 !  Begin 

253!  Inc (LineNum) ;  LinePos:=l;  RealLinePos :=1; 

254!  end; 

255!  Tab  :  Begin  (Tab  right  10  chars.} 

256!  If  RealLinePos+10<=Length (HelpLines [LineNum] ) +1  then 

257!  Inc (RealLinePos, 10)  else 

258!  RealLinePos :=Length (HelpLines [LineNum] )+l; 

259!  LinePos :=RealLinePos-Link_Count (HelpLines [LineNum] ) ; 

260!  end; 

261!  BkSpc  :  If  RealLinePos>l  then  (Backspace  over  prev.  char.) 

262!  Begin 

263!  If  HelpLines [LineNum, RealLinePos-1]  in  ['  '..'}']  then 

264!  Begin 

265 !  Delete (HelpLines [LineNum] , RealLinePos-1, 1) ; 

266!  Dec (RealLinePos) ; 

267!  Dec (LinePos) 

268 !  end  else 

269!  Begin 

270 !  Delete_Linked_Char (HelpLines [LineNum] , LinePos-1) ; 

271!  Dec (LinePos) ; 

272 !  RealLinePos :=Pred (Determine_Actual_Line_ 

273 !  Pos (HelpLines [LineNum] , LinePos) ) ; 

274!  end; 

275!  end; 

276!  ''..'}':  If  Length (HelpLines [LineNum] ) <MaxLineWidth  then 

277!  Begin  (Insert  a  valid  Ascii  char.} 

278!  If  (Ord (HelpLines [LineNum, RealLinePos] ) >127)  and 

279!  (RealLinePos<=Length (HelpLines [Linenum] ) )  then 

280!  Ch:=Chr (Ord (Ch) +128) ; 

281 !  Insert (Ch, HelpLines [LineNum] , RealLinePos) ; 

282!  Inc (RealLinePos) ; 

283!  Inc (LinePos) ;  Ch:=#255; 

284!  end; 

285!  end; 

286!  Until  CH  in  [ESC, PGUp, PgDn] ;  (ESC=Quit;PGUp=Prev  page;PgDn=Next  Page.) 
287!  Input_HelpPage:=Ch; 

288!  end;  (Input  helppage} 

289!  { - } 

290!  FUNCTION  Read_Helprec (Var  AHelpRec rHelpRecord;  RecNum: Integer) : Integer; 
291!  Var  I  :  Integer; 

292!  Begin 

293!  FillChar (AHelprec, SizeOf (AHelprec) , 0) ;  ($1-}  (Hyperdata  file  read  rec) 

294!  If  FileSize (HelpFile) <RecNum  then  exit;  (routine.  Includes  just  } 

295!  Seek (helpfile, RecNum-1) ;  (enough  error  checking  ) 

296!  Read (helpfile, AHelpRec) ;  (to  be  considered  safe.  } 

297!  Read_HelpRec : =I0Result ;  ($1+) 

298!  end;  (Read  helprec} 

299!  { - ) 

300!  FUNCTION  Write_HelpRec (Var  AHelpRec rHelpRecord;  RecNum: Integer) : Integer; 
301!  Begin  ($1-} 

302!  Seek (helpfile, RecNum-1) ;  (Hyperdata  file  write  rec  routine.) 

303!  Write (helpfile, AHelpRec) ;  {$1+}  (This  routine  also  contains  just  } 

304!  Write_HelpRec:=IOresult;  (enough  error  checking  to  be  } 

305!  end;  (Write  helprec}  (considered  safe.  } 

306!  { - 1 

307!  FUNCTION  Open_HelpFile (FileName :  String):  Integer; 

308!  Var  result:  Integer; 

309!  Begin 

310!  Assign (HelpFile, FileName) ;  ($1-}  (Opens  hyperdata  file  specified} 

311!  Reset (HelpFile) ;  (as  "FileName".  If  the  file  } 

312!  result :=IOResult;  (doesnt  exist,  then  it  will  be  } 

313!  If  Result=2  then  (created.  } 

314!  Begin  (Error  checking  is  limited,  but} 

315!  Rewrite (HelpFile) ;  (enough  to  be  safe.  } 

316!  Result :=IOResult; 

317!  end; 

318!  Open_HelpFile :=Result; 

319!  end;  (open  helpfile} 

320!  { - } 

321!  PROCEDURE  Help  Editor (FileName :  String); 

322!  Const  HelpMsgs  =  13; 

323!  HelpData  :  Array [1 . .HelpMsgs]  of  String[17]  = 

324!  (  'Editing  Keys:  ',  ' - ', 

325!  ' F2  :  Link  (+/-)',  ' AY  :  Del  EOLine' , 

326!  'Bkspc:  Del  left',  'Del  :  Del  char', 

327!  Chr (10)+' Movement  keys:  ',  ' - ', 

328!  Chr (24) +Chr (25) +Chr (27) +Chr (26) +' ,  ' +Chr (17) +Chr (217) +' , ' , 

329!  'Tab,  Home,  End',  'PgUp  :  Prev  page', 

330!  'PgDn  :  Next  page',  Chr (10)+' ESC  to  quit.'); 

331!  Var  I, HelpRecNum:  Integer; 
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(Open  the  specified  file.} 
(Continue  only  if  no  error.} 


AHelpRec  :  HelpRecord; 

Ch  :  Char; 

Result  :  Integer; 

Begin 

Result :=Open_HelpFile (FileName) ; 

If  Result=0  then 
Begin 

TextAttr  :=  Norma IColor; 

Draw_Box (1,  3,  80,  23,  NormalColor, 1) ; 

Draw_Box(2, 4, 60, 22, NormalColor, 2) ; 

Gotoxy (61, 4) ; 

For  I:=l  to  HelpMsgs  do 
Begin 

Gotoxy (62, WhereY+1) ;  Write (HelpData [i] ) ; 

end; 

HelpRecNum :=1; 

Gotoxy (40- (Length (Header)  div2),3);  Writeln (Header) ; 

Gotoxy (4, 2);  Writeln (' File :  ', FileName); 

Repeat 

Gotoxy (4, 4);  Writeln ('  Reading  '); 

Result :=Read_HelpRec (AHelpRec, HelpRecNum) ; 

Gotoxy (4, 4);  Writeln (' Page:  ', HelpRecNum: 3) ; 

Ch : =Input_HelpPage (3,4, AHelpRec ) ; 

Result : =Write_HelpRec (AHelpRec, HelpRecNum) ; 

Gotoxy (4, 4);  Writeln ('  Writing  '); 

Case  Ch  of 

PgUp  :  If  helpRecNum>l  then  Dec (HelpRecNum) ; 

PgDn  :  If  HelpRecNum  <  255  then  Inc (HelpRecNum) ; 

end; 

Until  Ch=ESC; 

end  else  (Report  the  opening  error _ } 

Writeln (' ERROR:  ', Result,'  opening  ', FileName, ' .  Unable  to  continue.'); 
($1-}  Close (HelpFile) ;  Result :=IOresult;  ($1+} 
end;  (Help  editor) 

I - } 

FUNCTION  Find_Next_Link (  Var  X,Y:  Integer;  EndX,EndY:  Integer; 

Var  AHelpRec:  HelpRecord) :  Boolean; 

Var  OrigX,OrigY,Col,  (Recursive  routine  used  to  find  a  } 

Row, Started, StopCol:  Integer;  (hot-link  on  the  page  after  the  } 

Begin  (current  page  position  (X,Y).  } 

Find_Next_Link:=False; 

(First,  search  from  current  pos  to  end  of  page...} 

For  Row:=Y  to  EndY  do 
Begin 

If  RowOY  then  StartCol:=l  else  Started :=X; 

If  RowOEndY  then  StopCol  :=Length(AhelpRec. HelpLines  [Row] ) 
else  StopCol :=EndX; 

If  AhelpRec .HelpLines [Row] <>' '  then 
For  Cd:=StartCd  to  StopCol  do 

If  (AHelpRec. HelpLines [Row, Col] =Null)  then 
Begin 

Find_Next_Link : =True; 

X:=Col;  Y:=Row; 

Exit;  (make  a  quick  getaway!} 

end; 

end; 

(ok,  search  from  top  of  page  to  the  startpos} 

If  X+Y>2  then 
Begin 

Col :=1;  Row:=l; 

If  Find_Next_link (Col, Row, Pred (X) ,Y,AHelpRec)  then 
Begin 

X:=Col;  Y:=Row;  Find_Next_Link:=true; 

end 

end; 

end;  (find  next  link) 

1 - } 

FUNCTION  Find_Prev_Link (  Var  X,Y:  Integer;  EndX,EndY:  Integer; 

Var  AHelpRec:  HelpRecord) :  Boolean; 

Var  0rigX,0rigY,Cd,  (Recursive  routine  used  to  find  a  } 

Row,  Started,  StopCol :  Integer;  (hot-link  on  the  page  prev.  to  the} 
Begin  (current  page  pos.  (X, Y) .  } 

Find_Prev_Link:=False; 

(First,  search  from  current  pos  to  top  of  page...} 

For  Row:=Y  downto  1  do 
Begin 

StopCol :=1; 

If  RowOY  then  StartCol  :=Le.ngth  (AhelpRec  .HelpLines  [Row] ) 
else  StartCol :=X; 

If  AhelpRec. HelpLines [Row] o' '  then 
For  Col:=StartCol  downto  StopCol  do 

If  (AHelpRec. HelpLines [Row, Col]=Null)  then 
Begin 

Find_Prev_Link:=True; 

X:=Cd;  Y :  =Row ; 

Exit;  (make  a  quick  getaway! } 

end; 

end; 

(ok,  search  from  bottom  of  page  to  the  startpos} 

If  X+Y>2  then 
Begin 

Row : =MaxLinesPerPage  ; 

Col :=Length (AHelpRec .HelpLines [Row] ) ; 

If  Find_Prev_link (Col, Row, Succ (X) , Y, AHelpRec)  then 
Begin 

X:=Col;  Y:=Row;  Find_Prev_Link:=true; 

end 

end; 

end;  (find  prev  link} 

I - } 

PROCEDURE  Do_Help (FileName:  String;  GoPage, HomePage :  Word); 

Const  XPos  =  10; 

YPos  =  5; 

Color  :  Byte  =  Black*16+White; 

MaxStackSize  =  25; 


Type 


StackRec  =  Record 
Page  :  Byte; 
Row, 


(This  is  the  hypertext  engine.} 
(This  routine  is  used  to  read  } 
(and  navigate  through  a  data  } 
(file,  speefied  as  "FILENAME".} 
(GoPage  specifies  the  starting} 
(page  to  display,  and  HomePage} 


( Listing  continued  on  page  90) 
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listing  One  (Listing  continued,  text  begins  on  page  22.) 

441 

Col  :  Integer;  {is  used  to  specify  an  main  ) 

4421 

end;  {index  (or  home)  page.  } 

4431 

Var 

Result  :  Integer; 

444  : 

Stack  :  ArraylO. .MaxStackSize]  of  StackRec; 

445: 

AHelpRec :  HelpRecord; 

446: 

Ch  :  CHar; 

4471 

StackLvl:  Byte; 

448: 

Started:  Integer; 

449', 

Linked, 

450 : 

Load  :  Boolean; 

451 

FUNCTION  Pop  Stack:  Byte;  {Pop  the  top  page  info  (Stack)  record} 

452! 

Begin 

4531 

If  StackLvl>l  then 

4541 

Begin 

455: 

Dec (StackLvl) ; 

456: 

Load:=True; 

457: 

end; 

4581 

Pop  Stack :=StackLvl; 

459: 

end;  {pop  stack} 

460 : 

FUNCTION  Push  Stack (PageNum:  Byte):  Byte; 

461 : 

Begin  {Push  a  page  info  (stack)  record.} 

462: 

Inc (StackLvl) ; 

463: 

Stack [StackLvl] .Page:=PageNum; 

464: 

Stack [StackLvl] .Col:=l; 

465: 

Stack [StackLvl] .Row:=l; 

466: 

Push  Stack:=StackLvl; 

467: 

end;  {push  stack) 

468: 

Begin 

469: 

If  GoPage=0  then  GoPage:=l;  {Make  sure  GoPage  is  valid.) 

470 : 

Result :=Open  HelpFile (FileName) ; 

471 : 

If  Result=0  then 

472: 

Begin 

473: 

Load :=t rue; 

474: 

TextAttr  :=Color; 

475: 

Draw  Box (Xpos, YPos, XPos+59, YPos+MaxLinesPerPage+2, NormalColor, 2) ; 

476: 

FillChar (Stack, SizeOf (Stack) ,  0) ; 

477: 

StackLvl  :=  0; 

478; 

If  Homepage  in  [1..255]  then  StackLvl :=Push  Stack (HomePage) ; 

479: 

If  (GoPage  in  [1..255])  and  (GoPageOHomePage)  then 

480 : 

StackLvl :=Push  Stack(GoPage) ; 

481 : 

GotoXY(XPos+29- (Length (Header)  div  2), YPos); 

482: 

Writeln (Header) ; 

483: 

Repeat 

484  : 

With  Stack [StackLvl]  do 

485: 

Begin 

486: 

If  Load  then  {System  needs  new  hyperdata  file  page.) 

487: 

Begin 

488: 

Result :=Read  HelpRec (AHelpRec, Page) ; 

489: 

Show  Help  Page (XPos+1, YPos, AHelpRec) ; 

490 : 

Gotoxy (XPos+51, YPos+MaxLinesPerPage+2) ; 

491 : 

If  StackLvl>l  then  Write (' Esc, PgUp' )  else 

492: 

Write ('Esc=Quit' ) ; 

493: 

Linked :=Find  Next  Link (Col, Row, 80, MaxLinesPerPage, 

494: 

AHelpRec) ; 

495: 

Load:=False; 

496: 

end; 

497: 

If  Linked  then  {We  have  a  hot-link  to  show,  so  do  it.) 

498: 

Begin 

499: 

Started  :=  Col; 

500 : 

While  Ord (AHelprec .HelpLines [Row, StartCol-1] ) >127 

501 : 

do  Dec  (Started) ; 

502: 

Show  HelpLine  (XPos+1 ,  YPos+Row,  Started,  Pred (Col ) , 

503: 

AHelpRec. HelpLines [Row] ) ; 

504! 

end; 

505: 

Repeat  Ch:=Read  KeyBoard  until  ChoNull; 

506: 

Show  HelpLine (XPos+1, YPos+Row, 0, 0,  AHelpRec. HelpLines [Row] ) ; 

507: 

Case  Ch  of  {Now  handle  navigation...} 

508! 

RArrow, 

509: 

Tab  :  Begin 

510 : 

Inc (Col) ; 

511 : 

Linked:=Find  Next  Link (Col, Row, 80, 

512: 

MaxLinesPerPage, AHelpRec) ; 

513: 

end; 

514: 

Return  :  If  Linked  then 

515: 

Begin 

516: 

Load :=t rue; 

517: 

If  (StackLvl>l)  and 

518! 

(Stack [StackLvl-1 ] .Page= 

519: 

Ord(AHelpRec.HelpLines[Row,Col+l] ) )  then 

520 : 

StackLvl :=Pop  Stack  else 

521 : 

StackLvl :=Push  Stack (Ord (AHelpRec. HelpLines 

522: 

[Row, Col+1 ] ) ) ; 

523: 

end; 

524: 

LArrow  :  Begin 

525: 

Dec (Col) ; 

526: 

Linked:=Find  Prev  Link (Col,  Row, 1, 1, AHelpRec) ; 

527! 

end; 

528: 

DnArrow:  Begin 

529: 

Col :=1; 

530 : 

If  Row<MaxLinesPerPage  then  Inc (Row)  else  Row:=l; 

531 : 

Linked:=Find  Next  Link (Col, Row, 80, 

532: 

MaxLinesPerPage, AHelprec) ; 

533: 

end; 

534: 

UpArrow:  Begin 

535: 

If  Row>l  then  Dec (Row)  else  Row:=MaxLinesPerPage; 

536: 

If  Col<Length (AHelpRec. HelpLines [Row] ) 

537: 

then  Inc (Col); 

538: 

Linked:=Find  Prev  Link (Col, Row, 1, l,Ahelprec) ; 

539: 

end; 

540 : 

PgUp  :  StackLvl :=Pop  Stack; 

541 : 

PgDn  :  Begin  (Let  programmer  set  this!)  end; 

542: 

end; 

543: 

end; 

544  : 

Until  Ch=ESC; 

545: 

end 

else 

546: 

Writelnf' ERROR:  Result,'  opening  ' , FileName, ' .  Unable  to  continue.'); 

547! 

($1- 

}  Close (HelpFile) ;  result :=IOResult;  {$1+} 

548: 

549: 

end 

(do  help) 

550 : 

Begin  (No  init  code  required} 

551 : 

end 

End  Listing 
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Listing  One  (Text  begins  on  page  34.) 

/* - 

Demonstrates  basic  principles  of  hypertext 
document  construction  and  management. 

(c)  Copyright  1989  Todd  King 
All  Rights  Reserved 
Written:  Todd  King 

- */ 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  <conio.h> 

♦include  <ctype.h> 

♦include  "hyper_d.h" 

main  () 

{ 

int  n; 
clrscr () ; 

printf("(c)  Copyright  1989  Todd  King.  All  Rights  ReservedXn") ; 
sleep (2) ; 

if ( (Hyper_fptr  =  f open ("HYPER.TXT",  "r"))  ==  NULL) 

{ 

perror ("fopen") ; 
exit  (1) ; 

} 

build_hyperbase  ()  ; 
n  =  0; 

while ( (n  =  enter_text (Hyperbase [n] .tag) )  !=  -1)  ; 
clrscr  () ; 

fclose (Hyper_fptr) ; 


/* - 

Builds  the  global  index  data  base  for  the 
hypertext  document. 

Written:  Todd  King 

- */ 

build_hyperbase () 

{ 

char  buffer [MAX_HYPER_LINE] ; 

HYPERITEM  *hitem; 
int  n; 

for (; ; ) 

( 

if  (fgets  (buffer,  sizeof (buffer) ,  Hyper_fptr)  ==  NULL) 

{ 

_ bptr  =  fgets (buffer,  sizeof (buffer) ,  Hyper_fptr); 

textcolor (LIGHTGRAY) ; 
gotoxy (1, 24) ; 

cputs ("ESCAPE:  to  exit;  UP  ARROW,  DOWN  ARROW:  to  navigate"); 
gotoxy (1, 1) ; 

cputs (tag);  cputs ("\r\n") ;  cputs ("\r\n") ; 

while  (bptr  !=  NULL)  /*  For  all  lines  in  the  current  hypercard  */ 

{ 

col_cnt  =  1; 

for(i  =  0;  i  <  Hyper_cnt;  i++) 

( 

if((pptr  =  strstr(bptr,  Hyperbase [i] .tag) )  !=  NULL) 

{ 

if (  i  ==  hidx)  continue;  /*  no  self-referencing  */ 
if (pptr  !=  bptr) 

{ 

if ( lispunct (* (pptr  -  1))  6&  ! isspace (* (pptr  -  1)))  continue; 

) 

tptr  =  pptr  +  strlen (Hyperbase[i] .tag) ; 

if (ispunct (*tptr)  ! !  isspace (*tptr)  I!  *tptr  ==  '\0') 

{ 

/*  Deliniator  */ 

}  else  {  /*  No  good  */ 

continue; 

} 

/*  If  we  reach  here  we've  found  a  genuine  tag  */ 
pptrfO]  ='\0'; 
col_cnt  +=  strlen (bptr) ; 
hyper_ref [ref_cnt] . line  =  line_cnt; 
hyper_ref [ref_cnt] .column  =  col_cnt; 
hyper_ref [ref_cnt] .tag  =  Hyperbase[i] .tag; 
cputs (bptr) ; 
textcolor (YELLOW) ; 
cputs (Hyperbase [i] .tag)  ; 
textcolor (LIGHTGRAY)  ; 
bptr  =  pptr  +  strlen (Hyperbase [i] .tag) ; 
col_cnt  +=  strlen(Hyperbase[i] .tag) ; 
ref_cnt++; 

) 

) 

cputs (bptr) ; 
cprintf ("\r") ; 

if (line_cnt  >=  23)  {  /*  What  to  do  at  the  end  of  a  screen  */ 

break; 

) 

bptr  =  fgets (buffer,  sizeof (buffer) ,  Hyper_fptr) ; 
if (buffer [0]  ==  '\f')  bptr  =  NULL; 
line_cnt++; 
col_cnt  =  0; 

} 

if((n  =  nav_ref (hyper_ref ,  ref_cnt) )  >=  0)  return (n) ; 


break; 

} 

switch (buffer [0] ) 

{ 

case  ' \f ' : 

if ( (hitem  =  make_item())  ==  NULL) 

{ 

fprintf (stderr,  "No  more  room  in  the  Hyperbase\n") ; 
exit(0); 

} 

fgets (buffer,  sizeof (buffer) ,  Hyper_fptr) ; 
n  =  strlen (buffer) ; 

if (buffer [n  -  1]  ==  ' \n' )  buffer [n  -  1]  =  '\0'; 
set_tag (hitem,  buffer); 
set_position (hitem,  ftell (Hyper_fptr) ) ; 
break; 

} 

} 

return (Hyper_cnt) ; 

} 

/* - 

Enters  the  hypertext  document  at  a  specific 
tag  location.  It  then  allows  navigation  within 
the  document. 

Written:  Todd  King 

- */ 

enter_text (tag) 
char  tag [ ] ; 

{ 

int  c,  n; 

HYPERITEM  *hitem; 
char  *bptr; 
char  *pptr; 
char  *tptr; 
int  i; 

char  buffer [MAX_HYPER_LINE] ; 

int  line_put; 

int  line_cnt  =  3; 

int  col_cnt  =  0; 

int  ref_cnt  =  0; 

int  hidx; 

HYPER_REF  hyper_ref [MAX_HYPER] ; 

hitem  =  find_item(tag) ; 

if (hitem  ==  NULL) 

( 

fprintf (stderr, 

"No  hypertext  subject  by  the  name  of  '%s'  exists\n",  tag) ; 
return (-1)  ; 

) 

hidx  =  hyper_idx (tag) ; 
clrscr () ; 

fseek  (Hyper  fptr,  hitem->position,  SEEK  SET); 
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The  function  that  performs  the  actual 
navigation  within  a  hypertext  document. 
Written:  Todd  King 


- */ 

nav_ref (hyper_ptr ,  max_ref) 

HYPER_REF  hyper_ptr[]; 
int  max_ref; 

1 

int  advance  =  0; 
int  selected  =  -1; 
int  cur_ref  =  0; 

for ( ; ; ) 

{ 

cur_ref  +=  advance; 

if (cur_ref  <  0)  cur_ref  =  max_ref  -  1; 
if(cur_ref  >=  max_ref)  cur_ref  =  0; 
advance  =  0; 

gotoxy (hyper_ptr [cur_ref ] .column,  hyper_ptr [cur_ref ] .line) ; 

textbackground(LIGHTGRAY) ; 

textcolor (BLACK) ; 

cputs (hyper_ptr [cur_ref ] .tag) ; 

switch (getch () ) 

{ 

case  0: 

switch (getch () ) 

{ 

case  DOWN_ARROW : 
advance  =  1; 
break; 

case  UP_ARROW : 
advance  =  -1; 
break; 

} 

break; 
case  ' \r' : 
case  ' \n' : 

selected  =  cur_ref; 

break; 
case  ESC: 

textbackground (BLACK)  ; 
textcolor (LIGHTGRAY) ; 
return (-1) ; 

} 

gotoxy (hyper_ptr [cur_ref] .column,  hyper_ptr (cur_ref ] .line)  ; 

textcolor (YELLOW)  ; 

textbackground (BLACK)  ; 

cputs (hype r_ptr[cur_ref] .tag) ; 

if (selected  !=  -1)  return (hyper_idx(hyper_ptr (selected] .tag) ) ; 

) 

} 

/* - 

Determines  the  index  of  a  hypertext  tag 
within  the  global  database. 

Written:  Todd  King 

- - _*/ 

hyper_idx (tag_str) 
char  tag_str[]; 

( 

int  i; 

for(i  =0;  i  <  Hyper_cnt;  i++)  { 

if (strcmp(tag_str,  Hyperbase [i] .tag)  ==  0)  return(i); 

) 

return (-1) ; 


/* - 

Locates  an  item  in  the  global  database 
with  the  tag  as  a  key.  Returns  a  pointer 
to  the  entry  or  NULL  if  one  does  not  exist. 
Written:  Todd  King 

- */ 

HYPERITEM  *f ind_item (tag) 
char  tag[ ] ; 

( 

HYPERITEM  *hitem; 
int  i; 

for(i  =0;  l  <  Hyper_cnt;  i++) 

( 

hitem  =  SHyperbase ( i ] ; 

if (strcmp (tag,  hitem->tag)  ==  0)  return (hitem) ; 

) 

return (NULL) ; 


/* - 

Sets  the  tag  portion  of  a  database  entry  to 
the  contents  in  a  passed  string 
Written:  Todd  King 

- */ 

set_tag (hitem,  buffer) 

HYPERITEM  *hitem; 
char  buffer [ ] ; 

( 

char  *malloc(); 

hitem- >tag  =  malloc (strlen (buffer)  +1); 
if (hitem->tag  ==  NULL) 

{ 

perror ( "malloc" )  ; 
exit (2) ; 

} 

strcpy (hitem->tag,  buffer) ; 


(Listing  continued  on  page  94) 
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HYPE  RTEXT  ENGINE 


Listing  One  (Listing  continued,  text  begins  on  page  34.) 

/* - 

Makes  (extracts)  a  new  database  entry  item 
from  the  item  pool. 

Written:  Todd  King 

- */ 

HYPERITEM  *make_item() 

( 

if (Hyper_cnt  >=  MAX_HYPER)  return (NULL) ; 
return (SHyperbase [Hyper_cnt++] ) ; 


Listing  Two 

♦define  UP_ARROW  72 

♦define  DOWN_ARROW  80 

♦define  ESC  27 

typedef  struct  { 
char  *tag; 
int  position; 

1  HYPERITEM; 

typedef  struct  { 
int  line; 
int  column; 
char  *tag; 

)  HYPER_REF; 

♦define  MAX_HYPER  1024 

HYPERITEM  Hyperbase [MAX_HYPER] ; 
int  Hyper_cnt  =  0; 

FILE  *Hyper_fptr; 

HYPERITEM  *make_item ( ) ; 

HYPERITEM  *find_item() ; 

♦define  set_position (h,  p)  h->position  =  p 

♦define  TRUE  1 
♦define  FALSE  0 

♦define  MAX_HYPER_LINE  80 

Listing  Three 


End  Listing  One 


End  Listing  Two 


Function  Flow  Diagram 

main()  build_hyperbase ()  make_item() 

set_tag () 
set_position () 

enter_text()  find_item() 

hyper_idx () 
nav_ref () 


main () 

This  is  an  application  that  displays  a  hypertext  document. 

It  automatically  creates  a  list  of  hyper-items  (or  cards) 
that  are  in  the  hypertext  document.  Then  it  creates  the 
appropriate  links  so  that  you  can  navigate  to  any  item 
that  is  referenced  by  any  other  item.  It  uses  the  contents 
of  the  file  "HYPER.TXT"  as  the  hypertext  document  and  begins 
at  the  first  item  in  the  document. 


Function  Flow  Diagram 


build_hyperbase () 
build_hyperbase ( ) 

This  function  builds  the  global  database  for  the  hypertext 
document.  It  scans  the  entire  document  and  assembles  a  list 
of  all  cards  in  the  document  and  stores  their  location 
within  the  file  and  the  tag,  which  the  card  is  to  be  known 
by.  This  database  is  stored  in  the  global  variable 
"Hyperbase" . 


Function  Flow  Diagram 


enter_text ( ) 

enter_text (tag) 
char  tag[] ; 

Enters  the  hypertext  document  at  a  specific 
tag  location.  The  tag  (a  string)  is  passed  in  the  variable 
first  variable  called  "tag".  It  then  allows  navigation 
within  the  document. 


Function  Flow  Diagram 


nav_ref  () 

nav_ref (cur_ref ,  hyper_ptr,  max_ref) 
int  cur_ref; 

HYPER_REF  hyper_ptr [ ] ; 
int  max_ref; 
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This  function  performs  the  actual  navigation  within  a 
single  card.  It  returns  the  index  of  the  hyper-item  within 
the  card  which  was  selected.  A  special  code  (-1)  is  returned 
if  a  request  to  exit  is  entered.  "cur_ref"  is  the  index  of 
the  current  card,  "hyper_ptr"  is  a  pointer  to  a  structure 
containing  the  list  of  references  in  the  card  and  "max_ref 
is  the  number  of  references  in  "hyper_ptr". 


Function  Flow  Diagram 


hyper_idx () 

hyper_idx (tag_str) 
char  tag_str(); 

Returns  the  index  of  the  tag  "tag_str" .  The  global 
database  {"Hyperbase")  is  searched  for  the  existence  of 
the  tag. 


Function  Flow  Diagram 


find_item() 

HYPERITEM  *f ind_item (tag) 
char  tag ( ] ; 

Locates  an  item  in  the  global  database  ("Hyperbase") 
with  the  tag  as  a  key.  Returns  a  pointer 
to  the  entry  or  NULL  if  one  does  not  exist. 


Function  Flow  Diagram 


set_tag() 

set_tag (hitem,  buffer) 

HYPERITEM  *hitem; 
char  buffer [ ] ; 

Sets  the  tag  portion  of  the  database  entry  pointed 
to  by  "hitem"  to  the  contents  in  the  string  "buffer". 


Function  Flow  Diagram 


make_item() 

HYPERITEM  *make_item() 

Makes  a  new  database  entry.  Actually  it  extracts 

the  next  available  entry  for  a  pool  and  returns  a  pointer 

to  the  entry. 


Function  Flow  Diagram 


set_position () 

set_position (h,  p) 

HYPERITEM  *h; 
int  p; 

Actually  a  psuedofunction  (created  with  a  define)  which 
assigns  an  location  of  an  item  in  a  file  to  the  item 
definition . 


Function  Flow  Diagram 


HYPERITEM 

A  structure  that  contains  a  complete  description  a  single 
item  (or  card)  with  the  hypertext  document.  It  is  of  the 
form: 

typedef  struct 
char  *tag; 
int  position; 

}  HYPERITEM; 


Function  Flow  Diagram 


HYPER_REF 

A  structure  of  the  form: 

typedef  struct  { 
int  line; 
int  column; 
char  *tag; 

|  HYPER_REF; 


Function  Flow  Diagram 


HYPER.TXT 

The  text  file  that  contains  the  hypertext  document.  The 
beginning  of  an  item  is  marked  by  a  special  line.  This  line 
is  a  formfeed  followed  by  a  newline.  The  next  line  after 
this  is  considerd  to  be  the  name  of  the  item  (the  item  tag) . 
If  this  name  appears  in  any  other  tag  then  navigation  to 
the  item  is  allowed  by  selecting  the  tag  in  the  item. 


Function  Flow  Diagram 

End  listings 


Dr.  Dobb  s  Journal,  June  1990 

534 


Listing  One  (Text  begins  on  page  50.) 


/*  FILETEST.HPP  Written  by  Kevin  D.  Weeks  Released  to  the  Public  Domain  */ 

#ifndef  FILESPEC_HPP  //  prevent  multiple  #includes 

♦define  FILESPEC_HPP 


♦include  <stdio.h> 

♦define  ERR  -1 

//  create  a  boolean  type 

typedef  enum{ FALSE, TRUE)  bool; 

//  specify  attribute  sizes 
♦define  SIZE_DEVICE  2 
♦define  SIZE_PREFIX  64 
♦define  S I ZE_NAME  9 
♦define  SIZE_SUFFIX  3 

//  these  constants  are 
♦define  FLAG_DEVICE 
♦define  FLAG_PREFIX 
♦define  FLAG_NAME 
♦define  FLAG_SUFFIX 
♦define  INCOMPLETE 
♦define  INVALID_CHAR 
♦define  READ_ONLY 

class  File_Spec 
{ 

//  first  define  the  attributes 
char  device [ SI ZE_DEVICE  +  1] ; 

char  ‘prefix; 

char  name [SIZE_NAME  +  1]; 

char  suffix [SIZE_SUFFIX  +  1]; 

char  ‘request; 

int  prefix_length; 

int  request_length; 

unsigned  int  condition; 


//  the  dot  is  part  of  the  name 


//  under  MS-DOS,  the  disk  drive 
//  "  "  ,  the  path 

//  "  "  ,  still  the  name 

//  "  "  ,  the  extension 

//  pointer  to  response  string  for 
//  get_XXXX()  methods 


//  current  status  of  the  object 


used  as  flags  in  the  condition  attribute 
0x0001 
0x0002 
0x0004 
0x0008 
OxOOOf 
oxoofd 

0x0100 


//  and  then  the  private  methods 

bool  check_pref ix (void) ;  //  determine  completeness  of  prefix 

bool  parse_pref ix (void) ;  //  interpret  relative  prefix 

bool  check_chars (char  ‘string,  unsigned  int  attrib_f lag) ; 

//  test  for  valid  MS-DOS  file  chars 
void  copy (const  File_Spec&  original);  //  copy  another  file  spec 
bool  clear_attribute (char  ‘attribute,  unsigned  int  attrib_flag) ; 
bool  realloc (char  “pointer,  int  ‘length,  int  new_length) ; 

//  make  class  File_Spec  a  friend  of  itself 
friend  class  File_Spec; 


//  now  the  public  methods 
public: 

//  construct  file  specifications 
File_Spec (void) ; 

File_Spec (const  char  ‘file); 

File_Spec (const  File_Spec&  original); 

//  destroy  a  file  specification 
~File_Spec (void) ; 

//  return  status  of  object 
unsigned  int  status (void); 


//  extend  the  language  by  overloading  the  =  operator 
File_Spec  operator= (const  File_Spec&  original); 

//  ALL  get_XXXX ( )  methods  guarantee  to  return  NUL-terminated  strings 

char  *get_device(void) ; 

char  *get_prefix(void) ; 

char  *get_name (void) ; 

char  *get_suf fix (void) ; 

char  ‘filespec (void) ; 

//  ALL  change_XXXX ( )  methods  guarantee  to  copy  no  more  than  SIZE_n 

//  characters  from  the  pass  parameter 

bool  change_device (const  char  ‘string  =  NULL) ; 

bool  change_prefix (const  char  ‘string  =  NULL); 

bool  change_name (const  char  ‘string  =  NULL) ; 

bool  change_suf fix  (const  char  ‘string  =  NULL) ; 

//  disables/enables  change_XXXX ( ) 
void  read_only (bool  flag) ; 

//  attempt  to  complete  the  file  specification 
bool  complete (void) ; 


♦endif 


End  listing  One 


Listing  Two 

/*  FILESPEC. CPP  Written  by  Kevin  D.  Weeks  Released  to  the  Public  Domain  */ 

♦include  <stdio.h> 

♦include  <errno.h> 

♦include  <string.h> 

♦include  <ctype.h> 

♦include  "filespec.hpp" 

//  this  declaration  instructs  the  compiler  to  NOT  perform  name-mangling 
//on  these  functions, 
extern  "C" 

{ 
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extern  char  ll_get_drive (void) ; 

extern  int  ll_get_cwd(int,  char  *) ; 

extern  unsigned  int  ll_write (int,  unsigned  int,  const  void  *); 


//  these  constants  are  states  used  in  parsing  the  file  string 

#define  DEVICE  1 

Idefine  PREFIX  2 

Idefine  NAME  3 

#define  SUFFIX  4 

//a  macro  to  return  out  of  memory  errors 

Idefine  MEM_ERR (length)  {  errno  =  ENOMEM;  length  =  0;  return  NULL;  } 
extern  volatile  int  errno; 


This  final  File_Spec  constructor  is  passed  a  character  string  that  it 
attempts  to  parse  into  its  various  components.  Parsing  is  done  with 
a  finite  state  machine  that  begins  at  the  end  of  the  string  and  backs 
up  to  the  beginning,  changing  state  as  it  encounters  the  element  delimiters 
and  'V.  Once  the  string  has  been  parsed  the  components  are 
checked  for  completeness  and  for  the  validity  of  the  file  characters. 

In  order  to  correctly  interpret  a  string  with  a  prefix  but  no  name  the 
string  must  end  with  a  'V.  Also  note  that  any  individual  component 
device,  name,  etc.)  that  is  too  long  is  truncated  to  a  legal  length. 


File_Spec: :File_Spec (const  char  *file) 


*tmp_file; 

*tmp_prefix; 

pos; 

state; 


//  local  copy  of  tmp_file 
//  temporary  string  for  the  prefix 
//  current  position  in  tmp_file  string 
//  current  state 
//  trash  variable 


char 
char 
int 
int 
int 

//  initialize  everything  that  needs  initializing 
prefix  =  NULL; 
prefix_length  =  0; 
request_length  =  0; 
condition  =  0; 

device [0]  =  device (SIZE_DEVICE)  =  '\0'; 
name [ 0 ]  =  name [SIZE_NAME]  =  '\0'; 
suffix [0]  =  suffix [SIZE_SUFFIX]  =  '\0'; 
errno  =  0; 

if  (file  ==  NULL  II  *file  ==  '\0') 

{ 

condition  =  INCOMPLETE; 
return; 

} 

if  ((tmp_file  =  new  char [strlen (file)  +1])  ==  NULL) 

( 

errno  =  ENOMEM; 
return; 

} 

strcpy (tmp_file, file) ; 

if  ( (tmp_prefix  =  new  char [SIZE_PREFIX  +  1])  ==  NULL) 

{ 

errno  =  ENOMEM; 
return; 

} 

tmp_pref ix [0]  =  tmp_prefix [SIZE_PREFIX]  =  '\0'; 

pos  =  strlen (tmp_file)  -  1;  //  set  pos  to  last  character 

//  this  while  loop  is  the  finite  state  machine  mentioned  above,  note 
//  that  the  strncpyO  calls  copy  everthing  from  just  beyond  the 
//  character  that  satisfies  the  case,  and  then  the  tmp_file  is  truncated 
//  at  that  point  with  a  '\0' . 
state  =  SUFFIX; 
do 
< 


switch  (tmp_file [pos] ) 


case  ' . ' : 

//  a  dot  only  counts  in  the  SUFFIX  state 
if  (state  ==  SUFFIX) 

( 

strncpy (suffix, &tmp_file [pos  +  1] , SIZE_SUFFIX) ; 
tmp_file[pos  +  1]  =  '\0'; 
state  =  NAME; 

) 

else 

if  (state  ==  NAME) 

//  this  means  we've  got  two  or  more  dots  in  a  name 
//  which  is  illegal,  flag  it  as  an  invalid  char 
condition  !=  FLAG_NAME  «  4; 

break; 
case  ' \\' : 

if  ((state  ==  SUFFIX)  II  (state  ==  NAME)) 

{ 

strncpy (name, &tmp_file [pos  +  1] , SIZE_NAME) ; 
tmp_file[pos  +  1]  =  ' \0'; 
state  =  PREFIX; 


break; 
case  '  : '  : 

if  ((state  ==  SUFFIX)  !!  (state  ==  NAME)) 


} 

— pos; 


strncpy (name, 4tmp_file [pos  +  1] , SIZE_NAME) ; 
tmp_file[pos  +  1]  =  '\0'; 
state  =  DEVICE; 


else 

if 

{ 


> 

break; 


(state  ==  PREFIX) 

strncpy (tmp_pref ix, &tmp_f ile [pos 
tmp_file[pos  +  1]  =  '\0'; 
state  =  DEVICE; 


1] ,SIZE_PREFIX) ; 


//  go  to  next  character 
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}  while (pos  >=  0); 

//  now  resolve  whatever  state  we  ended  up  in 
if  ((state  ==  SUFFIX)  II  (state  ==  NAME)) 
strncpy (name, tmp_f ile, SIZE_NAME) ; 

else 

if  (state  ==  PREFIX) 

strncpy (tmp_pref ix, tmp_f ile, SIZE_PREFIX) ; 

else 

strncpy (device, tmp_f ile, SIZE_DEVICE)  ; 

//  validate  the  device 
device [1]  =  '  : ' ; 
device [2]  =  ' \0'  ; 
if  (device[0]  ==  '\0') 

condition  !=  FLAG_DEVICE; 

else 

{ 

//  make  the  device  upper-case  for  simplicity's  sake  later  on 
device [0]  =  toupper (device [0] ) ; 
if  (device[0]  <  'A'  I!  device[0]  >  'Z') 
condition  !=  FLAG_DEVICE  <<  4; 

} 

//  use  the  existing  change_prefix ()  method  to  create  the  prefix  and 

//  validate  it 

change_prefix (tmp_prefix) ; 

delete (SIZE_PREFIX  +  1]  tmp_prefix; 

//  now  validate  the  name 
if  (name [0]  ==  '  \0' ) 

condition  1=  FLAG_NAME; 

else 

{ 

if  (name [0]  ==  '  . ' ) 

1 

condition  !=  FLAG_NAME; 
name [0]  =  ' \0' ; 

I 

else 

if  (check_chars (name, FLAG_NAME) ) 

{ 

//  as  far  as  we're  concerned  name  HAS  to  end  with  a  dot. 
i  =  strlen (name) ; 
if  (name[i  -  1)  !='.') 

{ 

if  (i  ==  SIZE_NAME) 

i  =  SIZE_NAME  -  1; 
name [i++]  =  ' . ' ; 
name[i]  =  '\0'; 


) 

//  and  suffix 
if  (suffix[0)  !=  '\0') 

check_chars (suffix, FLAG_SUFFIX) ; 

) 

/*  This  constructor  creates  an  empty  object  suitable  for  later  filling.  */ 
FileSpec: :File_Spec (void) 

{ 

//  Set  both  ends  of  device,  name,  and  suffix  to  NUL.  Since  strncpy () 

//  is  used  later  on  this  guarantees  these  three  are  always  NUL-terminated. 

device [0]  =  device (SI ZE_DEVICE]  =  '\0'; 

name ( 0 )  =  name [SIZE_NAME]  =  '\0'; 

suffix [0]  =  suffix [SIZE_SUFFIX]  =  '\0'; 

prefix  =  NULL; 

prefix_length  =  0; 

request  =  NULL; 

request_length  =  0; 

condition  =  INCOMPLETE;  //  everthing's  incomplete 

) 

/*  The  so-called  "copy"  constructor  actually  calls  a  copyO  method  after  - 
doing  some  preliminary  initialization. 

*/ 

File_Spec: :File_Spec (const  File_Spec&  original) 

{ 

prefix  =  NULL; 
pref ix_length  =  0; 
request  =  NULL; 
request_length  =  0; 
copy (original)  ; 

} 

/*  The  destructor  simply  releases  the  memory,  if  any,  assigned  to  prefix 
and  request. 

*/ 

File_Spec: :~File_Spec (void) 

( 

if  (prefix  !=  NULL) 

( 

delete[prefix  length]  prefix; 
prefix  =  NULL; 
pref ix_length  =  0; 

1 

if  (request  !=  NULL) 

{ 

delete [request_length]  request; 
request  =  NULL; 
request_length  =  C; 

} 
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) 

/*  Tell  'em  how  we're  doing  */ 
unsigned  int  File_Spec: : status (void) 

{ 

return (condition) ; 

} 

/*  This  method's  purpose  is  to  return  a  string  containing  a  complete  file 
specification  string  for  use  by  clients. 

*/ 

char  *File_Spec : : f ilespec (void) 

{ 

int  length; 

//  first  calculate  the  length  of  the  file  specification 
length  =  strlen (device) ; 
length  +=  strlen (prefix) ; 
length  +=  strlen (name) ; 

//  +  2  to  allow  for  the  NUL-terminator  and  the  colon 
length  +=  strlen (suffix)  +  2; 

//if  request  isn't  already  long  enough  then  de-allocate  the  current 
//  pointer  and  allocate  a  new  one 
if  (request_length  <  length) 

if  ( ! realloc [& request, &request_length, length) ) 
return (NULL) ; 

//  build  the  string 
strcpy (request, device) ; 
if  (prefix  !=  NULL) 

strcat (request, prefix) ; 
strcat (request,  name) ; 
strcat (request,  suffix)  ; 
return (request) ; 

) 

/*  get_device () ,  get_prefix() ,  get_name(),  and  get_suffix()  are  all  essen- 
tialy  alike,  if  the  request  string  isn't  long  enough  then  it  is  re¬ 
allocated,  then  the  attribute  that  was  requested  is  copied  into  request. 

*/ 

char  *File_Spec: :get_device (void) 

( 

errno  =  0; 

if  (request_length  <  SIZE_DEVICE  +  1) 

if  (! realloc (&request, &request_length, SIZE_DEVICE  +1)) 
return (NULL) ; 
strcpy (request, device) ; 
return (request) ; 

} 

/*  Returning  the  prefix  is  a  bit  more  complicated  than  the  other  get 
routines . 

*/ 

char  *File_Spec: :get_prefix (void) 

{ 

errno  =  0; 
if  (prefix_length) 

( 

if  (request_length  <  prefix_length) 

if  ( ! realloc (Srequest, &request_length, pref ix_length) ) 
return (NULL) ; 
strcpy (request, prefix) ; 

) 

else 

//  even  if  the  prefix  is  NULL  we  promised  to  return  something.  Here, 

//  a  string  1  character  long  consisting  of  a  NUL-terminator 

{ 

if  (request_length  ==  0) 

if  (realloc (firequest, &request_length, 1) ) 

* request  =  '\0'; 

) 

return (request) ; 

) 

/***************************************/ 
char  *File_Spec: :get_name (void) 

( 

errno  =  0; 

if  (request_length  <  SIZE_NAME  +  1) 

if  (! realloc (Srequest, &request_length, SIZE_NAME  +  1)) 
return (NULL) ; 
strcpy (request, name) ; 
return (request) ; 

} 

/***************************************/ 
char  *File_Spec: :get_suf fix (void) 

{ 

errno  =  0; 

if  (request_length  <  SIZE_SUFFIX  +  1) 

if  (! realloc (Srequest, &request_length, SIZE_SUFFIX  +  1)) 
return (NULL) ; 
strcpy (request, suffix) ; 
return (request) ; 

} 

/**************************************/ 
as  with  the  get_XXXX()  methods  above,  change_device () ,  change_prefix () , 
change_name ( ) ,  and  change_suffix ()  are  basically  the  same,  if  the 
current  condition  is  "read-only"  then  return  a  FALSE,  if  a  NULL  string 
is  passed  (note  the  default)  the  current  object  is  truncated  and  the 
corresponding  incomplete  flag  is  set.  otherwise  SIZE  n  characters  are 
copied  and  the  standard  validity  checks  are  made. 

bool  File_Spec: :change_device (const  char  *string) 

( 

if  (condition  &  READ_ONLY) 
return (FALSE) ; 

if  (string  ==  NULL  II  *string  ==  '\0') 

return (clear_attribute (device, FLAG_DEVICE) ) ; 
strncpy (device, string, SIZE_DEVICE) ; 
device [0]  =  toupper (device [0] ) ; 
device [1]  = 
device [2]  =  '\0'; 

if  (device[0]  <  'A'  !!  device[0]  >  'Z') 

( 

condition  :=  FLAG_DEVICE  «  4; 
return (FALSE) ; 
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else 

condition  &=  ~ (FLAG_DEVICE  «  4); 
condition  &=  ~FLAG_DEVICE; 
return (TRUE) ; 

/*  get_prefix () ,  like  change_prefix () ,  is  somewhat  more  complicated  than  the 
other  change  routines 

*/ 

bool  File_Spec: :change_p refix (const  char  ‘string) 

{ 

int  new_length; 
if  (condition  &  READ_ONLY) 
return (FALSE) ; 

if  (string  ==  NULL  I!  ‘string  ==  ' \0' ) 

return (clear_attribute (prefix, FLAG_PREFIX) ) ; 
errno  =  0; 

//  get  the  size  of  the  new  prefix  and  if  the  existing  prefix  isn't  long 
//  enough  then  re-allocate  it 
new_length  =  strlen (string) ; 
if  (new_length  >  SIZE_PREFIX) 
new_length  =  SIZE_PREFIX; 
if  (prefix_length  <  new_length  +  1) 

if  (! realloc (Sprefix, &prefix_length, new_length  +  1)) 
return (FALSE) ; 

//  copy  in  the  new  string  and  validate  it. 
strncpy (prefix, string, new_length) ; 
prefix [new_length]  =  '\0'; 

if  (check_chars (prefix, FLAG_PREFIX)  ==  FALSE) 
return (FALSE) ; 
return (check_prefix() ) ; 

} 

/***************************************/ 
bool  File_Spec: :change_name (const  char  ‘string) 

{ 

int  i; 

if  (condition  &  READ_ONLY) 
return (FALSE) ; 

if  (string  ==  NULL  !!  ‘string  ==  ' \0' ) 

return (clear_attribute (name, FLAG  NAME) ) ; 
i  =  0; 

while  (string[i]) 

{ 

if  (string[i]  ==  ' .' ) 

{ 

change_suffix(&string[i  +  1 ] ) ; 
if  (i  ==  0) 

{ 

name [0]  =  ' \0' ; 
condition  !=  FLAG_NAME; 
condition  S=  ~(FLAG_NAME  «  4); 
return (FALSE) ; 

) 

++i; 

break; 

} 

if  (string[i]  ::  string[i]  ==  '\\') 

( 

condition  :=  FLAG_NAME  «  4; 
return (FALSE) ; 

) 

if  (++i  ==  SIZE_NAME) 
break; 

) 

strncpy (name, string,  i) ; 
name[i]  =  '\0'; 

if  (check_chars (name, FLAG_NAME)  ==  FALSE) 
return (FALSE) ; 
i  =  strlen (name) ; 

//  as  far  as  we're  concerned  name  HAS  to  end  with  a  dot. 
if  (name [i  -  1]  !='.') 

{ 

if  (i  ==  SIZE_NAME) 

i  =  SIZE_NAME  -  1; 
name[i++]  =  '  ; 

name [i]  =  ' \0' ; 

} 

condition  &=  ~FLAG_NAME; 
return  (TRUE.)  ; 

} 

/**************************************/ 
bool  File_Spec: :change_suf fix (const  char  ‘string) 

i 

if  (condition  &  READ_ONLY) 
return (FALSE) ; 
if  (string  ==  NULL) 

{ 

clear_attribute (suffix,  FLAG_SUFFIX) ; 

condition  &=  ~FLAG_SUFFIX;  //  unset  the  incomplete  suffix  flag 

1 

if  (‘string  ==  ' . ' ) 

{ 

++string; 

strncpy (suffix, string, SIZE_SUFFIX) ; 

} 

else 

strncpy (suffix, string, SIZE_SUFFIX) ; 
if  (check_chars (suffix, FLAG_SUFFIX)  ==  FALSE) 
return (FALSE) ; 
condition  &=  ~FLAG_SUFFIX; 
return (TRUE) ; 

} 

/*  This  method  determines  whether  or  not  the  prefix  is  complete.  */ 
bool  File_Spec: :check_prefix (void) 

{ 

int  i; 
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//  if  the  1st  character  isn't  a  'V  then  the  prefix  is  relative  to  the 
//  current  working  directory, 
if  (prefix[0]  !=  '\\') 

{ 

condition  !=  FLAG_PREFIX; 
return (FALSE) ; 

} 

i  =  0; 

//  this  loop  checks  for  the  presence  of  a  dot  followed  by  another  dot 
//  or  a  dot  followed  by  a  backslash,  either  one  indicates  the  prefix 
//  is  relative  the  the  current  working  directory, 
while  (prefix[i  +  1]) 

{ 

if  ((prefix[i)  =='.')  && 

(prefix [i  +  1]  ==  'W  prefix[i  +  1]  == 

{ 

condition  !=  FLAG_PREFIX; 
return (FALSE) ; 

) 

if  (++i  ==  SIZE_PREFIX  -  1) 
break; 


) 

//  a  prefix  HAS  to  end  with  a  'V 
if  (prefix[i)  !=  'W) 

{ 

prefix  [i++]  =  '\V; 
prefix [i]  =  '\0'; 

) 

condition  &=  ~FLAG_PREFIX; 
return (TRUE) ; 


I 

/******************* 
void  File_Spec: :read_only (bool  flag) 
{ 

if  (flag) 

condition  1=  READ_ONLY; 

else 

condition  &=  ~READ_ONLY; 


/*  This  method  actually  attempts  to  complete  a  file  specification.  */ 
bool  File_Spec : : complete (void) 

{ 

char  *tstr; 

char  drive; 

if  (condition  &  READ_ONLY) 
return (FALSE) ; 

//an  invalid  character  in  any  of  the  components  is  an  automatic  failure 
if  (condition  &  INVALID_CHAR) 
return (FALSE) ; 

//  no  name  is  also  an  automatic  failure 
if  (condition  &  FLAG_NAME) 
return (FALSE) ; 

//  if  no  device  specified  then  get  the  current  drive 
if  (condition  &  FLAG_DEVICE) 


drive  =  ll_get_drive () ; 
device [0)  =  drive  +  'A'; 
device [1]  =  ' ; ' ; 
device [2]  =  '\0'; 
condition  &=  ~FLAG_DEVICE; 


> 

//  if  the  prefix  isn't  complete  call  parse_prefix () 
if  (condition  &  FLAG_PREFIX) 

if  (parse_prefix()  ==  FALSE) 
return (FALSE) ; 

//  everything's  alright  so  give  the  client  the  go-ahead 
condition  =  0; 
return (TRUE) ; 


*/ 


} 

/*  Looks  rather  unimpressive  doesn't  it.  */ 

File_Spec  File_Spec: :operator= (const  File_Spec&  original) 

( 

copy (original) ; 

/*  As  with  the  (char  *string)  constructor  above,  this  routine  uses  a  finite 
state  machine  to  produce  a  complete  path,  the  existing  prefix  (if  any) 
is  processed  front  to  back  while  the  current  working  directory  (cwd)  is 
processed  back  to  front,  the  end  result  is  that  the  partial  prefix  is 
appended  at  the  correct  point  to  the  cwd. 

*/ 

bool  File_Spec: :parse_prefix (void) 

{ 

int  prefix_elem; 
int  cwd_elem; 

int  state; 

char  *cwd; 

errno  =  0; 

//  set  the  defaults 

if  ((cwd  =  new  char (SIZE_PREFIX  +  1])  ==  NULL) 

( 


errno  =  ENOMEM; 
return (FALSE) ; 


) 

II  since  the  directory  returned  by  ll_get_cwd()  doesn't  begin  with  a 
//  'V  we'll  start  by  adding  one  to  the  beginning  of  cwd 
cwd[0]  =  '\V; 
cwd[l]  =  ' \0' ; 

//  get  the  current  working  directory  for  the  specified  drive 
if  (ll_get_cwd (device [0]  -  64,&cwd[l])  ==  ERR) 

( 

delete [SIZE_PREFIX  +  1]  cwd; 
return (FALSE) ; 
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) 

//  DOS  doesn't  append  a  ' V  either  so  we  will 
cwd_elem  =  strlen(cwd); 
if  (cwd[l]  !=  '\0') 

{ 

cwd[cwd_elem]  =  '\V; 
cwd[cwd_elem  +  1]  =  '\0'; 

} 

//  if  there  was  no  prefix,  there  is  now.  assign  it  and  return 
if  (prefix  ==  NULL) 

{ 

prefix_length  =  SIZE_PREFIX  +  1; 
prefix  =  cwd; 
return (TRUE) ; 

) 

prefix_elem  =  0; 
state  =  0; 
do 
{ 

switch (state) 


{ 

case  0: 

if  (prefix [prefix_elem]  ==  '.') 

//  a  dot  means  check  for  another  dot  or  'V.  goto  state  1 
state  =  1; 

else 

//  DOS  would  give  you  a  fit  over  this,  since  we're  here, 
//  check_prefix ()  found  a  relative  component  in  the  path. 
//  however,  the  initial  'V  means  "start  at  the  root". 

//  so  we  go  to  the  root  by  setting  cwd_elem  to  zero  and 
//  start  looking  for  a  dot. 
if  (prefix [prefix_elem]  ==  '\\') 

{ 

state  =  1; 
cwd_elem  =  0; 

> 

else 


( 

//  our  current  character  IS  a  character  so  get  ready  to 
//  append  it  to  cwd  by  going  to  state  3  and  backing  up 
//  so  we  don't  lose  it. 
state  =  3; 

— prefix_elem; 

) 

break; 

case  1:  //we  have  seen  a  dot  (or  a  ' \' ) 

if  (prefix [prefix_elem]  ==  '.') 

//  another  dot  means  go  up  a  directory,  enter  state  2. 
state  =  2; 

else 

//  a  'V  means  stay  here,  get  ready  to  append  to  the 
//  cwd  and  enter  state  3. 
if (prefix [prefix_elem]  ==  ' \ \ ' ) 
state  =  3; 

else 

//  a  character  here  means  we  just  saw  something  like 
//  . s  -  remain  in  the  current  directory  and  pass  the 
//  buck  back  to  state  0. 
state  =  0; 

break; 

case  2:  //  two  (or  more)  dots  in  a  row 

if  (prefix [pref ix_elem]  ==  '\\') 

{ 

if  (cwd_elem  >  0) 
do 


{ 

— cwd_elem; 

)  while  (cwd(cwd_elem]  !=  '\\'); 

} 

else 

//  more  than  two  dots  in  a  row.  maintain  current  state 
if  (prefix [pref ix_elem]  ==  '.') 
break; 

else 

//  this  means  we're  seeing  a  "..s"  type  situation. 

//  treat  it  as  a  "..\s"  and  back  up  one  so  we  don't 
//  lose  the  prefix  character. 

— prefix_elem; 
state  =  3; 
break; 

case  3:  //  append  the  prefix  to  the  cwd 

if  (prefix [pref ix_elem]  ==  '.') 

//  whoops,  another  dot.  go  back  to  state  1 
state  =  1; 

else 

//  more  than  one  '\'  in  a  row.  don't  change  state, 
if  (prefix [pref ix_elem]  ==  ' \\' ) 
break; 

else 

( 

//  the  order  of  element  increments  is  a  bit  peculiar 
//  but  remember  we've  been  moving  in  opposite 
//  directions 
do 


++cwd_elem; 

cwd[cwd_elem]  =  prefix [pref ix_elem] ; 
++pref ix_elem; 

}  while  (prefix [pref ix_elem]  !=  '\\'); 
++cwd_elem; 

cwd[cwd_elem]  =  prefix [pref ix_elem] ; 

) 

break; 

); 


++prefix_elem; 

)  while  (prefix [pref ix_elem] ) ; 


cwd[++cwd_elem]  =  '\0'; 

//  it  worked!  reset  the  prefix  pointer  and  get  out 
delete [pref ix_length]  prefix; 
prefix  =  cwd; 

pref ix_length  =  SIZE_PREFIX  +  1; 
return (TRUE) ; 

} 

/*  This  routine  checks  for  valid  DOS  file  name  characters.  */ 

bool  File_Spec: :check_chars (char  ‘string,  unsigned  int  attrib_flag) 

I 

while  (‘string) 

I 

if  ( (‘string  <  ' ! ' )  ! ! 

(‘string  =='"')  : : 

(‘string  >  ')'  &&  ‘string  <  '-')  !! 

(‘string  =='/')  II 

(‘string  >  '9'  &&  ‘string  <  '@')  !I 

(‘string  =='[')  ! \ 

(‘string  >  'W  &6  ‘string  <  'A')  \ 

(‘string  ==  ' : ' ) ) 

{ 

condition  1=  attrib_flag  «  4; 
return (FALSE) ; 

) 

++string; 

> 

condition  &=  ~(attrib_flag  «  4); 
return (TRUE) ; 

) 

/*  Since  two  methods  (the  2nd  constructor  and  the  "="  operator)  need  to 

make  copies  of  other  File_Spec  instances,  this  private  method  is  provided 
to  avoid  duplicating  the  code,  this  method  is  also  the  main  reason  for 
making  File_Spec  a  friend  of  itself. 

*/ 

void  File_Spec: : copy (const  File_Spec&  original) 

{ 

errno  =  0; 

strcpy (device, original .device) ; 
if  (prefix_length  <  original .pref ix_length) 

if  ( ! realloc (Sprefix, ipref ix_length, original .prefix_length) ) 
return; 

strcpy (prefix, original .pref ix) ; 
strcpy (name, original. name) ; 
strcpy (suffix, original .suffix) ; 
condition  =  original. condition; 

1 

/*  clear_attribute  sets  the  first  element  of  the  attribute  it  is  passed  to 
a  NUL  and  then  resets  the  condition  flags. 

*/ 

bool  File_Spec: :clear_attribute (char  ‘attribute,  unsigned  int  attrib_flag) 

{ 

if  (attribute  !=  NULL) 

‘attribute  =  '\0'; 
condition  !=  attrib_flag; 
condition  &=  ~ (attrib_flag  «  4); 
return (TRUE) ; 

1 

/*  realloc ()  is  used  by  the  request  and  prefix  attributes  when  they're  changed 
to  see  if  they  require  re-allocating  and  to  handle  the  re-allocation 
if  needed. 

*/ 

bool  File_Spec: : realloc (char  “pointer,  int  ‘length,  int  new_length) 

( 

if  (‘length) 

delete [‘length]  ‘pointer; 
if  ((‘pointer  =  new  char [new_length] )  ==  NULL) 

{ 

‘length  =  0; 

‘pointer  =  NULL; 
return (FALSE) ; 

} 

‘length  =  new_length; 
ret urn( TRUE ) ; 

} 

End  Listing  Two 


Listing  Three 

/*  FILE.HPP  Written  by  Kevin  D.  Weeks  Released  to  the  Public  Domain  */ 

#ifndef  FILE_HPP  //  prevent  multiple  #includes 

#def ine  FILE_HPP 

♦include  "filespec.hpp" 

//  file  access  mode  definitions 

♦define  F_RDONLY  0x0000 

♦define  F_WRONLY  0x0001 

♦define  F_RDWR  0x0002 

♦define  F_COMPAT  0x0000 

♦define  F_DENYALL  0x0010 

♦define  F_DENYWR  0x0020 

♦define  F_DENYRD  0x0030 

♦define  F_DENYNO  0x0040 

//  flag  to  determine  whether  reads  and  writes  have  a  side-effect  on  the 

//  file  pointer 

♦define  F_ADVANCE  0x0100 

class  File:  public  File_Spec 

( 


(Listing  continued  on  page  108) 


106 


Dr.  Dobb's Journal,  June  1990 

541 


Listing  Three  (Text  begins  on  page  50.) 


//  DOS  file  handle 
//  flags  used  to  open  or  create 
//  DOS  file  position 
//  length  of  file 


//  class  attributes 
int  handle; 

int  open_flags; 

long  file_pos; 

long  filelength; 

//  public  class  methods 
public: 

//  constructors  for  file  objects 
File (void) ; 

File (const  File_Spec&  original,  bool  open_flag  =  FALSE); 

File (const  char  *name,  bool  open_flag  =  FALSE); 

//  destroy  the  object 
“File (void) ; 

bool  exists (void) ;  //  see  if  the  file  exists 

bool  create (int  mode_flags  =  2,  bool  exclusive  =  TRUE); 

bool  open (int  mode_flags  =  2); 

bool  close (void); 

unsigned  int  read (void  ‘buffer,  unsigned  int  size); 

//  guarantees  to  write  size  bytes  or  fail 

bool  write (const  void  ‘buffer,  unsigned  int  size); 

bool  truncate (void) ;  //  truncate  file  at  current  position 

//  guarantees  to  position  file  pointer  within  file  or  fail 

bool  set_position (long  new_file_pos) ; 

long  get_position (void) ; 

long  size (void); 

bool  rename (const  char  ‘newname); 

bool  erase (void) ; 

File  ‘copy (const  char  ‘newfile,  bool  overwrite  =  FALSE); 


End  Listing  Three 


Listing  Four 

/*  FILE .CPP  Written  by  Kevin  D.  Weeks  Released  to  the  Public  Domain  */ 

linclude  <errno.h> 

#include  <io.h> 
linclude  <sys\stat.h> 
linclude  <dos.h> 
linclude  "file.hpp" 

//  this  declaration  instructs  the  compiler  to  NOT  perform  name-mangling 
//  on  these  functions, 
extern  "C" 

( 

extern  char  ll_get_drive (void) ; 

extern  int  ll_get_cwd(int,  char  *); 

extern  unsigned  int  ll_write (int,  unsigned  int,  const  void  *); 

} 


if  (! complete () ) 
return (FALSE) ; 

if  (findfirst (filespec () , 0)  ==  NULL) 
return (FALSE) ; 
return (TRUE) ; 


//  check  for  a  completed  file  spec 

//  and  either  fail  if  not 

//  or  else  check  for  directory  entry 


/*  Create  the  file.  */ 

bool  File: :create (int  mode_flags,  bool  exclusive) 

{ 

int  tmp_handle; 

if  (! complete () )  //  is  the  file  spec  complete? 

return (FALSE) ; 

if  (handle  >  -1)  //  if  the  file  is  open 

{ 

if  (exclusive) 

return (FALSE) ; 

else 

close () ; 


else 

if  (exists ()) 

if  (exclusive) 

{ 

errno  =  EEXIST; 
return (FALSE) ; 


//  if  the  file  exists 
//  if  this  flag  is  TRUE 
//  return  an  error 


) 

//  create  the  the  file  and  then  close  it  to  re-open  with  the  appropriate 
//  mode  flags  set 

if  ( (tmp_handle  =  creat (filespec (), S_IWRITE  :  S_IREAD) )  ==  ERR) 


return (FALSE) ; 

: : close (tmp_handle) ; 
if  (open (mode_f lags)  ==  FALSE) 
return (FALSE) ; 
set_position (OL) ; 
filelength  =  OL; 
read_only (TRUE)  ; 

return (TRUE) ; 


//  the  : :  means  use  the  library  close 
//no  : :  -  use  the  File  method 

//  position  at  the  beginning 

//  tell  File_Spec  that  it  can't 
//  be  changed 


/*  Open  the  file.  */ 
bool  File: : open (int  mode_flags) 
{ 


//  if  the  file  is  already  open 
//  don't  re-open  it 

//  check  for  a  complete  file  spec 


if  (handle  >  -1) 
return (TRUE) ; 
if  ( ! complete () ) 
return (FALSE) ; 

//  use  the  standard  library  to  actually  open  it  (  ::open(...)  ) 
if  ((handle  =  : :open (filespec (), mode_flags) )  ==  ERR) 
return (FALSE) ; 

open_flags  =  mode_flags;  //  keep  the  mode  flags 

read_only (TRUE) ;  //  tell  File_Spec  not  to  change  a 

//  thing 

return (TRUE) ; 


extern  volatile  int  errno; 

/*  An  empty  file  object  seems  silly  but  here  it  is  anyway  */ 

File: :File (void) 

{ 

handle  =  -1; 
file_pos  =  OL; 
open_flags  =  0; 
filelength  =  OL; 

} 

/*  This  is  the  File  version  of  the  "copy"  constructor,  it  is  posible  to 
open  the  file  when  the  object  is  instantiated  by  passing  TRUE  as  a 
second  parameter. 

*/ 

File: : File (const  File_Spec&  original,  bool  open  file) : (original) 

I 

handle  =  -1; 
file_pos  =  OL; 
open_flags  =  0; 

if  ((filelength  =  filesize (filespec ()) )  ==  -1L) 
filelength  =  OL; 
if  (open_file  ==  TRUE) 
open { ) ; 

} 

/*  This  constructor  is  the  same  as  the  one  above.  The  differences  in  pass 
parameters  are  handled  by  their  respective  ancestors. 

*/ 

File: :File (const  char  ‘name,  bool  open  file) : (name) 

{ 

handle  =  -1; 
file_pos  =  OL; 
open_flags  =0; 

if  ((filelength  =  filesize (filespec ()) )  ==  -1L) 
filelength  =  0L; 
if  (open_file  ==  TRUE) 
open ( ) ; 


/*  File  destructor  */ 

File: :~File (void) 

{ 

if  (handle  >  0) 
closet) ; 

} 

/*  Does  the  file  exist?  */ 
bool  File: :exists (void) 

{ 


/*  Close  the  file.  */ 
bool  File: : close (void) 

1 

if  (handle  >  -1) 

if  (: : close (handle)  ==  ERR) 
return (FALSE) ; 
handle  =  -1; 
file_pos  =  0L; 
open_flags  =  0; 
read_only (FALSE) ; 


//  if  the  file's  open 
//  close  it 

//  and  re-initialize  everything 
//  File_Spec  can  change  again 


/*  Read  the  file.  NOTE:  bytes  actually  read  may  be  less  than  requested.  */ 
unsigned  int  File: : read (void  ‘buffer,  unsigned  int  num  bytes) 

{ 

int  bytes_read; 

if  (handle  <  0)  //  make  sure  the  file's  open 

{ 

errno  =  EBADF; 
return (FALSE) ; 

) 

//  first  set  the  file  position,  if  auto-advance  is  on  set_position () 

//  will  just  return,  otherwise  it  will  move  the  file  pointer  to  where 
//it  should  be.  then  use  the  standard  read  to  read  the  file 
if  (set_position (file_pos)  !=  FALSE) 

if  ( (bytes_read  =  :: read (handle, buffer, num_bytes) )  ==  ERR) 
return (FALSE) ; 

//if  auto-advance  is  on  we  still  need  to  keep  ourselves  current 
if  (open_f lags  &  F_ADVANCE) 

file_pos  +=  (long)bytes_read; 

//  return  the  number  of  bytes  actually  read 
return (bytes_read) ; 

> 


/*  Write  to  the  file.  In  this  case  failure  to  write  the  number  of  bytes 
specified  IS  considered  a  failure. 

*/ 

bool  File: : write (const  void  ‘buffer,  unsigned  int  num  bytes) 

{ 

if  (handle  <  0)  //  is  the  file  open? 

{ 

errno  =  EBADF; 
return (FALSE) ; 

} 

if  (num_bytes  ==  0)  //  if  zero  bytes  are  to  be  written 

return (TRUE) ;  //  return  WITHOUT  truncating  the  file 

//  make  sure  the  file  pointer  is  positioned  right  and  then  call  our 
//  low  level  write  routine  to  write  it.  there's  no  reason  to  clutter  up 
//  the  program  with  the  library  write () 
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Listing  Four  (Listing  continued,  text  begins  on  page  50.) 

if  (set_position (file_pos)  !=  FALSE) 

if  (ll_write (handle, num_bytes, buffer)  <  num_bytes) 

{ 

//at  this  point  we  failed  to  write  as  many  bytes  as  desired,  to 
//  eliminate  side  effects  we  truncate 
truncate () ; 
return (FALSE) ; 

} 

//  if  we  wrote  at  the  end  of  the  file,  increase  its  length 
if  (file_pos  ==  filelength) 

filelength  +=  (unsigned  long) num_bytes; 
if  (open_flags  &  F_ADVANCE)  //  check  for  auto-advance 

file_pos  +=  (long) num_bytes; 
return (TRUE) ; 


/*  Truncate  chops  a  file  off  at  the  current  file_position.  */ 
bool  File : : truncate (void) 

( 

if  (handle  <  0)  //  don't  bother  if  we're  not  open 

{ 

errno  =  EBADF; 
return (FALSE) ; 

} 

//  re-set  the  file  pointer  and  write  zero  bytes 
if  (set_position (file  pos)  !=  ERR) 
if  (! ll_write (handle,  0,  NULL) ) 
return (FALSE) ; 

filelength  =  file_pos;  //  re-set  the  length 

return (TRUE) ; 


/*  Position  the  DOS  file  pointer  */ 

bool  File: : set_position (long  new_file_pos) 

{ 

if  (handle  <  0)  //  guess! 

{ 

errno  =  EBADF; 
return (FALSE) ; 

) 

//  first  make  sure  we're  not  attempting  to  set  before  the  beginning  or 
//  after  the  end  of  the  file. 

if  (new_file_pos  >  filelength  ! !  new_file_pos  <  0L) 
return (FALSE) ; 

//  position  it 

if  (lseek (handle, new_file_pos, SEEK_SET)  ==  -1L) 
return (FALSE) ; 
file_pos  =  new_file_pos; 
return^ TRUE) ; 


/*  Get  the  current  file  position  */ 
long  File: :get_position (void) 

{ 

return (file_pos) ; 

} 

/*  Get  the  file  size  */ 
long  File: : size (void) 

{ 

long  length; 
if  (handle  >  -1) 

return (filelength) ; 

else 

( 

if  (open()  ==  FALSE) 
return (0L) ; 
length  =  filelength; 
close  ()  ; 
return (length) ; 

} 


/*  If  we  attempt  to  rename  an  open  file  it  is  first  closed  and  then 
reopened  after  the  rename. 

*/ 

bool  File: : rename (const  char  *newname) 

( 

bool  reopen  =  FALSE; 
int  tmp_flags; 

int  i; 

if  (handle  >  -1)  //  close  the  file  if  it's  open 

{ 

tmp_flags  =  open_flags; 
close () ; 
reopen  =  TRUE; 

} 

else 

if  (exists ()  ==  FALSE)  //  make  sure  the  file  exists 

return (FALSE) ; 

//  create  a  new  file  spec  just  like  this  one  (note  that  it's  also 
//  instantiated  at  this  point) 

File_Spec  newspec  =  ‘this; 

newspec .change_name (newname) ;  //  and  then  change  the  name 

if  (:: rename (filespec (), newspec . filespec {) )  !=  0) 

{ 

if  (reopen) 

//  pass  the  existing  open_flags  in  case  the  default  wasn't  used 
//  when  the  file  was  originally  opened, 
open (tmp_flags) ; 
return (FALSE) ; 


} 

change_name (newname) ;  //  now  update  this  file  name 

if  (reopen) 

return (open (tmp_f lags) ) ; 
return (TRUE) ; 


/*  Erase  the  file,  if  it's  open,  close  it  first.  */ 
bool  File: : erase (void) 

{ 

if  (handle  >  -1) 
close ( ) ; 

if  (unlink (filespec () )  ==  ERR) 
return (FALSE) ; 
return (TRUE) ; 


/*  This  might  also  be  a  good  opportunity  for  operator  overloading.  */ 
File  ‘File: : copy (const  char  ‘newname,  bool  overwrite) 

{ 


File 

‘newfile; 

//  file  to  copy  to 

char 

‘buffer; 

//  I/O  buffer 

unsigned  int 

buf_size; 

//  size  of  I/O  buffer 

unsigned  int 

num  bytes; 

//  number  of  bytes  transfered 

long 

tmp_file_pos; 

//  temporary  file  position  holder 

bool 

re_close  =  FALSE; 

//  flag  indicating  if  source  file 

//  should  be  closed  following  the 

//  copy  (to  avoid  side  effects) 

int 

tmp_old_flags; 

//  the  original  source  open  flags 

errno  =  0; 

//  first  create  the  new  object  instance 
if  ( (newfile  =  new  File (newname) )  ==  NULL) 
{ 


errno  =  ENOMEM; 
return (NULL) ; 

} 

//  then  create  the  new  file  (invert  overwrite  for  create) 
if  ( ! (newfile->create (F_ADVANCE  !  F_RDWR, (bool) ! overwrite) ) ) 


delete  newfile; 
return (NULL) ; 

} 

//  attempt  to  allocate  a  buffer,  loop  until  successful  or  fail  at  1  char 
buf_size  =  32768; 

while  ((buffer  =  new  char [buf_size] )  ==  NULL) 

{ 

buf_size  /=  2; 
if  (buf_size  ==  1) 

I 

errno  =  ENOMEM; 
delete  newfile; 
return (NULL) ; 

> 


(handle  <  0) 
if  ( ! open ( ) ) 

I 

newfile->close () ; 
newf ile->erase () ; 
delete  newfile; 
delete [buf_size]  buffer; 
return (NULL) ; 


//  if  the  source  file  isn't  open 
//  open  it 

//  if  we  can't  open  the  source 
//  file  we  need  to  clean  up 


re_close  =  TRUE;  //  copyO  opened  it  so  copy() 

}  //  should  close  it 

tmp_old_flags  =  open_flags;  //  keep  the  original  open  flags 

open_flags  1=  F_ADVANCE;  //  and  turn  auto-advance  on 

tmp_file_pos  =  file_pos;  //  keep  the  original  file  pointer 

set_position (0L) ;  //  go  to  the  beginning  of  the  file 

//  loop  until  the  entire  file  has  been  copied 
while  (num_bytes  =  read (buffer, buf_size) ) 

( 


if  (newfile->write (buffer, num_bytes)  ==  FALSE) 

(  //  if  a  write  error  occurs  we 

newfile->close () ;  //  need  to  clean  up  the  mess 

newfile->erase () ;  //  and  return  an  error 

delete  newfile; 
delete [buf_size]  buffer; 
open_flags  =  tmp_old_f lags; 
set_position (tmp_file_pos) ; 
if  (re_close) 
close  ()  ; 
return (NULL)  ; 


) 

//  clean  up  and  return  the  new  file 
newf ile->close ( ) ; 
delete [buf_size]  buffer; 
open_flags  =  tmp_old_flags; 
set_position (tmp_file_pos) ; 
if  (re_close) 
close  () ; 

return (newfile) ; 


End  Listing  Four 
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Listing  Five 


LOWIO.ASM  Written  by  Kevin  D.  Weeks  Released  to  the  Public  Domain 


include  MACROS. ASM  ;  macro  file  provided  by  Zortech 

;  import  errno 
begdata 

extrn  _errno:word 
enddata 


bool  ll_write(int  file_handle,  unsigned  int  num_bytes,  void  *buffer) ; 
ll_write  simply  makes  a  call  to  DOS  for  a  write,  it  varies  in  two  ways 
from  the  standard  C  write (). 

1.  the  order  of  pass  parameters  (to  simplify  dealing  with  80x86  segments) 

2.  it  WILL  truncate  a  file 

begcode  ll_write 

c_public  ll_write 


func  11  write 

push 

bp 

mov 

bp,  sp 

push 

bx 

push 

cx 

push 

dx 

mov 

bx,P(bp] 

;  get  file  handle  from  stack 

mov 

cx,P(bp  +  2] 

;  get  number  of  bytes  to  write 

mov 

dx,P[bp  +  4] 

;  get  offset  of  buffer 

if  LPTR 

;  if  large  memory  model 

mov 

ds,P[bp  +  6] 

;  get  segment  of  buffer 

endif 

mov 

ax, 4000h 

;  dos  write  file  function 

int 

21h 

;  call  dos 

jc 

write_err, 

;  carry  flag  indicates  error 

jmp 

write_ret 

write_err : 

mov 

_errno, ax 

;  set  errno  to  error 

write_ret : 

pop  ds 

pop  dx 

pop  cx 

pop  bx 

mov  sp,bp 

pop  bp 

ret 

c_endp  ll_write 
endcode  11  write 


int  ll_get_drive (void) ; 

ll_get_drive  simply  returns  the  current  looged  disk  drive,  there  is  no 
error  return. 


begcode  ll_get_drive 

c_public  ll_get_drive 
func  ll_get_drive 


push 

bp 

mov 

bp,  sp 

mov 

ax, 1900h 

;  dos  get  current  drive  function 

int 

21h 

;  call  dos 

xor 

ah,  ah 

;  clear  high  byte 

mov 

sp,  bp 

pop 

bp 

ret 

c_endp  ll_get_drive 
endcode  ll_get_drive 


;***** 

************** 

****************** 

;  bool 

11  get  cwd(int  drive); 

;  ll_get_ 

cwd  gets  the  current  working  directory  for  the  specified  drive. 

;  0  means 

the  current  drive,  1  means 

drive  A,  2  means  drive  B,  etc.  it 

;  returns 

a  0  if  an  error  occurs  and 

errno  is  set. 

begcode  11 

get  cwd 

c  public  11  get  cwd 

func  11  get 

cwd 

push 

bp 

mov 

bp,  sp 

push 

dx 

push 

si 

push 

ds 

mov 

dx,  P  [bp] 

;  get  drive 

mov 

si,P[bp  +  2] 

;  get  offset  of  buffer 

if  LPTR 

;  if  large  memory  model 

mov 

endif 

ds,P[bp  +  4] 

;  get  segment  of  buffer 

mov 

ax, 4700h 

;  dos  get  current  cwd  function 

int 

21h 

;  call  DOS 

jc 

get_cwd  err 

;  carry  flag  indicates  error 

xor 

ax,  ax 

jmp 

get  cwd  ret 

get_cwd_err 

mov 

errno, ax 

;  set  errno  to  error 

mov 

ax, Offffh 

;  &  set  ax  to  -1 

get  cwd  ret 

(Listing  continued  on  page  1 12) 
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Listing  Five  (Listing  continued,  text  begins  on  page  50.) 

pop  ds 

I; 

pop  si 

pop  dx 

extern  volatile  int  errno; 

mov  sp, bp 

.void  check  file  spec (void); 

pop  bp 

void  check  file (void); 

ret 

void  make  f ilespec (char  *test  case); 

c  endp  11  get  cwd 

void  print  condition (File  Specs  file, char  *test  name, char  *test  case); 

endcode  11  get  cwd 

int  main (void) 

END 

•{ 

check  file  spec(); 

End  Listing  Five 

check  file(); 

} 

void  check  file  spec() 

{ 

int  i,  j,  k; 

char  test  case [81]; 

char  title [81]; 

printf ("\nTESTING  File_Spec. . .\n\n") ; 

File_Spec  filel;  //  check  void  constructor 

print  condition (filel, "void  constructor","  "); 

Listing  Six 

for  (i  =  0;  i  <  4;  i++) 

/*  FILETEST . CPP  Written  by  Kevin  D. 

Weeks  Released  to  the  Public  Domain  */ 

{ 

printf ("CHECKING  %s\n",test  type[i]); 

#include  <stdio.h> 

j  -  0; 

((include  <errno.h> 

while  (test [ i ] [ j ]  !=  NULL) 

#include  <string.h> 

1 

((include  "file.hpp" 

make  f ilespec (test [i] [ j] ) ; 

++j; 

//  File  Spec  test  cases 

1 

char  *device_test [ ]  =' 

) 

//  no  device 

//  check  first  four  complete  combinations 

"a: ", 

//  complete  device 

printf (WnCHECKING  COMPLETE  FILE  SPECSNn"); 

//  invalid  file  char 

for  (i  =  0;  i  <  4;  i++) 

"ab: ", 

//  device  too  long 

f 

"a: : ", 

//  invalid  char  (double  colon) 

strcpy(test  case, test [0] [i] ) ; 

NULL 

I; 

strcat (test  case, test [ 1 ] [ i j ) ; 

strcat (test_case, test [2] [i] ) ; 
strcat (test  case, stest [3] [i] [1] ) ; 

char  *pref ix_test [ ]  = 

make  f ilespec (test  case); 

} 

//  no  prefix 

for  (i  =0;  i  <  4;  i++) 

"WsubW", 

//  complete  prefix 

//  complete  with  invalid  file  char 

1 

printf ("CHECKING  change  %s\n",test  type [ i ] ) ; 
j  =  0; 

while  (test [ i ] [ j ]  !=  NULL) 

//  prefix  too  long 

"W0123456789W0123456789W0123456789W01234  56789W0123456789W0123456789W", 

"sub.dirW", 

//  incomplete  prefix  (no  backslash) 

( 

switch  (i) 

"WWsubW", 

//  double  back  slash 

"Wsub.dirW", 

//  complete  prefix  with  extension 

I 

"subl\\sub2\\" , 

//  bi-level  incomplete  prefix 

case  0: 

"\\subl\\sub2\\", 

//  bi-level  conplete  prefix 

if  (filel. change  device (test [i] [ j] )  ==  FALSE) 

.Wsub", 

//  relative,  incomplete  prefix 

printf ("Error  changing  device"); 

"..WsubW", 

//  "  , 

break; 

"..W", 

//  "  , 

case  1 : 

".WsubW", 

// 

if  (filel .change  prefix (test [i] [ j] )  ==  FALSE) 

"W.  .WsubW", 

//  relative  but  starts  at  root 

printf ("Error  changing  prefix"); 

". .\\>sub\\", 

//  relative  with  invalid  file  char 

break; 

"W", 

//  complete  prefix 

case  2: 

NULL 

}; 

if  (filel .change  name (test [i] [ j] )  ==  FALSE) 

printf ("Error  changing  name"); 
break; 

case  3: 

if  (filel .change  suffix (test [i] [ j ] )  ==  FALSE) 

//no  name 

printf ("Error  changing  suffix"); 

"file. ", 

//  complete  name 

break; 

"file>. ", 

//  complete  with  invalid  file  char 

) ; 

print_condition (filel,  "  ",test[i] [ j]) ; 

"filetestl . " , 

//  name  too  long 

"file. . ", 

//  invalid  char  (double  dot) 

++j; 

"file", 

//  incomplete,  no  dot 

} 

NULL 

) 

); 

printf  (WnCOMPLETION  TEST\n")  ; 

filel. change  device ();  //  erase  current  device 

filel. change  prefixO;  //  &  prefix 

print  condition (filel, "BEFORE", "  "); 

//no  suffix 

filel . complete () ; 

" . tst " , 

//  complete  suffix 

print_condition (filel, "AFTER",  "  ") ; 

" .ts>", 

//  complete  with  invalid  file 

char 

File  Spec  file2  =  filel; 

" .tstl", 

//  suffix  too  long 

print_condition (file2, "\nTEST  '='  OPERATOR\n", "file2  =  filel"); 

NULL 

1; 

) 

char  **test[]  = 

void  make  f ilespec (char  *test_case) 

{ 

device  test, 

File  Spec  file2(test  case); 

print  condition (file2, "char  constructor" ,  test  case); 

File  Spec  f ile3 (f ile2) ; 

suffix  test 

}; 

print  condition (file3,  "copy  constructor" , test  case) ; 

} 

char  *test_type[]  = 

void  print  condition (File  Specs  file,  char  *test_name,  char  *test_case) 

"DEVICE  ", 

"PREFIX  ", 

"NAME  ", 

"SUFFIX  " 

(Listing  continued  on  page  115) 
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C  +  +  FILE  OBJECTS 


Listing  Six  (Listing  continued ,  text  begins  on  page  50.) 

unsigned  int  status; 

printf ("Error  re-creating  %s\n", filel. filespec ()) ; 

char  Completion; 

perror ("") ; 

char  ‘character; 

return; 

static  char  incomplete []  =  ("INCOMPLETE"); 

1 

static  char  complete!]  =  {"  complete"); 

) 

static  char  invalid!]  =  {"INVALID  CHAR"); 

static  char  valid!]  =  {"  chars  ok  "); 

printf ("File  %s  successfully  created  and  opened\n", filel . filespec ()) ; 

strcpy (buffer, "this  is  a  test  file"); 

printf ("%s\t%s\n", test  name, test  case); 

i  =  strlen (buffer) ; 

status  =  file. status {) ; 

if  (filel. write (buffer, i)  ==  FALSE) 

printf ("file  condition:  %x\n", status) ; 

{ 

perror ("Error  writing"); 

completion  =  (status  &  FLAG  DEVICE)  ?  incomplete  :  complete; 

printf ("Closing  file\n"); 

character  =  (status  &  (FLAG  DEVICE  «  4))  ?  invalid  :  valid; 

return; 

printf  ("\tdevice:  %-9s\t%s\t%s\n", file. get  device () , completion, character) ; 

) 

printf ("\"%s\"  written  to  file\n", buffer) ; 

completion  =  (status  &  FLAG  PREFIX)  ?  incomplete  :  complete; 

printf  ("Current  file  position  is:  %ld\n",  filel  .get  positionO); 

character  =  (status  &  (FLAG  PREFIX  «  4))  ?  invalid  :  valid; 

printf ("Current  file  length  is:  %ld\n", filel. size ()) ; 

printf  ("\tprefix:  %-9s\t%s\t%s\n", file. get  prefixO , completion, character) ; 

if  (filel .read (buffer, i)  ==  FALSE) 

completion  =  (status  &  FLAG  NAME)  ?  incomplete  :  complete; 

perror ("Error  reading"); 

character  =  (status  &  (FLAG  NAME  «  4))  ?  invalid  :  valid; 

printf ("Closing  file\n"); 
return; 

printf ("\t  name:  %-9s\t%s\t%s\n", file.get_name () completion, character) ; 

character  =  (status  &  (FLAG  SUFFIX  «  4))  ?  invalid  :  valid; 

printf ("\"%s\"  read  from  file\n", buffer) ; 

printf  ("\tsuffix:  %-9s\t%s\t%s\n", file.get_suffix () ,  "  ",  character) ; 

if  (filel . rename ("test.fil")  ==  FALSE) 

printf ("\tfilespec:  %s\n\n", file. filespec () ); 

perror ("Error  renaming"); 

} 

printf  ("Closing  file\n") ; 
return; 

void  check  file (void) 

} 

( 

char  buffer [81]; 

printf ("File  renamed  to  %s\n", filel . filespec ()) ; 

int  i; 

File  *file2  =  filel. copy ("test2.fil") ; 
if  (errno) 

printf ("\n\n\nTESTING  File. . .\n\n\n") ; 

I 

perror ("test2 . fil") ; 

/*  we  won't  try  to  perform  any  constructor  tests  since  most  of  the 

printf ("Overwriting  it.\n"); 

attributes  are  in-accessable  and  therefore  best  checked  using 

file2  =  f ilel. copy ("test2. fil", TRUE) ; 

either  a  source-level  debugger  or  printf  statements.  */ 

) 

if  (file2->exists () ) 

printf("%s  successfully  copied  to  %s\n", filel . filespec (), file2- 

File  filel ("file.tst") ; 

printf  ("Creating  %s\n", filel. filespecO  ) ; 

>filespec () ) ; 

if  (filel .create ()  ==  FALSE) 

else 

printf ("%s  already  exists.  Re-creating  it. \n", filel. filespecO ) ; 

printf ("Copy  failed. \n"); 

if  (filel. create (F  RDWR, FALSE)  ==  FALSE) 

{ 

) 

delete  file2; 

End  listings 
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PIXEL  ORDERING 


Listing  One  (Text  begins  on  page  56.) 

/*  points. c  Copyright  (c)  1989  by  Norton  T.  Allen  */ 

♦include  "points. h" 

int  nbits(int  i)  { 
int  nb; 

for  (nb  =  0;  i  !=  0;  nb++)  i  »=  1; 
return (nb) ; 


static  int  focus_x,  focus_y,  focus_width,  focus_height; 

/*  zeros  in  map  correspond  to  x  bits,  l's  to  y  bits  */ 
static  long  int  z,  map,  zlim; 
static  int  tbits,  xor_y; 

void  init_points (int  left,  int  top,  int  width,  int  height)  { 
int  nbits_w,  nbits_h; 
long  int  mask; 

focus_x  =  left; 
focus_y  =  top; 
focus_width  =  width; 
focus_height  =  height; 
nbits_w  =  nbits (focus_width) ; 
nbits_h  =  nbits (focus_height) ; 
tbits  =  nbits_w  +  nbits_h; 
xor_y  =  nbits_w  <  nbits_h; 
z  =  0L; 

zlim  -  1L  «  tbits; 
map  =  0L; 

for  (mask  =  1L;  nbits_w  I !  nbits_h;  )  { 

if  (nbits_w  >  nbits_h  !!  (nbits_w  ==  nbits_h  &&  xor_y))  { 
nbits_w — ; 
mask  «=  1; 

) 

if  (nbits_h  >  0  && 

(nbits_h  >  nbits_w  !!  (nbits_w  ==  nbits_h  &&  !xor_y)))  { 
nbits_h--; 
map  !=  mask; 
mask  «=  1; 

} 

) 

} 

int  next_point (int  *dx,  int  *dy)  ( 
int  x,  y,  n; 
long  int  m,  rz; 

for  (;;)  { 

if  (z  ==  zlim)  return(l); 
m  =  map;  rz  =  z;  n  =  tbits; 
x  =  y  =  0; 
while  (n —  >  0)  { 

if  (m  &  1)  {  /*  this  is  a  ybit  */ 
y  «=  1; 

if  (rz  &  1)  y++; 

}  else  ( 
x  «=  1; 

if  (rz  &  1)  x++; 

} 

m  »=  1;  rz  »=  1; 

} 

z++; 

if  (xor_y)  y  =  x  A  y; 
else  x  =  x  A  y; 

if  (x  >=  focus_width)  continue; 
if  (y  >=  focus_height)  continue; 
break; 

) 

*dx  =  x  +  focus_x; 

*dy  =  y  +  focus_y; 
return (0) ; 


End  Listing  One 


xmin  -=  delta; 
xmax  +=  delta; 

}  else  ( 

yscale  =  xscale/ASPECT; 

delta  =  (ymin  +  yscale  *  vp_height()  -  ymax)/2.; 
ymin  -=  delta; 
ymax  +=  delta; 


) 

xo  =  xmin; 
yo  =  ymin; 

1  /*  -  */ 

double  vx  (int  dx)  /*  convert  device  x  to  virtual  x  */ 

( 

return  ((double)  dx  *  xscale  +  xo) ; 

,  /*  -  */ 

double  vy  (int  dy)  /*  convert  device  y  to  virtual  y  */ 

( 

return  ( (double)  dy  *  yscale  +  yo) ; 

I  /* -  */ 


/*  Membership  in  the  Mandelbrot  set  is  determined  by  an 
iterative  function.  Given  the  complex  starting 
coordinate  C  the  function  is: 

Z (0)  =  0. 

Z (n+1)  =  Z(n)A2  +  C 

A  point  is  deemed  to  be  in  the  set  if  NLOOP  iterations  fails 
to  produce  a  point  with  absolute  value  greater  than  LIMIT. 
Points  within  the  set  are  colored  black.  Points  outside  the 
set  are  colored  based  on  how  many  iterations  passed  before 
exceeding  LIMIT.  Miriad  other  schemes  are  possible.  Other 
values  for  NLOOP  and  LIMIT  are  probably  desirable,  depending 
on  how  deep  you  go. 

*/ 

♦define  NLOOP  100 
♦define  LIMIT  10000. 

♦define  NCOLORS  15 

int  mandel_color (double  cx,  double  cy)  { 
int  k; 

double  zx,  zy,  zx2,  zy2; 
zx  =  zy  =  0 . ; 

for  (k  =  0;  k  <  NLOOP;  k++)  { 
zx2  =  zx*zx; 
zy2  =  zy*zy; 

if  (zx2+zy2  >  LIMIT)  break; 
zy  =  2*zx*zy  +  cy; 
zx  =  zx2  -  zy2  +  cx; 

) 

if  (k  <  NLOOP)  return ( (k  %  NCOLORS) +1); 
return (0) ; 


End  Listing  Two 


Listing  Three 

/*  generate. c  Copyright  (c)  1989  by  Norton  T.  Allen  */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <dos.h> 

♦include  "points. h" 

♦include  "grafix.h" 

/*  This  structure  defines  a  rectangular  box  which  we  can  move  around  the 
screen  using  the  cursor  keys,  fbox.on  is  TRUE  if  the  box  is 
currently  displayed,  fbox.mode  takes  the  values: 

0  Not  active 

1  Cursor  keys  move  the  whole  box 

2  Cursor  keys  change  box's  size 

struct  bx  ( 

int  x,  y,  dx,  dy,  on,  mode; 

)  fbox  =  (300,  160,  50,  40,  0,  0}; 


Listing  Two 

/*  mandel.c  will  handle  the  actual  Mandelbrot  set  calculations. 
Copyright  (c)  1989  by  Norton  T.  Allen  */ 

♦include  "grafix.h" 

/*  This  is  the  aspect  ratio  calculated  on  my  screen:  */ 

♦define  ASPECT  0.739 

static  double  xscale,  yscale,  xo,  yo; 

/*  set_range()  is  similar  to  setcoordsO  except  that  it  guarantees 
equal  x  and  y  scales,  taking  the  aspect  ratio  into  account. 

The  axis  with  the  smaller  scale  is  adjust  so  the  specified 
range  will  be  centered  on  the  screen.  Another  reason  for 
not  using  setcoordsO  is  that  I  need  the  inverse  functions 
mapping  device  coordinates  to  virtual  coordinates. 

*/ 

void  set_range (double  xmin,  double  ymin,  double  xmax,  double  ymax) 
double  delta; 

yscale  =  (ymax-ymin) /vp_height () ; 
xscale  =  (xmax-xmin) /vp_width () ; 
if  (yscale*ASPECT  >  xscale)  { 
xscale  =  yscale*ASPECT; 

delta  =  (xmin  +  xscale  *  vp_width()  -  xmax)/2.; 


void  flip_box (void)  { 
set_write_mode (WM_XOR) ; 
set_colorl (15) ; 

draw_rect (fbox.x,  fbox.y,  fbox.dx,  fbox.dy); 
set_write_mode (WM_REPLACE) ; 
fbox.on  =  ! fbox. on; 

} 


void  help (void) 
printf ("'Esc' 
print f ("? 
printf ("m 
printf ("s 
printf ("f 
printf ("z 
getch  ()  ; 

} 


{ 

to  exit\n"); 

for  this  message\n"); 

to  move  the  focus  box. (use  cursor  keys)\n"); 
to  size  the  focus  box. (use  cursor  keys)\n"); 
to  focus  on  the  focus  area\n"); 
to  zoom  in  on  the  focus  area\n"); 


static  int  dm  =  1;  /*  How  many  pixels  to  move  with  each  cursor  step 


*/ 


/*  check_box  makes  sure  the  new  box  meets  the  following  requirements: 

1.  It  isn't  off  the  screen. 

2.  It's  not  smaller  then  2  pixels  in  either  dimension 

Check  box  turns  off  the  old  box,  but  leaves  the  new  box  off  also; 
menu{)  will  turn  it  on  when  there's  no  more  keyboard  input. 

void  check_box (struct  bx  *nb)  { 
if  (nb->x  <  0  ! !  nb->y  <  0  ! ! 

nb->x  +  nb->dx  >  vp_width()  I! 
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Listing  Three  (Listing  continued,  text  begins  on  page  56.) 

nb->y  +  nb->dy  >  vp_height()  ! ! 
nb->dx  <21!  nb->dy  <  2  ! ! 

(nb->x  ==  fbox.x  &&  nb->y  ==  fbox.y  && 
nb->dx  ==  fbox.dx  &&  nb->dy  ==  fbox.dy)) 
return; 

if  (fbox.on)  flip_box(); 
fbox  =  *nb; 
fbox.on  =  0; 


/*  These  are  scan  codes  for  cursor  keys:  */ 

#define  EX_UP  72 
#define  EXJ30WN  80 
#define  EX_RIGHT  77 
# define  EX_LEFT  75 

/*  Menu  supports  the  following  keys: 

ESC  Exit 

M  suspend  calculations  and  put  box  on  the  screen  in 

mode  1  for  'moving' . 

S  As  with  M,  but  mode  2  for  'sizing'. 

C  Remove  box  and  continue  calculations  as  before 

F  Focus  on  boxed  region. 

Z  Zoom  in  on  boxed  region. 

Cursor  keys  Move  or  size  box 

0-9  Change  step  size  for  cursor  keys 

*/ 

void  menu (void)  { 

int  c; 

struct  bx  new_box; 

double  xmin,  ymin,  xmax,  ymax; 

for  (;;)  { 

while  (kbhitO)  { 
c  =  getch { ) ; 
switch  (c)  { 
case  ' \033' : 

exit (0) ; 
case  'c' : 
case  'C' : 

fbox. mode  =  0; 
break; 
case  'm' : 
case  'M' : 

fbox. mode  =  1; 
break; 
case  ' s' : 
case  ' S' : 

fbox. mode  =  2; 
break; 

case  'f':  /*  Focus  on  boxed  region  */ 
case  'F' : 

if  (fbox. mode  ==  0)  break; 

init_points (fbox.x,  fbox.y,  fbox.dx,  fbox.dy); 

fbox. mode  =  0; 

break; 

case  'z':  /*  Zoom  in  on  boxed  region  */ 
case  '  Z' : 

if  (fbox. mode  ==  0)  break; 
xmin  =  vx (fbox.x); 
ymin  =  vy (fbox.y+fbox.dy) ; 
ymax  =  vy (fbox.y); 
xmax  =  vx ( f box. x+ fbox.dx) ; 
set_range (xmin,  ymin,  xmax,  ymax); 
init_points (0,  0,  vp_width(),  vp_height () ) ; 
pc_textmode ( ) ;  /*  Kluge  to  clear  screen  */ 

init_video(EGA) ; 
fbox. mode  =  fbox.on  =  0; 
break; 
case  ' 1' : 
case  ' 2' : 
case  ' 3' : 
case  ' 4' : 
case  ' 5' : 
case  ' 6' : 
case  ' 7' : 
case  ' 8' : 
case  ' 9' : 
dm  =  c-'0'; 
break; 
case  0: 
c  =  getch () ; 
new_box  =  fbox; 

if  (fbox. mode  ==  1)  {  /*  moving  the  box  */ 
switch  (c)  { 
case  EX_UP: 
new_box.y  -=  dm; 
break; 

case  EX_DOWN : 
new_box.y  +=  dm; 
break; 

case  EX_RIGHT: 
new_box.x  +=  dm; 
break; 

case  EX_LEFT : 
new_box.x  -=  dm; 
break; 

default:  break; 

> 

}  else  if  (fbox. mode  ==  2)  { 
switch  (c)  { 
case  EX_UP : 

new_box.dy  -=  dm; 
break; 

case  EX_DOWN: 

new_box.dy  +=  dm; 
break; 

case  EX  RIGHT: 


new_box.dx  +=  dm; 
break; 

case  EX_LEFT : 

new_box.dx  -=  dm; 
break; 

default:  break; 


checkjbox (&new_box) ; 
break; 
default : 
break ; 

} 

} 

if  (fbox. mode  ==  0)  break; 
else  if  (! fbox.on)  flip_box(); 

) 

if  (fbox.on)  flip_box(); 


/*  Generate  cycles  through  all  the  pixels,  possibly  starting  over  as 
dictated  by  menu().  Generate  never  returns. 

*/ 

void  generate (void)  { 
int  c,  x,  y; 
double  fx,  fy; 

for  ( ; ; )  { 

while  (next_point (&x,  &y)  ==  0)  { 
fx  =  vx(x) ; 
fy  =  vy  (y) ; 

c  =  mandel_color (fx,  fy) ; 
set_colorl (c) ; 
draw_point (x,  y) ; 
if  (kbhitO)  menu(); 

) 

menu ( ) ; 

1 

} 


void  main (int  argc,  char  **argv)  { 
if  (init_video  (EGA))  { 

init_points (0,  0,  vp_width(),  vp_height () ) ; 
set_range (-2 . ,  -.95,  .75,  .95); 
generate  () ; 

)  else  printf ("Cannot  select  graphics  mode"); 

} 


End  Listing  Three 


Listing  Four 

/*  points. h  include  file  for  pixel  ordering  program.  */ 
void  init_points (int  left,  int  top,  int  width,  int  height); 
int  next j>oint (int  *dx,  int  *dy) ; 
int  mandel_color (double  cx,  double  cy) ; 

void  set_range (double  xmin,  double  ymin,  double  xmax,  double  ymax) ; 
double  vx  (int  dx) ;  /*  convert  device  x  to  virtual  x  */ 

double  vy  (int  dy) ;  /*  convert  device  y  to  virtual  y  */ 

End  Listing  Four 


Listing  Five 

To  be  included  in  grafix.h 


/*  Added  by  Norton  Allen  */ 

/* - */ 

void  set_write_mode (int  mode) ; 

fdefine  WM_REPLACE  0 
#define  WM_XOR  0x18 

End  Listing  Five 


Listing  Six 

/*  wmode.c  for  DDJ  grafix  library  Copyright  (c)  1989  by  Norton  T.  Allen  */ 

# include  <dos.h> 

#include  "grafix.h" 

int  write_mode  =  WM_REPLACE; 

void  set_write_mode (int  mode)  { 
write_mode  =  mode; 

} 


End  Listings 
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EXAMINING  ROOM 


listing  One  (Text  begins  on  page  62.) 

;  protmode.asm  —  286  protected-raode  instructions 

;  requires  MASM  5.0  or  higher  or  TASM 

;  masm  -ml  protmode; 

;  or,  tasm  -ml  protmode; 


.286p 

.model  large 
.code 

public  _lsl,  _lar,  _verr,  _verw,  _sgdt,  _sidt,  _sldt 

;  extern  unsigned  far  lsl (unsigned  short  sel); 

;  input :  selector 

;  output:  if  valid  and  visible  at  current  protection  level, 

;  return  segment  limit  (which  is  0  for  1-byte  seg!) 

;  else 

;  return  0 

_lsl  proc 

enter  0,  0 
sub  ax,  ax 

lsl  ax,  [bp+6] 

leave 
ret 

_lsl  endp 

;  extern  unsigned  short  far  lar (unsigned  short  sel); 

;  input:  selector 

;  output:  if  valid  and  visible  at  current  protection  level, 

;  return  access  rights  (which  will  never  be  0) 

;  else 

;  return  0 

;  bug:  retval  for  1-byte  seg  =  retval  for  invalid  selector 

_lar  proc 

enter  0,  0 


sub 

lar 

shr 

leave 

ret 

_lar  endp 


ax,  ax 
ax,  [bp+6] 
ax,  8 


extern  BOOL  far  verr (unsigned  short  sel); 
input:  selector 

output:  valid  for  reading  ?  1  :  0 


De 

dec 

verr_okay : 

leave 

ret 

_verr  endp 


word  ptr  [bp+6] 
short  verr_okay 


extern  BOOL  far  verw (unsigned  short  sel); 
input:  selector 

output:  valid  for  writing  ?  1  :  0 


Listing  Two 

/*  PROTMODE. H  */ 

typedef  enum  {  FALSE,  TRUE  )  BOOL; 
lifdef  InstantC 
unsigned  far  lsl (unsigned  short  sel)  (extern;) 

unsigned  short  far  lar (unsigned  short  sel)  (extern;) 
BOOL  far  verr (unsigned  short  sel)  (extern;) 

BOOL  far  verw(unsigned  short  sel)  (extern;) 

void  far  sgdt(void  far  *gdt)  (extern;) 

void  far  sidt(void  far  *idt)  (extern;) 

unsigned  short  sldt (void)  (extern;) 

#else 

extern  unsigned  far  lsl (unsigned  short  sel); 
extern  unsigned  short  far  lar (unsigned  short  sel); 
extern  BOOL  far  verr (unsigned  short  sel); 
extern  BOOL  far  verw (unsigned  short  sel); 
extern  void  far  sgdt (void  far  *gdt); 
extern  void  far  sidt (void  far  *idt); 
extern  unsigned  short  sldt (void) ; 
lendif 


Listing  Three 

/*  BROWSE. C  */ 

#ifdef  InstantC 
♦loadobj  "protmode. obj" 
#endif 

# include  " protmode. h" 

void  browse () 

{ 

unsigned  long  addr; 
unsigned  i,  acc; 
for  (i=0;  i<0xFFFF;  i++) 
if  (acc  =  lar(i)) 


End  Listing  Two 


//  for  all  possible  selectors 
//  if  a  valid  selector 


addr  =  D16AbsAddress (MK_FP (i,  0) ) ; 

printf ("%04X  %061X  LAR=%02X  LSL=%04X  PL=%02X  %s  %s  %s  %s\n" 
i,  //  selector 

addr,  //  physical  base  addr 

acc,  //  access-rights  byte 

lsl(i),  //  segment  limit 

i  &  3,  //  protection  level 

verr (i)  ?  "VERR"  :  "  ",  //  readable? 

verw (i)  ?  "VERW"  :  "  ",  //  writeable? 

i  &  4  ?  "LDT"  :  "GDT",  //  which  table? 

i  ==  addr  »  4  ?  "TRANS"  :  "");  //  transparent? 


End  Listing  Three 


Listing  Four 


enter  0,  0 
mov  ax,  1 
verw  word  ptr  [bp+6] 

je  short  verw_okay 

dec  ax 

verw_okay: 

leave 

ret 

_verw  endp 

;  extern  void  far  sgdt (void  far  *gdt); 

;  input:  far  ptr  to  6-byte  structure 

;  output:  fills  structure  with  GDTR 

_sgdt  proc 

enter  0,  0 

les  bx,  dword  ptr  [bp+6] 
sgdt  fword  ptr  es:[bx] 
leave 
ret 

_sgdt  endp 

;  extern  void  far  sidt (void  far  *idt); 

;  input:  far  ptr  to  6-byte  structure 

;  output:  fills  structure  with  IDTR 

_sidt  proc 

enter  0,  0 

les  bx,  dword  ptr  [bp+6] 
sidt  fword  ptr  es:[bx] 
leave 
ret 

_sidt  endp 

;  extern  unsigned  short  sldt (void) ; 

;  input :  none 

;  output:  Local  Descriptor  Table  register  (LDTR) 

_sldt  proc 

sldt  ax 


void  sel (void  far  *fp) 

{ 

extern  DESCRIPTOR  far  *gdt; 
extern  DESCRIPTOR  far  *ldt; 
unsigned  seg  =  FP_SEG(fp); 
unsigned  index  =  seg  »  3; 

DESCRIPTOR  far  *dt  =  (seg  &  4)  ?  gdt  :  ldt;  //  table  indicator 
ACCESS_RIGHTS  *pacc  =  (ACCESS_RIGHTS  *)  &dt [index] .access; 
printf ("SEL=%04X  ADDR=%02X%04X  LIMIT=%04X  ACCESS=%d%c%c%c%c%clc\n" 
seg,  dt [index] .addr_hi,  dt [index] .addr_lo,  dt [index] .limit, 

//  display  access  rights  as  if  they  were  file  attributes: 
pacc->dpl, 

pacc->accessed  ?  'a'  : 

pacc->read_write  ?  ( (pacc->code_data)  ?  ' r'  :  'w')  : 
pacc->conf_exp  ?  ( (pacc->code_data)  ?  'f'  :  'e')  : 
pacc->code_data  ?  ' c'  :  'd', 
pacc->xsystem  ?  :  's', 

pacc->present  ?  'p'  :  '-'); 


End  listing  One 


End  Listings 
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Listing  One  ( Text  begins  on  page  78.) 

/*  i.e.  just  like  MS  C  */ 


♦include  <dos.h> 
void  note { ) ; 
main  {) 


} 


note  (440,  500)  ; 


void  note (pitch,  duration) 
int  pitch, duration; 

{ 

int  u,v; 

union  REGS  regs; 

unsigned  int_count, int_duration, count, intjpitch; 

int_pitch  =  1190000/pitch; 
int_duration  =  (duration*1821) /10000; 

regs. x. ax  =  0;  /*  call  timer  */ 

int86(0xla,  Sregs,  Sregs); 

int_count  =  regs.x.dx;  /*  internal  count  =  lowest  16-bits  of  time*/ 

u  =  inp(0x61)  !  3;  /*  Turn  on  channel  2  of  8255  using  port  61h  */ 

outp (0x61, u) ;  /*  send  byte  to  back  */ 

outp (0x43, 0xb6) ;  /*  set  up  I/O  register  */ 

outp (0x42, (char)  intjpitch) ;  /*  send  freq  to  latch  */ 

outp (0x42, (int_pitch  »  8)); 

do  { 

regs. x. ax  =  0;  /*  use  timer  to  get  end  of  duration  */ 

int86(0xla,  Sregs,  Sregs); 

count  =  regs.x.dx;  /*  use  lowest  16-bits  of  count  */ 

}  while  (count  <  int_duration  +  int_count); 
v  =  inp(0x61)  s  Oxfc;  /*  turn  off  the  sound  */ 

outp (0x61, v) ; 


} 


Listing  Two 

♦define  outp(p,v)  dx 
♦define  inp(p,v)  dx 

unsigned  char  x,y,page 
void  note(); 
main  () 

{ 


End  Listing  One 


p;al  =  v;asm(dx, al, "  out  dx,al") 
p;asm(dx, "  in  al,dx",al);v  =  al 

0;  /*  globals  for  pc_test  */ 


note (440, 500) ; 


void  note (pitch,  duration) 
int  pitch, duration; 

{ 

reg$eax  unsigned  short  ix; 
reg$eax  unsigned  char  al,x,y; 
reg$edx  unsigned  short  dx; 
reg$ah  unsigned  char  ah; 

/*  this  section  was  added  for  play  */ 
unsigned  int_count, int  jiu ration, count,  intjpitch; 
if  (duration  ==  0)  return; 
int_duration  =  (duratxon*1821) /10000; 

/*  We  left  the  original  interrupt  as  a  comment  for  comparison  purposes 

/*  regs. x. ax  =  0;  call  timer  */ 

/*  int86(0xla,  Sregs,  Sregs);  */ 

/*  int_count  =  regs.x.dx;  internal  count  =  lowest  16-bits  of  time*/ 

/*  the  inline  assembly  language  is  line  for  line  identical  in  function 

although  there  is  an  obvious  difference  in  format.  */ 
ax  =  0; 

asm (ax,"  int  01ah",dx); 

int  count  =  dx; 


if  (pitch==0)  goto  time_it; 
intjpitch  =  1190000/pitch; 

The  port  input  is  a  little  different  using  inline  asm  macros  */ 
x  =  inp(0x61)  !  3;  the  original  code  becomes  */ 
inp(0x61,x);  /*  Turn  on  channel  2  of  8253  using  port  61H  */ 

x  =  x  !  3;  /*  After  read  turn  on  lowest  2  bits  */ 

The  outp  macro  looks  just  like  the  outp  function  */ 
outp (0x61, x) ;  /*  send  byte  to  back  */ 

outp (0x43, 0xb6) ;  /*  set  up  I/O  register  */ 

outp (0x42, (char)  int_pitch) ;  /*  send  freq  to  latch  */ 

outp (0x42, (int j)itch  »  8)); 

do  { 

ax  =  0; 
asm (ax, " 
count  =  dx; 

)  while  (count  <  int_duration  +  int_count); 
inp(0x61,y);  /*  Turn  off  channel  2  */ 

y  =  y  s  Oxfc;  /*  use  1111  1100  to  turn  off  lowest  2  bits  only 

outp (0x61, y) ; 


End  Listing  Two 


/*  use  timer  to  wait  for  end  */ 
int  01ah",dx); 


Listing  Three 


name  sound4 . c 
.387 

assume  cs:codeseg 
assume  ds:dataseg 

codeseg  segment  dword  er  use32  public  'code' 
dataseg  segment  dword  rw  use32  public  'data' 

dataseg  ends 

align  4 


jiote  proc  near 

push 

push 

push 

mov 

cmp 

jne 

pop 

pop 

pop 

ret 

align  4 

L17 : 

mov 
imul 
cdq 
idiv 
mov 
mov 
int 
movzx 


esi,  dx 


or 

jne 

jmp 

align 

mov 

cdq 

idiv 

mov 

mov 

in 

or 

mov 

out 

mov 

mov 

out 

mov 

mov 

out 

mov 

mov 


edi 

esi 

ebx 

ebx, [esp]+16 

dword  ptr  [esp]+20,0 

L17  short 

ebx 

esi 

edi 


ecx, 10000 

eax, [esp] +20, 1821 

ecx 

edi, eax 
ax,  0 
Olah 

ebx, ebx 

LI 6  short 

L13 


eax, 1190000 
ebx 

ebx, eax 
dx,  97 
al,dx 
al,  3 
dx,  97 
dx,  al 
dx,  67 
al, 182 
dx,  al 
dx,  66 
al,bl 
dx,  al 
dx,  66 
eax, ebx 


shr 

eax, byti 

out 

dx,  al 

align 

4 

L14: 

align 

4 

L13: 

mov 

ax,  0 

int 

Olah 

movzx 

ecx,dx 

mov 

eax, edi 

add 

eax, esi 

cmp 

eax, ecx 

ja 

L13 

mov 

dx,  97 

in 

al,  dx 

and 

al, 252 

mov 

dx,  97 

out 

dx,  al 

align 

4 

L9: 

pop 

ebx 

pop 

esi 

pop 

edi 

ret 

align 

4 

jiote 

endp 

dataseg  segment  dword  rw  use32  public  'data' 


;_y 

;_dx 
;  ah 


al 

al 

al 

dx 

ah 


local 

local 

local 

local 

local 

local 


;_int_count 

esi 

local 

;_int  duration 

edi 

local 

;_count 

ecx 

local 

;_int_pitch 

ebx 

local 

; parameters 

;  j)itch 

ebx 

local 

;  duration 
dataseg  ends 
end 

[esp] +20 

local 

End  Listing  Three 


Listing  Four 


♦include  <stdio.h> 

♦include  <dosl.h> 

♦include  <ctype.h> 

/*  ***WARNING***  if  you  change  the  scale  so  that  it  starts 

on  middle  C,  instead  of  A,  the  resulting  routine  will 
exhibit  not  only  the  look  and  feel  of  the  BASIC  PLAY 
command,  but  its  sound  as  well. 


*/ 


*/ 

♦define 

aa 

440 

/* 

middle  a  =  440 

♦define 

as 

469 

/* 

a  sharp  */ 

♦define 

bb 

493 

♦define 

cc 

523 

/* 

middle  c  */ 

♦define 

cs 

556 

♦define 

dd 

587 

♦define 

ds 

624 

_ _ 

(Listing  continued  on  page  124) 
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Listing  Four  (Listing  continued ,  text  begins  on  page  78.) 

♦define  ee  659 

♦define  ff  698 

♦define  fs  739 

♦define  qq  783 

♦define  gs  832 


♦define  outp(p,v)  dx  =  p;al  =  v;asm(dx,al, "  out  dx,al") 
♦define  inp(p,v)  dx  =  p;asm(dx,"  in  al,dx",al);v  =  al 

unsigned  char  x,y,page  =  0;  /*  globals  for  pc_test  */ 
void  note ( } ; 

void  look_ahead_and_toot ( ) ; 

void  play () ; 

int  check_length{) ; 

int  check_integer () ; 

int  gobble_dots () ; 

/*  the  buffer  for  the  notes  to  be  input  */ 


int  pitch; 
int  count  =  0; 
int  length  =  4; 
int  tempo  =  240; 
int  duration  =  60; 
int  shift  =  0; 
char  c_note; 


/*  points  to  current  location  in  string  */ 

/*  default  is  a  quarter  note  */ 

/*  =  120  beats  per  minute  */ 

/*  =  tempo/length  =1/4  @  120  bpm  */ 

/*  current  octave  shift  factor  */ 

/*  the  current  note  character  used  for  diag  */ 


main () 

{  /*  Stereo  version  of  Heart  and  Soul  for  two  PCs 

lifted  from  a  BASIC  program  Transcribed  by 
Michael  Benjamin  Fried  -  Age  11  */ 

/*  bass  line  plays  on  first  machine  */ 
play (  "T150L804CCEEAACCDDFF03GG>BB04 " ) ; 
play  (  "L804CCEEAACCDDFF03GOBB04")  ; 

/*  while  melody  plays  on  a  second  */ 
play (  "04L4CCC.P32C8B8A8B8C8D8P32") ; 

play (  "EEE.P32E8D8C8D8E8F8G.C.>A8<G8F8E8D8CB8Ao3G8FFGGo4") ; 

} 

void  play (in_string) 
char  in_string[]; 

{ 

int  temp_duration;  /*  gets  set  by  L  or  change  in  1  */ 

int  temp_octave;  /*  holds  temporary  octave  */ 

char  n_note; 
count  =  0; 

printf ("note  =  %s  \n", in_string) ; 

while  (c_note  =  in_string[ count] ) {  /*  loop  till  out  of  characters  */ 
n_note  =  in_string(count+l] ;  /*  look  ahead  1  char  now  */ 

switch (c_note) {  /*  switch  on  current  note  */ 


case  'A':  /*  do  a,a  sharp  and  a  flat  */ 

case  ' a' : 

pitch  =  aa;  /*  set  the  default  to  A  natural  */ 
if  ( (n_note  ==  '♦')!! (n_note  ==  '+')){ 

pitch  =  as;  /*  it  was  A  sharp  */ 
count ++; 

} 

if  (n_note  ==  /*  it  was  A  flat  */ 

pitch  =  gs;  /*  A  flat  ==  G  sharp  */ 
count ++; 

} 

look_ahead_and_toot (in_string) ;  /*  self  explanatory  */ 
break;  /*  line  duration  */ 


case  'B':  /*  B  is  just  like  A  */ 

case  'b' : 

pitch  =  bb; 

if  {(n_note  ==  '♦')!! (n_note  ==  '+')){ 

pitch  =  cc;  /*  B  sharp  is  actually  C  */ 
count++; 

} 

if  (n_note  == 

pitch  =  as;  /*  B  flat  is  A  sharp  */ 
count++; 

) 

look_ahead_and_toot (in_string) ; 
break; 


case  'C':  /*  C  is  just  like  A  */ 

case  'c'  : 

pitch  =  cc; 

if  ( (n_note  ==  '♦')!! (n_note  ==  '+')){ 
pitch  =  cs; 
count++; 

} 

if  (n_note  ==  /*  C  flat  is  actually  B  */ 

pitch  =  bb;  /*  and  a  perfectly  legal  note  */ 
count++; 

) 

look_ahead_and_toot (in_string)  ; 

break; 


case  'D' :  /*  D  is  like  A  */ 

case  'd' : 

pitch  =  dd; 

if  ( (n_note  ==  ' ♦' ) I ! (n_note  ==  '+')){ 
pitch  =  ds; 
count++; 

) 

if  (n_note  == 

pitch  =  cs;  /*  D  flat  is  C  sharp  */ 
count ++; 

} 

look_ahead_and_toot (in_string) ; 
break; 


case  'E' :  /*  E  is  like  A  */ 

case  'e' : 

pitch  =  ee; 

if  ( (n_note  ==  '♦')!! {n_note  ==  '+')){ 
pitch  =  ff;  /*  E  sharp  is  F  */ 


count++; 

) 

if  (n_note  =  )  { 

pitch  =  ds; 
count++; 

} 

look_ahead_and_toot (in_string) ; 

break; 

case  'F':  /*  F  is  like  A  */ 

case  ' f '  : 

pitch  =  ff; 

if  ( (n_note  ==  '♦')!''  (n_note  ==  '+')){ 
pitch  =  fs; 
count++; 

} 

if  (n_note  == 

pitch  =  ee; 
count ++; 

} 

look_ahead_and_toot (in_string) ; 

break; 


case  'G' :  /*  G  is  like  A  */ 

case  ' q'  : 

pitch  =  gg; 

if  ( (n_note  ==  '♦');! (pitch  ==  '+')){ 
pitch  =  gs; 
count++; 

} 

if  (n_note  ==  { 

pitch  =  fs; 
count++; 

} 

look_ahead_and_toot (in_string) ; 

break; 


case 

case 


/  :  /*  set  length  */ 

if (temp_duration  =  check_length (in_string) ) ( 
duration  =  tempo/temp_duration; 
length  =  temp_duration; 


break; 


} 


shift++; 

break; 


shift- 

break; 


/*  go  up  an  octave  */ 

/*  go  down'  an  octave  */ 

/*  chose  an  octave  */ 


case  'O' : 
case  'o' : 

temp_octave  =  njnote  -  'O'; 

if  ( (temp_octave  <  0) ! ! (temp_octave  >  6) ) ( 
printf ("octave  out  of  range"); 
break; 

} 

switch (n_note) { 

case  ' 0' : 

shift  =  -4; 
break; 
case  ' 1' : 

shift  =  -3; 
break; 
case  '  2'  : 

shift  =  -2; 
break; 
case  ' 3' : 

shift  =  -1; 
break; 
case  ' 4'  : 

shift  =  0; 
break; 
case  '  5'  : 

shift  =  1; 
break; 
case  ' 6' : 

shift  =  2; 


/*  default  octave  */ 


count ++; 
break; 


case 

case 

case 

case 


break; 

/*  advance  over  digit  */ 


/*  set  pause/rest  length  */ 

/*  issue  note  of  freq  0  to  rest  */ 
/*  computer  scientists  pause  */ 

/*  but  musicians  rest!  */ 


pitch  =  0; 

look_ahead_and_toot (in_string) ; 
break; 


case  'T':  /*  set  tempo  */ 

case  't' : 

temp_duration  =  check_integer (in_string) ; 
if  ( (temp_duration  <  32) ! ! (temp_duration  >  255)) 
break; 

tempo  =  temp_duration*2; 
duration  =  tempo/length; 
break; 

case  '  ' :  /*  spaces  are  gobbled  up  */ 

break; 

default:  /*  had  a  problem  so  issue  error  */ 

printf ("Syntax  error  in  character  %d  \n", count); 
goto  terminate; 

} 

count++;  /*  advance  pointer  to  next  note  */ 

) 


124 
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terminate: 

} 

/*  The  trickiest  part  of  the  syntax  are  the  optional  trailers  that 
can  follow  each  note.  These  include  an  optional  integer  that 
specifies  a  quarter  (4)  or  eighth  note  (8)  (or  any  integer 
between  1  and  64)  and  1  or  more  optional  dots,  each  of  which 
increases  the  current  duration  by  half.  This  section  parses 
these  trailers,  and  then  uses  the  global  variables  that  contain 
the  tempo  and  octave  to  compute  the  duration  and  pitch,  and 
then  call  note.  Note  that  rests  are  handled  as  notes  of  0  pitch. 


void  look_ahead_and_toot (in_string) 
char  in_string [ ] ; 

| 

int  temp_duration; 

if  (temp_duration  =  check_length (in_string) )  /*  if  non  zero  have  a  temp  */ 
temp_duration  =  tempo/temp_duration;  /*  compute  new  duration  */ 

else 

temp_duration  =  duration;  /*  if  0  play  default  duration  */ 

/*  check  for  dot,  and  if  found  call  gobble_dots  to  increase  temp_duration  : 
if  (in_string[count+l]  ==  '.') 

temp_duration  =  gobble_dots (temp  duration, in_string) ; 

/*  range  check  octaves  *7 

if  (shift  <  -4) 

shift  =  -4; 
if  (shift  >  2) 

shift  =  2; 

/*  shift  to  change  octaves  */ 

if  (shift  <  0)  /*  negative  shifts  go  down  in  frequency  */ 

pitch  =  pitch  »  -shift; 

else  /*  positive  shifts  go  up  in  frequency  */ 

pitch  =  pitch  «  shift; 

/*  optional  diagnostics  for  debugging  */ 
printf("%c  =  %d  duration  =  %d  octave  =  d\n", 

c_note, pitch, temp_duration, shift+4) ; 

/*  finally  we  are  ready  for  a  little  toot  */ 
note (pitch, temp_duration) ; 

} 

int  gobble_dots (duration_in, in_string) 
int  duration_in; 
char  in_string[]; 

{ 

int  duration_out; 
int  duration_increment; 
duration_out  =  duration_in; 
duration_increment  -  duration_in; 

/*  gobble  as  long  as  there  are  dots  adding  half  the  prior  duration  inc  */ 
while  (in_string [count+1]  == 

duration_increment  =  duration_increment  »  1;  /*  divide  it  by  2  */ 

duration_out  =  duration_out  +  duration_increment; 

count++;  /*  advance  string  pointer  */ 

} 

return (duration_out) ; 

) 

/*  returns  1-64  in  range  1-64  else  returns  0  */ 
int  check_length(in_string) 
char  in_string[); 

I 

int  result  =  check_integer (in_string) ; 

if  ((result  <  1)  II  (result  >  64)) 

return (0);  /*  out  of  range  */ 

else 


return (result) ;  /*  in  range  */ 

1 

/*  0  1  to  999  if  1  -  999  found  and  advances  count 
/*  returns  0  otherwise  */ 
int  check_integer (in_string) 
char  in_string[]; 

{ 

int  n_char,m_char, l_char; 
n_char  =  in_string [count+1]  -  'O'; 
if  ( (n_char  >  9)  ! !  (n_char  <  0))  return  (0); 


/*  return  if  out  of  range  */ 


we  found  a  digit  so  advance  count 
/*  check  next  integer  */ 


count ++;  /* 

m_char  =  in_string [count+1]  -  'O'; 
if  ( (m_char  >9)  II  (m_char  <  0) ) 
return  (n_char) ; 

else 

count++; 

l_char  =  in_string [count+1]  -  'O'; 
if  ((l_char  >9)  ::  (l_char  <  0))  /* 
return  (n_char*10+m_char) ;  / 

else  ( 

count++;  /*  we  found  a  third  and  last  digit 

return (n_char*100+m_char*10+l  char) ; 

) 


*/ 


/‘found  second  didit  so  advance  again  */ 


check  last  possible  digit  */ 
k  compute  2  digit  result  */ 


7 


/*  optional  main  program  works  as  an  interactive  interpreter  */ 
char  note  string[120]; 

/* 

main  () 


do{ 

puts ("enter  note  "); 
f flush (stdin) ; 
gets (note_string) ; 

printf ("\nnote  string  =  %s  \n",note  string); 
play() ; 

}  while  (strlen (note_string)  >  0); 


End  listings 
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Revisited 

Speeding  up  an  old  data  compression  favorite 


Shawn  M.  Regan 


When  the  October  1989  issue 
of  Dr.  Dobb’s  came  out,  I 
was  delighted  to  see  Mark 
Nelson’s  article  on  LZW 
data  compression  (“LZW 
Data  Compression”).  Mark  presented 
a  clear  description  with  code  of  a  basic 
LZW  compression  program.  As  I  used 
the  program,  however,  I  discovered 
that  for  some  larger  files,  even  when 
using  14-bit  codes,  the  compressed  file 
would  actually  be  larger  than  the  origi¬ 
nal.  Because  Mark’s  intention  was  to 
enlighten  and  not  to  complicate  the 
subject,  his  code  omitted  some  opti¬ 
mizing  additions  to  LZW  compression. 
Although,  he  did  describe  some  opti¬ 
mization  techniques  —  including  the 
use  of  variable  code  size  —  as  well  as 
clearing  the  string  table  after  the  com¬ 
pression  ratio  degrades. 

The  original  program’s  lack  of  per¬ 
formance  on  larger  files  can  be  traced 
to  the  fixed-length  string  table.  When 
the  table  is  full,  new  codes  cannot  be 
added  and  must  be  sent  out  in  charac¬ 
ter  form  with  no  compression  done. 
When  this  happens,  you  could  actually 
be  sending  out  an  8-bit  character  using 
a  14-bit  code;  this  explains  how  the  file 
can  get  larger.  If  your  incoming  data 
changes,  even  moderately,  with  the 
string  table  full,  then  the  compression 
ratio  begins  to  degrade  rapidly. 

With  this  in  mind,  imagine  compress¬ 
ing  a  small  file  with  your  code  size  set 
at  14  bits.  If  your  string  table  needs  less 
than  511  entries,  you  could  have  used 
9-bit  codes  saving  5  bits  per  output 
code.  Of  course  you  wouldn’t  want  to 
fix  your  code  size  at  9  bits  because  the 


Shawn  is  a  programmer/analyst  forMi- 
croBilt  Inc.  of  Atlanta,  Georgia.  You 
can  reach  him  through  Interlink;  or 
write  to  him  at  2127B  Powers  Ferry 
Rd.,  Marietta,  GA  30067. 


compression  on  larger  files  would  suf¬ 
fer.  What  you  would  like  is  for  the  code 
size  to  start  at  9  bits  and  if  that  table 
filled,  the  code  size  could  increment 
to  10,  thus  providing  optimal  perfor¬ 
mance  on  any  size  file. 

My  Implementation 

One  of  the  more  elegant  features  about 
LZW  compression  are  that  the  compres¬ 
sion  and  expansion  programs  build  the 
exact  same  string  table  for  a  particular 
file.  This  means  at  the  same  point  the 
compression  program’s  string  table  is 
full  so  is  the  expansion  program’s.  At 
this  point  you  should  try  to  adjust  your 
code  size.  As  you  can  see  in  the  com¬ 
pression  section  of  Listing  One  (page 
127),  I  wait  until  after  I  have  sent  out 
the  current  code  before  the  code  size 
is  incremented  because  the  current  code 
belongs  to  the  previous  code  size.  No¬ 
tice  in  the  compression  section  I  incre¬ 
ment  when  the  code  size  is  greater 
than  max_code,  while  in  the  expan¬ 
sion  program  I  increment  when  the 
code  size  equals  max_code.  This  is  be¬ 
cause  the  expansion  section  is  work¬ 
ing  a  code  behind  using  old_code  in¬ 
stead  of  new_code.  It  is  also  because 
of  this  that  I  must  handle  a  special  case 
when  incrementing  the  code  size  on 
an  end-of-file  condition. 

Finally,  you  should  also  set  some 
arbitrary  limit  on  your  code  size.  If  you 
use  14  bits,  your  codes  stay  well  under 
the  positive  integer  maximum  of  32767, 


which  suits  the  program  without  any 
modification.  Don’t  forget  your  table 
size  needs  to  be  a  prime  number  some¬ 
what  larger  than  2~MAX_CODE_SIZE. 
To  implement  the  table  clearing,  start 
by  monitoring  the  number  of  bytes  (not 
codes)  read  in  and  then  sent  out.  After 
a  predetermined  interval,  compute  the 
new  compression  ratio  and  check  it 
against  the  previous  one.  If  the  ratio 
has  increased,  you  need  to  clear  out 
the  string  table  and  start  over.  You  then 
need  a  device  to  send  a  signal  from  the 
compression  program  to  the  expan¬ 
sion  program  to  clear  the  string  table. 
The  easiest  way  to  accomplish  this  is 
by  reserving  the  first  of  the  9-bit  codes. 
In  my  example,  I  used  256  as  the 
CLEAR_TABLE  code.  I  also  used  257 
as  the  TERMINATORto  signal  the  end-of- 
file  condition.  This  means  the  first  avail¬ 
able  code  for  compression  is  now  258, 
which  I’ve  defined  as  FIRST_CODE. 

When  combining  both  methods,  you 
should  not  experience  any  degrada¬ 
tion  in  compression  until  the  table  is 
full.  When  the  table  is  full,  you  will  first 
check  to  see  if  you  can  increase  the 
code  size.  If  you  can’t,  then  (and  only 
then)  will  you  start  to  monitor  your 
compression  ratio  at  your  predefined 
interval  and  ultimately  clear  the  string 
table.  When  this  happens,  you  can  re¬ 
set  your  code  size  back  to  9-bits  be¬ 
cause  basically  you’re  starting  from 
scratch.  Although  you  still  won’t  get 
performance  as  good  as  PKZIP  (from 


Before 

After 

%  of  Original 

File  type 

115,094 

40,636 

35% 

.C  -  C  program 

11,054 

4,811 

43% 

.C  -  C  program 

230,582 

141,659 

61  % 

.EXE  -  Executable 

16,944 

12,905 

76% 

.EXE  -  Executable 

90,610 

20,806 

22% 

.TXT  -  Redundant  text  file 

110,592 

64,804 

58% 

.LIB  -  C  object  library 

Table  1:  Typical  compression  levels  using  revised  LZW 


126 


Dr.  Dobb’s  Journal,  June  1990 

553 


PKWARE,  Glendale,  Wise.),  you  now 
have  the  source  for  a  much  improved 
version  of  this  basic  LZW  compression 
program.  Table  1  lists  some  typical  com¬ 
pression  levels  I’ve  achieved  with  this 
program. 

Your  Implementation 

Even  though  the  program  works  well 
as  is,  there  are  still  some  improvements 
that  can  be  made.  As  Mark  suggested, 
the  input  and  output  routines  can  be 

For  better  compression, 
you  might  experiment 
with  table  clearing 


modified  for  more  speed.  Also,  a  more 
sophisticated  hashing  routine  might 
speed  it  up.  For  better  compression, 
you  might  experiment  with  table  clear¬ 
ing.  I  found  on  .EXE  files  the  com¬ 
pression  ratio  drops  steadily  after  a  code 
size  increase,  then  bottoms  out  and 
then  starts  rising  again.  If  you  suspend 
clearing  until  you  are  back  to  just  be¬ 
low  the  starting  ratio  you  can  get  a 
somewhat  better  compression.  I  also 
noticed  that  in  smaller  text  files,  I  can 
at  times  get  better  compression  by  clear¬ 
ing  the  table  instead  of  increasing  the 
code  size.  Be  careful,  however,  about 
basing  any  optimization  methods  on 
any  preanalysis  of  the  data.  If,  for  ex¬ 
ample,  you  wish  to  use  it  with  stream 
I/O  you  will  be  working  with  buffers 
and  not  files  where  any  preanalysis 
might  be  difficult  or  useless. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  12. 


LZW  REVISITED 


Listing  One 

/*  Basic  LZW  Data  Compression  program  published  in  DDJ  October  1989  issue. 

*  Original  Author:  Mark  R.  Nelson 

*  Updated  by:  Shawn  M.  Regan,  January  1990 

*  Added:  -  Method  to  clear  table  when  compression  ratio  degrades 

-  Self  adjusting  code  size  capability  (up  to  14  bits) 

*  Updated  functions  are  marked  with  "MODIFIED".  main()  has  been  updated  also 

*  Compile  with  -ml  (large  model)  for  MAX  BITS  ==14  only 
*/ 

♦include  <stdio.h> 


♦define  INIT_BITS  9 

♦define  MAX_BITS  14  /*  Do  not  exceed  14  with  this  program  */ 

♦define  HASHING_SHIFT  MAX_BITS  -  8 

♦if  MAX_BITS  ==  14  /*  Set  the  table  size.  Must  be  a  prime  */ 

♦define  TABLE_SIZE  18041  /*  number  somewhat  larger  than  2AMAX_BITS.*/ 

♦elif  MAX_BITS  ==13 
♦define  TABLE_SIZE  9029 
♦else 

♦define  TABLE_SIZE  5021 
♦endif 


♦define  CLEAR_TABLE  256  /*  Code  to  flush  the  string  table  */ 

♦define  TERMINATOR  257  /*  To  mark  EOF  Condition,  instead  of  MAX_VALUE  */ 

♦define  FIRST_CODE  258  /*  First  available  code  for  code  value  table  */ 


♦define  CHECKJTIME  100  /*  Check  comp 

♦define  MAXVAL(n)  ((  1  «(  n  ))  -1)  /* 

unsigned  input_code ( ) ; 
void  *malloc(); 


int  *code_value;  /* 
unsigned  int  *prefix_code;  /* 
unsigned  char  *append_character;  /* 
unsigned  char  decode_stack [4000] ;  /* 

int  num_bits=INIT_BITS;  /* 
unsigned  long  bytes_in=0,bytes_out=0;  /* 
int  max_code;  /* 
unsigned  long  checkpoint=CHECK_TIME;  /* 


ratio  every  CHECKJTIME  chars  input  */ 
max_value  formula  macro  */ 


This  is  the  code  value  array  */ 

This  array  holds  the  prefix  codes  */ 
This  array  holds  the  appended  chars  */ 
This  array  holds  the  decoded  string  */ 

Starting  with  9  bit  codes  */ 

Used  to  monitor  compression  ratio  */ 
old  MAX_C0DE  */ 

For  compression  ratio  monitoring  */ 


main (int  arge,  char  *argv[]) 

{ 

FILE  *input_file,  *output_file,  *lzw_file; 
char  input_file_name [81] ; 

/*  The  three  buffers  for  the  compression  phase.  */ 
code_value=malloc (TAELE_SIZE*sizeof (unsigned  int) ) ; 
prefix_code=malloc (TABLE_SIZE*sizeof (unsigned  int) ) ; 
append_character=malloc (TABLE_SIZE*sizeof (unsigned  char) ) ; 


if  (code_value==NULL  ! :  prefix_code==NULL  I :  append_character==NULL)  { 
printf ("Error  allocating  table  space !\n"); 
exit (1) ; 

} 

/*  Get  the  file  name,  open  it,  and  open  the  LZW  output  file.  */ 
if  (argc>l) 

strepy (input_file_name,argv[l] ) ; 
else  { 

printf ("Input  file  name:  "); 
scanf ("%s",input_file_name) ; 

} 

input_file=fopen (input_file_name, "rb") ; 
lzw_file=fopen ("test . lzw" , "wb") ; 
if  (input_file  ==  NULL  ! !  lzw_file  ==  NULL)  ( 
printf ("Error  opening  files\n"); 
exit (1) ; 


max_code  =  MAXVAL (num_bits) ;  /* 

compress (input_f ile, lzw_f ile) ; 

fclose (input_file) ; 
fclose (lzw_f ile) ; 
free (code_value) ; 

lzw_file=fopen ("test .lzw", "rb") ; 
output_f  ile=f open ( "test . out" , "wb" ) ; 
if  (lzw_file  ==  NULL  ! I  output_file 
printf ("Error  opening  files\n"); 
exit  (1) ; 

) 

num_bits=INIT_BITS; 
max_code  =  MAXVAL (num_bits) ; 
expand (lzw_f ile,  out put_f ile) ; 


Initialize  max_value  &  max_code  */ 
/*  Call  compression • routine  */ 

/*  Needed  only  for  compression  */ 

==  NULL)  { 

/*  Re-initialize  for  expansion  */ 
/*  Call  expansion  routine  */ 


fclose (lzw_file) ;  /*  Clean  it  all  up  */ 

fclose (output_file) ; 
free (pref ix_code) ; 
free (append_character) ; 

) 

/*  MODIFIED  This  is  the  new  compression  routine.  The  first  two  9-bit  codes 
*  have  been  reserved  for  communication  between  the  compressor  and  expander. 
*/ 

compress (FILE  *input,  FILE  ‘output) 

( 

unsigned  int  next_code=FIRST_CODE; 
unsigned  int  character; 
unsigned  int  string_code; 
unsigned  int  index; 

int  i,  /*  All  purpose  integer  */ 

ratio  new,  /*  New  compression  ratio  as  a  percentage  */ 

ratioj3ld=100;  /*  Original  ratio  at  100%  */ 


for  (i=0; i<TABLE_SIZE; i++)  /*  Initialize  the  string  table  first  */ 

code_value [i] =-l; 
printf ("CompressingXn") ; 

string_code=getc (input) ;  /*  Get  the  first  code  */ 

(continued  on  page  167) 
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PROGRAMMING  PARADIGMS 


HyperCard  and  (or?) 
Hypertext 


The  only  honest  way  to  start  a 
column  about  the  suitability  of 
this  product  for  hypertext  is  by 
quoting  its  creator: 

“1  don ’t  think  of  HyperCard  at 
all  as  a  hypertext  system.  It  is  not  a 
very  good  one.”  — Bill  Atkinson. 

That  would  also  be  the  end  of  the 
column  if  every  father  knew  his  own 
child.  But  out  there  on  the  nets  over 
the  past  three  years,  HyperCard  has 
been  doing  things  Bill  never  envisioned, 
and  is  playing  an  important  role  in  the 
development  of  hypertext  systems.  The 
role  is  a  research  role. 

Field  Research 

Since  Apple  caved  in  to  Atkinson’s  ulti¬ 
matum,  agreed  that  HyperCard  was  sys¬ 
tem  software,  and  began  bundling  it 
with  every  new  Macintosh  back  in  1987, 
HyperCard  authors  of  varying  levels 
of  skill  have  been  all  over  the  nets, 
showing  their  work  with  the  obnox¬ 
ious  eagerness  of  a  teacher’s  pet  in 
grade  school.  I  predicted  in  DDJ  back 
then  that  the  release  of  HyperCard 
would  lead  to  a  hyperglut  of  trashware, 
a  pretty  obvious  prediction. 

Not  all  this  hyperactivity  is  trashware; 
and  even  in  the  trash  there  are  some 
interesting  items.  (Jean-Louis  Gassee  says 


Michael  Swaine 


that  this  latter  point  is  not  lost  on  trash 
can  grubbing  “MacLeak”  reporters,  but 
he’s  just  grumpy  because  he  had  to 
give  back  the  company  car.)  (Many 
Americans  discovered  the  joy  of  search¬ 
ing  through  trash  cans  in  the  1980s,  for 
which  Apple  must  share  the  credit  with 
Ronald  Reagan.)  (The  parenthetical  note 
is  one  technique  that  writers  use  to 
overcome  the  limitations  of  linear  text. 


It’s  a  kludge.)  Interesting  items,  I  was 
saying,  thinking  particularly  of  what 
can  be  learned  from  that  “interesting 
experiment”  that  didn’t  quite  work  out. 
A  lot  of  HyperCard  development  fits 
this  description. 

I  want  to  call  this  undisciplined,  un¬ 
controlled,  enthusiastic  amateur  Hyper¬ 
Card  development  work  “research,”  but 
this  is  bending  the  word.  Then  again, 
magazines  sometimes  use  the  word  “re¬ 
search”  to  refer  to  casual  reader-inter¬ 
est  surveys,  which  is  just  as  bad.  These 
two  uses  are,  and  you  saw  this  word 
here  first,  “isotropes”  —  they’re  simi¬ 
larly  bent. 

Moving  right  along.  There  is  a  lot  of 
serious,  professional,  controlled  experi¬ 
mentation  in  hypertext  going  on  in  uni¬ 
versities  and  in  the  few  corporate  re¬ 
search  labs  that  haven’t  turned  into  short- 
range  product  development  shops.  In 
particular,  the  people  at  Brown  Univer¬ 
sity’s  IRIS  (Institute  for  Research  in  In¬ 
formation  and  Scholarship)  have  been 
following  one  thread  of  hypertext  re¬ 
search  ever  since  Ted  Nelson  coined 
the  term,  and  have  demonstrated  the 
virtues  of  hypertext  for  promoting  non¬ 
linear  thinking.  This  kind  of  result  does 
not  come  from  playing  with  Hyper¬ 
Card  and  uploading  your  work  to  Com¬ 
puServe. 

But  in  a  looser  sense,  these  Hyper¬ 
Card  experiments,  failed  and  flawed 
as  they  may  be,  are  crude  offerings  of 
aspects  of  hypertext.  Seeing  what  has 
been  tried,  and  how  it  has  been  re¬ 
ceived  out  there  among  the  savages,  is 
an  education  in  hypertext  field  research. 

“Crude  offerings,”  I  say,  but  I  do  not 
mean  it  as  a  criticism  of  the  developers. 
HyperCard  is,  as  Atkinson  acknowl¬ 
edges,  not  a  hypertext  system.  What  is 
it,  and  why  are  people  using  it  to  do 
hypertext-like  things?  Atkinson  calls  it 
a  “software  erector  set.”  That’s  pretty 
accurate,  down  to  the  point  made  by 


one  critic  that  when  you  build  things 
with  an  erector  set,  you  get  things  that 
look  like  they  were  built  with  an  erec¬ 
tor  set.  HyperCard  provides  a  limited 
set  of  classes  of  objects:  Stacks  (which 
are  HyperCard  documents),  cards  (in¬ 
formation  chunks  displayed  as  screen¬ 
sized  bitmap),  fields  for  text  (which 
can  exceed  the  screen  size  by  scroll¬ 
ing),  and  buttons  (basically  icons  with 
attached  programs).  In  limited  object- 
oriented  style,  HyperCard  lets  you  cre¬ 
ate  stacks  by  writing  message  handlers 
and  associating  them  with  instances  of 
these  classes  of  objects.  The  basic  meta¬ 
phor  is  of  a  stack  of  3  x  5  cards,  each 
card  displaying  text  and/or  graphics, 
and  the  cards  linked  to  one  another 
quite  freely,  with  buttons  being  the 
usual  tool  for  following  the  links. 

This  model  supplies  several  things 
that  a  hypertext  system  ought  to  have. 
The  user  can  create  links  among  chunks 
of  information  without  doing  any  pro¬ 
gramming  and  the  programmer  can  cre¬ 
ate  different  links  relatively  easily.  Hy¬ 
perTalk,  the  programming  language  in 
HyperCard,  is  interpreted,  so  it’s  a  quick 
development  tool,  yet  it’s  powerful  for 
an  interpreted  language.  Apple  gives 
HyperCard  away  with  every  new  ma¬ 
chine,  so  you  can  count  on  Mac  users 
having  it,  and  this  also  has  led  to  a  lot 
of  people  having  fiddled  with  it,  so 
HyperCard  is  helping  to  spread  famili¬ 
arity  with  some  hypertext  ideas. 

It  also  lacks  some  things  a  hypertext 
system  needs.  It  has  no  built-in  naviga¬ 
tion  system,  although  Apple  encour¬ 
ages  stack  developers  to  include  maps 
in  their  stacks.  There  is  nothing  analo¬ 
gous  to  a  browser.  HyperCard’s  links 
are  coarse-grain  links,  taking  the  reader 
from  card  to  card.  Fine-grain  linking, 
triggering  off  items  the  size  of  an  indi¬ 
vidual  word,  is  possible,  but  is  not  in¬ 
herent  in  the  product.  HyperCard  has 
no  text  links. 
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In  Search  of  the  Missing  Link 

The  biggest  failing  of  HyperCard  for 
anyone  interested  in  hypertext  is  the 
lack  of  text  links.  By  the  time  this  col¬ 
umn  sees  print  —  I’m  writing  this  in 
January,  believe  it  or  not  —  Apple 
should  have  released  Version  2.0  of 
HyperCard,  widely  expected  to  imple¬ 
ment  some  kind  of  text  links.  I  think  it’s 
fairly  safe  to  predict  that  Apple’s  text 
links  will  not  satisfy  all  those  people 
who  want  HyperCard  to  -be  a  better 
hypertext  tool. 

The  text  link  solution  supported  in 
Version  2  is  likely  to  be  an  extension 
of  the  button  model.  As  I  write  this, 
buttons  are  the  chief  tool  in  HyperCard 
for  supporting  links.  A  button  is  re¬ 
stricted  to  one  line  (usually  a  word  or 
two)  of  text.  Fields  are  where  you  put 
text  in  HyperCard.  Fields  were  never 
designed  to  support  linking. 

HyperTalk  programmers  have  been 
coding  workarounds  for  this  failing  since 
HyperCard  was  released,  though,  and 
some  of  these  are  effective  in  limited 
domains.  The  work  these  programmers 
are  doing  with  text  links  typifies  the 
kind  of  work  being  done  with  Hyper¬ 
Card  in  other  hypertext  or  hypermedia 
areas,  and  it  shows  how  easy  it  is  to 
test  alternative  hypertalk  user  interface 
techniques  using  HyperCard. 

What  Atkinson  gave  us  is  the  button. 
To  create  a  link  to  another  section  (card) 
of  a  HyperCard  document  (stack)  or 
to  another  stack,  you  create  a  button 
and  link  it  to  the  card  or  stack.  The  link 
is  by  default  unidirectional,  except  that 
the  user  can  always  return  from  a  linked 
card  via  a  standard  key  combination 
or  menu  selection.  If  you  want  explicit 


bidirectional  links,  you  have  to  create 
and  link  two  buttons.  (Buttons  can  also 
be  used  to  trigger  pop-up  fields,  for 
such  fine-grained  hypertext  purposes 
as  displaying,  in  a  pop-up  window  or 
field,  a  definition  of  a  term.) 

The  first  thing  many  people  did  when 
they  started  working  with  HyperCard 
was  to  place  an  invisible  button  over  a 
text  field  or  a  graphic  to  make  some¬ 
thing  happen  when  the  text  or  graphic 
was  clicked  on.  The  earliest  stacks  from 
Apple  used  this  technique.  One  early 
third-party  developer  who  made  good 
use  of  such  invisible  buttons  is  Amanda 
Goodenough,  whose  AmandaStories 
stacks  showed  one  way  to  author  inter¬ 
active,  child-directed  stories  for  young 
readers.  But  the  buttons  were  con¬ 
strained  to  be  rectangles  and  were  not 
really  connected  with  the  text  or  art 
with  which  they  were  associated. 
Change  the  text,  copy  the  art  and  paste 
it  elsewhere,  move  the  button,  and  the 
button  is  no  longer  associated  with  the 
text  or  graphic. 

Soon  after  HyperCard’s  release,  Keith 
Rollin  of  Apple  demonstrated  how  to 
write  a  HyperCard  external  command 
to  implement  region  buttons.  These  but¬ 
tons,  which  used  QuickDraw  regions, 
could  take  on  arbitrary  polygonal 
shapes.  This  development,  along  with 
the  fixed  bitmap  of  a  card  (which  makes 
screen  position  a  somewhat  reason¬ 
able  way  to  refer  to  a  picture),  appears 
to  make  transparent  buttons  fairly  use¬ 
ful  for  linking  off  pictures.  Good  stacks 
continue  to  be  developed  using  this 
technique.  But  it  doesn’t  do  the  job  for 
text:  You  can’t  even  change  the  font  in 
a  field  without  having  to  reposition  the 


button.  For  hypertext  linking,  you  need 
to  be  able  to  link  off  text,  not  off  a 
screen  position. 

One  step  toward  better  linking  might 
be  to  extend  the  find  facility  of  Hyper¬ 
Card.  Users  can  already  select  text  in  a 
field  and  perform  a  find  operation.  Why 
not  insert  a  step  between  selection  of 
the  text  and  the  conventional  search? 
If  the  text  selected  is  on  a  list  of  hy¬ 
pertext  link  words,  follow  the  link;  oth¬ 
erwise,  let  the  find  proceed  as  usual. 
Harvey  Chang  and  Steve  Drazga  are 
two  stack  developers  who  extended 
the  find  function.  Listing  One  (page 
153)  shows  Drazga’s  hypertext  tech¬ 
nique  while  Chang’s  is  in  Listing  Two 
(page  153).  Chang’s  technique  starts 
by  allowing  the  user  to  select  any  con¬ 
tiguous  text,  even  dragging  across  word 
boundaries.  Then  it  attempts  to  use  the 
selected  text  as  the  name  of  a  card  in  a 
“go  to  card  ...”  command.  If  that  fails, 
it  uses  the  selected  text  as  a  conven¬ 
tional  search  string.  His  implementa¬ 
tion  suffers  from  the  requirement  that 
the  user  select  text,  then  explicitly  click 
on  a  hypertext  button. 

There  are  a  couple  of  problems  with 
this  technique  as  an  approach  to  hy¬ 
pertext.  (Chang,  I  should  point  out, 
doesn't  call  it  that.)  First,  it  doesn’t  give 
the  reader  any  indication  of  where  the 
links  are.  Second,  it  raises  the  question 
of  what  unit  of  text  can  serve  as  links. 

Which  Text  is  Hyper? 

Chang’s  technique  doesn’t  identify  the 
links,  so  the  reader  must  hit  them  by 
chance.  In  other  hypertext  systems,  the 
linking  text  is  often  identified  by  a 
change  in  type  style:  Boldface,  italic, 
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underlining,  or  all  of  these,  may  be 
used.  HyperCard  doesn’t  make  such 
an  approach  easy.  Text  fields  in  Hyper¬ 
Card  are  impoverished  text  of  a  single 
font,  size,  and  style.  One  stack  devel¬ 
oper,  Gregory  Nelson,  investigated  what 
it  would  take  to  create  even  the  ap¬ 
pearance  of  rich  text  in  HyperCard  fields. 
He  faked  rich  text  by  using  10  (!)  over¬ 
lapping  fields  and  a  thoroughly  un¬ 
workable  text-entry  procedure.  That 
blind  alley  is  thoroughly  mapped, 
thanks  to  Nelson. 

John  Anderson  had  better  luck  in 
introducing  style  variations  in  Hyper¬ 
Card  fields,  by  creating  a  specialized 
font  that  included  italic  and  roman  char¬ 
acters.  Because  it  means  losing  the  spe¬ 
cial  characters  that  had  been  in  the 
font,  this  approach  trades  text  impov¬ 
erishment  for  font  impoverishment,  and 
is  still  a  long  way  from  support  for  the 
kind  of  hypertext  link  identification  seen 
in  products  such  as  Guide. 

HyperWords  and  HyperLines 

The  other  problem  with  Chang’s  tech¬ 
nique,  viewed  as  an  approach  to  hy¬ 
pertext  linking,  is  that  it  depends  on 
the  select  operation,  which  is  nicely 
standardized  across  the  Macintosh-user 
interface,  but  which  is  not  a  technique 
designed  for  grabbing  links.  This  is 
particularly  so  in  HyperCard,  where  the 
user  can’t  select  text  unless  the  field  is 
unlocked  —  in  which  case  the  text  is 
subject  to  modification.  You  certainly 
don’t  want  the  user  selecting  a  hypertext 
link  only  to  delete  it  from  the  document 
by  a  careless  touch  of  the  delete  key. 

Many  stackware  developers  have 
found  the  same  fix  for  this  problem. 
To  allow  the  user  to  select  a  word  in 
any  field  simply  by  clicking  on  it  once 
as  though  it  had  a  button  attached,  you 
do  the  following: 

%  lock  the  field 
%  wait  for  a  click  in  the  field 
%  save  the  coordinates 
%  unlock  the  field  invisibly 
%  send  two  clicks  to  the  coordinates 
%  save  the  selection 
%  relock  the  field 

The  first  significant  implementation 
of  the  single-word  link  I  know  of  is 
XrefText  by  Frank  Patrick  (available  as 
shareware  from  BMUG  or  BCS).  Raines 
Cohen  of  Team  BMUG  inspired  this 
shareware  quasi-hypertext  system, 
which  lets  users  create  links  from  arbi¬ 
trary  single  words  in  fields  by  option¬ 
clicking,  and  lets  them  follow  these 
links  by  simply  clicking.  XrefText  limits 
its  search  for  the  selected  word  to  a 
keyword  field  on  every  card.  The  link 
words  are  identified  by  an  asterisk. 

This  works  well  for  selecting  a  single 
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word,  and  I’ve  found  it  a  useful  way 
to  allow  the  user  to  select  an  item  from 
a  scrolling  list,  even  when  the  items  in 
the  list  are  not  single  words.  My  tech¬ 
nique,  which  handles  moved  or  scrolled 
fields,  is  shown  in  Listing  Three, 
page  153. 

This  technique  is  all  right  for  picking 
a  line  from  a  field,  but  neither  this  nor 
the  toggle-lock-and-simulate-double- 
click  technique  for  picking  a  single  word 
is  something  you  want  to  be  doing 
regularly  in  an  interpreted  language. 

One  serious  problem  with  all  these 
approaches  is  that  not  every  key  can 
be  a  single  word  or  a  complete  line. 
Footnotes  in  linear  text  sometimes  ap¬ 


ply  to  a  single  word,  but  can  also  apply 
to  a  sentence,  paragraph,  chapter, 
proper  name,  or  to  the  general  idea  of 
a  passage.  Hypertext  links  ought  to  be 
just  as  flexible. 

From  Superscript  to  Tagsterisk,  or 
Footnotes  of  the  Future 

John  Anderson,  when  he  was  develop¬ 
ing  stacks  under  the  Acme  Dot  logo, 
came  up  with  something  he  called  the 
“tagsterisk,”  a  tool  for  identifying  for 
the  reader  not  only  where  links  are  in 
the  text,  but  also  what  they  are.  “The 
idea,”  he  said,  “is  to  give  the  reader  a 
clue  indicating  just  where  he  or  she 
will  branch  if  he  or  she  clicks  on  a 


tagged  word.”  Tagsterisks  are  just  al¬ 
phabetic  superscript  characters  to  be 
used  in  the  way  that  asterisks  are  used 
in  linear  text  to  point  to  footnotes.  An¬ 
derson  implemented  them  as  part  of 
his  custom  font. 

Tagsterisks,  he  claimed,  “give  the 
reader  a  greater  feeling  of  control  over 
the  hypertext  process.  The  key  is  to  use 
no  more  than  three  or  four.”  One  An¬ 
derson  stack  used  four  tagsterisks:  sto 
flag  a  source  reference,  m  for  more 
information  on  the  subject,  g  for  a 
graphic,  and  p  for  pronunciation  (the 
last  two  being  hypermedia  rather  than 
hypertext).  Another  stack  used  p  for  a 
picture,  gfor  a  graph,  d for  a  definition, 
and  /  to  bring  up  a  list  of  links  to  other 
documents  on  the  subject.  Only  the 
last  of  these  was  actually  implemented 
as  a  link  to  another  card  or  stack;  the 
other  three  tagsterisks  triggered  pop¬ 
up  windows  or  fields. 

Tagsterisks  are  not  tied  to  any  par¬ 
ticular  method  of  implementing  the  link, 
which  could  be  done  with  a  button 
over  the  text,  a  field  script,  or  with 
whatever  technique  is  included  in  Ver¬ 
sion  2  of  HyperCard.  It’s  worth  noting 
that,  if  the  linking  script  is  associated 
with  the  tagsterisk  character  itself,  it 
becomes  possible  to  attach  two  or  more 
links  to  one  word,  say,  a  picture  and  a 
definition,  without  ambiguity. 

Hypertext  has  been  called  the  ex¬ 
tended  footnote,  but  only  as  a  refer¬ 
ence  to  its  closest  analog  in  linear  text, 
not  as  a  design  direction.  Tagsterisks 
take  the  expression  literally,  extending 
the  footnote  in  several  dimensions. 
There  are  some  advantages  to  this  ex¬ 
tended  footnote  approach  over,  say, 
boldfacing  links  in  text.  One  could  ar¬ 
gue,  for  example,  that  hypertext  ought 
to  extend  the  concept  of  text,  not  limit 
it.  Using  boldface  to  represent  links 
“uses  up”  this  font  style  variation,  pre¬ 
cluding  its  use  for  other  purposes.  The 
proponent  of  boldface  links  could 
counter  that  every  use  of  boldface  in 
linear  text  is  really  a  wannabe  link. 
Maybe  our  typographic  conventions  and 
type  style  variations  were  developed 
precisely  to  circumvent  the  limitations 
of  the  linear  medium.  If  so,  boldface 
has  been  waiting  all  this  time  to  be 
used  for  hypertext  link  identification. 
The  response  might  be  that  it’s  a  little 
naive  to  think  that  we  haven’t  found 
other,  nonhypertextual  uses  for  these 
typographical  conventions  over  the  cen¬ 
turies. 

It’s  not  clear  that  either  side  of  this 
argument  is  wrong.  No  doubt  different 
techniques  are  appropriate  for  differ¬ 
ent  purposes.  Designers  of  training  manu¬ 
als,  help  systems,  and  the  like  seem  to 
be  doing  all  right  with  boldface  and 
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italic  variations  to  identify  links.  Uni¬ 
versal  hypertext  may  require  something 
else,  but  universal  hypertext  is  some¬ 
thing  else. 

Whether  or  not  one  buys  the  argu¬ 
ment  that  hypertext  should  extend  text 
and  not  limit  it,  it  seems  clear  that  Hy¬ 
perCard  should  stop  limiting  its  users’ 
use  of  text.  The  impoverished  text  fields 
of  HyperCard  have  not  helped  research 
in  this  area,  either  to  investigate  ways 
to  use  text  style  variations  to  identify 
links,  or  to  show  that  this  is  a  bad  idea. 
HyperCard  needs  richer  text  fields. 

Hypertext,  though,  is  still  very  much 
in  the  research  stage,  and  HyperCard 
stack  development  is  one  legitimate 


form  of  hypertext  research.  The  labora¬ 
tory  studies,  valuable  as  they  may  be, 
are  not  going  to  tell  us  much  about  the 
market  acceptance  of  particular  user- 
interface  implementation  decisions  re¬ 
garding  hypertext.  I  recommend  that 
anyone  interested  in  hypertext  down¬ 
load  some  stacks  and  take  a  look  at 
them.  Even  better,  upload  some. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 


or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  153-) 

Vote  for  your  favorite  feature/artiole. 

Circle  Reader  Service  No.  9. 
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HYPERTREE:  A 
Hypertext  Index 
Technique 


Programmers  tend  to  think  of  hy¬ 
pertext  in  ways  that  we  use  it  in 
our  applications.  A  frequent  use 
in  our  experience  is  in  on-line 
help  systems  where  the  help  text  is 
organized  into  a  structured  set  of  help 
windows.  You  get  to  a  help  window 
as  a  result  of  some  context-sensitive 
control,  perhaps  with  the  cursor  on  a 
keyword  or  the  program  at  a  particular 
place  in  a  menu  or  data  entry  screen. 
The  help  system  then  allows  you  to 
select  higher  and  lower  levels  of  detail 
of  help  from  keywords  strategically  po¬ 
sitioned  in  the  current  window.  Such 
help  systems  use  lightweight  hypertext 
concepts,  but  they  are  the  ones  we  are 
most  familiar  with. 

The  real  potential  of  hypertext  tech¬ 
nology  comes  when  we  consider  using 
it  for  structured  retrievals  from  large 
static  text  databases.  Many  disciplines 
deal  regularly  with  such  data.  Lawyers, 
engineers,  programmers,  doctors,  pro¬ 
posal  writers,  and  researchers  of  all 
kinds  work  constantly  with  large 
amounts  of  boilerplate  text.  Hypertext 
offers  a  way  to  build  structured  and 
disciplined  retrieval  capabilities  into 
these  databases. 

The  heart  of  most  heavy-duty  hy¬ 
pertext  applications  is  the  index.  To 
find  your  way  to  an  associated  body 
of  text  from  a  selected  word  or  phrase, 
you  need  an  index  that  translates  the 
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word  into  a  pointer,  into  the  text  data¬ 
base.  Last  February  we  built  an  index 
system  for  our  TEXTSRCH  project  that 
used  a  hashing  technique  to  derive  the 
pointer  to  a  list  of  files  where  a  selected 
keyword  exists.  That  index  technique 
was  useful  to  the  purpose  of  TEXTSRCH, 
which  was  the  selection  of  files  that 
match  a  Boolean  keyword  query.  This 
application  is  a  form  of  hypertext,  but 


it  too  is  a  lightweight  use  of  it. 

This  edition  of  the  “C  Programming” 
column  looks  at  a  different  indexing 
technique,  a  loose  adaptation  of  the 
the  B-tree,  one  that  offers  a  more  heavy- 
duty  kind  of  support  to  the  problems 
of  text  searching.  Besides  providing 
the  random  selection  of  the  hashed 
keyword,  the  B-tree  allows  you  to  navi¬ 
gate  an  index  in  the  sequence  of  its 
keys  as  well.  This  facilitates  the  kind 
of  search  where  a  selected  word  deliv¬ 
ers  a  list  of  words  that  are  close,  for 
example. 

The  B-tree  is  a  data  structure  resem¬ 
bling  an  inverted  tree.  The  root  is  at  the 
top  of  the  tree  and  the  leaves  are  at  the 
bottom.  Each  node  contains  key  val¬ 
ues,  and  each  key  value  points  to  the 
node  at  the  next  lower  level  in  the  tree 
where  values  reside  that  are  greater 
than  it  and  less  than  the  next  adjacent 
key.  The  lower  nodes  are  child  nodes, 
the  higher  ones  are  parent  nodes.  Mixed 
metaphors,  these  families  and  trees.  The 
pointers  in  the  nodes  at  the  bottom 
level  —  the  leaves  —  are  not  node  point¬ 
ers  but  instead  contain  data  values  that 
match  the  keys.  B-trees  are  typically 
used  by  database  management  systems 
to  manage  the  indexes  for  primary  and 
secondary  data  element  keys.  To  sup¬ 
port  such  applications,  the  traditional 
B-tree  algorithms  must  be  capable  of 
adding  keys  in  a  random  sequence  and 
deleting  them.  I  published  the  C  lan¬ 
guage  source  code  for  such  B-tree  al¬ 
gorithms  in  two  books,  C  Development 
Tools  for  the  IBM  PC  (Brady  Books, 
1986)  and  C  Data  Base  Development 
(MIS  Press,  1987). 

The  modified  B-trees  that  we  will  use 
to  index  a  static  hypertext  database  do 
not  need  to  support  key  deletion,  and 
the  index  construction  can  be  done  in 
the  sequential  order  of  the  keys.  These 
two  features  greatly  simplify  the  code 
needed  for  tree  maintenance.  Because 
the  index  construction  techniques  are 


different,  the  trees  of  this  method  are 
not  always  precisely  balanced  after  the 
fashion  of  B-trees.  Every  B-tree  node 
below  the  root  always  contains  at  least 
half  the  number  of  keys  that  it  can  hold. 
This  is  because  when  a  node  is  filled  to 
capacity,  it  splits  into  two  nodes  to  ac¬ 
commodate  the  next  key.  When  it  splits, 
the  key  value  from  the  middle  goes  into 
the  node  above  it  in  the  tree.  When  a 
key  is  deleted,  the  node  is  combined 
with  one  of  its  sibling  nodes  if  the  two 
together  can  now  hold  the  keys  of  both. 
The  modified  B-tree  structure  for  this 
problem  does  not  work  that  way.  We 
add  keys  in  sequential  order,  so  the 
nodes  fill  up  from  left  to  right.  No  split¬ 
ting  occurs,  and  all  but  the  rightmost 
node  at  each  level  will  be  full.  Because 
the  index  supports  a  static  database,  no 
key  deletion  ever  happens. 

Our  index  is  different  from  the  B- 
tree  in  one  other  way.  A  B-tree  consists 
of  nodes  each  of  which  can  contain  a 
fixed  number  of  keys.  By  definition, 
the  key  length  is  fixed  if  the  node  length 
is  fixed.  In  our  trees,  the  node  length 
is  fixed  and  the  key  length  is  variable. 

We  call  this  data  structure  the  “Hyper- 
Tree.”  It  consists  of  a  header  record 
and  some  number  of  nodes.  The  header 
record  contains  the  node  number  of 
the  root  node.  Each  node  contains  a 
header  block  and  an  array  of  variable 
length  keys.  The  node  header  block 
contains  a  flag  indicating  whether  the 
node  is  a  leaf  or  not,  a  pointer  to  the 
node  that  is  a  parent  to  the  current 
one,  and  a  pointer  to  the  node  at  the 
next  lower  level  that  contains  keys  that 
are  less  than  the  keys  in  this  node. 
Each  key  in  the  array  contains  the  string 
-value  of  the  key  and  a  pointer  to  the 
node  at  the  next  lower  level  in  the  tree 
that  contains  keys  greater  than  the  cur¬ 
rent  key  and  less  than  the  next  adjacent 
key  in  this  array. 

When  the  node  is  a  leaf,  the  key 
pointers  and  the  node  header’s  pointer 
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to  lower  keys  serve  a  different  pur¬ 
pose.  They  contain  some  value  that  is 
relevant  to  the  key.  In  some  applica¬ 
tions  they  will  point  to  a  data  record. 
In  others  they  will  be  the  data  record. 
Perhaps  they  point  to  a  list  of  data 
records.  The  function  of  the  key  value 
is  independent  of  the  operation  of  the 
HyperTree.  When  you  add  a  key,  you 
add  its  associated  key  value.  When  you 
retrieve  a  key,  you  retrieve  its  value. 
The  HyperTree,  therefore,  serves  two 
retrieval  objectives:  It  tells  you  if  a  key 
argument  exists  in  the  index,  and  it 
delivers  the  key  value  associated  with 
key  arguments. 

Listing  One,  page  154,  is  <hyprtree.h>, 
the  header  file  that  describes  the  Hy¬ 
perTree  structures.  It  defines  several 
global  values  that  you  will  change  to 
suit  your  needs.  The  first  one  to  con¬ 
sider  is  NODELEN.  This  is  the  byte 
length  of  a  HyperTree  node.  If  the  node 
is  too  short,  it  will  contain  a  small  num¬ 
ber  of  keys,  and  the  tree  will  have 
many  levels.  This  circumstance  would 
affect  retrieval  performance  because 
each  search  must  navigate  all  the  levels 
of  the  tree.  If  the  node  length  is  too 
long,  the  individual  node  searches, 
which  are  serial,  would  be  affected. 

The  next  value  in  <hyprtree.h>  is 
MAXLEVELS,  the  maximum  number  of 
levels  in  a  tree.  This  value  is  a  function 
of  the  average  number  of  keys  in  a 
node  and  the  total  number  of  keys  in 
the  index.  You  can  conservatively  set 
it  to  a  safe  high  value  such  as  10.  Ten 
levels  of  HyperTree  would  be  a  big 
index,  indeed.  The  value  itself  is  used 
as  the  dimension  for  an  array  of  point¬ 
ers.  We  need  some  value  to  use,  be¬ 
cause  we  do  not  know  the  upper  limit 
until  we  reach  it  at  run  time. 

MAXKE YLEN GTH  is  used  to  limit  the 
length  of  a  key  string.  This  value  will 
depend  on  your  application.  It  pre¬ 
vents  a  key  from  completely  occupy¬ 
ing  a  node.  You  should  set  it  so  that 
each  node  can  contain  at  least  three 
maximum-length  keys.  This  will  assure 
the  correct  behavior  of  the  HyperTree 
algorithms. 

You  will  need  to  consider  the 
KEYVALUE  typedefm  <hyprtree.h>.  As 
shown  in  the  listing,  KEYVALUE  is  a 
long  integer.  That  usage  will  support 
the  examples  that  follow,  which  use 
the  KEYVALUE  as  a  pointer  into  a  file. 
KEYVALUE  could  be  any  valid  C  type 
including  a  structure.  Remember  that 
each  leaf  node  will  contain  KEYVAL- 
UEs  for  the  keys,  so  do  not  make  them 
too  long.  If  each  key  in  your  Hyper¬ 
Tree  is  a  vector  to  some  complex  data 
structure,  put  that  structure  into  its  own 
file  and  use  the  KEYVALUE  as  a  pointer 
into  that  file. 
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Building  a  HyperTree 

Listing  Two,  page  154,  is  <addkey.c>, 
the  code  needed  to  build  a  HyperTree. 
To  prepare  for  this  process,  you  need 
to  have  selected  your  keywords  and 
phrases  from  the  text  database  and 
sorted  them  into  the  collating  sequence 

The  program  searches 
the  HyperTree  by  using 
the  findkey  function 


of  the  tree.  The  search  algorithm  de¬ 
scribed  later  assumes  a  case-insensi¬ 
tive  collating  sequence.  You  must  pro¬ 
vide  the  data  value  to  associate  with 
each  keyword.  That  data  type  is  de¬ 
scribed  in  <hyprtree.h>  as  the  typedef 
KEYVALUE.  The  value  will  be  the  value 
returned  by  the  searching  algorithms. 
It  could  be  a  pointer  to  the  text  posi¬ 
tion  in  a  text  file,  or  it  could  be  a 
pointer  to  a  data  structure  that  describes 
files,  chapters,  and  paragraphs.  Depend¬ 
ing  on  the  architecture  of  your  Hy¬ 
pertext  database,  the  KEYVALUE  value 
could  have  the  database  document,  chap¬ 
ter,  and  paragraph  identifications  en¬ 
coded  into  its  bit  string.  The  important 
thing  here  is  that  you  have  prepared 
to  build  the  HyperTree  by  extracting 
keywords,  combining  each  of  them  with 
a  data  value  to  be  returned,  and  sorting 
them.  We’ll  have  an  example  of  that 
process  later  in  this  column. 

In  some  applications,  it  might  be 
appropriate  to  further  process  the  keys 
following  the  sort.  The  duplicate  val¬ 
ues  would  be  deleted,  and  the  data 
value  associated  with  each  key  value 
would  become  a  pointer  into  a  more 
complex  data  record  or  structure  that 
describes  the  location  and  significance 
of  the  key  value. 

Building  the  HyperTree  consists  of 
reading  the  keys  in  sequence  and  fill¬ 
ing  nodes.  When  a  node  is  full,  the 
next  value  is  added,  in  sequence,  to 
the  next  higher  node  with  the  node 
number  of  the  current  node  as  its  asso¬ 
ciated  data  value.  Subsequent  keys  are 
added  to  a  new  node  at  the  same  level 
as  the  one  that  filled  up.  This  upward 
growth  is  a  recursive  operation. 

You  call  the  addkey  function  to  add 
nodes  to  a  HyperTree.  Its  parameters 
are  a  pointer  to  the  key’s  string  and  the 
KEYVALUE  associated  with  the  key. 
The  first  time  you  call  this  function,  it 
creates  the  index  file.  When  you  are 
done  adding  keys,  you  call  it  with  a 
NULL  key  string  pointer  to  tell  it  to 


finish  up.  The  addkey  function  calls 
the  recursive  addkeyentry  function.  This 
function  is  the  tree-level  manager  for 
adding  keys.  The  calls  to  it  from  addkey 
specify  that  keys  are  to  be  added  to  level 
zero.  The  addkeyentry  function  calls 
itself  by  specifying  progressively  higher 
levels  as  nodes  fill  and  the  tree  grows. 

Each  node  contains  the  node  num¬ 
ber  of  its  parent.  This  data  element 
supports  the  search  of  a  HyperTree 
and  so  must  be  built  when  the  tree  is 
built.  Because  parents  are  growing  when 
the  children  are  fully  grown  —  these 
metaphors  are  backwards,  it  seems  — 
the  program  does  not  know  the  parent 
node  number  until  the  parent  is  filled. 
The  adopt  function  takes  care  of  that. 
When  the  writenode  function  writes  a 
node,  it  scans  the  node  and  extracts  the 
node  numbers  of  each  of  its  children. 
Then  it  calls  the  adopt  function  to  write 
the  parent’s  node  number  into  each  of 
the  node  records  of  the  children. 

Searching  a  HyperTree 

Listing  Three,  page  156,  is  <srchtree.c>, 
which  contains  the  functions  that  search 
a  HyperTree.  Several  of  the  functions 
modify  the  position  of  the  search  point¬ 
ers  to  a  key.  Others  return  the  key’s 
string  or  associated  value. 

The  first  search  function  is  findkey. 
You  pass  it  a  pointer  to  a  string  that 
contains  the  key  value  you  want  to 
find.  If  it  finds  a  match,  it  returns  a  true 
value.  Otherwise  it  returns  a  false  value. 
In  either  case,  it  positions  the  search 
pointers  to  the  key  that  terminated  the 
search.  You  may  now  call  current_ 
value  to  retrieve  the  KEYVALUE  of  the 
key  that  terminated  the  search,  or  cur- 
rentjkeystring  to  retrieve  the  key’s  string 
value.  This  latter  function  is  useful  when 
findkey  returns  a  false  value  to  4  say 
that  it  found  no  matching  entry  in  the 
HyperTree.  The  terminating  key  is  the 
next  highest  one  in  the  collating  se¬ 
quence  of  the  HyperTree. 

There  are  other  search  functions  that 
are  used  to  navigate  the  HyperTree  in 
its  collated  sequence.  These  ar efirstkey, 
lastkey ,  nextkey,  and  prevkey.  They  mod¬ 
ify  the  search  pointer’s  position,  and 
subsequent  calls  to  current_  keyvalue 
and  current_keystring  will  reflect  the 
new  position.  Each  function  returns  a 
true  value  if  it  can  satisfy  the  request. 
Iffirstkeyor  lastkey  returns  a  false  value, 
the  index  is  empty.  If  nextkey  returns 
a  false  value,  the  search  pointers  are 
already  positioned  at  the  end  of  the 
HyperTree’s  collating  sequence.  If 
prevkey  returns  a  false  value,  the  search 
pointers  are  already  positioned  at  the 
beginning  of  the  HyperTree’s  collating 
sequence. 

The  findkey  search  of  a  HyperTree 
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(continued  from  page  136) 
begins  at  the  root  node.  The  search 
functions  find  the  root  node  number 
by  reading  the  HyperTree  header  rec¬ 
ord.  To  search  the  tree,  the  function 
searches  the  root  node  for  a  match  on 
the  argument.  Keys  are  recorded  in 
sequence  in  a  node,  so  the  search  pro¬ 
ceeds  from  left  to  right.  If  the  key  is  not 
there,  the  function  picks  up  the  node 
pointer  to  the  left  of  the  key  that  termi¬ 
nated  the  search,  reads  that  node,  and 
starts  over.  This  continues  until  the 
search  either  finds  a  match  or  termi¬ 
nates  in  a  leaf  node. 

When  you  request  the  KEYVALUE 
by  calling  the  current_keyvalue  func¬ 
tion,  the  search  algorithm  must  navi¬ 
gate  from  the  key’s  position  in  the  Hy- 
perTree’s  system  of  levels  to  the  leaf 
level.  KEYVALUEs  exist  only  at  the  leaf 
level.  Higher  levels  contain  pointers  to 
lower  levels.  If  you  land  on  a  key  in  a 
non-leaf  node,  you  find  the  KEYVALUE 
by  navigating  down  to  the  leaf  this 
way.  Begin  by  reading  the  node  pointed 
to  by  the  pointer  just  to  the  right  of  the 
matching  key.  Then  read  the  node 
pointed  to  by  the  lower-key  node 
pointer  in  the  header  block  of  the  cur¬ 
rent  node.  Continue  doing  that  until 
you  reach  a  leaf.  The  lower-key  pointer 
field  contains  (in  a  union)  the  KEYVALUE 
of  the  matching  key.  It  doesn’t  make 
sense  when  I  explain  it,  but  it  really 
does  work  that  way. 

A  HyperTree  Example 

To  put  all  this  to  use,  I  devised  a  simple 
hypertext-like  application  that  builds  a 
HyperTree  index  from  a  text  file  and 
lets  you  search  it.  We  begin  with  some 
text  file  to  test  with.  It  should  be  made 
of  unadorned  ASCII  with  CR/LF  pairs 
terminating  each  line.  Use  your  editor 
to  mark  some  key  index  values  in  the 
text  by  surrounding  the  keys  with  an¬ 
gle  brackets  (less-than,  greater-than 
pairs).  Make  lots  of  keys.  Now  we  can 
build  a  HyperTree, 

Listing  Four,  page  158,  and  Listing 
Five,  page  158,  are  <keyextr.c>  and  <key- 
build.c>,  two  simple  filter  programs  to 
build  the  HyperTree.  You  must  link  the 
object  file  from  <keybuild.c>  with  that 
from  <addkey.c>.  Compile  <keyextr.c> 
by  itself.  Run  the  two  programs  along 
with  the  SORT  filter  (assuming  MS- 
DOS)  this  way: 

keyextr<  textfile.dat  !  sort  I  keybuild 

where  <textfile.dat>  is  the  name  of  the 
file  of  ASCII  text.  The  <keyextr>  pro¬ 
gram  extracts  the  key  values  you  marked 
with  angle  brackets  into  a  quoted  string, 
which  is  followed  by  a  comma  and  a 
numeric  value  that  represents  the  key’s 
position  in  the  text  file.  The  extracted 
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file  would  look  like  this: 

“fortran",  125  “the  merry  widow”, 
257  “godfrey  daniel”,  3244 

The  SORT  filter  sorts  the  extracted 
values  and  pipes  them  to  the  <keybuild> 
program,  which  builds  the  HyperTree. 
That’s  all  there  is  to  that.  You  can  look 
at  the  index  with  a  dump  utility.  Its 
name  is  <hyprtree.ndx>. 

To  use  the  new  HyperTree  index, 
you  will  build  the  example  program  in 
Listing  Six,  page  159,  <hyprsrch.c>.  Its 
command  line  specifies  the  text  file 
name  and  a  key  string  to  search,  such 
as  this  one: 

hyprsrch  textfile.dat  “windows  on 
the  world” 

The  program  searches  the  Hyper¬ 
Tree  by  using  the  findkey  function.  It 
then  displays  a  screen  of  text  starting 
at  the  text  position  represented  by  the 
KEYVALUE  of  the  key  that  terminated 
the  search.  The  top  of  the  screen  shows 
the  actual  key  value  that  was  found 
along  with  the  position.  The  bottom 
of  the  screen  is  a  menu  that  lets  you 
press  F,  L,  N,  P,  or  Q  to  move  to  the 
first,  last,  next,  or  previous  key,  or  to 
quit  and  terminate  the  program. 

HyperTree  Extended 

The  small  example  we  used  here  is 
merely  a  taste  of  how  you  can  use  the 
HyperTree  data  structure.  The  technique 
could  be  used  as  the  retrieval  engine 
for  a  spell  checker  or  thesaurus  pro¬ 
gram.  It  could  be  used  as  an  inverted 
index  to  other  documents  from  within 
a  document.  It  could  even  be  used  in 
the  concordance-like  retrieval  system 
that  we  built  into  TEXTSRCH. 

There  are  some  areas  where  Hyper¬ 
Tree  could  be  enhanced.  Here  are  a 
few  that  come  to  mind. 

In  the  example  application,  we  do 
not  bind  the  index  to  the  file  it  indexes, 
requiring  instead  that  you  name  the  file 
on  the  command  line.  Your  applica¬ 
tion  would  no  doubt  manage  this  asso¬ 
ciation  for  the  user.  One  way  would 
be  to  include  the  text  file’s  name  as  a 
part  of  the  TREEHDR  structure. 

Because  the  HyperTree  node  con¬ 
tains  keys  in  a  collated  sequence,  you 
could  add  the  data  compression  tech¬ 
nique  called  “run  length  encoding”  to 
the  node  structure.  Many  adjacent  keys 
will  begin  with  identical  character  se¬ 
quences  as  in  this  list: 

program 

programmer 

programming 

progress 

prototype 


A  simple  escape  sequence  could  spec¬ 
ify  how  many  characters  the  key  inher¬ 
its  from  the  one  that  preceeds  it.  The 
list  might  then  look  this  way: 

program 

\  7mer 

\  8ing 

\  5ess 

\  3totype 

The  random-then-sequential  proper¬ 
ties  of  HyperTree  make  it  a  natural  for 
wild  card  retrievals.  If  you  use  the  ? 
character  in  the  first  position  of  a  key 
(“?obbs,”  for  example),  you  would  do 
searches  on  all  combinations  of  the 
key  with  letters  and  numbers  in  the 
first  position.  If  the  question  mark  was 
further  into  the  key  (for  example, 
“Doc?or  Dobbs"),  you  would  use  the 
findkey  function  to  position  yourself 
near  the  likely  match  and  the  nextkey 
function  to  retrieve  all  the  possibilities, 
discarding  those  that  do  not  fit. 

Hypertext  Editing 

There  are  two  programmer’s  editor 
tools  —  BTAGS  and  4C  —  that  offer  Hy¬ 
pertext-like  features  to  the  PC  program¬ 
mer  who  is  working  with  a  system  that 
involves  a  lot  of  source  code  files.  We’ll 
look  at  each  of  them  in  turn. 

BTAGS  is  a  program  that  you  use 
along  with  the  Brief  programmer’s  edi¬ 
tor.  Brief  is  one  of  the  most  popular 
programmer’s  editors  for  the  PC  and  it 
includes  a  comprehensive  C-like  macro 
language.  BTAGS  is  a  source  file  pre¬ 
processor  and  a  set  of  Brief  macros 
that  implement  a  feature  similar  to  the 
one  used  in  the  Unix  vi  editor.  Here  is 
how  it  works. 

The  BTAGS  program  builds  a  “tags” 
file  by  reading  all  your  source  files  and 
finding  where  all  the  functions  are  de¬ 
fined.  The  tags  file  conforms  to  the 
Unix  ctags  format,  which  identifies  each 
function  identifier,  the  file  where  it  is 
declared,  and  a  string  taken  from  the 
declaration.  The  string  is  built  so  that  if 
the  editor  searches  the  file  for  the  string, 
it  will  find  the  function  declaration. 

The  BTAGS  brief  macros  add  com¬ 
mand  keys  to  the  Brief  editor.  With  the 
cursor  on  a  function  call,  you  press 
Ctrl-T,  and  the  macro  opens  a  new 
Brief  window,  reads  the  file  where  the 
function  is  declared,  and  positions  the 
cursor  on  the  function  declaration.  If 
you  are  not  near  a  call  to  the  function 
you  want,  Ctrl-E  lets  you  type  in  a 
function  name.  Ctrl-B  returns  you  to 
where  you  were  before  the  last  Ctrl-T 
or  Ctrl-E. 

BTAGS  works  only  with  function  dec¬ 
larations  and  typedefs.  It  would  be  bet¬ 
ter  if  it  also  recorded  external  variables 
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and  structure  members.  Another  minor 
annoyance  is  that  the  Ctrl-T  macro 
works  only  if  the  cursor  is  on  the  first 
character  of  a  function  name.  You  get 
the  Brief  macro  language  source  code 
for  the  macros,  so  you  could  hack  a  fix 
to  that  one  if  you  wanted  to. 

4C  is  a  programmer’s  editor  that  is 
similar  to  BTAGS  in  that  its  source  code 
analyzer  program  produces  a  ctags- 
compatible  tags  file.  4C  produces  ctags 
records  for  all  the  C  language  con¬ 
structs,  not  just  function  declarations. 
4C  includes  its  own  editor,  which  uses 
the  tags  file  to  allow  you  to  jump  around 
through  your  source  files  by  putting 
the  cursor  anywhere  on  a  variable  name 
and  pressing  a  function  key.  If  you  do 
prefer  to  use  your  own  editor,  you  can 
tell  4C  to  call  it  instead  of  its  own. 

The  4C  editor  and  its  invocation  of 
a  user-specified  editor  employ  a  dis¬ 
play  strategy  that  I  find  unnatural.  If 
you  call  up  the  main  function,  that’s  all 
you  get.  You  cannot  page  beyond  or 
ahead  of  it.  If  you  call  another  function 
or  variable,  that’s  all  you  see.  I  find  it 
frustrating  to  have  to  call  a  function  by 
name  when  I  already  know  that  it  ap¬ 
pears  within  scrolling  reach  of  where  I 
am  at  the  time. 

At  SD90  last  February,  the  4C  folks 
were  showing  a  new  version  of  4C  that 


they  plan  on  releasing  later  this  year. 
The  enhanced  version  provides  inter¬ 
faces  to  a  variety  of  editors,  including 
Brief,  Multi-edit,  Vedit,  ME,  and  Slick, 
while  the  source-code  analyzer  sup¬ 
ports  C++,  object-oriented  Pascals, 
Modula-2,  and  ASM.  The  database  query 
allows  lookups  by  filename  and  direc¬ 
tory  and,  for  object-oriented  languages, 
lookups  by  class  and  class  hierarchy. 

The  upshot  is  that  I  like  the  BTAGS 
integration  with  Brief  because  Brief  is 
the  editor  I  use.  I  like  4C’s  inclusion  of 
all  the  C  constructs  in  their  tags  file. 
Both  products  use  source  analyzers  that 


Product  Information 

BTAGS 

SD  Enterprises 
P.O.  Box  621 
Carpinteria,  CA  93013 
805-566-1317 
Price:  $49.95 

4C 

Tri-Technology  Systems  Inc. 
1225  S.  Elgin 
Forest  Park,  IL  60130 
312-366-7595 
Price:  $119 
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produce  ctags-compatible  tags  files,  so 
I  tried  the  obvious.  I  used  4C  to  build 
a  tags  file  and  BTAGS  brief  macros  to 
process  them.  Of  course  it  did  not  work, 
but  on  the  surface  it  looks  like  some 
hacking  would  bring  it  into  line.  Per¬ 
haps  later. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  154.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  10. 
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Chasing  Bubbles  in 
the  Waterbed 


Cold  fusion,  huh?  Well,  I  can  top 
that:  I  have  a  waterbed  that  breaks 
down  water  into  its  component 
gases  without  electricity.  I’m  not 
sure  what  these  gases  are.  They  could 
be  hydrogen  and  oxygen,  or  I  suppose 
they  could  as  well  be  carbon  dioxide 
and  xenon.  I’m  not  macho  enough  to 
perform  any  conclusive  experiments. 
About  all  I  am  sure  of  is  that  this  par¬ 
ticular  waterbed  has  generated  what 
seems  like  hundreds  of  cubic  feet  of 
invisible  gas  since  being  filled  with  equal 
parts  water  and  Algae-Go-Bye-Bye  in 
May  of  1987. 

Every  week  or  so  I  have  to  chase  Mr. 
Byte  off  the  comforter,  yank  the  bed¬ 
clothes  off  the  waterbed,  and  wheedle 
ten  zillion  little  bubbles  around  under 
the  vinyl  with  my  old  slide  rule,  merg¬ 
ing  tiny  bubbles  into  small  bubbles, 
small  bubbles  into  larger  bubbles,  larger 
bubbles  into  Godzillan  bubbles,  and 
finally  letting  the  single  monstrous  sur¬ 
vivor  out  through  the  fill  hole.  Other¬ 
wise,  an  ordinary  night  between  the 
sheets  can  sound  like  one  of  those  old 
Sea  Hunt  episodes. 

Dynamic  Variables  Recap 

Ever  alert  for  the  occasional  wild  meta¬ 
phor  roosting  in  the  rafters,  it  occurred 
to  me  that  we  have  this  same  problem 
in  the  structured  programming  world. 
The  faulty  waterbed  is  the  heap,  and 
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the  bubbles  —  like  the  ’ole  that  Ringo 
’ad  in  his  pocket  in  Yellow  Submarine  — 
are  simply  blocks  of  empty  space  that 
have  been  used  for  awhile  and  then 
turned  loose. 

First,  a  little  background  for  those 
who  work  in  languages  such  as  Basic 
that  do  not  support  explicit  memory 
allocation  and  deallocation.  Pascal  and 
Modula-2  (and  C  as  well)  set  aside  a 


certain  amount  of  memory  called  the 
“heap"  and  allow  the  running  program 
to  create  variables  out  of  that  memory 
(we  say  “on  the  heap”)  as  needed. 
These  variables  are  called  dynamic  vari¬ 
ables  to  differentiate  them  from  static 
variables,  which  are  named  in  the  source 
code  and  allocated  at  compile  time, 
and  exist  in  the  same  form  and  in  the 
same  location  as  long  as  the  program 
runs.  When  no  longer  needed,  dynamic 
variables  are  destroyed,  or  deallocated, 
and  the  memory  they  occupied  on  the 
heap  is  made  available  as  grist  from 
which  to  create  other  variables.  In  both 
Pascal  and  Modula-2  the  allocation  rou¬ 
tine  is  called  New,  and  the  deallocation 
routine  is  called  Dispose.  (Turbo  and 
QuickPascal  have  a  similar  pair  of  rou¬ 
tines  called  GetMem  and  FreeMem  as 
well.) 

Variables  created  on  the  heap  have 
no  names.  They  are  accessed  through 
a  type  of  variable  called  a  “pointer” 
that  exists  solely  to  “tie”  these  dynamic 
variables  into  the  program’s  reality.  The 
pointer  (which  is  declared  in  the  usual 
way  variables  are  declared)  is  set  to 
point  to  the  dynamic  variable  when  the 
dynamic  variable  is  allocated  using  New-. 

VAR 

I  A  pointer  to  type  Integer:  I 

My  Pointer  :  "Integer; 


New(MyPointer); 

MyPointer" :  =  42 

The  caret  symbol  is  the  dereference  op¬ 
erator.  To  specify  what  the  pointer  points 
to  (rather  than  to  specify  the  pointer 
itself)  you  must  use  the  dereference 
operator,  as  shown  in  the  assignment 
statement.  Accessing  the  item  that  a 
pointer  points  to  is  called  “dereferencing 
the  pointer”  and  the  item  pointed  to  is 
called  the  “pointer’s  referent.” 


If  you  could  only  create  dynamic 
variables  as  referents  of  pointers  allo¬ 
cated  as  static  variables,  it  would  be 
interesting  but  not  compellingly  use¬ 
ful.  Pointers  really  shine  when  they  are 
used  to  connect  the  components  of 
entire  data  structures  constructed  on 
the  heap.  Linked  lists,  queues,  stacks, 
and  other  data  structures  can  be  built 
from  simple  data  structures  and  point¬ 
ers.  This  is  done  by  making  pointers 
the  fields  of  records: 

TYPE 

DynaPtr  =  "DynaRec; 

DynaRec  = 

RECORD 

StrData  :  STRING; 

Next :  DynaPtr; 

END 

In  a  linked  list,  several  of  these  re¬ 
cords  are  allocated  on  the  heap  such 
that  the  Next  pointer  in  each  record 
points  to  the  “next”  record  in  the  list, 
allocated  elsewhere  on  the  heap.  The 
pointer  in  the  last  record  is  set  to  a 
value  of  NIL,  which  is  a  sentinel  value 
indicating  that  the  pointer  points  to 
nothing. 

Standard  procedures  exist  to  query 
the  system  and  find  out  how  much  free 
heap  memory  is  available.  The  Mem- 
Avail  function  returns  the  total  number 
of  bytes  of  free  memory  on  the  heap. 
The  MaxAvail  function  returns  the  size 
in  bytes  of  the  largest  single  chunk  of 
memory  on  the  heap. 

Heaps  of  Holes 

This  is  a  powerful  concept,  but  there’s 
a  worm  in  it:  When  you  deallocate  items 
stored  on  the  heap,  the  memory  where 
the  item  had  been,  becomes  a  “hole,” 
the  exact  size  of  the  item.  This  hole  is 
available  for  use  in  allocating  future 
dynamic  variables,  but  obviously,  you 
can’t  allocate  a  variable  any  larger  than 
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the  variable  that  created  the  hole  by 
going  poof. 

This  sounds  worse  than  it  often  is. 
Items  are  allocated  on  the  heap  in  or¬ 


der,  side  by  side.  If  you  allocate  100 
records  in  a  row,  use  them,  and  then 
deallocate  all  100  records  at  once;  the 
“hole”  resulting  from  the  deallocation 


will  be  contiguous,  the  size  of  the  full 
100  records.  Problems  arise  when  you 
allocate  a  great  many  items  of  varying 
sizes  on  the  heap,  and  deallocate  some 
but  not  others,  especially  if  the  deallo¬ 
cation  is  fairly  random.  Allocating  a 
record  in  a  hole  left  by  a  slightly  larger 
record  can  leave  a  tiny  sliver  of  unused 
memory  that  isn’t  good  for  anything  at 
all.  Do  this  often  enough,  and  you  may 
have  a  great  deal  of  free  memory  that 
can’t  be  used  at  all  because  it  exists  in 
a  large  number  of  very  small  chunks. 

This  condition  is  called  “heap  frag¬ 
mentation”  because  the  heap  becomes 
divided  into  a  great  many  separate  frag¬ 
ments  of  memory  in  varyingly  useful 
sizes.  Figure  1  represents  this  condi¬ 
tion  in  Pascal  or  Modula-2.  The  shaded 
areas  represent  memory  that  is  in  use, 
pointed  to  by  one  of  the  pointers  on 
the  left.  The  white  areas  represent  mem¬ 
ory  that  is  free  for  use.  Note  that  some 
of  the  slices  are  pretty  thin,  and  may  not 
be  large  enough  to  hold  anything  use¬ 
ful  to  the  currently  running  application. 

The  Long  Wait  for  the  Garbage  Man 

So,  what  happens  if  you  call  MaxAvail 
and  the  size  of  the  largest  free  chunk  of 
heap  memory  is  less  than  the  size  of  the 
item  you  need  to  allocate  on  the  heap? 
Not  much.  The  best  you  can  do  is  to  try 
deallocating  some  other  items  on  the 
heap  and  hope  that  they’ll  open  up  a 
hole  large  enough  to  fit  the  item  you 
need  to  create.  If  there’s  nothing  you 
can  turn  loose,  you’re  stuck.  Really. 

When  confronted  with  this  problem, 
most  people  assume  there  must  be  a 
way  to  rearrange  the  blocks  of  memory 
on  the  heap,  packing  them  up  nose-to- 
tail  so  that  all  the  little  empty  slivers  of 
memory  collect  in  one  place  and  add 
up  to  a  single  large  block  of  useful 
space  again.  It’s  pretty  disconcerting 
to  realize  that  there  is  absolutely  no 
general-purpose  way  to  do  this  in  Pas¬ 
cal  or  Modula-2.  (Or  C,  either.)  Every 
trick  involves  making  assumptions 
about  the  order  in  which  items  were 
allocated  on  the  heap  and  other  infor¬ 
mation  that  varies  from  application  to 
application  or  even  from  one  run  time 
to  the  next. 

This  Holy  Grail  of  gathering  together 
all  the  bubbles  in  the  great  waterbed 
of  heap  memory  is  what  we  call  “gar¬ 
bage  collection.”  It  is  one  of  the  most 
wretchedly  difficult  things  to  do  in  all 
computer  science,  and  in  many  lan¬ 
guages  it  is  simply  impossible. 

Why?  It  has  to  do  with  the  way  point¬ 
ers  are  implemented  in  our  most  com¬ 
mon  implementations  of  Pascal  and 
Modula-2.  Pointers  are  simply  machine 
addresses.  The  “long”  pointers  used 
in  Modula-2  (and  all  pointers  in  Turbo 
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(continued  from  page  144) 
and  QuickPascal)  are  32-bit  addresses 
consisting  of  a  1 6-bit  segment  address 
and  a  16-bit  offset  address.  So  a  pointer 
is  just  4  bytes  somewhere  in  the  mega¬ 
byte  of  8086  real  address  space,  con¬ 
taining  the  address  of  the  memory  block 
that  the  pointer  points  to.  (A  NIL  pointer 
contains  4  bytes  of  Os.) 

The  problem  with  rearranging  the 
heap  lies  in  notifying  the  pointers  that 
the  addresses  of  their  referents  have 
changed.  A  pointer  is  an  address,  so 
you  would  have  to  change  the  value 
of  every  pointer  that  pointed  to  any 
block  of  heap  memory  involved  in  a 
move.  The  problem  with  that  is  simply 
finding  all  the  pointers.  Although  you 
can  always  find  a  pointer’s  referent  start¬ 
ing  from  the  pointer,  you  can’t  work 
back  from  a  block  of  memory  to  find 
all  pointers  that  point  to  it.  Keep  in 
mind  that  any  number  of  pointers  may 
point  to  a  single  block  of  memory  on 
the  heap,  and  those  pointers  may  be 
anywhere  in  memory  at  all,  including 
on  the  heap,  in  the  code  segment,  or 
on  the  stack.  Nothing  marks  a  pointer 
as  being  a  pointer;  furthermore,  nearly 
all  4-byte  sequences  in  memory  con¬ 
tain  binary  patterns  that  could  repre¬ 
sent  valid  addresses. 

So  there  may  be  tens  of  thousands 
of  pointers  scattered  through  the  mega¬ 
byte  of  real  address  space,  and  they 
look  no  different  from  4  bytes  of  ma¬ 
chine  code,  4  bytes  of  data,  or  4  bytes 
of  anything.  Finding  pointers  just  by 


looking  for  them  is  thus  meaningless. 
And  if  you  can’t  find  every  pointer  that 
points  to  a  block  of  data,  you  had 
better  leave  that  block  of  data  right 
where  it  is.  That  in  a  nutshell  is  why 
garbage  collection  for  the  standard  Pas¬ 
cal/Modula-2  heap  is  impossible. 

What  Those  Other  Guys  Do 

Outside  of  the  Pascal/C/Modula  world 
things  are  considerably  better.  Small¬ 
talk  and  Actor  both  support  fully  gen¬ 
eral  automatic  garbage  collection  on 
their  dynamic  storage.  One  reason  both 
pick  up  their  trash  is  that  they  have  to; 
both  are  large,  ambitious  systems  that 
take  up  a  lot  of  memory.  Without  gar¬ 
bage  collection,  they  would  drink  their 
heap  dry  in  no  time  flat. 

Actor  contains  a  mechanism  that  con¬ 
stantly  scans  its  stack  and  dictionary, 
looking  for  “dead”  objects  to  which  no 
references  are  found.  Actor’s  dictionary 
is  roughly  equivalent  to  a  symbol  table. 
If  a  block  of  memory  is  allocated  for 
an  object,  and  that  object  is  not  refer¬ 
enced  in  the  dictionary  or  by  any  other 
object,  the  block  is  scavenged  and  made 
available  for  new  objects. 

This  happens  automatically,  and  the 
process  continues  in  the  background 
throughout  the  execution  of  an  Actor 
program.  This  way,  the  garbage  collec¬ 
tion  overhead  (which  takes  an  irritatingly 
large  fraction  of  the  CPU  cycles  de¬ 
voted  to  a  program’s  execution)  is 
spread  out  evenly  through  a  program’s 
life  and  is  thus  less  noticeable.  Some 


older  systems  performed  garbage  col¬ 
lection  all  at  once,  which  caused  the 
executing  program  to  stop  dead  in  its 
tracks  (sometimes  for  minutes  at  a  time) 
while  the  garbage  collector  fiddled  mem¬ 
ory  around.  This  happened  to  me  once 
back  in  my  Xerox  days  while  I  was 
learning  some  internal  revision  of  Small¬ 
talk  on  a  creaky  old  Alto  workstation. 
I  was  certain  the  system  had  croaked, 
but  lo!  It  was  only  picking  up  its  dirty 
socks,  and  came  back  to  me  after  what 
had  to  be  six  or  seven  minutes. 

Actor’s  garbage  collector  works  so 
well  that  there  is  no  dispose  message 
to  clean  up  after  allocations  triggered 
by  New. ;  when  a  program  no  longer 
needs  to  work  with  an  object,  it  cuts 
the  object’s  space  loose  by  setting  its 
internal  state  to  Nil.  The  scavenger  then 
picks  up  the  trash  on  its  next  pass. 

Smalltalk/V’s  documentation  says  less 
about  its  garbage  collection  system  than 
Actor’s,  but  things  seem  to  work  in 
about  the  same  way:  When  an  object 
is  no  longer  referenced,  it  is  removed 
from  memory  and  the  memory  is  re¬ 
claimed.  Unused  symbols  do  accumu¬ 
late,  however,  and  must  be  explicitly 
purged  and  their  space  reclaimed  by 
sending  the  purgeUnusedSymbolsm.es- 
sage  to  the  Smalltalk  system. 

The  Secret  of  the  Middleman 

There  are  lots  of  ways  to  implement 
garbage  collection,  most  of  them  far 
beyond  my  understanding.  What  I  will 
explain,  though,  is  the  minimum  ma¬ 
chinery  that  makes  garbage  collection 
possible.  What  you  need,  basically,  is 
a  middleman. 

I’ve  drawn  such  a  middleman  in  Fig¬ 
ure  2.  Between  the  pointers  scattered 
through  the  system  and  the  heap  itself 
is  an  array  of  handles.  I’ve  shown  the 
handles  as  pointers  themselves,  but  they 
aren’t  pointers  in  the  same  physical 
sense  that  Pascal  and  Modula-2  point¬ 
ers  are.  A  handle  is  means  of  access.  It 
could  be  a  pointer  to  the  actual  block 
of  heap  memory,  or  it  could  be  a  pointer 
into  some  larger  mechanism  that  maps 
blocks  of  storage  onto  disk  sectors,  or 
EMS  or  extended  memory.  Also,  a  han¬ 
dle  must  contain  the  size  of  the  mem¬ 
ory  block  it  points  to.  I’ve  not  shown 
this  in  the  figure  for  simplicity’s  sake, 
but  a  handle  might  be  a  very  simple 
record  containing  a  pointer  to  the  mem¬ 
ory  block  on  the  heap  and  a  16-bit 
block  size  value. 

A  handle’s  primary  virtues  are  two: 
First  of  all,  for  each  block  of  memory 
there  is  only  one  handle,  and  second, 
the  system  always  knows  where  every 
handle  is.  I  show  an  array  of  handles 
in  the  figure  for  simplicity;  in  many 
cases  the  handles  will  be  arranged  as 


Figure  2:  The  same  heap  accessed  through  an  array  of  handles 
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a  linked  list.  The  important  thing  is  that 
the  handles  are  stored  in  a  form  that  is 
always  under  the  system’s  control. 

A  handle  either  points  to  a  block  of 
memory  on  the  heap  or  it  is  set  to  NIL 
to  indicate  that  the  handle  is  free  and 
may  be  used.  Note  in  Figure  2  that  in 
two  cases,  two  different  pointers  point 
to  the  same  handle.  This  is  entirely 
equivalent  to  the  situation  in  Figure  1 
where  two  pointers  pointed  to  the  same 
block  of  memory  on  the  heap.  Any 
number  of  pointers  may  point  to  one 
handle,  but  only  one  handle  may  point 
to  any  given  block  of  memory. 

Packing  the  Heap 

The  heap  shown  in  Figure  2  is  identical 
to  that  shown  in  Figure  1 ,  that  is,  frag¬ 
mented  to  the  point  of  being  useless. 
Unlike  Figure  1,  however,  the  fragmen¬ 
tation  in  Figure  2  can  be  fixed  by  a  little 
scavenging.  Because  the  system  knows 
where  every  handle  is  located,  and  be¬ 
cause  each  handle  points  to  one  mem¬ 
ory  block  and  each  memory  block  has 
only  one  handle  pointing  to  it,  the  sys¬ 
tem  can  eliminate  wasted  space  by  mov¬ 
ing  memory  blocks  together  on  the 
heap  until  they  become  contiguous. 
This  condition  is  shown  in  Figure  3-  All 
of  the  available  heap  space  is  now  in 
one  large  block,  and  no  small  slivers 


of  memory  remain  wasted. 

In  a  practical  system,  a  few  more 
things  would  be  necessary,  such  as  a 


“free  list”  to  keep  track  of  available 
blocks.  Both  Turbo  Pascal  and  Quick- 
Pascal  use  such  a  list,  a  simple  linked 
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list  of  records  located  on  the  heap. 

Could  a  system  such  as  this  be  built 
into  a  Pascal  or  Modula-2  compiler? 
Of  course.  The  cost  is  in  speed,  and, 
to  a  lesser  extent,  in  the  memory  needed 
by  the  handles  and  the  code  to  ma¬ 
nipulate  them.  Dereferencing  a  pointer 
to  a  pointer  involves  two  separate  mem¬ 
ory  accesses  instead  of  only  one.  Also, 
as  mentioned  before,  the  garbage  col¬ 
lection  task  itself  takes  some  time,  but 
with  some  cleverness  can  be  spread 
so  thin  as  to  hardly  be  noticeable,  a  la 
Actor. 

Breaking  Old  Habits 

The  real  problem,  though,  is  breaking 
current  code.  Turbo  Pascal,  in  particu¬ 
lar,  allows  a  lot  of  direct  manipulation 
of  pointers.  If  it  were  as  simple  as  gen¬ 
erating  handle-manipulation  code  for 
New,  Dispose ,  and  the  dereference  op¬ 
erator,  there’d  be  little  difficulty  with 
compatibility.  However,  a  great  deal  of 
Turbo  Pascal  code  (including  a  lot  of 
my  own)  make  assumptions  about  the 
nature  of  pointers  that  would  not  jive 
with  a  handle-based  heap  manager. 

The  most  obvious  case  is  building 
pointers  from  segment  and  offset  ad¬ 
dresses  using  the  Ptr  function.  How 
many  times  have  you  done  something 
like  this: 

VAR 

Display  :  Pointer; 


mers  hit  a  conceptual  wall  when  they 
encounter  pointers,  and  rather  than  fig¬ 
ure  them  out  or  yell  for  help,  simply 
work  around  them.  Thus,  a  great  many 
Pascal  applications  don’t  make  use  of 
the  heap  at  all. 

2.  Seasoned  Pascal  developers  who 
use  the  heap  heavily  have  worked  out 
tricks  to  deal  with  heap  fragmentation. 
These  include  padding  records  out  so 
that  most  records  allocated  on  the  heap 
are  either  the  same  size  or  convenient 
multiples  of  the  size  of  the  smallest 
record,  or  massaging  an  algorithm  such 
that  records  are  allocated  and  deallo¬ 
cated  in  order  rather  than  at  random. 
“Heap  discipline”  of  this  sort  is  second 


Display  :=  Ptr($B800,0); 

The  last  thing  you  want  is  for  a  heap 
manager  to  decide  to  move  your  video 
refresh  buffer  somewhere  a  little  closer 
to  the  other  bubbles. 

The  kicker  is  that  pointers  are  often 
used  for  things  that  have  nothing  at  all 
to  do  with  the  heap.  And  as  long  as 
pointers  point  to  things  that  exist  at 
fixed  locations  and  cannot  (or  should 
not)  be  moved,  using  handles  for  heap 
management  with  traditional  pointer 
and  dereferencing  syntax  is  going  to 
be  difficult  indeed. 

The  Trouble  with  Objects 

I’m  making  a  very  big  deal  of  all  this 
because  sometime  soon  the  matter  of 
heap  fragmentation  is  going  to  become 
a  very  serious  problem  for  the  new¬ 
born  object-oriented  languages.  I  won’t 
speak  for  C++  because  I  don’t  under¬ 
stand  it  very  well  as  yet  (though  I’m 
trying)  but  for  Turbo  and  QuickPascal 
we’re  headed  for  trouble. 

Heap  fragmentation  has  been  with 
us  from  the  beginning,  but  it’s  attracted 
little  attention  for  two  major  reasons: 

1.  Many  self-taught  Pascal  program- 


nature  to  longtime  Pascal  developers, 
and  is  considered  by  many  to  be  part 
of  good  structured  programming  prac¬ 
tice,  even  though  it  violates  the  spirit 
of  true  dynamic  allocation. 

Unfortunately,  when  you  start  deal¬ 
ing  with  objects  in  a  big  way,  this  kind 
of  heap  discipline  no  longer  works.  A 
linked  list  of  objects  no  longer  contains 
items  all  of  one  type.  As  long  as  all 
objects  in  a  list  are  descended  from  a 
common  ancestor  (such  as  the  Node 
type  shipped  as  an  example  with  Turbo 
Pascal  5.5)  polymorphism  allows  the 
developer  to  stop  worrying  about  the 
type  of  the  nodes  in  a  list  and  let  the 
nodes  handle  their  own  business 
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through  virtual  methods.  When  the  ap¬ 
plication  has  to  have  carnal  knowledge 
of  the  contents  of  a  list  in  order  to 
make  things  happen,  most  of  the  bene¬ 
fits  of  object-oriented  techniques  get 
lost.  Much  of  OOP’s  novelty  lies  in 
giving  individual  objects  more  auton¬ 
omy,  but  heap  discipline  generally 
means  orchestrating  heap  management 
in  ways  that  individual  objects  —  be¬ 
ing  just  parts  of  a  larger  whole  —  can¬ 
not  accomplish. 

Compounding  the  problem  is  the  fact 
that  programmers  can  no  longer  ignore 
the  heap  once  they  start  using  OOP. 
In  QuickPascal  all  objects  are  allocated 
on  the  heap.  You  don’t  get  any  choices. 
In  Turbo  Pascal,  objects  may  be  defined 
statically  in  the  data  segment  without 
involving  the  heap  if  you  like,  but  such 
objects  may  not  take  part  in  polymorphic 
algorithms  and  are  considerably  less 
useful  than  objects  on  the  heap. 

So  picture  it:  An  ambitious  applica¬ 
tion  consisting  of  dozens  or  hundreds 
of  objects  popping  into  being  on  the 
heap  or  poofing  into  holes  more  or  less 
at  random,  without  the  application’s 
being  fully  aware  of  individual  objects’ 
exact  types  and  hence  their  sizes.  The 
old  tricks  no  longer  work,  and  (to  state 
it  in  line  with  the  metaphor  of  active 
data)  the  heap  fragments  itself  to  use¬ 
lessness  in  record  time. 
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The  Tyranny  of  the  Installed  Base 

Both  Turbo  Pascal  5.5  and  QuickPascal 
suffer  from  this  problem,  but  if  a  solu¬ 
tion  is  out  there,  QuickPascal  will  be 
the  easier  fix  by  far.  Because  the  in¬ 
stalled  base  for  QuickPascal  is  counted 
in  the  tens  of  thousands  rather  than  in 
the  many  hundreds  of  thousands,  there 
is  less  QuickPascal  code  to  break  and 
fewer  QuickPascal  users  to  alienate  if 
a  fundamental  syntactic  change  must 
be  made  to  the  language  to  allow  a 
handle-based  heap  manager. 

But  —  most  remarkably  - —  QuickPas¬ 
cal  may  not  need  to  make  any  syntactic 
changes  at  all.  What  I  originally  thought 
was  oversight  or  sheer  clumsiness  in 
the  Apple  Pascal  definition  (which  Quick¬ 
Pascal  follows  closely)  might  hold  the 
solution  to  the  whole  mess. 

Recall  the  inconsistent  nature  of  ob¬ 
ject  definition  in  QuickPascal.  Objects 
are  defined  like  records,  allocated  like 
pointers,  and  then  used  like  records: 

TYPE 

Figure  =  OBJECT 
X,Y :  Integer; 

Visible  :  Boolean; 
PROCEDURE  Show; 
PROCEDURE  Hide; 

END; 

VAR 


MyObject  =  Figure; 


New(MyObject); 

MyObject. A  :=  17; 

MyObject. Y  :=  42; 

MyObject. Show; 

Ordinarily,  New  works  only  with  point¬ 
ers,  but  QuickPascal  allows  New  to  take 
an  object  variable  identifier  as  though 
it  were  a  pointer.  In  fact,  beneath  the 
surface  the  variable  MyObject  is  a 
pointer,  but  once  passed  to  New  it  can 
be  used  as  though  it  were  the  object 
itself  and  not  simply  a  pointer  to  a 
nameless  block  of  memory  on  the  heap. 

What’s  important  is  that,  regardless 
of  its  physical  implementation,  a  Quick¬ 
Pascal  object  is  not  accessed  through 
pointers.  Unless  you  explicitly  declare 
an  object  as  the  referent  of  a  pointer 
type,  the  dereference  operator  is  not 
required  to  access  the  object’s  methods 
and  fields.  This  means  that,  if  Microsoft 
chose  to  do  so,  it  could  isolate  objects  in 
an  objects-only  heap,  and  implement  a 
handle-based  manager  for  objects  that 
could  include  automatic  garbage  col¬ 
lection.  The  name  of  the  object  would 
become  a  pointer  to  a  handle,  which 
would  then  point  to  the  object’s  actual 
location  on  the  heap.  This  does  not 
involve  redefining  pointer  syntax  or 
the  dereference  operator,  and  would 
not  break  a  single  line  of  Version  1.0 
code.  For  QuickPascal  it  would  solve 
the  heartbreak  of  heap  fragmentation 
for  objects,  which  is  itchier  than  psoria¬ 
sis  and  lots  harder  to  get  rid  of. 

I  won’t  say  that  this  was  what  the 
designers  of  Apple  Pascal  had  in  mind 
when  they  chose  their  somewhat  idi¬ 
osyncratic  syntax  for  object  creation 
(though  if  they  contact  me  I’d  love  to 
ask  them)  but  it  certainly  is  a  potential 
solution  aching  to  be  implemented.  It 
will  have  some  costs  in  performance, 
but  I  suppose  we  were  naive  in  assum¬ 
ing  that  the  amazing  flexibility  of  poly¬ 
morphism  would  come  for  free. 

Turbo  Pascal’s  designers  will  have  a 
much  harder  row  to  hoe.  There  is  no 
solution  that  won’t  involve  breaking 
megalines  of  existing  code.  They’re 
clever,  those  Borlanders;  as  clever  as 
you  find  in  this  business  and  then  some, 
but  the  tyranny  of  the  installed  base  is 
going  to  make  the  Big  Fragmentation 
Fix  for  Turbo  Pascal  a  painful  one  all 
the  way  around. 

Would  that  it  were  as  simple  as  chas¬ 
ing  bubbles  in  a  waterbed. 

DDJ 
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Listing  One  ( Text  begins  on  page  153  ) 

on  mousewithin 

— hypertext  technique  by  Steve  Drazga,  AnalytX 
— if  you  use  this  in  your  scripts  please  include  these  2  lines. 

if  the  locktext  of  the  target  is  true  then 

set  locktext  of  target  to  false  — unlock  the  field  if  it  is 

locked 
end  if 

if  selection  is  not  empty  then  — something  was  selected 
put  selection  into  SelectedWord 

if  space  is  in  SelectedWord  then  — user  selected  >  1  word 
click  at  loc  of  target  — so  we  will  clear  the  selection 
exit  mousewithin  — and  exit  to  wait  for  another 

selection 

end  if 

— this  is  the  section  where  you  do  something  with  the  selection 
— You  can  bring  up  a  pop  up  note  or  you  can  go  to  another  card. 

end  if 

end  mousewithin 


End  Listing  One 


Listing  Two 

on  mouseUp 

—  This  code,  placed  in  a  button  script,  implements 

—  Harvey  Chang's  hypertext  trick.  The  user  selects 

—  any  text  in  a  field  and  clicks  on  the  button. 

—  The  script  first  tries  to  use  the  selected  text  as  a 

—  hypertext  link,  then  falls  back  to  simple  search. 

doMenu  Copy  Text 

put  "Montreal  Hypertext,  Harvey  Y  Chang  MD,  1988  Jan  16" 
push  card 

go  to  Montreal  Hypertext  Demo 
doMenu  Find. . . 
doMenu  Paste  Text 

put  "  in  field  "  &  quote  &  "Title"  &  quote  after  message 
do  message 

if  the  result  is  "not  found"  then 

answer  "not  found  in  Titles:  search  text?"  with  "OK"  or  "No" 
if  it  is  "No"  then 
pop  card 
exit  mouseUp 
else 

doMenu  Find. . . 
doMenu  Paste  Text 

put  "  in  field  "  &  quote  &  "Text"  &  quote  after  message 
do  message 
end  if 
end  if 
end  mouseUp 


End  Listing  Two 


Listing  Three 

on  mouseUp 

--  This  is  a  scrolling  field  script.  Its  field  must  be  locked. 

—  It  implements  an  index  field,  to  be  placed  on  the  first 

—  card  of  the  stack  to  be  indexed.  This  is  the  index  card. 

--  When  the  mouse  is  clicked  inside  the  field,  this  script  causes 

—  a  jump  to  the  card  corresponding  to  the  line  clicked  on. 

—  The  line  commented  out  uses  the  text  in  the  line, 

—  rather  than  its  number,  as  the  link. 

go  to  card  getLineNum(the  mouseV) 

—  find  line  getLineNum(the  mouseV)  of  me  in  field  keyword 
end  mouseUp 

function  getLineNum  mouseVert 

—  Returns  the  number  of  the  line  clicked  on. 

—  It  works  like  this: 

--  Subtracting  the  top,  of  the  field  and  its  scroll  from 

—  the  mouse' s  vertical  location  gives  the 

—  mouse's  vertical  location  within  the  field. 

—  Dividing  this  by  the  textHeight  of  the  field  &  adding  0.5 

—  converts  pixel  counts  to  line  counts. 

—  Rounding  gives  a  value  acceptable  as  a  card  number. 

—  Note:  although  this  technique  should  work  with  any  font  size, 

—  turning  on  WideMargins  will  confuse  the  count. 

—  To  adapt  this  script  to  a  non-scrolling  field, 

—  remove  "+  the  scroll  of  me"  from  the  computation. 

return  round ( { (mouseVert  -  the  top  of  me  +  the  scroll  of  me)  / 

(the  textHeight  of  me))  +  0.5) 

end  getLineNum 

End  Listings 
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Listing  One  (Text  begins  on  page  135.) 


/* - hyprtree.h - */ 

#define  NODELEN  256  /*  length  of  a  node  */ 

#def ine  MAXLEVELS  10  /*  tree  levels  */ 

♦define  MAXKEYLENGTH  25  /*  maximum  key  length  */ 

#define  TRUE  1 
♦define  FALSE  ! TRUE 

♦define  KSPACE  (NODELEN-sizeof (NODEHDR) ) 

♦define  HYPERTREE  "hyprtree.ndx" 

/* - computes  length  of  a  key  in  a  node - */ 

♦define  keylength (nd, kp)  (strlen(kp)  +  1  +  \ 

((nd) . nodehdr.isleaf?sizeof (KEYVALUE) : sizeof (NODEPOINTER) ) ) 

/* - node  pointers  and  key  values - */ 

typedef  long  KEYVALUE; 
typedef  int  NODEPOINTER; 

typedef  union  ( 

KEYVALUE  keyvalue; 

NODEPOINTER  nodepointer; 

)  KEYPOINTER; 


/* - header  record  for  a  hypertree - */ 

typedef  struct  ( 

NODEPOINTER  rootnode; 

}  TREEHDR; 

/* - header  structure  for  a  hypertree  node - */ 

typedef  struct  ( 

int  isleaf;  /*  true  if  the  node  is  a  leaf  */ 

NODEPOINTER  parent;  /*  node  number  of  parent  */ 

KEYPOINTER  lower;  /*  keys  <  this  node  (or  value  if  leaf)*/ 

)  NODEHDR; 

/* - node  record  for  a  hypertree - */ 

typedef  struct  ( 

NODEHDR  nodehdr; 
char  keys [KSPACE] ; 

}  TREENODE; 

/* - prototypes -  */ 

void  addkey(char  ‘key,  KEYVALUE  keyvalue); 

int  findkey(char  *key) ; 

int  firstkey (void) ; 

int  lastkey (void) ; 

int  nextkey (void) ; 

int  prevkey (void) ; 

KEYVALUE  current_keyvalue (void) ; 
char  *current_keystring (void) ; 

End  Listing  One 


Listing  Two 

/*  - addkey.c - */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦include  "hyprtree.h" 

static  void  addkeyentry (int  level,  char  *key, 

KEYPOINTER  keypointer,  NODEPOINTER  lowernode); 
static  void  nullnode(int  level); 
static  int  freespace (TREENODE  node); 
static  void  writenode (int  level); 

static  void  adopt (NODEPOINTER  child,  NODEPOINTER  parent); 


static  void  addkeyentry (int  level,  char 
KEYPOINTER  keypointer, 


*key, 

NODEPOINTER  lowernode 


) 


char  *kp; 


if  (nodes [level]  ==  NULL)  { 

/* - build  a  new  node - */ 

if  (level  ==  0)  { 

/* - building  a  new  tree - */ 

htree  =  fopen (HYPERTREE,  "wb+"); 

/* - write  a  NULL  header  for  now - */ 

fwrite(&th,  sizeof (TREEHDR) ,  1,  htree); 

I 

if  ( (nodes [level]  =  malloc (sizeof (TREENODE) ) )  ==  NULL)  { 
fputs("\nOut  of  memory!",  stderr) ; 
exit  (1) ; 

} 

nodes [level+1]  =  NULL; 
nullnode (level) ; 

/*  -  point  to  the  node  of  the  lower  keys  —  */ 

nodes [ level ]->nodehdr. lower. nodepointer  =  lowernode; 

/*  —  assign  the  next  node  number  to  this  node  —  */ 
nodenbr [level]  =  ++nextnode; 

} 

if  (keylength (‘nodes [level] , key)  > 

freespace (‘nodes [level] ) )  ( 

/* - this  node  is  full - */ 

KEYPOINTER  keyp; 

NODEPOINTER  lowernode; 

/*  -  write  the  node  to  the  index  file  -  */ 

writenode (level) ; 

/*  -  remember  the  node  nbr  at  this  level  -  */ 

lowernode  =  nodenbr [level] ; 

/*  —  assign  a  new  node  number  to  this  level  —  */ 
nodenbr [level]  =  ++nextnode; 

/*  -  grow  or  add  to  parent  with  the  current  key  -  */ 

memset (Skeyp,  0,  sizeof (KEYPOINTER) ) ; 
keyp. nodepointer  =  nodenbr [level] ; 
addkeyentry (level+1,  key,  keyp,  lowernode); 

/*  -  now  set  the  node  at  this  level  to  NULL  values  -  */ 
nullnode (level) ; 

nodes [ level ]->nodehdr. lower  =  keypointer; 

1 

else  { 

/* - insert  the  key  into  the  node - */ 

kp  =  nodes [ level ] ->keys; 

/* - scan  t0  the  end  of  the  node - */ 

while  (*kp) 

kp  +=  keylength (‘nodes [level] ,  kp) ; 
strcpy(kp,  key) ; 

/* - attach  the  key  pointer  to  the  key - */ 

kp  +=  strlen (kp) +1; 
if  (level  ==  0) 

‘((KEYVALUE  *)kp)  =  keypointer . keyvalue; 

else 

‘((NODEPOINTER  *)kp)  =  keypointer . nodepointer ; 

) 

} 


/* - build  a  null  node - */ 

static  void  nullnode (int  level) 

{ 

memset (nodes [level] ,  0,  NODELEN); 

nodes [level] ->nodehdr. isleaf  =  level  ==  0; 

} 


/* - compute  space  remaining  in  a  node - */ 

static  int  freespace (TREENODE  node) 

( 

int  sp  =  KSPACE; 
char  *kp  =  node. keys; 


static  TREENODE  ‘nodes [MAXLEVELS] ; 
static  NODEPOINTER  nodenbr [MAXLEVELS] ; 
static  NODEPOINTER  nextnode; 

static  FILE  ‘htree; 
static  TREEHDR  th; 


while  (*kp)  ( 

sp  -=  keylength (node, kp) ; 
kp  +=  keylength (node, kp) ; 

} 

return  sp; 


/* 

*  Add  a  key  string  value  and  its  associated  KEYVALUE  to 

*  the  hypertree. 

*/ 

void  addkey(char  ‘key,  KEYVALUE  keyvalue) 

( 

KEYPOINTER  keypointer; 
if  (key  ==  NULL)  ( 

/* - terminal  key,  complete  the  tree - */ 

if  (htree  !=  NULL)  { 
int  level  =  0; 

/* - write  the  unwritten  nodes - */ 

while  (nodes [level]  !=  NULL)  ( 
writenode (level) ; 
free (nodes [level] ) ; 
level++; 

} 

/* - update  the  header  block - */ 

th. rootnode  =  nodenbr [level-1] ; 
fseek (htree,  0L,  SEEK_SET) ; 
fwrite(&th,  sizeof (TREEHDR) ,  1,  htree); 

fclose (htree)  ; 

} 

} 

else  { 

keypointer .keyvalue  =  keyvalue; 
if  (strlen (key)  <=  MAXKEYLENGTH) 

addkeyentry (0,  key,  keypointer,  0) ; 


/* - write  a  completed  node - */ 

static  void  writenode (int  level) 

{ 

long  where  =  (nodenbr [level] -1) ‘NODELEN+sizeof (TREEHDR) ; 

fseek (htree,  where,  SEEK_SET) ; 
f write (nodes [level] ,  NODELEN,  1,  htree); 
if  (level)  ( 

/*  -  this  is  a  parent  node,  update  its  children  -  */ 
char  *kp  =  nodes [level] ->keys; 
adopt (nodes [level] ->nodehdr. lower .nodepointer, 
nodenbr [level] ) ; 
while  (*kp)  ( 

adopt (‘((NODEPOINTER  *) (kp+strlen (kp) +1) ) , 
nodenbr [ level ] ) ; 

kp  +=  keylength (‘nodes [level] ,  kp) ; 


/*  -  write  a  parent  node  number  into  a  child  node  -  */ 

static  void  adopt (NODEPOINTER  child,  NODEPOINTER  parent) 

{ 

NODEHDR  nodehdr; 

long  here  =  ftell (htree) ; 

long  where  =  (child-1 ) ‘NODELEN+sizeof (TREEHDR) ; 


(Listing  continued  on  page  1 56) 
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Listing  Two  (Listing  continued,  text  begins  on  page  135.) 

fseek(htree,  where,  SEEK_SET) ; 
fread(&nodehdr,  sizeof (NODEHDR) ,  1,  htree) ; 
nodehdr .parent  =  parent; 
fseek (htree,  where,  SEEK_SET); 
fwrite (Snodehdr,  sizeof (NODEHDR) ,  1,  htree); 
fseek (htree,  here,  SEEK_SET) ; 

1  End  Listing  Two 


Listing  Three 

/* - srchtree.c - */ 

#include  <stdio.h> 
tinclude  <stdlib.h> 

#include  <string.h> 

♦include  "hyprtree.h" 

/* - search  packet - */ 

typedef  struct  { 

NODEPOINTER  node; 
char  *ky; 

)  SEARCH; 

FILE  *htree; 
static  TREEHDR  th; 

Static  TREENODE  node; 
static  SEARCH  current; 


static  void  readnode (NODEPOINTER  nodepointer); 
static  void  opentree (void); 


/* 

*  Find  a  specified  key  in  the  tree. 

*  Return  TRUE  if  found. 

*  Return  FALSE  if  not  found. 

*/ 


int  findkey(char  *key) 

{ 

opentree () ; 

if  (th. rootnode)  { 

SEARCH  save  =  current; 
readnode (th. rootnode) ; 
while  (TRUE)  { 

int  cmp; 

cur rent. ky  =  node. keys; 
while  (*current.ky)  { 

cmp  =  stricmp(key,  current. ky); 
if  (cmp  <  0)  ( 

save  =  current; 
break; 

} 

if  (cmp  ==  0) 

return  TRUE; 

current. ky  +=  keylength (node,  current. ky); 

} 

if  ( Inode. nodehdr. isleaf)  { 
if  (current. ky  ==  node. keys) 

readnode (node. nodehdr. lower. nodepointer) ; 

else 


readnode (*( (NODEPOINTER  *) 

(current .ky-sizeof (NODEPOINTER) ) ) ) ; 


else  { 

current  =  save; 
readnode ( current . node ) ; 
break; 


return  FALSE; 


/* 

*  Find  the  first  sequential  key  in  the  tree. 

*  Return  TRUE  if  found. 

*  Return  FALSE  if  not  found  (the  tree  is  empty) . 

*/ 

int  firstkey (void) 

{ 

opentree () ; 

if  (th. rootnode)  { 

readnode (th . rootnode) ; 
while  (! node. nodehdr . isleaf ) 

readnode (node . nodehdr . lower . nodepointer) ; 
current. ky  =  node. keys; 
return  TRUE; 

} 

return  FALSE; 

} 

/* 

*  Find  the  last  sequential  key  in  the  tree. 

*  Return  TRUE  if  found. 

*  Return  FALSE  if  not  found  (the  tree  is  empty) . 

*/ 

int  lastkey (void) 

{ 

NODEPOINTER  np; 

opentree () ; 

if  (th. rootnode)  { 
int  len  =0; 
np  =  th. rootnode; 
current. node  =  th. rootnode; 
current.ky  =  node. keys; 
do  { 
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SEARCH  save  =  current; 
readnode (np) ; 
current. ky  =  node. keys; 
while  (*current.ky)  { 

len  =  key length (node,  current. ky); 
current.ky  +=  len; 

} 

if  (current.ky  ==  node. keys)  { 

readnode (save. node) ; 
current.ky  =  save.ky; 
break; 

} 

else 

np  =  *( (NODEPOINTER  *) 

(current .ky-sizeof (NODEPOINTER) ) ) ; 

}  while  ( Inode. nodehdr.isleaf) ; 
current.ky  -=  len; 
return  TRUE; 

} 

return  FALSE; 

) 

/* 

*  Find  the  next  sequential  key  in  the  tree. 

*  Return  TRUE  if  found. 

*  Return  FALSE  if  not  found  (the  tree  is  empty  or  at  the  end) . 
*/ 

int  nextkey (void) 

{ 

opentree  () ; 
if  (th.rootnode)  { 

if  (current.ky  ==  NULL) 
return  firstkeyO; 

current.ky  +=  key length (node,  current.ky); 
if  ( inode. nodehdr.isleaf)  ( 
readnode ( * ( (NODEPOINTER  * ) 

(current. ky-sizeof (NODEPOINTER) ) ) )  ; 
current.ky  =  node. keys; 
while  ( Inode. nodehdr.isleaf) 

readnode (node . nodehdr . lower . nodepointer) ; 

) 

/* - while  at  the  end  of  a  node - */ 

while  (*current.ky  ==  ' \0')  { 

NODEPOINTER  child  =  current .node; 
if  (node. nodehdr. parent  ==  0) 
break; 

readnode (node. nodehdr. parent) ; 
current.ky  =  node. keys; 

if  (child  ==  node . nodehdr . lower. nodepointer) 
break; 

while  (*current.ky)  { 

NODEPOINTER  this  =  *( (NODEPOINTER  *) 

(current .ky+strlen (current.ky) +1) ) ; 
current.ky  +=  keylength (node,  current.ky); 
if  (this  ==  child) 


return  *current.ky  !=  '\0'; 

} 

return  FALSE; 

) 

/* 

*  Find  the  previous  sequential  key  in  the  tree. 

*  Return  TRUE  if  found. 

*  Return  FALSE  if  not  found 

* (the  tree  is  empty  or  at  the  beginning) . 

int  prevkey (void) 

{ 

char  *kp; 

opentree () ; 

if  (th.rootnode)  { 

if  (current.ky  ==  NULL) 
return  lastkeyO; 
if  ( inode. nodehdr.isleaf)  ( 

/* - navigate  to  end  of  the  lower  leaf - */ 

NODEPOINTER  np; 
if  (current.ky  ==  node. keys) 

np  =  node . nodehdr . lower .nodepointer ; 

else 

np  =  *( (NODEPOINTER  *) 

(current. ky-sizeof (NODEPOINTER) ) ) ; 
while  { Inode. nodehdr.isleaf)  { 

readnode (np) ; 
current.ky  =  node. keys; 
while  (‘current.ky) 

current.ky  +=  keylength (node,  current.ky); 
np  =  ‘((NODEPOINTER  *) 

(current .ky-sizeof (NODEPOINTER) ) ) ; 

) 

) 

/* - while  at  the  beginning  of  a  node - */ 

while  (current.ky  ==  node. keys)  { 

NODEPOINTER  child  =  current .node; 
if  (node. nodehdr. parent  ==  0) 
break; 

readnode (node. nodehdr .parent)  ; 
current.ky  =  node. keys; 

if  (child  ==  node . nodehdr . lower .nodepointer) 
continue; 

while  (‘current.ky)  ( 

NODEPOINTER  this  =  ‘((NODEPOINTER  *) 

(current. ky+strlen (current. ky ) +1 ) ) ; 
current.ky  +=  keylength (node,  current.ky); 
if  (this  ==  child) 
break; 

) 

(Listing  continued  on  page  158) 


Dr.  Dobb’s Journal,  June  1990 

574 


157 


C  PROGRAMMING 


Listing  Three  (Listing  continued,  text  begins  on  page  135.) 

} 

/* - go  to  previous  key  in  node - */ 

if  (cur rent. ky  !=  node. keys)  { 
kp  =  node. keys; 

while  (kp+key length (node,  kp)  <  current. ky) 
kp  +=  keylength (node,  kp) ; 
cur rent. ky  =  kp; 
return  TRUE; 

) 

} 

return  FALSE; 

) 

/* 

*  Return  the  key  value  associated  with  the  most  recently 

*  retrieved  key. 

*/ 

KEYVALUE  current_keyvalue (void) 

( 

KEYVALUE  rtn; 

if  ( Inode. nodehdr.isleaf)  ( 

SEARCH  save  =  current; 

current. ky  +=  keylength (node,  current. ky) ; 
while  ( Inode. nodehdr.isleaf)  { 

NODEPOINTER  np; 

if  ( current. ky  ==  node. keys) 

np  =  node. nodehdr. lower. nodepointer; 

else 

np  -  *( (NODEPOINTER  *) 

(current . ky-sizeof (NODEPOINTER) ) ) ; 
readnode (np) ; 
current.ky  =  node. keys; 

} 

rtn  -  node. nodehdr. lower. key value; 
current  =  save; 
readnode (save. node) ; 
return  rtn; 

} 

return  *<(KEYVALUE  *) (current. ky+strlen (current.ky) +1) ) ; 


/* 

*  Return  the  key  string  value  of  the  most  recently 

*  retrieved  key. 

*/ 

char  *current_keystring(void) 

{ 

return  current.ky; 

} 

/* - 0pen  the  tree - */ 

static  void  opentree (void) 


if  (htree  ==  NULL)  { 

if  ((htree  =  f open (HYPERTREE,  "rb"))  ==  NULL)  { 
fputs("\n"  HYPERTREE  "  not  found",  stderr) ; 
exit ( 1 ) ; 

} 

fread(&th,  sizeof (TREEHDR) ,  1,  htree); 

} 

} 

/* - read  a  specified  node - */ 

static  void  readnode (NODEPOINTER  nodepointer) 

{ 

long  where  =  (nodepointer-1) *NODELEN+sizeof (TREEHDR) ; 

f seek (htree,  where,  SEEK_SET) ; 
fread(&node,  NODELEN,  1,  htree); 

.  current. node  =  nodepointer; 


End  Listing  Three 


Listing  Four 

/* - keyextr.c - */ 

/* 

*  Build  a  test  HyperTree  from  standard  input. 

*  <>  delimiters  define  the  key  values. 

*  This  is  pass  one,  which  builds  the  sortable  table. 

*/ 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  "hyprtree.h" 

♦define  KEYTOKEN  '<' 

♦define  TERMINAL  •>• 

♦define  QUOTE 
♦define  ESCAPE  'W 

void  main (void) 

{ 

int  c; 

while  ((c  =  getcharO)  !=  EOF)  { 
if  (c  ==  KEYTOKEN)  { 

long  fileposition  =  ftell (stdin) -1; 
int  counter  =  0; 
putchar (QUOTE); 

while  ((c  -  getcharO)  I  =  TERMINAL)  { 

if  (c  ==  EOF  1 !  counter++  ==  MAXKEYLENGTH) 
break; 

if  (c  ==  QUOTE) 

putchar (ESCAPE) ; 
putchar (c) ; 

) 

putchar (QUOTE) ; 
putchar (' , ' ) ; 

printf ("%ld\n",  fileposition) ; 

} 

) 

} 

End  Listing  Four 


Listing  Five 

/* - : - keybuild.c - - - */ 

/* 

*  Build  a  test  HyperTree  from  standard  input. 

*  This  is  pass  three,  which  builds  the  HyperTree 

*  from  the  sorted  table. 

*/ 


♦include  <stdio.h> 

♦include  <string.h> 

♦include  <stdlib.h> 

♦include  "hyprtree.h" 

♦define  QUOTE 
♦define  ESCAPE  'W 

void  main (void) 

{ 

int  c; 

char  key [MAXKEYLENGTH+1 ] ; 
char  kv[20]; 

KEYVALUE  keyvalue; 

while  ((c  =  getcharO)  !=  EOF)  { 
if  (c  ==  QUOTE)  { 
int  counter  =  0; 
char  *cp  =  key; 

while  ( (c  =  getcharO)  !=  QUOTE)  { 

if  (c  ==  EOF  I  I  counter++  ==  MAXKEYLENGTH) 
break; 

if  (c  ==  ESCAPE) 
c  =  getcharO; 

*cp++  =  c; 

} 

*cp  =  ' \0' ; 

if  (getcharO  ==',')  { 

char  *kp  =  kv; 
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while  ( (c  =  getcharO)  !=  '\n'  &&  c  !=  EOF) 
*kp++  =  c; 

*kp  =  ' \0' ; 
keyvalue  =  atol (kv) ; 
addkey(key,  keyvalue); 


) 

) 

addkey (NULL,  keyvalue); 


End  Listing  Five 


Listing  Six 

/* - hyprsrch.c - */ 

/* 

*  Search  the  test  HyperTree  for  a  match  on  the 

*  command-line  parameter. 

*  Display  a  screen  of  text  starting  at  the 

*  position  indicated  for  the  matching  (or  closest) 

*  entry  in  the  HyperTree. 

*/ 

#include  <stdio.h> 

#include  <string.h> 

♦include  <ctype.h> 

♦include  <conio.h> 

♦include  "hyprtree.h" 

♦define  SCRLINES  25 

void  main(int  argc,  char  *argv[]) 

{ 

if  (argc  <  3) 

fprintf (stderr,  "Usage:  hyprsrch  textfile  keyvalue"); 
else  ( 

int  kb  =  0; 

FILE  *fp  =  fopen (argvfl] ,  "r"); 
if  (fp  ==  NULL)  { 

fprintf (stderr,  "No  such  file  as  %s",  argv(lj); 
return; 

) 

findkey (argv[2] ) ; 
while  (toupper(kb)  !=  'Q')  { 

int  lc  =  4,  c; 

KEYVALUE  kv  =  current_keyvalue ( ) ; 
printf("\n%s  (%ld)",  current_keystring() ,  kv) ; 


printf  ("\n - \n") ; 

if  (kv)  { 

fseek (fp,  kv,  SEEK_SET) ; 

while  ((c  =  getc(fp))  !=  EOF  &&  lc  <  SCRLINES) { 
if  (c  ==  ' \n' ) 


lc++; 

putchar (c) ; 

) 

) 

printf ("\nF  =  first,  " 

"L  =  last,  " 

"N  =  next,  " 

"P  =  previous,  " 
"Q  =  quit. . . ") ; 
kb  =  getch(); 
switch  (toupper (kb) )  { 

case  ' F' : 

firstkey () ; 
break; 
case  ' L' : 

lastkey () ; 
break; 
case  'N' : 

next key () ; 
break; 
case  'P' : 

prevkey () ; 
break; 
default: 
break; 

} 


) 

) 


End  Listings 
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The  Watcom  C  Optimizing  Compiler 
and  Tools  has  been  upgraded  to  Ver¬ 
sion  8.0,  Watcom  announced.  The  com¬ 
pany  describes  this  as  a  complete  line 
of  professional  C  development  prod¬ 
ucts  for  the  IBM  PC  and  compatibles. 
Included  in  this  version  is  support  for 
OS/2  run-time  libraries  and  Windows 
run-time  conventions,  and  a  386  source- 
level  debugger  user  interface  provides 
multiple  windows  and  mouse  support. 
Watcom  claims  the  compiler  is  better 
in  such  areas  as  performance,  debug¬ 
ging  capability,  multiplatform  support, 
language  extensions,  and  performance 
tuning.  And  C8.0  is  run-time  compat¬ 
ible  with  the  new  Watcom  Fortan  77 
compiler. 

Special  versions  of  the  compiler  run 
in  protected  mode  on  OS/2  or  386  DOS 
systems  and  use  memory  greater  than 
640K  to  optimize  large  programs.  A 
new  execution  profiler  for  performance 
tuning  pinpoints  high-use  regions  of 
code,  so  you  can  revise  the  parts  of 
your  program  that  get  the  most  use. 
Expanded  language  support  now  in¬ 
cludes  IBM’s  SAA  C  specification,  in 
addition  to  ANSI  C  and  Microsoft  C 
source  compatibility.  Both  C8.0  and 
C8. 0/386  are  also  available  in  profes¬ 
sional  editions,  which  provide  such  fea¬ 
tures  as  OS/2  and  Windows  support, 
the  execution  profiler,  graphics  library, 
and  386  protected-mode  compiler.  The 
386  source-level  debugger  comes  with 
the  professional  edition  of  C8. 0/386. 
These  editions  cost  $495  for  C8.0  and 
$1,295  for  C8. 0/386.  The  standard  edi¬ 
tions  cost  $395  and  $895,  respectively. 
Reader  service  no.  20. 

Watcom  Products  Inc. 

415  Phillip  St. 

Waterloo,  Ontario 
Canada  N2L  3X2 
519-886-3700 

A  new  hypermedia  engine  for  manipu¬ 
lating  multimedia  information  objects 
has  been  released  by  OWL  Interna¬ 
tional.  They  have  redesigned  their  hy¬ 
pertext  product,  Guide;  release  3-0  al¬ 
lows  you  to  incorporate  text,  graphics, 
sound,  and  video  images  in  hyperme¬ 
dia  software  for  PCs. 

DDJmet  with  William  Nisen,  the  presi¬ 


dent  of  OWL,  who  explained  that 
“Guide  3.0  has  an  object-oriented  frame¬ 
work  that  was  rewritten  in  C.  The  hy¬ 
permedia  engine  manages  objects  that 
are  directly  addressable.  Developers  can 
customize  the  environment  and  keep 
the  interface  simple  —  one  click  of  the 
mouse  can  do  five  things.”  He  also  said 
that  in  addition  to  providing  the  prod¬ 
uct,  OWL  provides  the  services  to  help 
people  with  the  software. 

A  new  full-function  programming  lan¬ 
guage,  LOGiiX,  gives  you  control  over 
the  Guide  hypermedia  engine,  and  al¬ 
lows  you  to  create  customized  docu¬ 
ments;  hypennedia  linking  tools  let  you 
add  multidimensional  and  versatile  ref¬ 
erencing  capabilities;  and  you  can  im¬ 
port  and  export  graphics  through  in¬ 
dustry-standard  file  formats.  Other  im¬ 
provements  include  hypertext  links  for 
searching  interrelated  or  selected  docu¬ 
ments,  document  formatting  for  cus¬ 
tomizing  the  graphical  user  interface, 
text-in-window  control  of  text  place¬ 
ment  and  line  wrapping,  document  main¬ 
tenance  tools,  and  Windows  compati¬ 
bility.  Guide  3.0  costs  $495.  Reader  ser¬ 
vice  no.  21. 

OWL  International  Inc. 

2800  156th  Ave.  SE 
Bellevue,  WA  98007 
206-747-3203 

A  pop-up  file  scan  and  hypertext  tool 
for  IBM  PCs  and  compatibles,  PC- 
Browse,  is  available  from  Quicksoft. 
This  program  lets  you  view  files,  find 
lost  files,  search  files  for  information, 
and  link  them  together,  using  hypertext. 
One  hotkey  press  can,  for  example, 
import  a  text  file  into  a  spreadsheet 
application;  once  in  view,  it  can  either 
be  printed  or  pasted  into  the  host  ap¬ 
plication.  DOS  wildcards  allow  searches 
in  multiple  files,  directories,  or  drives, 
and  the  lookup  search  finds  files  with 
sorted  records. 

PC-Browse  can  be  used  for  cross- 
referencing  information;  words  can  be 
flagged  within  whatever  word  proces¬ 
sor  you  use,  and  then  linked  within 
files  or  between  two  or  more  files.  You 
can  customize  on-line  cross-references 
and  make  large  files  more  manageable. 
You  can  also  develop  menu  systems 
for  end  users,  change  hotkeys,  recon¬ 
figure  buffer  size,  and  customize  screen 
colors  and  delimiter  characters.  PC- 
Browse  is  shareware  —  full  registration, 
for  $49,  includes  the  software,  manual, 
one  year  of  technical  support,  and  a 
quarterly  newsletter.  OEM  licensing  is 
also  available.  Reader  service  no.  22. 
Quicksoft  Inc. 

219  First  Ave.  N  #224 
Seattle,  WA  98109 
206-282-0452 


Seminars  on  online  documentation  will 
be  held  this  fall  in  Chicago,  Boston, 
and  San  Jose,  sponsored  by  William 
Horton  Associates.  These  two-day  semi¬ 
nars  discuss  issues  such  as  the  differ¬ 
ences  between  paper  and  online  docu¬ 
ments;  what  should  and  should  not  go 
online;  and  various  types  of  online  docu¬ 
mentation  such  as  help,  hypertext,  video¬ 
text,  hypermedia,  and  tutorials. 

The  seminars  will  also  cover  the  styles 
online  documents  should  be  written 
in,  options  in  display  design,  and  the 
various  software  available  for  online 
documentation.  The  kinds  of  storage 
and  delivery  media,  such  as  CD-ROM, 
file  servers,  and  local-  and  wide-area 
networks  will  also  be  discussed,  as  well 
as  how  to  make  information  accessible 
through  menus,  indexes,  information 
retrieval,  context  sensitivity,  and  full- 
text  search.  The  seminars  will  deal  with 
problems  such  as  producing  online  docu¬ 
ments  with  limited  staff  and  resources, 
converting  existing  paper  documents 
to  effective  online  documentation,  and 
publishing  both  paper  and  online  docu¬ 
ments  from  a  single  source.  Group  ac¬ 
tivities  and  hands-on  exercises,  as  well 
as  handouts  and  William  Horton’s  book 
Designing  and  Writing  Online  Docu¬ 
mentation,  are  included  in  the  $395  fee 
for  the  seminars.  In-house  seminars  are 
also  available.  Reader  service  no.  25. 
William  Horton  Associates 
1523  Ward  Ave.  NE 
Huntsville,  AL  35801 
205-536-8207 

HyperEdit,  a  hypertext  program  editor 
from  SpeedyWrite  Software,  can  sup¬ 
posedly  find  any  procedure,  variable, 
or  type,  or  anything  else,  anywhere  in 
your  program,  no  matter  what  language 
you  use.  HyperEdit  features  the  ability 
to  view  an  automatically  generated  list 
of  variable,  type,  and  procedure  names 
(to  search  for  parts  of  names  or  just 
scroll  through  the  list);  to  look  up  call¬ 
ing  sequences  for  C  and  Modula-2  li¬ 
brary  functions;  to  use  wildcards  in  any 
search  or  look-up  command;  and  to 
design  complex  searches  including  base 
conversion,  arithmetic,  and  looking  for 
characters  in  a  certain  range.  Hyper¬ 
Edit  also  allows  you  to  work  with  any 
number  of  files  or  languages  in  the 
same  project. 

A  smart  pair-matching  command 
matches  any  parenthesis,  bracket,  brace, 
or  language-specific  pair  such  as  begin 
and  end,  ignoring  parentheses  in  string 
constants  and  comments,  in  order  to 
check  program  balance.  Included  are 
such  programming  utilities  as  a  calcu¬ 
lator,  ASCII  table,  screen-attribute  ta¬ 
ble,  and  keycode  display.  Requires  an 
(continued  on  page  166) 
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(continued  from  page  161) 

IBM  PC  or  compatible  with  DOS  2.1 
or  later,  and  384K  of  RAM.  Hard  disk 
recommended,  lists  for  $69-95  fornonedu- 
cational  uses,  $49.95  for  educational 
(single  user).  Reader  service  no.  26. 
SpeedyWrite  Software 
1600  Grand  Ave.,  Box  1691 
St.  Paul,  MN  55105 
612-696-6732 

Three  hypertext-based  reference  tools 
are  available  from  Sageline.  Write*On 
is  a  comprehensive  reference  system 
that  provides  rules  and  tips  on  ques¬ 
tions  of  grammar,  usage,  and  punctua¬ 
tion.  Effective  examples  illustrate  the 
rules,  and  cross-references  are  provided 
when  necessary. 

GPOStyle  is  a  hypertexted  edition 
of  the  Government  Printing  Office 
(GPO)  Style  Manual.  While  we  here  at 
DDJ  prefer  The  Chicago  Manual  of  Style, 
GPOStyle  is  a  handy  reference  to  us¬ 
age.  It  is  not  as  comprehensive  as 
Write*On,  however. 

The  Shell  automatically  integrates  ex¬ 
isting  and  future  Sageline  reference  sys¬ 
tems,  so  that  they  are  all  accessible 
from  one  directory.  It  is  packaged  with 
the  Almanac,  a  handy  but  limited  refer¬ 
ence  .  Categories  include  computers  ( char¬ 
acter  tables,  numbers,  PC  extended  key 
codes,  and  more),  U.S.  history  (the  Dec¬ 
laration  of  Independence,  the  Constitu¬ 
tion  and  Amendments),  language  (the 
name  implies  a  wider  category  —  but 
one  fun  feature  is  the  “Quotes  for  Con¬ 
templation”),  math  (useful  formulas,  loga¬ 
rithmic  identifiers,  geometry  and  trigo¬ 
nometry  functions),  science  (physical 
constants,  statistics  on  the  Sun,  Moon, 
and  planets,  a  table  of  the  elements), 
and  geography  (mail  and  UPS  rates, 
state  capitals,  area  codes,  and  time 
zones).  Though  a  lot  of  work  obviously 
went  into  the  almanac,  a  more  compre¬ 
hensive  treatment  would  be  great. 

All  three  are  easy-to-use  and  well 
referenced.  The  only  drawback  is  that 
you  have  to  leave  whatever  application 
you’re  working  in  in  order  to  access 
these  tools.  The  Almanac  costs  $29, 
Write"'On  is  $49,  and  GPOStyle  is  $79- 
Reader  service  no.  27. 

Sageline 
P.O.  Box  2346 
Kingston,  NY  12401 
800-345-5571 

HyperTMON,  a  debugger  for  the  Hy¬ 
perTalk  programming  language,  is  avail¬ 
able  from  ICOM  Simulations.  The  com¬ 
pany  claims  this  is  the  first  tool  of  its 
kind  for  HyperTalk  programming.  It 
can  find  errors  within  HyperCard  scripts 
and  immediately  modify  them.  The  main 
purpose  of  HyperTMON  is  to  enable 
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users  to  study  scripts  step-by-step,  short¬ 
ening  development  time.  Access  to 
stacks  is  done  simply  by  cutting  and 
pasting  the  debug  button  from  the  Hy¬ 
perTMON  stack.  It  sells  for  $99-95. 
Reader  service  no.  24. 

ICOM  Simulations  Inc. 

648  S.  Wheeling  Rd. 

Wheeling,  IL  60090 
708-520-4440 

If  you’re  developing  CD-ROM  applica¬ 
tions  for  Apple  systems,  you  might  be 
interested  in  the  CD-ROM  Developer’s 
Lab  from  Software  Mart.  It  is  a  multi- 
media  production  reference  on  CD- 
ROM  —  a  searchable,  full-text  database 
that  contains  how-to  information  on  all 
aspects  of  production.  Includes  such 
topics  as  design,  programming,  data 
preparation,  transportability,  media  pro¬ 
duction,  premastering,  manufacturing, 
project  management,  encryption,  and 
data  assembly. 

Included  are  functional  applications 
that  were  created  with  Media-Mixer, 
another  Software  Mart  product,  which 
is  a  set  of  subroutine  libraries  for  proto¬ 
typing  and  creating  full-text  or  multi- 
media  CD-ROM  databases  and  retrieval 
software.  The  tools  for  these  libraries 
were  written  in  Turbo  Pascal  and  Mi¬ 
crosoft  C.  The  Developer’s  Lab  also 
includes  technical  specifications,  dem¬ 
onstrations  of  off-the-shelf  tools  for  me¬ 
dia  production,  and  industry  contacts 
for  the  fields  of  animation,  sound  pro¬ 
duction  and  editing,  and  high-resolu- 
tion  images.  Requires  a  Mac  with  1 
Mbyte  of  RAM,  a  CD-ROM  drive  with 
an  Apple-compatible  SCSI  interface,  Ap¬ 
ple  CD-ROM  driver  v.  2.0  or  later,  and 
a  printer.  Retails  for  $795  (Media-Mixer 
usage  licenses  start  at  $1,750).  Reader 
service  no.  29. 

Software  Mart  Inc. 

4131  Spicewood  Springs  Rd.,  Ste.  1-3 
Austin,  TX  78759-8606 
512-346-7887 

IBM  Linkway:  Hypermedia  for  the  PC, 
by  Harrington,  Fancher,  and  Black,  has 
been  published  by  John  Wiley  &  Sons. 
It  is  a  hands-on  guide  to  understanding 
Linkway,  IBM’s  version  of  HyperCard, 
and  is  suitable  for  both  beginners  and 
experienced  LinkWay  users.  It  covers 
various  components,  object-oriented  pro¬ 
gramming,  and  script  commands.  And 
it  features  a  multimedia  application  to 
guide  you  through  the  process  of  com¬ 
bining  media.  ISBN  0-471-51298-2, 
$22.95.  Reader  service  no.  30. 

John  Wiley  &  Sons 
605  Third  Ave. 

New  York,  NY  10158 
212-850-6000 

DDJ 

Dr.  Dobb's Journal,  June  1990 


LZW  R  E  VISIT  E  D 


Listing  One  (Listing  continued,  text  begins  on  page  126.) 

/*  This  is  the  main  compression  loop;  Notice  when  the  table  is  full  we  try 

*  to  increment  the  code  size.  Only  when  num_bits  ==  MAX_BITS  and  the  code 

*  value  table  is  full  do  we  start  to  monitor  the  compression  ratio. 

*/ 

while ( (character=getc (input) )  !=  (unsigned) EOF)  { 

if  ( ! (++bytes_in  I  1000))  {  /*  Count  input  bytes  and  pacifier  */ 

putchar (' . ' ) ; 

} 

index=find_match (string_code, character) ; 
if  (code_value [index]  !=  -1) 

string_code=code_value [index] ; 
else  { 

if  (next_code  <=  max_code  )  { 
code_value [index] =next_code++; 
pref ix_code [index] =string_code; 
append_character [ index] =character; 


output_code (output,  string_code) ; 
string_code=character; 
if  (next_code  >  max_code)  {  /* 

if  (  num_bits  <  MAX_BITS)  ( 
putchar ('+' )  ; 

max  code  =  MAXVAL(++num  bits) 


/*  Send  out  current  code 


/*  Is  table  Full?  */ 

/*  Any  more  bits?  */ 


/*  Increment  code  size  then 


putchar ('C' ) ; 

max_code  =  MAXVAL (num_bits) ; 
continue; 

} 

if  (++counter  ==  1000)  (  /*  Pacifier  */ 

counter=0; 
putchar (' . ' ) ; 

) 

if  (new_code  >=  next_code)  {  /*  Check  for  st. 

*decode_stack=character; 

string=decode_string(decode_stack+l, old_code) ; 

) 

else 

string=decode_string (decode_stack, new_code) ; 


/*  Check  for  string+char+string  */ 


character  =  ‘string;  /*  Output  decoded  string  in  reverse  */ 

while  (string  >=  decode_stack) 
putc (‘string — , output) ; 

if  (next_code  <=  max_code)  {  /*  Add  to  string  table  if  not  full  */ 

pref ix_code [next_code]=old_code; 
append_character [next_code++] =character; 
if  (next_code  ==  max_code  &&  num_bits  <  MAX_BITS)  { 
putchar ('+' )  ; 

max  code  =  MAXVAL (++num  bits); 


else  if  (bytes_in  >  checkpoint)  {  /*  At  checkpoint?  */ 

if  (num_bits  ==  MAX_BITS  >  max_code)  { 
ratio_new  =  bytes_out*100/bytes_in;  /*  New  compression  ratio  */ 
if  (ratio_new  >  ratio_old)  (  /*  Has  ratio  degraded?  */ 

output_code (output, CLEAR_TABLE) ;  /*  YES, flush  string  table  */ 
putchar ('C' ) ; 
num_bits=INIT_BITS; 

next_code=FIRST_CODE;  /*  Reset  to  FIRST_CODE  */ 

max_code  =  MAXVAL (num_bits) ;  /*  Re-Initialize  this  stuff  */ 
bytes_in  =  bytes_out  =  0; 

ratio_old=100;  /*  Reset  compression  ratio  */ 

for  (i=0;i<TABLE_SIZE;i++)  /*  Reset  code  value  array  */ 
code_value[i]=-l; 


else 

ratio  old  =  ratio  new; 


checkpoint  =  bytes_in  +  CHECKJTIME; 


/*  NO,  then  save  new  */ 
/*  compression  ratio  */ 


/*  Set  new  checkpoint  */ 


old_code=new_code ; 

) 

putchar (' \n' ) ; 

) 

/*  UNCHANGED  from  original 

*  Decode  a  string  from  the  string  table,  storing  it  in  a  buffer. 

*  The  buffer  can  then  be  output  in  reverse  order  by  the  expansion 

*  program. 

*/ 

char  *decode_string (unsigned  char  ‘buffer,  unsigned  int  code) 

{ 

int  i=0; 

while (code  >  255  )  ( 

*buffer++  =  append_character [code] ; 
code=prefix_code [code] ; 
if  (i++  >=  4000  )  { 

printf ("Error  during  code  expansion\n")  ; 
exit (1) ; 


/*  Output  the  last  code  */ 

/*  Handles  special  case  for  bit  */ 
/*  increment  on  EOF  */ 


/*  Output  the  end  of  buffer  code  */ 
/*  Flush  the  output  buffer  */ 


output_code (output, string_code) ; 
if  (next_code  ==  max_code)  ( 
++num_bits; 
putchar (' +' ) ; 

) 

output_COde (output, TERMINATOR) ; 
output_code (output, 0) ; 
output_code (output, 0) ; 
output_code (output, 0) ; 
putchar (' \n' ) ; 

) 

/*  UNCHANGED  from  original 
*  This  is  the  hashing  routine. 


find_match(int  hash_prefix,  unsigned  int  hash_character) 


int  index,  offset; 

index  =  (hash_character  «  HASHING_SHIFT  )  A  hash_prefix; 
if  (index  ==  0  ) 
offset=l; 
else 

offset  =  TABLE_SIZE  -  index; 
whiled)  ( 

if  (code_value [index]  ==  -1  ) 
return (index) ; 

if  (pref ix_code [index]  ==  hash_prefix  && 

append_character [index]  ==  hash_character) 

return (index) ; 
index  -=  offset; 
if  (index  <  0) 

index  +=  TABLE  SIZE; 


/*  MODIFIED  This  is  the  modified  expansion  routine.  It  must  now  check  for  the 
*  CLEAR_TABLE  code  and  know  when  to  increment  the  code  size. 

*/ 

expand (FILE  ‘input,  FILE  ‘output) 

{ 

unsigned  int  next_code=FIRST_CODE; 

unsigned  int  new_code; 

unsigned  int  old_code; 

int  character, 

counter=0, 

clear_f lag=l;  /*  Need  to  clear  the  code  value  array  */ 

unsigned  char  ‘string; 

char  *decode_string (unsigned  char  ‘buffer,  unsigned  int  code); 
printf ("ExpandingNn") ; 

while ( (new_code=input_code (input) )  !=  TERMINATOR)  { 

if  (clear_flag)  {  /*  Initialize  or  Re-Initialize  */ 

clear_flag=0; 

old_code=new_code;  /*  The  next  three  lines  have  been  moved  */ 
character=old_code;  /*  from  the  original  */ 
putc (old_code, output) ; 
continue; 


*buffer=code; 
return (buffer) ; 


/*  UNCHANGED  from  original 
*  Input  a  variable  length  code. 

*/ 

unsigned  input_code (FILE  ‘input) 

{ 

unsigned  int  return_value; 

static  int  input_bit_count=0; 

static  unsigned  long  input_bit_buffer=0L; 

while  (input_bit_count  <=  24  )  ( 

input_bit_buffer  !=  (unsigned  long)  getc(input)  «  (24  -  input_bit_count) ; 
input_bit_count  +=  8; 

) 

return_value=input_bit_buffer  »  (32-num_bits) ; 
input_bit_buffer  «=  num_bits; 
input_bit_count  -=  num_bits; 
return (return_value) ; 

) 

/*  MODIFIED  Output  a  variable  length  code. 

*/ 

output_code (FILE  ‘output,  unsigned  int  code) 

{ 

static  int  output_bit_count=0; 

static  unsigned  long  output_bit_buffer=0L; 

output_bit_buffer  1=  (unsigned  long)  code  «  (32  -  num_bits  - 

output_bit_count) ; 

output_bit_count  +=  num_bits; 
while  (output_bit_count  >=  8)  {  » 

putc(output_bit_buffer  »  24,  output); 
output_bit_buffer  «=  8; 
output_bit_count  -=  8; 

bytes_out++;  /*  ADDED  for  compression  monitoring  */ 

} 


End  Listing 


if  (new_code  ==  CLEAR_TABLE )  { 
clear_flag=l; 
num_bits=INIT_BITS; 
next_code=FIRST_CODE; 


/*  Clear  string  table  */ 
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Hyperterminology  from  Hell 

Hyperception  n  An  altered  state  of  consciousness  induced  by  reading  hypertext  and 
characterized  by  the  inability  to  focus  on  single,  distinct  ideas.  Cognitive  astigmatism 
Hyperemptory  adj  Exceptionally  abrupt,  as  a  direct  hypertext  link  to  a  random 
location  in  RAM 

Hyperennial  n  Any  topic  of  which  computer  journalists  annually  announce  that  this 
is  The  Year  ,  such  as  Unix,  networking,  OS/2,  AI,  multimedia,  desktop  fill-in-the-blank, 
or  hypertext 

Hyperenthetical  adj  Characterized  by  being  a  digression  within  a  digression  (within 
a  digression.  .  .)  The  variation  in  spelling  is  not  arbitrary.  The  Indo-European  root  from 
which  the  par  of  parenthetical  derives  is  spelled  with  an  e,  and  means  to  grant 
reciprocally,  with  the  idea  of  getting  something  back.  The  Indo-European  tradition 
that  one  ought  to  be  able  to  get  something  back,  or  just  to  get  back,  from  a  digression, 
perished  with  their  culture 
Hyperformance  n  Multidimensional  ineptitude 
Hyperfume  n  The  smell  of  hype 

Hypergonomics  n  An  academic’s  idea  of  a  catchy  term 
Hyperhaps  n  Goings-on  in  hyperspace 

Hyperimeter  n  A  multidimensional  boundary  separating  the  obvious  from  the  irrele¬ 
vant 

Hyperiodical  n  Any  nonlinear  serial  publication;  a  journal  that  appears  regularly  but 
not  regular 

Hyperipatetic  adj  Lost  in  hyperspace 

Hyperipheral  adj  Lying  beyond  the  hyperimeter,  as  opposed  to  ordinary  lying 
Hyperiscope  n  A  hypertext  navigational  aid  used  when  maps  and  browsers  fail;  in 
earlier  days  called  a  “core  dump.” 

Hypermanent  store  n  1.  The  locus  of  data  protected  from  accidental  deletion  by 
virtue  of  being  lost;  hypertext’s  contribution  to  the  architecture  of  write-only  memory. 
2.  A  bouffant  boutique 

Hypermute  v.t  To  rearrange  hypertext  links  randomly.  To  engage  in  data  annealing 

Hyperparallel  adj  Skew 
Hyperpendicular  adj  Skew 

Hyperpetrate  v.t  To  implement  a  hypertext  system 
Hyperpilosity  n  A  measure  of  the  hairiness  of  a  hypertext  system 
Hyperplex  n  A  movie  theater  of  the  1990s.  If,  as  has  been  suggested  by  no  less  eminent 
hypermedia  experts  than  Ted  Nelson  and  Paul  Heckel,  the  future  of  the  personal 
computer  can  be  read  on  the  silver  screen,  we  should  expect  the  workstation  of  1999 
to  run  more  expensive  software  with  less  content  and  more  flash,  and  to  display  it  on 
six  tiny  monitors 

Hypersian  n  Persian  poet  Omar  Khayyam,  who  wrote  one  of  the  oldest  known  non¬ 
linear  documents  (later  linearized  by  Edward  Fitzgerald  as  the  Rubaiyat)  and  left  this 
advice  to  readers  of  hypertext: 

Drink! for  you  know  not  whence  you  came,  nor  why; 

Drink!  for  you  know  not  why  you  go,  nor  where. 

Hyperu  n  The  Andes 

Hyperversion  number  n  A  complexity  measure  for  hypertext  documents 
Hypervert  interj  A  greeting  from  one  hypertext  system  designer  to  another 
Hypuree  n  Hypertext  with  the  links  removed 
Hypurgative  n  Garbage  collection  for  hypertext 

Hypurpose  n  A  noble  ambition  worthy  of  significant  financial  backing  but  incapable 
of  being  expressed  in  terms  that  mere  linearists  can  understand 
Hypursuant  adj  In  accordance  with  in  a  higher  dimension,  as  in,  “Hypursuant  to  your 
directive  that  the  staff  dress  more  formally  while  in  the  office,  I  am  taking  Friday 
afternoon  off  to  go  to  the  beach” 

These  hijinks  were  inspired  by  Stan  Kelly-Bootle’s  The  Devil's  DP  Dictionary,  McGraw- 
Hill,  1981. 


Michael  Swaine 
editor-at-large 
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SOURCE  CODE  AVAILABILITY 

All  source  code  is  available  on  a  disk  and 
online.  To  order  the  disk,  send  $14.95  (Calif, 
residents  add  sales  tax)  to  Dr.  Dobb 's Jour¬ 
nal,  501  Galveston  Dr.,  Redwood  City,  CA 
94063,  or  call  800-356-2002  (inside  Calif.) 
or  800-533-4372  (outside  Calif.).  Specify 
issue  number  and  disk  format.  Code  is  also 
available  through  the  DDJ  Forum  on 
CompuServe  (type  GO  DDJ). 


NEXT  ISSUE _ 

August  brings  our  annual  C  issue,  where 
we’ll  examine  a  variety  of  C  programming 
topics,  from  memory  allocation  and  debug¬ 
ging  to  linking  C  with  other  languages. 
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EDITORIAL 


The  Kent  Porter 
Scholarship  Fund 


There’s  always  been  something  special  about  DDJ  s  coverage  of  graphics  programming,  this 
month’s  theme.  As  far  back  as  July  1976  (our  first  year  of  publication),  DDJ  began  publishing 
articles  such  as  “A  Home  Brew  TV  Display  with  Graphics  for  the  Altair  8800.”  From  that  point 
on,  graphics  programming  became  a  regular  topic  in  DDJ,  leading  up  to  Kent  Porter’s  enormously 
popular  “Graphics  Programming”  column  in  1989.  Sadly,  Kent  passed  away  before  he  had  a  chance 
to  complete  the  job  he  set  out  to  do. 

In  Kent’s  memory,  we’ve  established  a  scholarship  program  for  full-time  computer  science  majors 
enrolled  in  accredited  colleges  and  universities.  The  purpose  of  the  scholarship  is  to  recognize 
academic  achievement  and  potential,  and  to  financially  assist  continuing  students  in  the  pursuit  of 
their  educational  goals.  At  the  request  of  Kent’s  family,  consideration  will  be  given  (but  not  limited) 
to  students  who  are  raising  children  while  attending  school,  a  situation  similar  to  that  of  Kent  and 
Jeanne  in  their  university  days.  Scholarships  will  be  awarded  in  increments  of  $500  for  the  1990  -  91 
academic  year. 

M&T  Publishing  will  provide  $1,000  a  year  to  fund  the  scholarship,  and,  for  this  year,  Markt  and 
Technik  (M&T’s  parent  company)  will  provide  another  $1,000.  Additionally,  we’re  accepting 
contributions  to  the  scholarship  fund  from  individuals  and  corporations.  Your  contributions  will 
be  appreciated  and  acknowledged  if  you  take  part  in  this  program. 

To  apply  for  a  scholarship,  request  in  writing  an  application  from: 


The  Kent  Porter  Scholarship 
Dr.  Dobb’s Journal 
501  Galveston  Drive 
Redwood  City,  CA  94063 


Software  being  what  it  is,  we  made  a  couple  of  last  minute  changes  to  June’s  hypertext  project. 
Because  of  the  size  of  the  self-extracting  file  (380K  on  the  bare-bones  version),  we’re  providing  the 
system  as  a  PKZIP  file;  the  resulting  compressed  file  is  about  275K.  Once  you  extract  either  file, 
running  the  system  is  the  same  —  just  type  DDJ. 

The  hypertext  document  included  with  the  June  source  code  listings  disk,  available  through  M&T 
Books,  is  also  compressed  with  PKZIP  so  that  the  issue  will  fit  on  a  single  360K  disk.  PKUNZIP, 
which  you’ll  need  to  extract  the  file,  is  included  on  the  disk. 

Remember  that  the  enhanced  version  —  the  one  that  includes  everything  —  is  available  online 
and  from  Scott  Johnson  at  NTERGAID  (and  it’s  a  really  big  file). 

Once  you’ve  had  a  chance  to  use  the  hypertext  edition,  let  us  know  what  you  think  about  it. 
What  would  you  have  liked  to  see  different  about  it?  How  have  you  been  using  it?  And,  most 
importantly,  what  sort  of  applications  will  you  be  developing  with  the  hypertext  engine  source 
code  (and  other  programs)  included  in  the  issue? 

Thanks  for  the  great  response  to  our  May  editorial  survey  card.  We’ve  received  thousands  of  cards 
so  far  and  more  arrive  every  day.  If  you  haven’t  returned  your  card,  it  isn’t  too  late,  so  keep  those 
cards  and  letters  coming  —  and  we  really  are  reading  every  one  of  them. 


Finally,  the  folks  at  Springtree  Partners  have  compiled  a  DD/subject  and  author  index  that  spans 
the  years  1982-1989.  It’s  available  on  disk  and  in  paperback.  Call  804-286-3466,  Ext.  3,  or  write 
Springtree  Partners,  Rt.2  Box  89,  Scottsville,  VA  24590-9512.  They’ve  done  a  great  job  of  documenting 
the  last  seven  years  of  DDJ. 


Jonathan  Erickson 
editor-in-chief 
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Alive  and  Apparently 
Well  in  Louisville 

Dear  DDJ 

In  his  April  1990  “Structured  Program¬ 
ming”  column,  Jeff  Duntemann  asked 
readers  to  drop  him  a  postcard  if  they 
saw  his  book  Assembly  Language  From 
Square  One.  Elvis  was  sighted  browsing 
through  a  copy  of  Assembly  Language 
From  Square  One  in  Hawley-Cooke 
Booksellers  of  Louisville,  Kentucky. 
David  Rush 
Louisville,  Kentucky 

A  Plus  for  Patents 

Dear  DDJ , 

I  work  in  the  research  division  of  a 
major  pharmaceutical  company  where 
I  and  my  colleagues  strive  to  invent  new 
drugs.  The  research  and  development 
process  for  new  pharmaceuticals  typi¬ 
cally  requires  seven  years  and  averages 
$125  million.  As  such,  patents  are  a  nec¬ 
essary  early  part  of  the  commercializa¬ 
tion  process.  Without  the  exclusivity  a 
patent  grants,  commercialization  would 
be  a  far  riskier  venture. 

My  experience  with  patents  is  as  an 
inventor.  Although  I  am  no  legal  ex¬ 
pert,  I  do  have  a  working  knowledge 
of  the  patenting  process.  I  also  have  a 
perspective  on  the  patent  issue  brought 
on  both  by  my  vocation  and  by  an 
involvement  with  software  develop¬ 
ment.  I  would  like  to  clarify  some  issues 
raised  in  your  March  1990  editorial. 

The  enormous  hue  and  cry  gener¬ 
ated  by  the  issue  of  software  patents 
has  left  me  puzzled  as  to  the  reasons 
behind  the  concerns.  I  believe  this  rea¬ 
son  is  a  fear  that  the  access  to  ideas  will 
be  prevented  in  an  unfair  manner,  the 
result  of  which  is  stifled  innovation. 
Actually,  the  real  cause  is  a  fundamental 
misunderstanding  of  the  purpose  of  pat¬ 
ents  and  how  they  should  fit  into  soft¬ 
ware  development.  A  component  of 
the  problem  is  the  apparent  sudden- 
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ness  at  which  patents  are  issued.  The 
solution  to  the  problem  will  be  to  ex¬ 
pose  the  details  of  software  patents 
and  educate  the  professional  program¬ 
ming  community  accordingly.  They  will 
have  to  understand  that  the  long  delay 
between  filing  and  issuance  is  part  of 
the  patent  process  and  builds  in  risk 
for  those  who  use  patentable  ideas  with¬ 
out  having  patent  protection.  Program¬ 
mers  may  not  like  software  patents, 
but  they  should  also  know  that  soft¬ 
ware  patents  will  not  go  away. 

Algorithms,  as  such,  are  not  patent- 
able.  Algorithms  that  have  an  applica¬ 
tion  can  be  considered  inventions  and 
are  patentable.  In  short,  any  idea  which 
can  be  shown  to  be  novel  and  useful 
can  be  patented.  An  issued  patent  gives 
the  inventor  a  period  of  exclusive  con¬ 
trol  over  the  invention,  which,  as  mem¬ 
ory  serves,  is  17  years,  in  exchange  for 
full  disclosure  of  the  details  of  the  in¬ 
vention.  After  the  exclusivity  period  is 
over,  the  inventor  has  no  control  and 
anyone  is  free  to  use  the  invention.  A 
valid  application  is  an  improvement 
over  existing  inventions,  referred  to  as 
“prior  art.”  As  such,  the  first  electronic 
spreadsheet  may  have  been  patentable 
as  an  invention  (although  it  is  “obvi¬ 
ous”)  because  of  the  improved  perfor¬ 
mance.  General  patents  that  cover  spe¬ 
cific  patents  are  considered  to  “roof’  the 
specific  patents  and  restrict  the  use  of 
the  application  by  the  inventor.  An  ex¬ 
ample  of  roofing  would  be  a  general 
patent  on  the  basic  concepts  of  a  spread¬ 
sheet  —  it  would  restrict  the  applica¬ 
tion  of  a  patent  for  automatic  recalcula¬ 
tion  of  spreadsheet  cells.  Finally,  pat¬ 
ents  make  general  and  specific  claims  as 
to  what  constitutes  the  invention,  the 
so-called  scope  of  the  invention.  For  a 
software  patent,  any  new  idea  not  pre¬ 
viously  claimed  for  a  patent  is  in  itself 
patentable.  If  the  LZW  data  compres¬ 
sion  algorithm  was  claimed  to  be  only 
useful  for  telecommunications,  the  same 
algorithm  could  be  patented  for,  say, 
archival  database  data  compression  and 
Unisys  could  do  nothing  about  it. 

As  for  litigation,  the  patent  law  is 
stacked  entirely  on  the  side  of  the  in¬ 
ventor.  There  is  nothing  necessary  about 
needing  to  outwait  those  with  less  re¬ 
source:  if  the  infringement  is  clear  (an 
important  point),  the  infringer  loses. 
The  problem  here  is  not  so  much  will¬ 
ful  infringement,  which  is  really  intel¬ 
lectual  property  theft,  but  confusion 
caused  by  the  delay  in  patent  issuance. 
Programmers  are  quick  to  adopt  good 
ideas,  some  of  which  constitute  patent- 
able  inventions,  with  the  result  that 
several  products  may  emerge  into  the 
marketplace  before  the  patent  is  issued 
to  one  company  —  and  the  others  lose. 


This  gives  the  impression  of  restricting 
the  market  and  can  be  dissatisfying  to 
consumers.  One  company,  whose  name 
has  escaped  me,  has  even  gone  as  far 
as  sending  letters  to  the  owners  of  a 
competing  product  to  inform  them  that 
it  was  about  to  be  rewarded  with  the 
patent  covering  the  product,  and  all 
those  who  had  the  other  products  would 
be  liable  for  damages.  Now  that  is  dis¬ 
gusting  and  should  be  discouraged.  The 
solution  to  this  is  for  companies  and 
programmers  to  be  more  patent  aware. 
This  could  be  accomplished  if  those 
filing  for  patents  publicly  state  their 
intent,  thus  forewarning  others.  Could 
it  happen?  Probably  not,  because  law¬ 
yers  control  the  dissemination  of  prod¬ 
uct  development  information,  the  na¬ 
ture  of  which  is  typically  confidential. 

Does  patenting  stifle  innovation?  No, 
not  at  all.  Only  those  working  on  com¬ 
parable  projects  are  affected  and,  natu¬ 
rally,  the  use  of  the  algorithm  for  the 
claimed  applications  is  protected  in  all 
its  forms.  This  is  far  better  protection 
than  one  can  get  by  copyrighting  code, 
which  only  protects  the  expression  of 
the  algorithm,  not  the  actual  algorithm. 
Therefore,  if  someone  invents  a  novel 
algorithm,  one  with  commercial  poten¬ 
tial,  patent  protection  is  the  proper 
course.  The  use  of  patented  inventions 
is  usually  regulated  by  lawyers  in  the 
form  of  licensing  and  royalty  arrange¬ 
ments.  If  a  patented  algorithm  is  essen¬ 
tial  to  the  success  of  another  software 
project,  the  appropriate  legal  arrange¬ 
ments  can  usually  be  made  to  use  the 
invention  and  still  make  money. 

Does  the  exclusivity  time  of  17  years 
stifle  innovation?  No.  Patents  are  sub¬ 
ject  to  technology  changes,  just  as  ev¬ 
erything  is.  If  the  Basic  interpreter  that 
was  DDJ’s  charter  project  15  years  ago 
had  critical  elements  patented,  the  ex¬ 
clusivity  would  still  have  two  years  to 
go.  Just  looking  in  the  pages  of  DDJ 
over  the  last  seven  years,  one  wouldn’t 
know  Basic  existed.  The  facts  are  that 
times  change  and  patents  can  become 
obsolete.  However,  if  some  lucky  in¬ 
ventor  hit  the  right  idea,  one  that  con¬ 
sumers  wished  to  consume,  he  would 
have  the  luxury  of  no  competition,  could 
enjoy  the  fruits  of  his  labors,  and  per¬ 
haps  even  improve  the  invention.  Does 
that  mean  he  can  charge  whatever  he 
wants  and  the  consumers  must  pay? 
No.  Patent  rights  do  not  translate  to 
automatic  sales.  The  natural  forces  of 
the  marketplace  are  always  at  work.  If 
an  inventor  asks  too  high  a  price,  he 
quickly  finds  that  most  consumers  can 
live  without  his  invention.  The  result  is 
that  patents  do  not  free  the  inventor 
from  normal  marketing  considerations, 

( continued  on  page  12) 
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(continued  from  page  8) 

but  do  remove  the  competition  for  a 

time. 

An  issue  that  will  affect  software  pat¬ 
ents,  both  in  review  time  and  quality, 
is  an  apparent  lack  of  patent  examiners 
with  expertise  in  the  area  of  software 
patents.  With  few  examiners,  the  re¬ 
view  time  increases  from  two  years  to 
many  years.  If  their  expertise  isn’t  fully 
up  to  snuff,  poor  quality  patents  can 
slip  through.  Poor  quality  can  mean 
many  things,  ranging  from  the  actual 
invention  to  the  scope  of  the  inven¬ 
tion,  which  would  cover  more  general 
applications  of  the  invention. 

Personally,  I  would  like  to  see  those 
who  are  complaining  loudly  go  off  and 
invent  something  new.  The  world  needs 
perhaps  one  less  spreadsheet  program 
or  database  and  perhaps  more  radical, 
innovative,  and  new  programs.  But  we 
will  never  know  what  those  new  pro¬ 
grams  are  until  someone  invents  the 
fundamental  algorithms  to  power  them. 
I  would  also  like  those  who  do  manage 
to  patent  new  software  inventions  to 
do  the  next  step,  which  is  to  bring  that 
invention  to  consumers  in  the  form  of 
running  programs.  That  is  the  intent  of 
the  patent  law  (which  is  as  old  as  this 
country)  —  to  encourage  inventors  to 
invent  and  bring  those  inventions  to 
market.  It  was  good  then,  it  is  just  as 
good  now. 

My  bottom  line  is  that  programmers 
should  consider  an  issued  software  pat¬ 
ent  an  opportunity  to  work  another 
area,  and  be  inventive  in  their  own 
right.  Patents  should  provide  protec¬ 
tion  for  the  inventor,  and  patented  in¬ 
ventions  should  be  brought  to  market. 
And  some  form  of  information  exchange 
needs  to  be  developed  so  that  those 
applying  and  receiving  patents  can  let 
their  intentions  be  known. 

Barr  Bauer 

Bloomfield,  New  Jersey 

Here  We  Go  Again 

Dear  DDf 

In  your  assembly  language  issue  (March, 
1990)  you  do  your  readership  a  dis¬ 
service.  You  allow  Michael  Abrash  to 
propagate  the  myth  that  code  produced 
by  compilers  cannot  match  code  pro¬ 
duced  by  good  assembler  language  pro¬ 
grammers.  The  truth  is  the  compilers 
used  in  his  comparison  are  not  worthy 
of  being  called  “optimizing.” 

Consider  his  example  of  CopyUp- 
percase.  A  C  programmer  might  write 
the  body  as  that  in  Example  1 . 1  would 
expect  any  compiler  to  construct  the 
intermediate  form  in  Figure  1.  I  would 
then  expect  an  optimizing  compiler  to 
identify  common  subexpressions  and 
perform  dataflow  analysis  resulting  in 


that  in  Figure  2.  During  memory  alloca¬ 
tion  I  would  expect  an  optimizing  com¬ 
piler  to  recognize  that  the  idioms  in 
Figure  3  can  be  implemented  using 
string  instructions  if  the  DS,SI  and  EI,DI 
registers  are  associated  with  the  appro¬ 
priate  subexpressions.  Without  such  rec¬ 
ognition,  string  instructions  will  never 
be  generated.  Recognition  of  these  idi¬ 
oms  leads  to  the  allocation  for  subex- 


Example  2 


Figure  1 


Figure  2 


pressions  to  machine  locations  as  in 
Example  2,  which  leads  to  the  code 
shown  in  Example  3.  Since  these  ideas 
(continued  on  page  14) 


do  { 

x  =  *a++; 

x  +=  ( ('a'<=x) && (x<=' z' ) ) ? 
*b++  =  x; 

}  while  (x) ; 

CA'-'a') 

:  0; 

Example  1 


subexpression  name 

register  name 

register  contents 

@a, offset 

DS,  SI 

address  for  source  byte 

@b, offset 

EI,DI 

address  for  destination  byte 

x,  x+0,  x+32 

AL 

source/destination  byte  value 
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(continued  from  page  12.) 
are  at  least  10-15  years  old,  any  opti¬ 
mizing  compiler  should  incorporate 
them.  Michael  Abrash  made  a  mistake 
in  regarding  the  Microsoft  and/or 
Borland  compilers  to  be  optimizing  com¬ 
pilers.  By  the  way,  I  am  The  OPG  Co., 
a  firm  that  performs  research  into  com¬ 
piler  writing  tools. 

George  H.  Roberts 

Broken  Arrow,  Oklahoma 

Michael  responds:  And  so  once  again 
we  come  to  the  difference  between  “what 
is”  and  “what  should  be.  ” Mr.  Roberts’ 
letter  reminds  me  of  the  debate  between 
the  RISC  and  CISC  people;  the  RISC 
people  keep  saying  that  RISC  has  the 
potential  to  be  two,  four,  even  ten  times 


faster  than  CISC,  and  the  CISC  people 
keep  sighed  and  pointing  out  that  to¬ 
day’s  CISC  software,  running  on  to¬ 
day's  CISC  computers,  is  just  about  as 
fast  per  dollar  cost —  and  there’s  a  heck 
of  a  lot  more  of  it  available.  In  the 
high-level  versus  assembly  language 
arena,  it's  much  the  same.  I  remember 
a  lively  debate  three  or  four  years  ago 
about  the  relatively  low  quality  of  code 
generated  from  C  source,  with  the  C 
proponents  insisting  that  the  critics  were 
mistaking  poor  compiler  implementa¬ 
tions  for  a  poorly  optimizable  language. 
“Just  wait  until  real  optimizing  C  com¬ 
pilers  arrive!”  they  protested. 

Well,  here  we  are,  years  later,  and 
95  percent  of  the  world  uses  two  com¬ 
pilers  that  Mr.  Roberts  claims  aren’t 


optimized  prologue 

les 

si,  [bp+a  pointer] 

les 

di,  [bp+b  pointer] 

Convert_and_Copy  Loop: 
lodsb 

cmp 

al,  'a' 

jb 

Save  Upper 

cmp 

al,  'z' 

ja 

Save  Upper 

add 

Save  Upper: 
stosb 

al,  'A'-'a' 

and 

al,  al 

jnz 

Convert  and  Copy  Loop 

optimized  epilogue 

Example  3 


optimizing  compilers  at  all.  I  note  that 
Mr.  Roberts  doesn’t  actually  name  a 
compiler  that  generates  the  code  he 
lists;  even  if  there  is  such  a  compiler,  I 
suggest  that  since  almost  no  one  is  us¬ 
ing  that  compiler,  whatever  it  is,  it’s  a 
moot  point.  Mr.  Roberts  may  be  entirely 
correct  in  that  a  good  optimizing  com¬ 
piler  will  generate  the  code  he  lists ;  I 
suggest  that  today,  given  currently  used 
PC  tools,  that's  pretty  much  irrelevant. 
There’s  another  point  to  be  addressed 
here.  After  claiming  that  I  ‘propagate 
the  myth  that  code  produced  by  com¬ 
pilers  cannot  match  code  produced  by 
good  assembler  [sic]  language  program¬ 
mers,  ”  Mr.  Roberts  follows  with  the  non- 
sequitur  that  the  compilers  I  used  aren ’t 
worthy  of  being  called  optimizing  com¬ 
pilers,  as  if  the  latter  is  evidence  for  the 
former.  Even  if  Turbo  C  and  Microsoft 
C  aren’t  optimizing  compilers,  that 
doesn’t  mean  that  “worthy”  compilers 
can  generate  code  as  good  as  assembly 
language  programmers  can.  Consider 
Mr.  Roberts’s  own  example:  His  hypo¬ 
thetical  “ optimized ”  code  is  indeed 
much  better  than  the  code  Microsoft  C 
produced —  but  it’s  a  good  50 percent 
slower  than  the  hand-optimized  code 
in  my  article!  Anyone  who  believes  that 
a  compiler  can  match  top-notch  as¬ 
sembly  language for  small,  well-defined 
tasks  is  kidding  themselves.  (There  just 
isn’t  enough  information  bandwidth 
from  the  programmer  to  the  compiler 
in  a  high-level  language  for  this  not  to 
be  true.)  Assembly  language  isn ’t  ap¬ 
propriate  for  most  tasks,  but  when  you 
need  maximum  performance,  it  is  the 
only  choice. 

Errata 

Please  note  the  following  changes  to 
the  source  code  listing  on  page  86  in 
last  month’s  “Building  a  Hypertext  Sys¬ 
tem”  by  Rick  Gessner  ( DDJ ,  June  1990). 

44:  ((  'V,'LVJV-V_V|',<|<), 

45:  (  'r',' V,V»'j,.'=V=Vj  V|')); 

112:  If  Line  [  j] <>Null  then 

113:  Inc (i)  else  Inc (j, 2) ; 

114:  Inc.  (j); 

115:  ’  end; 

116:  Determine_Actual_Line_Pos :=J; 

117:  end;  (Determine  actual  line  pos) 

140:  If  Ord (Line [LinePos] ) >127  then 

141 :  Begin 

On  page  167  of  the  same  issue, 
change  the  line  of  source  code  accom¬ 
panying  “LZW  Revisited”  by  Shawn  Re¬ 
gan  from: 

if  (  num_bits  ==  MAX_BITS  >  max_code  )  { 

to 

if  (  num_bits  ==  MAX  BITS  )  { 

DDJ  apologizes  for  the  confusion. 


DDJ 
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Coping  with  a  myriad  of  options 


Christopher  A.  Howard 


Once  upon  a  time  users  were  presented  a  short  and 
simple  list  of  display  adapter  choices  —  color  or 
monochrome.  Although,  from  a  programmer’s  per¬ 
spective  those  days  are  still  enticing  —  a  myriad 
of  standards  has  developed  since  then.  The  reso¬ 
lutions  of  the  Hercules,  CGA,  EGA,  and  VGA  adapters  have 
all  provided  a  common  ground  for  users  and  developers 
alike.  The  next  step  (as  defined  by  IBM)  is  the  8514/A,  but 
it  has  been  slow  in  its  adoption.  There  is  also  Texas  Instru¬ 
ments  TIGA  (pronounced  TIE-GA),  an  interface  for  its  34010 
and  34020  chips,  but  it,  too,  is  in  the  first  stages  of  support. 
Meanwhile,  a  number  of  video  board  manufacturers  have 
released  adapters  with  capabilities  beyond  the  IBM  VGA 
standard  resolution  of  320  x  200  x  256.  These  extended 
resolutions  are  collectively  known  as  Super  VGA. 

In  the  simpler  days  of  CGA  and  Hercules,  the  graphics 
screen  was  directly  memory  mapped.  All  a  programmer  had 
to  do  was  point  at  it  and  write  it.  Aside  from  the  minor 
headache  of  interleave  addressing,  graphics  programming 
was  relatively  easy.  To  save  the  screen,  just  save  that  block 
of  memory  with  a  function  such  as  BSAVE,  and  load  it  with 
BLOAD.  Later  came  the  EGA  with  its  planar  memory  and 
hosts  of  registers,  and  things  suddenly  got  more  compli¬ 
cated  and  easier  at  the  same  time.  Although  functions  such 
as  BSAVE  would  no  longer  work,  features  like  masking  and 
logical  operations  became  easier.  The  VGA  followed  this 
theme  with  higher  resolutions  and  more  colors,  and  finally 
we  have  Super  VGA. 

This  article  provides  the  ability  to  program  the  Super  VGA 
modes  for  some  of  the  major  chipsets.  A  method  of  detect¬ 
ing  each  of  the  chipsets  is  presented,  along  with  functions 


Chris  is  president  of  Genus  Microprogramming,  which  pro¬ 
vides  a  number  of  tools  that  support  Super  VGA  (including 
the  PCX  Programmer’s  Toolkit,  PCX  Effects,  and  PCX  Text). 
He  can  be  reached  at  Genus  Microprogramming,  11315 
Meadow  Lake,  Houston,  TX  77077,  or  on  CompuServe: 
75100,17. 


for  addressing  video  memory  and  displaying  a  pixel  at  any 
location.  Because  any  graphics  function  reduces  down  to 
plotting  a  pixel  somewhere  on  the  display,  it  is  possible  to 
extrapolate  these  functions  to  any  other  graphics  operation, 
from  the  simple  to  the  complex. 

The  Chipsets 

Currently,  there  are  many  chipsets  on  the  market  that  pro¬ 
vide  Super  VGA  capabilities.  In  order  to  provide  an  ade¬ 
quate  sample,  I’ll  cover  three  of  the  major  chipsets  —  Tseng 
Labs,  Paradise,  and  Video  Seven.  Although  board  vendors 
may  use  the  same  chipset,  it  is  still  up  to  the  vendor  which 
features  are  incorporated  into  a  particular  adapter  (see  Ta¬ 
ble  1).  SuperVGA  offers  the  advantages  of  higher  resolution 
and  color  capabilities,  with  the  disadvantage  of  no  existing 
standard.  In  fact,  each  chipset  must  be  programmed  sepa¬ 
rately  even  though  you  may  wish  to  support  only  one  mode, 
such  as  640  x  480  x  256.  Even  something  as  basic  as  mode 
numbers  can  vary  wildly  between  board  manufacturers. 

Identification 

Some  manufacturers  have  made  it  easy  to  identify  their 
chips.  One  of  the  easiest  is  Video  Seven.  Basically,  they 
have  provided  an  extended  BIOS  function  call  that  returns 
valid  information  when  the  chipset  is  present,  and  garbage 
otherwise.  This  provides  a  consistent  and  reliable  interface. 

The  other  vendors,  however,  provide  no  method  of  iden¬ 
tifying  their  chips.  In  these  cases,  a  crude  but  effective  BFAI 
(brute  force  and  ignorance)  approach  can  be  used.  All 
vendors  include  a  copyright  notice  at  the  beginning  of  the 
video  BIOS.  You  can  search  this  area  for  strings  —  such  as 
“Tseng”  or  “PARADISE”  —  in  order  to  identify  the  chip. 
This  method  has  worked  rather  well,  but  I  would  like  to 
take  this  opportunity  to  suggest  that  these  vendors  provide 
a  solution  similar  to  Video  Seven’s. 

This  method  is  not  a  new  one.  Many  software  vendors 
used  a  similar  technique  in  order  to  identify  an  IBM  adapter, 
and  they  keyed  in  the  letters  “IBM”  in  the  copyright  string. 
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This,  of  course,  caused  problems  for  clone  vendors.  How 
could  they  remain  compatible  with  those  software  pack¬ 
ages,  and  still  use  the  letters  IBM  without  copyright  con¬ 
flicts?  Orchid  Technology’s  solution  is  shown  in  Figure  1, 
but  for  fun  you  can  use  DEBUG  to  display  your  video 
board’s  BIOS  by  running  DEBUG  and  using  the  command  D 
C000.  0, 100  to  dump  the  first  256  bytes  of  your  VGA’s  ROM 
BIOS. 

Initially,  a  function  should  be  called  that  identifies  the 
standard  adapters  (such  as  HGC,  CGA,  EGA,  or  VGA),  but 
that  would  cover  another  article.  An  excellent  reference  is 
Richard  Wilton’s  book,  Programmer’s  Guide  to  PC  and  PS/2 
Video  Systems  (Microsoft  Press).  Once  a  VGA  adapter  has 
been  identified,  the  svQueryChipset  function  can  be  called 
to  identify  whether  the  VGA  has  a  chipset  that  supports 
Super  VGA  resolutions.  It  tests  for  boards  that  have  a  BIOS 
function  call  first,  and  continues  with  ROM  BIOS  searches 
if  that  fails.  In  the  event  no  match  is  found,  it  returns  an  error 
code.  At  that  point  your  program  must  query  the  user,  or 
assume  that  no  supported  Super  VGA  adapter  exists. 


Initializing  the  Mode 

Initializing  the  Super  VGA  graphics  mode  is  no  different 
from  setting  any  standard  graphics  mode.  Each  adapter  has 
extended  the  ROM  BIOS  interrupt  10H  function  so  that  the 
Super  VGA  modes  are  included.  However,  each  board  ven¬ 
dor  has  assigned  its  own  mode  numbers  to  those  extended 
modes  —  which  is  one  reason  why  they  are  harder  to  sup¬ 
port.  Because  there  is  no  standard  mode  number,  a  table  of 
modes  must  be  maintained  for  all  supported  chipsets. 

The  example  code  uses  a  two-step  process  for  managing 
display  modes,  based  on  the  method  Genus  Micropro¬ 
gramming  uses  for  our  graphics  products.  First,  the  display 
type  is  set  with  the  function  svSetDisplay,  which  selects  the 
chipset  and  the  mode.  A  defined  constant  is  used  so  that 
other  display  types  and  modes  can  be  easily  added,  thereby 
hiding  the  internal  workings  of  the  library.  Note  that  this 
function  does  not  actually  set  the  mode  —  it  only  performs 
initialization  internal  to  the  Super  VGA  library  and  does  not 
affect  the  calling  program’s  environment.  The  mode  change 
is  performed  in  the  svSetMode  function,  which  takes  as  its 
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arguments  either  the  svTEXT  or  svGRAPHICS  constants. 
Listing  One,  page  82,  and  Listing  Two,  page  84,  contain  the 
defines  macros  for  Super  VGA  graphics  manipulation.  Both 
are  implemented  in  Microsoft  ASM,  Version  5.x.  The  file  in 
Listing  Three,  page  84,  contains  procedures  for  identifying 
various  SuperVGA  adapters  and  uses  the  procedures  svQue- 
ryChipset.  Listing  Four,  page  85,  contains  the  internal  rou¬ 
tine  procedures  for  calculating  a  pixel’s  address  for  any 

Initializing  the  Super  VGA  graphics 
mode  is  no  different  from  setting  any 
standard  graphics  mode.  Each  adapter 
has  extended  the  ROM  BIOS  interrupt 
10H  function  so  that  the  Super  VGA 
modes  are  included 


given  display  mode  using  the  procedures  svPixelAddr2D , 
svPixelAddr30,  and  svPixelAddr5F.  Listing  Five,  page  86, 
contains  procedures  for  putting  (displaying)  a  pixel  for  any 
given  display  mode  or  virtual  buffer  using  the  procedure 
svPutPixel.  Listing  Six,  page  90,  lists  the  function  declara¬ 
tions  for  the  Super  VGA  library  for  C,  while  Listing  Seven, 
page  90,  is  a  Microsoft  C  5.1  test  program  for  testing  the 
Super  VGA  QueryChipset  and  PutPixel  functions.  (Compile 
with  CL  /c  /AS  svTest.C  and  link  svTest , , ,  svLib-).  Listings 
Eight  (page  91)  and  Nine  (page  92)  are  the  make  files  for 
making  the  Super  VGA  Library  and  the  Super  VGA  test 
program.  For  more  detail  on  Super  VGA  used,  Table  2  lists 
the  ports,  indexes,  and  functions.  Figure  3  illustrates  the  bits 
required  for  Bank  selection. 

There  are  several  reasons  for  splitting  up  the  initialization 
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Table  1:  Video  adapters  and  supported  modes 
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Figure  1:  Orchid  ProDesigner  VGA  ROM-BIOS  dump 


and  mode  change  functions.  First,  it  allows  the  library  to 
coexist  with  other  graphics  libraries,  each  of  which  requires 
an  initialization  routine  of  its  own  —  and  its  routine  needs 
to  set  the  mode.  In  that  case,  a  call  to  svSetDispiay  and  then 
its  init  would  set  the  mode  and  make  both  libraries  usable. 
Second,  most  initialization  is  required  only  once,  not  every 
time  the  mode  is  set.  By  calling  svSetDispiay  once,  later  calls 
to  svSetMode  can  be  made  to  switch  back  and  forth  between 
graphics  and  text  modes.  Lastly,  the  program  is  easier  to 
maintain  because  the  initialization  function  is  performed 
once  at  the  top  of  the  program,  not  every  time  the  mode  is 
changed. 

What  you  may  notice  is  that  the  mode  numbers  in  the 
table  for  the  Video  Seven  chipset  do  not  match  the  pub¬ 
lished  mode  constants.  Technically,  the  correct  modes  are 
the  66H,  67H,  and  ©//numbers,  and  Video  Seven  recom¬ 
mends  that  the  mode  be  set  through  a  modified  BIOS 
SetMode  function.  We  found  that  every  time  the  mode  was 
set  to  66H,  a  BIOS  GetMode  function  call  would  always 
return  1AH.  This  caused  problems  because  the  svSetMode 
function  always  reads  back  the  mode  to  ensure  it  was 
successfully  set  —  and  it  would  always  appear  that  it  did 
not.  To  get  around  this  problem  and  provide  a  standard  way 
of  setting  and  getting  the  mode,  all  of  our  libraries  just  go 
ahead  and  set  the  mode  to  1AH  (or  1BH  or  1DH),  and 
everything  works  fine.  If  you  wish  to  set  the  mode  for  the 
Video  Seven  in  the  recommended  way,  use  the  @V7Mode 
macro  provided. 

Extended  16-Color 

There  is  one  Super  VGA  mode  that  remains  fairly  constant 
across  all  boards,  the  800  x  600  x  16  color  mode.  It  is 
basically  an  extension  of  the  640  x  350  x  1 6  color  EGA  and 
640  x  480  x  16  color  VGA  modes.  It  is  programmed  in 
exactly  the  same  way,  with  the  major  changes  being  the 
mode  number  and  pixel  addressing.  Because  EGA  pro¬ 
gramming  has  been  well  covered  for  several  years  now,  we 
will  not  go  into  it  here.  To  summarize,  it  is  still  planar,  with 
each  of  the  four  planes  fitting  into  one  segment  (64K  bytes), 

(continued  on  page  22.) 


Figure  2:  Super  VGA  256-color  memory  layout  for  640  x 
480  x  256  mode 
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(continued  from  page  18) 

for  a  total  memory  requirement  of  just  under  256K  bytes. 
To  address  a  single  pixel,  use  the  formula  b  =  ( (y*800)+  x  )/ 
8,  then  mask  out  the  pixel  in  that  byte.  The  bit  you  want  to 
affect  is  x  mod  8.  All  logical  operations  and  bit  masking  are 
performed  as  any  normal  EGA  or  VGA  16-color  mode. 

Extended  256-Color 

The  Super  VGA  256-color  modes  are  an  entirely  new  format. 
The  memory  layout  is  different  from  any  previous  video 
mode.  It  is  not  interleaved  such  as  the  CGA  or  Hercules 
adapters,  nor  is  it  planar  such  as  the  EGA  and  VGA  16-color 
modes.  It  is  closest  to  the  320  x  200  x  256  VGA  13H  mode, 
complicated  by  the  fact  that  the  memory  crosses  64K-byte 
segment  boundaries. 

Like  the  EGA  and  VGA,  the  Super  VGA  video  memory  is 
accessed  through  a  64K-byte  area  located  at  A0000  hex.  To 


get  around  the  memory  requirements  of  the  Super  VGA 
modes  (a  mode  like  640  x  480  x  256  requires  over  300K  of 
video  RAM),  all  chipsets  use  a  sliding  window  scheme.  For 
the  Tseng  and  Video  Seven  chipsets,  this  window  can  be 
thought  of  as  a  64K  bank  of  memory  that  can  be  located  at 
any  64K  boundary.  Do  not  think  of  it  as  a  purely  rectangular 
window  —  the  64K  window  can  start  and  stop  anywhere 
within  video  memory  (see  Figure  2).  This  also  means  that 
the  window  starts  and  stops  in  the  middle  of  a  scanline, 
limiting  some  optimizations  (such  as  checking  for  a  bank 
change  at  the  end  of  a  scanline  instead  of  any  pixel).  For  the 
Tseng  chipset,  bank  selection  is  all  handled  within  a  single 
byte.  However,  the  Video  Seven  chipset  gets  the  award  for 
the  most  complicated  bank  switch.  It  involves  setting  three 
different  bits  in  three  different  registers.  The  bank  selection 
code  for  the  example  library  is  performed  through  macros, 

(continued  on  page  26) 


Port 

Index 

Function 

Description 

EGAgraph 

(3CEH) 

parPROA 

parPR5 

(09H) 

(0FH) 

(bank) 

parLOCK 

parUNLOCK 

(OH) 

(5H) 

EGA/VGA/SVGA  graphics  controller 

Paradise  PROA  reg  used  for  bank  sel 

Paradise  PR5  reg  used  for  locking  and  unlocking 

EGAseq 

(3C4H) 

v7pagesel 

v7banksel 

v7SR6 

(F9H) 

(F6H) 

(06H) 

v7enabte 

v7disable 

(EAH) 

(AEH) 

EGA/VGA/SVGA  Sequencer  register 

Video7  SR6  reg  used  for  locking  and  unlocking 

VGAsegsel 

VGAmisci 

VGAmisco 

(3CDH) 

(3CCH) 

(3C2H) 

(bank) 

VGA  Segment  select  (Tseng) 

VGA  Miscellaneous  In 

VGA  Miscellaneous  Out 

Table  2:  Register  explanations 
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VGA 


( continued  from  page  22) 
called  @TsengSeg  and  @V7Seg. 

The  Paradise  chipset  is  a  little  different  in  that  it  does  not 
restrict  the  window  to  64K  boundaries.  It  is  closer  to  an 
actual  sliding  window  because  it  can  be  placed  at  any  4K 
increment.  Unlike  the  Tseng  and  Video  Seven,  the  window 
can  be  kept  purely  rectangular  by  placing  it  every  32  lines. 

Each  chipset  must  he  programmed 
separately  even  though  you  may  wish 
to  support  only  one  mode,  such  as 
640  x  480  x  256.  Even  something 
as  basic  as  mode  numbers  can  vary 
wildly  between  board  manufacturers 


This  is  because  32  lines  *  640  bytes  =  20480  =  5  *  4K 
increment.  For  some  functions  this  is  an  advantage,  but  in 
the  case  of  svPutPixel  it  does  not  help.  The  macro  @ParSeg 
emulates  the  other  chipsets  by  forcing  the  window  to  a  64K 
increment  (every  sixteenth  4K  position). 

Note  that  both  the  Video  Seven  and  the  Paradise  chipsets 
require  that  the  extended  Super  VGA  registers  be  unlocked/ 
enabled  before  they  can  be  written  to,  and  they  recommend 
that  these  registers  be  locked/disabled  when  the  function 


Extended  1 9-bit  address 


N _ _ _ X 


4K  Bank 


Figure  3:  Bank  selection  register  descriptions 
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( continued  from  page  26) 

has  completed  using  them.  This  is  done  with  an  out  to  a 
port,  and  they  are  supposedly  locked  in  order  to  prevent 
accidental  writes  to  those  port  locations.  The  only  extended 
registers  used  in  these  examples  involve  bank  selection. 

Addressing  Memory 

Address  calculations  are  simpler  in  the  256-color  modes 
because  each  pixel  is  represented  by  1  byte,  and  the  mem¬ 
ory  is  linear  (all  in  a  row,  with  no  planes,  and  no  interleav¬ 
ing).  Compared  to  the  CGA  and  Hercules  interleaving  and 
the  planes  of  the  EGA  and  VGA,  Super  VGA  is  the  easiest. 

The  address  calculations  are  performed  by  the  functions 
in  the  svPA.ASM  module  (see  Listing  Four).  Only  two  func¬ 
tions  are  necessary:  One  for  640-wide  modes,  and  one  for 
800-wide  Tseng  and  Video  Seven  modes.  The  routines 
merely  involve  multiplying  the  y  coordinate  by  the  screen 
width,  and  then  adding  in  the  x  coordinate.  Because  each 
pixel  is  a  byte,  no  conversion  is  necessary.  The  64K  bank 
number  is  automatically  determined  by  the  multiplication, 
because  the  AX  register  holds  a  maximum  of  64K  before  it 
overflows  into  DX.  Thus,  the  bank  is  returned  to  DX  and  the 
offset  into  that  bank  is  returned  in  AX  —  easy. 

Displaying  a  Pixel 

Now  that  the  pixel  can  be  addressed,  it  is  only  a  matter  of 
writing  it.  The  svPutPixel  function  contained  in  the  svPP.ASM 
module  (see  Listing  Five)  simply  uses  the  information  re¬ 
turned  from  the  svPixelAddr  function  to  set  the  window 
bank  and  update  the  pixel.  The  function  appears  a  little 
more  convoluted  due  to  the  logical  operations  supported. 
To  set  the  logical  operation,  use  the  function  svSetOp  before 
calling  the  svPutPixel  function. 


Optimization 

These  example  functions  were  derived  from  Genus  Micro¬ 
programming’s  current  graphics  tools  that  support  multiple 
languages  and  compilers.  Although  the  routines  are  fast,  the 
derivation  presented  here  is  not  necessarily  optimized  for 
speed.  Optimizations  may  include  streamlining  the  svPutPixel 
functions  themselves  so  that  the  QEntry  and  @Exit  macros 
are  removed,  or  including  separate  pixel  functions  within 
other  primitives  such  as  line  or  circle  functions.  The  exam¬ 
ples  are  meant  to  illustrate  the  Super  VGA  programming 
process  itself,  and  modular  programming  techniques.  As 
my  old  physics  professor  used  to  eloquently  understate, 
“The  rest  of  the  proof  is  trivial,  and  is  left  as  an  exercise  for 
the  student.”  In  other  words,  why  hand  it  to  you  when  you 
can  have  fun  trying? 

Conclusion 

The  Super  VGA  modes  are,  in  my  opinion,  easier  to  program 
than  most  other  video  modes  for  two  main  reasons: 

1 .  The  memory  is  linear,  not  interleaved  or  planar,  which 
simplifies  buffer  addressing. 

2.  Pixels  are  addressed  as  single  bytes,  which  simplifies 
pixel  addressing,  masking,  and  logical  operations. 

The  only  constraining  factor  is  the  lack  of  standardization, 
which  has  slowed  the  adoption  of  the  extended  modes. 
With  new  standards  such  as  VESA  on  the  horizon,  this 
situation  should  change  soon. 

DDJ 

(Listings  begin  on  page  82.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  1. 
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Circles  and  the 
Digital  Differential 

Analyzer 

This  drawing  method  belongs  in  every  graphics  library 


Tim  Paterson 


Drawing  circles  has  long  been 
a  topic  of  discussion  in  the 
pages  of  DDJ.  Earlier  this  year, 
Robert  Zigon  (“Parametric  Cir¬ 
cles,”  DDJ,  January  1990)  pre¬ 
sented  a  mathematical  analysis  in  which 
he  simplified  the  brute  force  approach 
that  would  normally  require  either  lots 
of  sines  and  cosines,  or  lots  of  squares 
and  square  roots. 

Unfortunately,  Mr.  Zigon  got  on  the 
wrong  track  by  switching  to  the  polar 
coordinate  system  for  most  of  his  analy¬ 
sis.  His  result  was  an  improvement,  but 
still  required  four  floating-point  multi¬ 
plications  per  point  drawn.  His  answer 
also  required  the  calculation  of  a  sine 
and  a  cosine  once  for  each  circle.  An¬ 
other  serious  drawback  was  the  fact 
that  his  equations  computed  points  at 
fixed  angles,  which  does  not  translate 
well  into  an  unbroken  curve  of  screen 
pixels. 

I  was  sure  there  was  a  better  way, 
so  I  looked  into  my  filing  cabinet  and 
pulled  out  the  folder  labeled  “Circles.” 
In  it  I  found  the  May  1983  issue  of 


Tim  is  the  original  author  of  MS-DOS, 
Version  1.x,  which  he  wrote  in  1980- 
82  while  employed  by  Seattle  Computer 
Products  and  Microsoft.  He  was  also 
founder  of  Falcon  Technology,  which 
became  part  of  Phoenix  Technologies, 
the  ROM  BIOS  maker.  Tim  can  be 
reached  c/o  DDJ. 


DDJ.  Daniel  Lee  had  written  “A  Fast 
Circle  Routine”  and  had  reached  a  sim¬ 
pler  conclusion  than  Mr.  Zigon’s. 

Both  Messrs.  Zigon  and  Lee  were 
calculating  the  next  point  on  the  circle 
in  relation  to  the  last  point.  If  you’ve 
had  calculus,  this  sounds  like  a  classic 
case  of  computing  “the  change  in  y, 
given  a  small  change  in  x.”  In  other 
words,  a  derivative  is  called  for.  The 
basic  equations  are  shown  in  Figure  1 . 
In  other  words,  as  Mr.  Lee  put  it,  “the 
change  in  y,  given  a  small  change  in 


x,  is  simply  the  negative  of  the  ratio  of 
x  to  y.” 

The  obvious  way  to  use  this  fact  is 
to  compute  point  n+1  from  point  n  as 
follows: 

Xn+1  =  Xn  +  1 

yn+i  =  yn-x/y 

As  written,  these  would  appear  to  need 
to  be  floating-point  operations.  How¬ 
ever,  fixed-point  arithmetic  would  work 
as  well.  For  example,  x  and  y  could  be 
stored  as  32-bit  numbers,  with  the  bi- 
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(continued  from  page  30) 
nary  point  in  the  middle:  A  16-bit  inte¬ 
ger  part  and  a  16-bit  fraction  part.  Only 
the  high  16  bits  would  be  used  for 
plotting  points.  The  low  bits  are  needed 
to  keep  the  circle  accurate.  Mr.  Lee's 
version  wasn’t  quite  this  simple,  as  he 
scaled  x  and  y  by  1000,  but  it’s  the 
thought  that  counts. 

In  order  to  plot  an  unbroken  curve, 
two  consecutive  points  cannot  be  fur¬ 
ther  apart  than  one  pixel  in  either  the 
x  or  y  direction.  In  the  equations  above, 
this  is  always  true  for  x,  of  course,  but 
is  true  for  y  only  as  long  as  x  <=y.  This 
means  the  technique  can  be  used  on 
only  one  octant  (one  eighth)  of  the 
circle  at  a  time.  However,  circles  being 
so  symmetrical,  computing  one  octant 
is  all  that’s  needed  to  plot  the  whole 
thing.  For  each  point  computed  in  one 
octant,  eight  points  are  plotted:  Four 
in  all  combinations  of  positive  and  nega¬ 
tive  coordinates,  and  the  same  four 
again  but  with  the  x  and  y  values  inter¬ 
changed. 

The  Digital  Differential  Analyzer 

Mr.  Lee’s  approach  still  requires  a  divi¬ 
sion  operation  (albeit  integer  division), 
and  I  was  sure  there  was  a  better  way. 
I  found  in  my  folder  some  handwritten 
notes  on  the  algorithm  used  by  the 
run-time  library  of  the  Microsoft  Basic 
compiler  —  circa  1981,  when  I  was  part 
of  the  team  porting  it  from  the  8080  to 
the  8086.  This  algorithm  uses  unsealed 
integers  only,  with  no  operations  more 
difficult  than  16-bit  adding  and  shift¬ 
ing.  I  have  since  heard  this  technique 
called  the  “digital  differential  analyzer,” 
or  DDA.  The  DDA  is  the  standard 
method  for  drawing  both  straight  lines 
and  circles  for  every  graphics  library. 

Let’s  start  trying  to  understand  the 
DDA  by  examining  the  case  of  straight 
lines.  Suppose  we  have  two  points  that 
we  are  drawing  a  line  between,  (xlf  yt) 
and  (x2,  y2).  First  we  compute  two  con¬ 
stants,  Dx  and  Dy. 

Dx  =  x2  -  Xj 

Dy  =  y2  -  y, 

Dx  and  Dy  are  simply  how  far  we  have 
to  go  in  each  direction  to  get  from  the 
first  point  to  the  second.  If  we  were 
going  to  use  an  approach  such  as  Mr. 


Figure  1:  Equation  for  a  circle  and  ts 
derivative 


Lee’s,  we  could  compute  points  on  the 
line  like  this: 

Xn+l=Xn+1  , 

yn+i  =  yn  +  °y/Dx 

But  Dy/Dx  is  not  an  integer  (usually), 
so  at  least  fixed-point  arithmetic  using 
scaled  integers  would  be  required. 

The  DDA  is  the 
standard  method  for 
drawing  both  straight 
lines  and  circles  for 
every  graphics  library 


So  far,  we’ve  been  looking  at  this  in 
fairly  “analog”  (as  opposed  to  “digi¬ 
tal”)  terms.  Yes,  we’ve  been  increment¬ 
ing  xby  whole  pixels,  but  yha.s  needed 
to  take  on  noninteger  values.  The  ac¬ 
tual  drawing  operations,  however,  are 
interested  only  in  whole  numbers  for 
pixel  coordinates.  Let’s  change  our  think¬ 
ing  so  that  y  stays  a  whole  number,  and 
we’ll  keep  another  variable  that  will 
tell  us  when  to  increment  it. 

Basically  y  should  get  incremented 
when  we’ve  added  Dy/Dx  enough  times 
to  equal  one  more.  This  is  the  same  as 
adding  in  one  more  Dy  for  each  x  pixel 
until  the  total  reaches  Dx.  The  C  code 
in  Example  1  shows  the  calculation  of 
one  additional  point  on  the  line.  That 
code  would  appear  in  a  loop  repeated 
to  draw  the  whole  line. 

Looking  more  closely  at  Example  1, 
sum  would  have  been  initialized  to 
-Dx/2  (or  better  still,  -Dx  »  1).  For 
each  pixel  in  the  x  direction,  we  add 
Dy  to  sum.  When  sum  crosses  over  to 
being  positive,  that  means  we’re  ready 
to  move  one  y  pixel,  and  we  subtract 
Dx  from  sum.  sum  gets  Dy  added  for 
each  x  pixel,  Dx  to  subtract  for  each  y 
pixel:  It  almost  amounts  to  division  by 
repeat  subtraction. 

But  we’re  really  here  to  look  at  cir¬ 
cles.  In  the  case  of  lines,  we  were  add¬ 
ing  the  constant  Dy/Dx  to  y  as  dis- 


sum  +=  Dy; 
x++; 

if  (sum  >  0) 

{ 

sum  -=  Dx; 
y++; 

1 


Example  1:  The  calculation  of  one 
additional  point  on  the  line 


cussed  earlier  for  circles,  we  need  to 
add  x/y.  That  doesn’t  sound  much 
harder,  and,  in  fact,  it’s  not.  Drawing  a 
circle  is  just  as  easy  as  drawing  a  line. 
Example  2  has  the  C  code  for  one  pass 
through  the  circle’s  pixel  loop,  with  a 
few  added  features  for  more  accuracy. 

You  should  have  expected  x  to  be 
added  to  sum  each  time  through  the 
loop;  instead  we  have  2x  +  1.  The 
reason  for  this  is  accuracy.  Unlike  the 
straight  line  case,  the  derivative  we’re 
using  as  the  basis  for  our  technique, 
y/x,  is  continuously  varying.  As  we  move 
from  one  x  pixel  to  the  next,  which 
value  of  y/x  do  we  use  —  the  one  be¬ 
fore  or  the  one  after  the  move?  The 
best  answer  is  to  use  the  value  in  be¬ 
tween.  That  is,  instead  of  adding  x,  or 
adding  x+1,  we  can  add  the  average: 
(2xfl)/2.  But  there’s  no  reason  to  di¬ 
vide  by  two  as  long  as  we  do.it  the 
same  way  for  the  y  pixel.  Note  that 
these  lines  could  also  be  coded  as: 

sum  +  =  X; 

x++; 

sum  +  =  X; 
and 

sum  -  =  y; 

y--; 

sum  -  =  y; 

By  using  the  value  of  x  (or  y)  both 
before  and  after  incrementing  it,  we’re 
clearly  showing  how  we  want  the  ef¬ 
fect  of  the  midpoint. 

The  initial  conditions  for  the  loop 
would  be  sum  and  x  set  to  zero,  and  y 
set  to  the  radius  of  the  circle.  But  this 
won’t  work  quite  right.  Starting  sum  at 
zero  means  y  will  be  kept  less  than  or 
equal  to  its  perfect  value  on  the  circle 
for  any  given  x  coordinate.  That  is, 
we’ll  plot  only  points  that  fall  exactly 
on  or  inside  the  circle.  What  we’d  like 
is  to  plot  the  nearest  point  to  the  circle, 
whether  it  be  inside  or  outside  it.  For 
the  straight  line  case,  we  initialized  sum 
to  -Dx/2,  which  effectively  shifted  the 
y  coordinate  one-half  a  pixel.  But  again 
because  the  derivative  for  the  circle  is 
varying  instead  of  constant,  there  is  no 
value  that  can  be  used  to  initialize  sum 
to  get  the  same  effect. 

The  solution  is  to  explicitly  shift  the 


sum  +=  2*x  +  1; 
x++; 

if  (sum  >  0) 

{ 

sum  -=  2*y  -  1; 
y— ; 

} 


Example  2:  C  code for  one  pass  through 
the  circle’s  pixel  loop 
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(continued  from  page  32) 
y  coordinate  by  half  a  pixel  as  we  plot 
the  points.  That  is,  instead  of  having 
the  error  from  the  perfect  value  for  y 
range  from  0  to  -1  pixel,  we’ll  add  one 
half,  and  the  error  will  be  1/2  to  -1/2 
pixel.  To  do  this  with  integers  is  sim¬ 
ple:  Double  the  radius,  so  that  adding 
one  is  equivalent  to  half  a  pixel.  Then 
we’ll  plot  only  even  values  of  x,  using 
the  points  x/2  and  (jh-1)/2. 

To  add  aspect 
ratio  to  our 
circle  drawing 
algorithm  requires 
a  little  bit  of  work 
up  front 


Example  3  shows  a  working  C  func¬ 
tion  that  plots  a  circle.  It  calls  an  addi¬ 
tional  function  plot8( ),  which  actually 
plots  the  point  generated  in  all  eight 
octants.  Note  that  all  multiplications 
and  divisions  by  two  have  been  re¬ 
placed  with  shift  operations  «  and 
»,  respectively. 

Ellipses  and  Aspect  Ratio 

Circles  plotted  with  any  of  these  tech¬ 
niques  are  round  only  when  the  di¬ 
mensions  of  the  graphics  controller,  in 
pixels,  correspond  to  the  aspect  ratio 
of  the  video  monitor.  Standard  video 
monitors  have  a  4:3  aspect  ratio,  so 
VGA  640  x  480  and  super  VGA  800  x 
600  resolutions  produce  a  “square”  pixel 
(and  a  round  circle).  Other  typical  graph- 


Example  3:  C function  that  plots  a 
circle 
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ics  resolutions  (such  as  CGA,  EGA,  and 
Hercules)  do  not  match  the  4:3  screen 
aspect  ratio,  and  will  display  an  ellipse 
instead  of  a  circle. 

Ellipses  have  their  place,  too.  If  we 
could  have  arbitrary  control  over  as¬ 
pect  ratio  of  the  circle  itself,  then  we 
could  draw  circles  or  ellipses  for  every 
graphics  system.  And,  in  fact,  any  graph¬ 
ics  library  will  have  this  capability,  al¬ 
though  it  is  often  expressed  in  different 
ways.  The  CIRCLE  statement  of  Micro¬ 
soft  Basic,  for  example,  requires  you 
to  specify  the  center,  the  radius,  and 
the  aspect  ratio.  On  the  other  hand, 
Microsoft  Windows  and  the  Microsoft 
C  graphics  library  want  you  to  specify 
a  “bounding  rectangle”:  You  get  the 
biggest  ellipse  (or  circle)  that  will  fit 
into  the  box. 

To  add  aspect  ratio  to  our  circle  draw¬ 
ing  algorithm  requires  a  little  bit  of 
work  up  front,  plus  a  single  integer 
multiplication  for  each  point  plotted. 
The  simple-minded  approach  would 
be  to  multiply  the  y  coordinate  value 
by  the  aspect  ratio.  However,  if  the 
aspect  ratio  is  greater  than  one,  this 
could  cause  gaps  in  the  arc.  In  that 
case,  we  will  multiply  the  x coordinate 
by  the  reciprocal  of  the  aspect  ratio. 
Thus  we  will  always  be  multiplying  by 
less  than  one,  compressing  points  on 
the  arc  and  keeping  it  unbroken. 

Always  multiplying  by  a  number  less 
than  one  has  the  further  advantage  of 
giving  us  a  limit  on  the  range  of  the 
number.  We  can  scale  the  number  by 
up  to  16  bits  and  still  store  it  as  a  16-bit 
number.  This  is  done  by  SetAspectO 
in  the  complete  circle  drawing  pro¬ 
gram  shown  in  Listing  One,  page  96. 
Then  as  points  are  plotted,  the  scaled 
aspect  ratio  is  multiplied  by  the  x  or  y 
coordinate,  as  appropriate,  with  the  re¬ 
sult  shifted  right  16  bits.  Individual 
points  are  plotted  using  the  _setpixel( ) 
function  of  the  Microsoft  C  graphics 
library. 

So  we  now  have  a  complete  algo¬ 
rithm  for  generating  circles  or  ellipses 
of  any  aspect  ratio.  Of  course,  in  a  real 
graphics  library,  assembly  language 
would  be  used  for  maximum  speed. 
And  one  feature  still  missing  is  the  abil¬ 
ity  to  draw  only  an  arc,  rather  than  the 
complete  ellipse.  The  algorithm  for  a 
partial  arc  is  no  different  from  what 
we  have  so  far,  but  adds  a  check  to  see 
which  points  we  actually  want  to  plot, 
and  which  will  be  discarded. 

DDJ 

(Listing  begins  on  page  96.) 
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Improving  Line 
Segment  Clipping 

More  bang  for  your  line  clipping  buck 


Victor  J.  Duvanenko,  W.E.  Robbins, 
Ronald  S.  Gyurcsik 


Over  the  past  few  years,  win¬ 
dowing  environments  have 
become  enormously  popu¬ 
lar.  Intuitive  graphical  inter¬ 
faces  with  pop-up  menus  are 
now  expected  of  commercial  software; 
successful  products  such  as  Apple’s 
Macintosh,  X  Windows,  and  Microsoft 
Windows  are  thriving  because  they  pro¬ 
vide  these  features, 

Windowing  doesn’t  come  for  free, 
however.  Many  sophisticated  algorithms 
are  behind  the  creation  of  the  illusion 
called  a  window.  In  this  article  I’ll  dis¬ 
cuss  clipping,  one  of  the  key  algo¬ 
rithms,  by  examining  Cohen-Suther- 
land’s  classic  clipping  algorithm  and 
then  implement  —  and  optimize  —  it 
in  C.  The  resulting  algorithm  will  clip 
about  55  percent  more  lines  per  sec¬ 
ond  than  Cohen-Sutherland’s  original 
algorithm. 

As  it  applies  to  computer  graphics, 
“clipping”  is  a  process  of  removing 
that  portion  of  an  object  that  cannot 
be  seen  through  a  bounding  region 
(that  is,  a  “window”).  See  Figure  1. 
Examples  of  clipping  can  be  found  ev¬ 
erywhere  in  everyday  life.  If  you  look 
through  the  physical  window  of  your 
house,  for  instance,  you  see  only  a 
small  portion  of  the  outside  world.  To 
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reached  at  1001  Japonica  Court, 
Knight-dale,  NC 27545. 


create  the  same  effect  on  a  computer, 
decisions  must  be  made  as  to  which 
portion  of  the  world  is  to  be  displayed 
and  which  is  to  be  discarded  (because 
the  wall  that  surrounds  the  physical 
window  conceals  that  portion  of  the 
world).  Clipping  is  the  process  of  re¬ 
moving  the  portion  of  the  world  that 
cannot  be  seen. 

In  computer-aided  design  (CAD)  and 
other  computer  graphics  applications, 
very  large  and  complex  databases  are 
often  created  and  manipulated.  The 
space  shuttle  is  one  such  example. 
When  working  on  a  tail  section  of  a 
project  like  the  space  shuttle,  engineers 
don’t  necessarily  want  to  see  the  entire 
space  shuttle  on  the  screen.  Conse¬ 
quently,  the  CAD  program  must  be  ca¬ 


pable  of  cutting  away,  or  clipping,  the 
undesired  sections  of  the  shuttle  while 
displaying  only  the  tail  section  (appro¬ 
priately  scaled)  on  the  screen. 

Because  the  general  topic  of  clip¬ 
ping  is  much  too  broad  to  cover  in  a 
single  article,  I’ll  focus  on  the  clipping 
of  line  segments  that  are  displayed  in 
a  rectangular  window  that  is  parallel 
to  the  display  device  axes.  This  covers 
most  of  the  present  windowing  sys¬ 
tems  that  use  rectangular  windows 
aligned  with  the  monitor  screen.  Also, 
a  very  large  class  of  physical  objects 
can  be  drawn  with  lines. 

A  Line  Segment 

To  be  able  to  manipulate  line  segments, 
you  must  first  understand  everything 
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(continued  from  page  36) 
about  them.  How  are  line  segments 
different  from  lines?  How  are  lines  and 
line  segments  described?  How  are  line 
segments  shortened  or  lengthened?  I’ll 
answer  these  questions  in  this  section. 

A  “line,”  in  analytic  geometry,  is  a 
graph  of  a  linear  equation  Ax  +  By  +  C 
=  0  where  A,  B  are  not  zero.  A  line  can 
also  be  described  mathematically  as 
shown  in  Table  l.2 

Note  that  the  right  side  of  the  two- 
point  form  is  the  slope  (m),  making  the 
two-point  form  equivalent  to  the  point- 
slope  form.  There  are  several  other  ways 
to  describe  a  line,  but  they  are  not  as 
useful  to  this  discussion.  For  our  pur¬ 
poses,  a  line  is  a  set  of  all  points  with 
coordinates  (x,y)  that  satisfy  a  line  equa¬ 
tion  (see  Figure  2).  A  line  extends  infi¬ 
nitely  and  contains  an  infinite  number 
of  points.  This  infinity  stuff  is  very  troub¬ 
lesome,  however.  To  draw  an  infinite 
number  of  points  in  a  line  would  take 
infinitely  long,  no  matter  how  quickly 
each  point  is  drawn.  Also,  there  are 
not  many  physical  objects  that  contain 
lines  of  infinite  length.  In  fact,  any  such 
object  would  have  to  be  infinitely  large. 

A  finite  portion  of  a  line  is  much 
more  useful  when  dealing  with  realis¬ 
tic  physical  objects.  Somehow,  the 
boundaries  of  this  finite  portion,  or 
segment,  of  a  line  must  be  specified. 
One  convenient  way  to  specify  these 
boundaries  is  by  using  two  points  to 
indicate  the  end  points  of  that  line  seg¬ 
ment,  and  then  by  using  the  two-point 
form  line  equation.  Therefore,  a  line 
segment  is  a  set  of  all  points  on  a  line 
between  the  end  points  of  that  line 
segment  (see  Figure  3).  There  are  other 
ways  to  define  a  line  segment  that  are 
convenient  to  other  applications. 

Clipping  shortens  the  line  segment. 
To  accomplish  clipping,  one  or  both 
end  points  of  the  line  segment  must 
be  modified.  New  end  points  must  then 
be  calculated.  These  new  end  points 
must  satisfy  the  line  equation  in  that 
they  must  lie  on  the  original  line  and 
be  within  the  boundaries  of  the  origi¬ 
nal  line  segment  (again,  see  Figure  3). 
For  example,  if  as  in  Figure  4  a  line 
segment  intersects  X_RIGHT  (the  right 
window  boundary),  only  the  section 
Pl-A  should  be  displayed.  The  section 
A-PO  should  be  discarded.  To  accom¬ 
plish  this,  point  A  must  replace  point 
PO  as  the  end  point  of  the  line  segment. 
Somehow,  the  X  and  Y  coordinates  of 
point  A  must  be  computed. 

The  X-coordinate  of  the  intersection 
point  must  be  XJRIGHT,  since  the  P0- 
P1  line  segment  intersects  the  right  side 
of  the  window  (whose  line  equation 
is  x  =  X_RIGHT).  Only  the  Y-coordi- 
nate  is  left  to  be  determined.  This  can 


be  done  by  solving  the  two-point  form  quickly.  The  result  is  a  new  end  point 
line  equation  for  Y,  and  substituting  of  a  shorter,  clipped,  line  segment.  This 
X_RIGHT  for  X  in  that  equation.  The  simple  method  can  be  extended  to  clip 
resulting  equation  (shown  in  Figure  4)  lines  to  the  four  boundaries  of  a  rectan- 
is  manageable  and  can  be  computed  gular  window. 


Figure  1:  Clipping  is  the  process  of  removing  portions  of  an  object  that  cannot 
be  seen  through  a  bounding  region 


Form 

Math  Description 

Slope  y-interceptform: 

y  =  mx  +  b 

Point-slope  form: 

y-yl  =  m*(x-x1  ) 

Two-point  form: 

( y  —  yl  )/( x  —  xl  )  =  (  y2  —  y  1  )/(x2-x1  ) 

Table  1:  Mathematically  describing  a  line 


Figure  2:  A  line  is  a  set  of  all  points  with  coordinates  (x,y)  that  satisfy  a  line 
equation 


Figure  3:  A  line  segment  is  a  set  of  all  points  on  a  line  between  the  end  points 
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(continued  from  page  38) 

A  straightforward  way  to  perform  line 
clipping  is  to  find  an  intersection  be¬ 
tween  the  line  to  be  clipped  and  every 
boundary  of  the  window  and  to  make 
sure  that  the  intersection  points  are 
within  the  window  limits.  If  the  inter¬ 
section  points  are  all  outside  the  win¬ 
dow  limits,  then  the  line  can  be  thrown 
away.  In  other  words,  you  must  choose 
the  new  end  points  very  carefully  — 
between  the  “best”  intersection  points 
and  the  end  points  of  the  original  line. 
This  method  would  require  an  inter¬ 
section  calculation  for  all  four  window 
boundaries.  But  is  this  amount  of  com¬ 
putation  really  necessary?  Couldn’t  con¬ 
clusions  be  made  as  each  intersection 
point  (up  to  four  of  them)  is  found,  to 
speed  up  the  process?  That  is  precisely 
what  the  Cohen-Sutherland  algorithm 
does.  The  algorithm  decides  the  fate 
of  the  line  after  an  intersection  with  a 
single  window  boundary  has  been  de¬ 
termined;  it  does  this  up  to  four  times. 

The  Cohen-Sutherland  Algorithm  (2D) 

The  Cohen-Sutherland  line  clipping  al¬ 
gorithm,  introduced  in  1968,  is  power¬ 
ful,  simple,  and  compact.  The  first  ad¬ 
aptation  of  the  algorithm,  implemented 
in  C,  is  shown  in  Listing  One  (page 
98).  This  version  corresponds  to  the 
implementations  that  are  found  in  lit¬ 
erature  (see  endnotes  3,  4,  7,  and  9). 
An  “improved”  version  of  the  algo¬ 
rithm  is  shown  in  Listing  Two  (page 
98).  I  will  thoroughly  explain  the  code 
shortly  but,  first,  the  method. 

Cohen  and  Sutherland  thought  of 
the  window  boundaries  as  lines,  not 
line  segments.  If  these  window  bounda¬ 
ries  were  extended  (lines  are  of  infinite 
length),  the  world  would  be  partitioned 
into  nine  regions  that  can  be  thought 
of  as  being  within,  above,  below,  to 
the  right,  or  to  the  left  of  the  window 
(see  Figure  5).  Each  region  can  then 
be  given  a  unique  identifier,  an  outcode/ 
number.  This  identifier  would  be  more 
useful  if  there  were  some  logic  behind 
it,  especially  if  it  allowed  for  quick 
rejection  of  line  segments  that  are  com¬ 
pletely  outside  the  window,  or  for  quick 
acceptance  of  line  segments  that  are 
completely  within  the  window.  Cohen 
and  Sutherland  suggested  the  follow¬ 
ing  scheme: 

•  Bit  0  of  the  identifier  should  indicate 
whether  the  end  point  is  above  the 
window. 

•  Bit  1,  whether  the  end  point  is  below 
the  window. 

•  Bit  2,  whether  the  end  point  is  to  the 
right  of  the  window. 

•  Bit  3,  whether  the  end  point  is  to  the 
left  of  the  window. 


This  scheme  leads  to  the  region  encod¬ 
ing  shown  in  Figure  6.  Note  that  Bit  0 
is  on  the  left,  so  the  region  encoded 
with  1010  has  bits  0  and  2  set  to  indi¬ 
cate  that  it  is  above  and  to  the  right  of 
the  window.  Each  region  has  now  been 
identified  uniquely.  For  the  rest,  keep 
Listing  One  handy  while  I  lead  you 
through  every  detail  of  the  code. 

The  algorithm 
modifications  resulted 
in  a  353 percent  speed 
improvement  for  this 
sample  of  1000  lines. 

This  results  in  an 
incredible  54.6  percent 
more  lines  clipped  per 
second! 


Procedure  clip_2d_cs  is  the  main  pro¬ 
cedure  of  the  algorithm.  It  is  called  to 
perform  the  actual  clipping  (read  the 
comments  for  details  about  the  calling 
conventions).  Note  the  two  integer  vari¬ 
ables,  outcodeO  and  outcodel.  These 
will  be  assigned  to  each  end  point,  and 
will  indicate  which  region  an  end  point 
lies  in. 

The  algorithm  consists  of  a  while 
loop,  which  is  executed  up  to  four 
times.  The  first  step  in  the  algorithm  is 
to  identify  in  which  of  the  nine  regions 
an  end  point  of  the  line  segment  lies 


and  to  assign  an  appropriate  outcode 
to  it.  For  example,  if  an  end  point  lies 
in  a  region  that  is  above  and  to  the  left 
of  the  window,  an  outcode  1001  is 
assigned  to  it.  This  is  exactly  what  the 
procedure  outcodes  does.  Both  end 
points  of  the  line  segment  get  outcodes 
assigned  to  them. 

Two  quick  decisions  can  now  be 
made  about  the  line  based  on  the  out¬ 
codes.  First,  a  line  can  be  trivially  re¬ 
jected  in  four  cases:  If  both  end  points 
are  above  the  window;  if  both  end 
points  are  below  the  window;  if  both 
end  points  are  to  the  left  of  the  win¬ 
dow;  and  if  both  end  points  are  to  the 
right  of  the  window.  In  these  cases  the 
line  should  not  be  drawn  at  all,  as  it 
lies  completely  outside  the  window. 
An  easy  and  quick  way  to  check  for 
these  four  conditions  is  to  perform  the 
logical  AND  of  the  end  point  outcodes 
(see  procedure  reject_cbeck) .  For  ex¬ 
ample,  if  both  end  points  are  above  the 
window,  both  outcodes  will  have  Bit 
0  set  to  a  1.  A  logical  AND  will  produce 
a  1  in  Bit  0,  and  the  line  is  rejected. 

The  second  decision  that  can  be  made 
quickly  is  the  trivial  acceptance  if  both 
end  points  are  within  the  window.  In 
this  case,  the  outcodes  of  both  end 
points  will  be  0000.  The  procedure  ac- 
cept_check  checks  both  outcodes  and 
accepts  the  line  if  both  outcodes  are 
0000. 

At  this  point  the  trivial  cases  have 
been  taken  care  of,  and  the  more  com¬ 
plicated  cases  must  be  dealt  with.  Co¬ 
hen  and  Sutherland  took  the  divide-and- 
conquer  approach  to  the  problem.  A 
series  of  simple  adjustments,  up  to  four, 
is  made,  and  the  line  is  checked  for 
trivial  rejection  or  acceptance  after  each 
adjustment.  The  simple  adjustments  are 
exactly  like  the  one  demonstrated  in 
Figure  4.  Basically,  a  line  is  shortened 
with  respect  to  a  single  window  bound¬ 
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A  is  (?,?) 

P0  is  (X0,Y0) 
PI  is  (XI, Y1) 


The  two  point  form  line  equation  is 
Y  -  Y0  Y1  -  Y0 


X  -  X0  XI  -  X0 


But,  from  the  diagram  A  is  (X  RIGHT,?) 
Therefore,  X  =  XRIGHT 


Then  Y  =  Y0  + 


Y1  -  Y0 
XI  -X0 


(X  RIGHT  -  X0) 


. 


Figure  4:  Computing  the  X  and  Y  coordinates  of  point  A.  The  result  is  a  new 
end  point  of  a  shorter,  clipped,  line  segment.  This  simple  method  can  be 
extended  to  clip  lines  to  the  four  boundaries  of  a  rectangidar  windoiv. 
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(continued  from  page  40) 
ary  during  each  iteration.  After  up  to 
four  iterations,  because  there  are  four 
window  boundaries,  the  line  segment 
has  been  clipped. 

The  best  way  to  explain  the  algo¬ 
rithm  is  to  walk  through  an  example. 
In  Figure  7  the  progress  of  the  clipping 
algorithm  is  shown  one  iteration  at  a 
time.  Line  segment  end  points  are  first 
encoded  with  outcodes.  This  line  seg¬ 
ment  can’t  be  trivially  accepted  because 
both  end  points  are  not  within  the  win¬ 
dow  boundaries  (both  outcodes  are 
not  0000).  This  line  segment  can’t  be 
trivially  rejected  either,  because  the  logi¬ 
cal  AND  of  the  end  point  outcodes  is 
0000.  The  algorithm  then  starts  operat¬ 
ing  on  P0  end  point,  because  this  end 
point  is  outside  the  window  bounda¬ 
ries:  Its  outcode  is  not  0000.  Because 
Bit  0  is  set  in  the  outcode  of  P0,  P0 
must  be  above  the  top  window  bound¬ 
ary.  P0  can  be  moved  to  the  intersec¬ 
tion  of  the  line  segment  with  the  line 
drawn  through  the  top  window  bound¬ 
ary.  This  point  will  still  be  on  the  line 
segment  and  will  be  a  bit  closer  to  the 
window.  This  action  eliminated  the  sec¬ 
tion  of  the  line  segment  that  was  above 
the  top  window  boundary  and,  there¬ 
fore,  could  not  possibly  be  seen  through 
the  window.  The  Y  coordinate  of  the 
new  end  point  is  already  known:  Y_TOP 
(the  top  boundary  of  the  window).  The 
only  calculation  that  remains  is  to  com¬ 
pute  the  X  coordinate.  This  is  done  by 
the  method  similar  to  that  shown  in 
Figure  4,  only  solving  the  equation  for 
X,  because  it  —  not  Y  —  is  the  un¬ 
known.  The  code  for  this  is  in  the 
clip_2D_cs  inside  the  if  ( outcodeO  & 
1)  statement. 

Next,  because  the  end  points  have 
been  moved,  they  are  given  new  out¬ 
codes.  Then  the  new  line  segment  is 
checked  once  again  for  trivial  rejection 
or  acceptance.  The  outcode  of  P0  shows 
that  P0  is  to  the  right  of  the  window. 
Therefore,  P0  can  be  moved  to  the 
intersection  of  the  right  window  bound¬ 
ary  and  the  line  segment.  This  action 
will  cause  the  section  of  the  line  seg¬ 
ment  that  is  to  the  right  of  the  window 
to  be  discarded  (shown  in  step  2).  The 
X  coordinate  of  this  intersection  is 
known,  but  not  the  Y,  so  the  algorithm 
calculates  the  Y  coordinate. 

Turbocharging  the  Algorithm 

Now  that  you  understand  the  algorithm, 
I’ll  introduce  several  modifications  to 
boost  the  algorithm  performance.  These 
modifications  are  shown  in  Listing  Two. 
Benchmarks  are  summarized  in  the  next 
section. 

The  first  modification  is  to  calculate 
the  slope  and  the  inverse  slope  only 


once.  This  modification  comes  from  a 
simple  idea  —  the  slope  of  a  line  be¬ 
fore  clipping  should  be  equal  to  the 
slope  of  a  line  after  it  has  been  clipped. 

The  implementation  is  just  as  simple 
as  the  concept  itself.  After  the  first  triv¬ 
ial  rejection  or  acceptance  has  been 
completed,  and  failed,  the  calculation 
of  the  slope  is  inevitable.  For  half  of  the 
cases  the  slope  must  be  calculated;  for 
the  other  half  the  inverse  of  the  slope 

CAD  programs  must  be 
capable  of  cutting 
away,  or  clipping,  the 
sections  of  objects  that 
cannot  be  seen  through 
a  window 


must  be  calculated.  That’s  right,  if  a 
line  can  be  broken  up,  or  subdivided, 
at  the  top  or  the  bottom  of  the  window, 
then  the  Y  coordinate  of  the  intersec¬ 
tion  is  known  and  X  must  be  com¬ 
puted.  Therefore,  in  this  case  the  in¬ 
verse  of  the  slope  must  be  computed. 
If,  however,  a  line  can  be  subdivided 
at  the  left  or  right  of  the  window,  the 
slope  must  be  calculated. 

If  you  look  at  the  code  in  Listing 
One,  you  will  notice  that  all  computa¬ 
tions  of  *y0  or  *x0  involve  very  similar 
calculations.  In  fact,  all  of  them  com¬ 
pute  (*xl  -  *xO)  and  (*yl  -  *y0).  Realiz¬ 
ing  that  the  result  of  these  two  compu¬ 
tations  will  be  used  only  in  the  slope 
or  inverse  slope  calculations,  which 
do  not  change,  leads  to  the  conclusion 
that  these  values  need  be  computed 
only  once.  That  is  what  you  see  in 
Listing  Two.  Two  variables  have  been 
added,  dx  and  dy,  and  these  are  com¬ 
puted  only  once. 

A  perfectly  reasonable  question  to 
ask  at  this  point  is,  “If  we  calculated  the 
slope,  can  the  inverse  be  quickly  deter¬ 
mined  by  dividing  a  one  by  the  slope?” 
Ah,  but  there  is  a  problem  with  this 
method.  Remember  the  trouble  with 
division  by  zero  —  it  leads  to  an  an¬ 
swer  that  computers  just  can’t  deal  with. 
In  fact,  Hearn  and  Baker4  missed  this 
point  in  their  implementation  of  the 
Cohen-Sutherland  algorithm.  Their  im¬ 
plementation  will  not  work  for  vertical 
lines.  I  hope  this  serves  as  sufficient 
warning  for  programmers  everywhere  — 
check  even  the  most  trivial  of  cases! 

The  Cohen-Sutherland  algorithm  care- 
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Figure  5:  Cohen  and  Sutherland 
thought  of  the  window  boundaries  as 
lines,  which  when  extended  partition 
the  world  into  nine  regions  that  can 
be  thought  of  as  being  within,  above, 
below,  to  the  right,  or  to  the  left  of  the 
window. 
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Figure  6:  Each  region  has  a  unique 
identifier,  an  outcode/number. 
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Figure  7:  The  progress  of  the  clipping 
algorithm,  one  iteration  at  a  time. 
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( continued  from  page  42) 
fully  avoids  division  by  zero  by  calcu¬ 
lating  the  slope  inside  the  z/statements. 
For  example,  if  a  line  needs  to  be  sub¬ 
divided  at  the  top  of  the  window,  that 
line  cannot  be  horizontal.  If  it  were,  it 
would  have  been  either  trivially  rejected 
or  accepted,  or  it  would  be  impossible 
for  its  outcodes  to  require  subdivision 
at  the  top  of  the  window.  Also,  wouldn’t 
it  be  a  bit  difficult  to  subdivide  a  hori¬ 
zontal  line  at  the  top  or  the  bottom  of 
the  window  to  begin  with?  The  line  is 
parallel  to  the  top  and  bottom  bound¬ 
ary  (there  is  no  intersection  point). 

The  second  speed  improvement 
comes  from  several  sources  (see  refer¬ 
ences  6,  3,  and  7).  Exercise  4.2  in  Fun¬ 
damentals  of  Interactive  Computer 
Graphics  contains  a  suggestion  to  en¬ 
code  only  PO,  the  modified  end  point. 
This  modification  has  the  most  dra¬ 
matic  speed  improvement  on  the  algo¬ 
rithm.  It  reduces  the  number  of  floating¬ 
point  comparisons  almost  in  half.  Bravo! 

This  concept  can  be  taken  one  step 
further  by  optimization  fanatics  like  my¬ 
self.  After  a  line  has  been  subdivided 
once,  only  3  bits  are  needed  for  the 
outcodes.  So,  only  three  of  the  four 
boundary  comparisons  are  needed.  For 
example,  if  a  line  has  just  been  subdi¬ 
vided  at  the  top  of  the  window,  there 
is  no  need  to  compare  that  end  point 
with  the  top  of  the  window  again.  You 
can  be  assured  that  the  new  end  point 
will  not  be  above  the  window,  because 
we  just  discarded  that  portion  of  the 
line.  Therefore,  the  comparison  with 
the  top  window  boundary  can  be  elimi¬ 
nated.  This  reduces  the  number  of  com¬ 
parisons  a  bit  more,  but  makes  the 
code  not  quite  as  elegant  as  it  once 
was.  Well,  performance  versus  elegance 
has  its  trade-offs.  .  .  . 

The  next  improvement  can  be  made 
by  noticing  another  physical  property. 
If  a  line  is  being  clipped  at  the  top 
boundary,  it  is  physically  impossible 
for  the  new  top  end  point  to  be  below 
the  bottom  boundary.  In  other  words, 
the  end  point  that  was  above  the  win¬ 
dow  can  move  only  to  one  of  the  three 
middle  regions  (0001,  0000,  0010).  It 
will  never  move  below  the  window, 
so  why  check  it?  Therefore,  we  can 
remove  yet  another  floating-point  com¬ 
parison.  Now,  if  the  line  is  being  subdi¬ 
vided  at  the  top  or  the  bottom  bound¬ 
ary,  we  need  to  check  against  and  en¬ 
code  only  the  right  and  left  boundary. 
And,  if  the  line  is  being  subdivided  at 
the  right  or  left  boundary,  we  need  to 
check  against  and  encode  only  the  top 
and  bottom  boundary. 

Now,  the  number  of  comparisons, 
after  the  initial  encoding,  has  been  cut 
in  half.  Not  bad.  But  is  it  possible  to 
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do  more?  Yes,  of  course.  The  last  im¬ 
provement  is  even  more  dramatic  than 
any  of  the  previous  ones.  This  speed 
improvement  comes  from  the  physical 
properties  described  earlier  as  well.  If 
you  look  at  Figure  6  once  again,  you 
will  notice  that  only  2  out  of  the  possi¬ 
ble  4  bits  are  ever  set  for  any  region. 
Why,  then,  should  we  do  four  com¬ 
parisons?  Couldn’t  we  stop  after  the 
first  2  bits  have  been  set,  and  not  do 
the  other  2  bits?  Yes,  we  could  defi¬ 
nitely  do  that.  For  example,  if  we  found 
that  an  end  point  is  located  above  the 
window,  we  no  longer  have  to  check 
the  region  below  the  window.  The  same 
holds  for  left  and  right  regions.  This  is 
the  reasoning  behind  all  of  those  mys¬ 
terious  if/else  statements  in  the  OUT¬ 
CODES  macro  and  in  the  body  of  the 
main  loop.  In  the  best  case,  only  two 
floating-point  comparisons  are  made. 
In  the  worst,  still  four  are  needed?  The 
number  of  comparisons  drops  dramati¬ 
cally,  especially  for  the  trivial  rejection 
case,  from  eight  to  four.  Note,  that  triv¬ 
ial  acceptance  doesn’t  benefit  at  all. 
Newmann  and  Sproull6  used  this  tech¬ 
nique  in  their  implementation  of  the 
OUTCODES  subroutine. 

As  promised,  I  pulled  all  of  the  C 
tricks  from  my  bag  of  tricks.  I  con¬ 
verted  the  outcodes  and  swap_  pts  pro¬ 
cedures  to  OUTCODES  and  SWAP_PTS 
macros.  This  eliminated  stack  data  move¬ 
ment,  resulting  in  further  speed  im¬ 
provement.  Therefore,  the  final  routine 
does  no  procedure  calls,  and  no  pa¬ 
rameter  passing,  at  all.  I  had  to  add  a 
couple  of  temporary  variables  that  swap 
procedure  used,  however,  to  store  the 
values  during  swapping. 

There  are  several  other  small  optimi¬ 
zation  steps  that  can  be  taken  even  fur¬ 
ther.  You  could  calculate  the  slope  {dy/ 
dx)  and  then  set  a  flag  to  indicate  that 
the  slope  has  already  been  computed. 
Then,  if  the  need  arises  to  use  the  slope 
in  another  z/statement,  that  calculation 
can  be  avoided.  This  yields  very  small 
performance  improvement.  It  would  be 
beneficial  for  hardware  implementations 
of  the  algorithm,  however. 

Benchmarks 

I  used  the  Microsoft  C,  Version  5.0, 
compiler  and  set  all  performance  en¬ 
hancing  switches  that  I  could  find,  -Ox 
-FPi87.  I  set  the  -FPi87  switch,  be¬ 
cause  I’m  fortunate  enough  to  have  an 


Table  2:  Line  clipping  benchmark  results 


80287  math  coprocessor  in  my  8  MHz, 
1  wait  state  PC/AT.  I  also  used  the  -  W2 
switch,  requesting  the  compiler  to  find 
any  stupid  mistakes  that  I  often  make. 

To  compare  the  algorithms  against 
one  another  I  wrote  a  fairly  involved, 
and  long,  program  that  will  be  avail¬ 
able  through  the  DDJ  Forum  or  on 
CompuServe.  For  details  see  info  at  the 
end  of  this  article.  This  program  allows 
a  large  database  of  lines,  specified  by 
two  end  points  in  three  dimensions, 
to  be  loaded  from  a  disk  file.  Then,  the 
user  is  able  to  choose  from  a  menu  of 
several  line  clipping  algorithms.  The 
program  takes  a  time  stamp  before  the 
clipping  algorithm  is  run  on  the  data¬ 
base  and  when  the  clipping  has  been 
completed.  The  time  difference  is  then 
displayed  on  the  screen.  The  user  can 
run  the  chosen  clipping  algorithm  as 
many  times  as  they  wish  for  improved 
timing  accuracy.  The  window  size  can 
be  easily  modified,  and  the  database 
can  be  rotated,  scaled,  and  translated 
for  added  flexibility. 

To  generate  the  database  of  line  end 
points,  I  wrote  a  short  program,  shown 
in  Listing  Three  (page  100),  that  gener¬ 
ates  random  end  points  in  three  di¬ 
mensions.  Yes,  I  realize  that  random 
data  is  not  exactly  the  best  way  of  bench¬ 
marking  an  algorithm,  but  I  haven’t 
seen  a  fair  benchmark  for  line  clipping 
yet.  The  most  fair  test,  in  my  opinion, 
would  be  to  generate  a  tight,  paralleled- 
piped-shaped  grid  of  interconnected 
points  in  three  dimensions. 

The  benchmarks  in  Table  2  were 
done  with  the  window  dimensions  set 
at  5  <  X  <  630,  3  <  Y  <  300.  The  values 
of  the  line  end  points  varied  from  -16K 
<  (X,  Y)  <16K.  One  thousand  lines 
were  clipped  100  times.  The  resulting 
clipped  lines  were  drawn  in  one  case 
and  not  in  the  other,  giving  a  true  value 
of  the  line  clipping  overhead  in  the 
latter  case. 

The  algorithm  modifications  resulted 
in  a  35.3  percent  speed  improvement 
for  this  sample  of  1000  lines.  This  re¬ 
sults  in  an  incredible  54.6  percent  more 
lines  clipped  per  second  than  the  first 
implementation  of  the  Cohen-Suther- 
land  algorithm! 

Additional  improvements  can  be  de¬ 
veloped  to  increase  the  performance 
further.10  Presently,  a  record  of  about 
80  percent  more  lines  clipped  has  been 
achieved.  The  number  of  comparisons 


..  -.u 

Algorithm 

‘Vi  •  •  1  ..  •  . 

■ 

Draw 
(in  sec.) 

Not  Draw 
(in  sec.) 

Ciips/sec. 

Cohen-Sutherland 

104 

85 

1,176 

Cohen-Sutherland-Duvanenko 

74 

55 

1,818 

Dr.  Dobb’s  Journal,  July  1990 

601 


is  the  biggest  time  consumer  in  the 
Cohen-Sutherland  algorithm.8  If  you 
think  of  some  other  improvements,  let 
me  know.  I’d  love  to  hear  about  your 
results  and  see  the  code. 
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Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
online.  To  order  the  disk,  send  $14.95 
(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb's  Journal,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ). 
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Drawing  Character 
Shapes  with 

Bezier  Curves 

A  modern  approach  to  an  old  problem 


Todd  King 


Text  is  the  most  common  me¬ 
dium  of  exchanging  ideas,  theo¬ 
ries,  and  concepts.  As  we  all 
learned  in  school,  the  building 
blocks  of  printed  text  are  typo¬ 
graphic  characters.  A  complete  set  of 
characters  of  a  certain  design  or  style 
is  known  as  a  “font.”  Currently,  there 
exist  more  than  10,000  different  font 
designs  for  the  Roman  alphabet. 

Until  the  last  few  years,  most  com¬ 
puter  systems  did  not  devote  resources 
to  presenting  text  in  any  but  the  most 
primitive  form:  either  dot-matrix  or 
stroked  characters.  With  increased  com¬ 
puting  power,  larger  memory,  and 
higher  resolution  displays  and  printers, 
personal  computer  systems  can  now 
handle  typographic  characters  with 
greater  fidelity  than  before. 

In  this  article,  we’ll  take  a  look  at  one 
of  the  most  common  ways  for  repre¬ 
senting  and  rendering  typographic  char¬ 
acter  shapes  on  a  computer  —  the 
Bezier  curve. 

Bezier  Curves 

A  Bezier  curve  is  a  parametric  curve 
that  is  specified  using  a  small  number 


Todd  is  a  programmer/analyst  with  the 
Institute  of  Geophysics  and  Planetary 
Physics  at  UCLA  where  he  works  on 
various  software  projects.  He  is  writing 
a  hook ,  Dynamic  Data  Structures,  which 
will  be  published  by  Academic  Press, 
late  in  1990.  Todd  can  be  reached  at 
1104  N.  Orchard,  Burbank,  CA  91506 


of  points.  This  implies  a  compact  and 
efficient  means  for  storing  the  defini¬ 
tion  of  a  character  shape.  Bezier  curves 
have  other  properties  that  make  them 
particularly  useful  for  representing  the 
shapes  found  in  typographic  charac¬ 
ters  (see  next  section). 

The  Bezier  curve  was  originally  de¬ 
veloped  in  the  early  1970s  by  the  French 
mathematician  Pierre  Bezier  for  Renault 
(the  automaker),  as  a  way  to  describe 
the  three-dimensional  shapes  and  sur¬ 
faces  of  cars.  In  the  two-dimensional 
world,  Bezier  curves  were  not  used  un¬ 
til  recently  by  manufacturers  of  digital 


typesetting  equipment.  Instead,  they  re¬ 
lied  on  straight  lines,  circles,  and  arcs 
to  represent  typographic  shapes  — 
mostly  because  these  were  well-under¬ 
stood  and  easy  to  compute  efficiently. 

Adobe,  in  its  implementation  of  the 
Postscript  page  description  language, 
was  the  first  mainstream  manufacturer 
to  use  Bezier  curves.  Since  then,  other 
manufacturers  have  followed  suit. 

The  equation  that  defines  a  general 
Bezier  curve  is  a  polynomial.  This  poly¬ 
nomial  can  be  of  any  order  or  degree, 
but  as  the  order  increases,  so  does  the 
computational  requirement.  Rather  than 
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(continued  from  page  46) 
try  to  model  a  complex  shape  with  a 
higher-degree  polynomial,  it  is  more 
practical  to  construct  a  composite  curve 
that  is  built  by  joining  together  several 
simpler  Bezier  curves.  These  simpler 
curves  are  of  degree  three  —  the  cubic 
Bezier  form. 

With  this  form,  a  Bezier  curve  seg¬ 
ment  is  specified  by  four  points,  called 
“control  points.”  Two  of  these  points 
define  the  positions  of  the  curve’s  end 
points.  The  other  two  points  control 
the  shape  of  the  curve.  Figure  1  shows 
the  important  features  of  a  cubic  Bezier 
curve  (hereafter  referred  to  simply  as 
Bezier  curve). 

Representing  Characters 

A  Bezier  curve  has  several  properties 
that  make  it  well  suited  to  representing 
typographic  characters,  the  first  being 
that  the  defined  shape  is  both  continu¬ 
ous  and  smooth. 

Second,  the  curve  is  tangent  to  the 
line  formed  by  the  end  point  and  the 
nearest  control  point.  This  is  useful  in 
creating  smooth  curves  that  consist  of 
one  or  more  curve  segments  joined 
together.  The  reason  is  that  if  the  two 
curve  segments  are  joined  properly  then 
the  resulting  curve  will  also  be  con¬ 
tinuous.  This  occurs  if  the  adjacent  curve 
segments  share  a  common  end  point, 
and  if  the  nearest  control  points  for 
each  curve,  as  well  as  the  common  end 
point,  are  all  collinear. 

Third,  because  the  curves  are  de¬ 
fined  by  parametric  equations,  the  fonts, 
which  are  built  up  from  the  curves  can 
be  scaled  and  sized  at  the  time  of  dis¬ 
play.  This  is  done  by  multiplying  the 
results  derived  from  the  equations  by 
some  scaling  factor. 

Bezier  curves  are  also  well  behaved 
under  other  kinds  of  mathematical  trans¬ 
formations,  such  as  rotation  and  shear¬ 
ing.  This  was  a  problem  with  the  line/ 
arc  representation  used  by  many  digi¬ 
tal  type  manufacturers:  The  shapes  were 
well  behaved  for  scaling  and  transla¬ 
tion,  but  not  for  shearing.  (A  sheared 
circle  does  not  remain  a  circle  but  be¬ 
comes  an  ellipse.) 

In  addition,  Bezier  curves  have  the 
property  of  being  bounded  by  the  con¬ 
trol  points,  which  define  it.  No  portion 
of  the  curve  extends  beyond  the  edges 
of  the  box  formed  by  drawing  lines 
between  adjacent  control  points.  If  you 
collapse  the  box  so  that  all  the  control 
points  are  collinear,  then  the  Bezier 
curve  defines  a  straight  line.  This  means 
that  Bezier  curves  can  be  used  to  rep¬ 
resent  both  the  straight  and  the  curved 
features  of  a  character. 

Finally,  Bezier  curves  can  be  com¬ 
puted  relatively  efficiently  using  a  method 


known  as  the  “deCasteljau”  algorithm. 
While  not  as  fast  as  Bresenham  or  other 
circle-drawing  methods,  it  is  fast  enough 
for  modern  microprocessors. 

The  Bezier  Equation 

The  general  form  of  a  Bezier  curve 
segment  is: 


_ Dl_  a,t'(1-t) 

i!  (n  - 1)1 


The  cubic  form  of  the  Bezier  curve, 
for  a  two-dimensional  coordinate  space, 
can  be  more  easily  described  by  a  pair 
of  parametric  equations,  which  deter¬ 
mine  the  x  and  y  coordinates  of  points 
on  the  curve. 

The  x  component  of  a  Bezier  curve 
is  defined  by  the  formula: 

x(t)  =  (1  -  t)3x,  +  3t(l-  t)2x2  +  3t2(l-t)x3 

+  t3x4 

The  formula  for  y  is  the  same,  except 
y  replaces  x  in  the  equation  above.  The 
variable  t  is  the  parameter  for  the  equa¬ 
tion  and  is  varied  from  0  to  1 . 

Designing  Fonts 

When  you  design  a  font  it  is  important 
to  draw  the  character  shapes  at  a  size 
that  will  ensure  that  all  features  of  the 
font  can  be  accurately  captured.  Also, 
because  it  is  possible  that  the  font  may 
be  enlarged  greatly  (for  example,  as 
part  of  a  billboard),  it  is  best  to  draw 
the  prototypical  font  at  an  equally  large 
scale. 

In  Adobe’s  implementation,  charac¬ 
ter  shapes  are  defined  on  a  grid  of  1000 
x  1000  points,  where  a  point  is  1/  72 
of  an  inch.  An  11-inch  page  is  approxi- 


Figure  1:  Elements  of  a  Bezier  curve 


Figure  2:  Attributes  of  typographic 
characters 


mately  825  points  long.  So,  for  typical 
publishing  applications  this  is  a  rea¬ 
sonable  choice. 

Characters  within  a  font  have  certain 
features  or  attributes  (see  Figure  2), 
which  are  used  in  their  design.  One 
attribute  is  the  baseline.  This  is  a  hori¬ 
zontal  line  that  passes  through  the  font 
and  is  used  for  vertical  alignment  of  a 
character.  All  (or  nearly  all)  parts  of  an 
“a”  remain  above  its  baseline,  while 
the  tail  of  a  “g”  (also  known  as  its 
descender)  extends  below. 

Another  feature  is  the  sidebearings. 
This  is  the  amount  of  space  on  the  left 
and  right  sides  of  a  character.  The  side- 
bearings  can  be  different  for  each  char¬ 
acter  in  a  font,  but  typically  are  the 
same.  The  sidebearings  are  included 
in  the  total  width  of  the  character.  In 
mono-spaced  fonts  (such  as  computer 
line-printer  fonts),  the  character  width 
is  the  same  for  all  characters.  Typo¬ 
graphic  fonts  have  proportionally 
spaced  characters,  where  each  charac¬ 
ter’s  width  depends  on  its  individual 
design. 

You  may  have  heard  or  read  about 
“hints”  buried  in  the  definitions  of  Post¬ 
script  fonts  (Type  1  Adobe  format). 
These  hints  describe  minor  adjustments 
to  the  way  in  which  the  shape  is  calcu¬ 
lated  as  the  size  of  the  letter  becomes 
very  small.  This  is  necessary  because 
the  typical  display  device  is  a  raster 
device  —  composed  of  discrete  pixels. 
As  the  letter  is  reduced  in  size,  there 
may  be  some  distortion  of  the  charac¬ 
ter  due  to  round-off  errors  related  to 
the  calculations  of  which  pixel  a  line 
is  in.  The  “hints”  provide  information 
to  the  rendering  system  so  that  the 
distortion  is  minimized,  and  the  shape 
is  consistent  with  the  font  designer’s 
original  intent. 

Rendering  Bezier  Curves 

The  most  straightforward  way  of  ren¬ 
dering  a  Bezier  curve  is  to  use  the 
parametric  equations  shown  earlier.  It 
is  not  too  difficult  to  express  these  two 
equations  in  C,  Pascal,  or  Fortran,  us¬ 
ing  floating-point  values.  To  calculate 
a  series  of  points  along  the  curve,  just 
vary  the  parameter  t  from  0  to  1  in 
fractional  increments  and  calculate  the 
corresponding  values  for  x  and  y. 

A  faster  but  less  straightforward 
method  of  rendering  Bezier  curves  is 
the  deCasteljau  algorithm.  With  this  ap¬ 
proach,  the  control  box,  which  sur¬ 
rounds  the  Bezier  curve  is  divided  into 
two  smaller  control  boxes.  These  boxes 
are  each  successively  divided  into  two 
smaller  boxes,  and  so  on,  in  a  recursive 
manner,  until  a  specific  degree  of  accu¬ 
racy  is  obtained. 

At  that  time,  the  specific  segments 
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(continued  from  page  48) 
of  each  of  the  smallest  control  boxes 
are  drawn.  The  net  result  is  that  the 
Bezier  curve  is  approximated  by  a  se¬ 
ries  of  straight-line  segments.  The  first 
order  bounding  box  is  defined  by  the 
points  aO,  bO ,  cO,  dO.  One  of  the  sec¬ 
ond  order  bounding  boxes  is  defined 
by  the  points  aO,  al ,  a2,  a3.  The  other 

Bezier  curves  were 
originally  developed  for 
designing  French 
automobiles 


second  order  bounding  box  is  defined 
by  the  points  a3,  b2,  cl,  dO.  Figure  3 
shows  how  all  these  points  relate  to 
one  another.  The  point  al  is  calculated 
by  finding  the  midpoint  of  the  line  that 
connects  aO  and  bO.  The  other  points 
( a2 ,  a3,  bl,  b2,  and  cl)  are  calculated 
in  a  similar  manner. 

A  Sample  Program 

Listing  One,  page  102,  contains  the  en¬ 
tire  source  for  a  program,  which  dis¬ 
plays  a  character  shape  represented  by 
a  composite  Bezier  curve. 

To  do  this,  we  must  first  have  a  func¬ 
tion  that  will  draw  a  Bezier  curve  seg¬ 
ment.  In  the  listing  is  a  function  called 
draw_bezierl( ).  This  function  accepts 
a  variable  of  type  BEZIER_BOX,  which 
contains  the  x  and  y  coordinates  of  the 
four  control  points  for  the  Bezier  curve 
segment.  The  function  then  calculates 
the  points  on  the  Bezier  curve  from  the 
parametric  equations  (as  discussed  ear¬ 
lier),  and  draws  line  segments  between 
them. 

A  second  function,  called  draw_be- 
zier2( ),  takes  the  same  arguments  as 
draw_bezierl( ),  but  draws  the  curves 
using  the  deCasteljau  rendering  method, 
also  discussed  earlier. 

Both  the  functions  draw_bezierl( ) 
and  draiv_bezier2( )  have  been  writ¬ 
ten  so  that  the  accuracy  at  which  the 


Figure  3-'  The  control  {Mints  for  the  deCas¬ 
teljau  algorithm.  Depicted  is  one  level  of 
division  of  a  Bezier  bounding  box 


Bezier  curves  are  drawn  can  be  ad¬ 
justed.  For  draw_bezierl( ),  the  Bezier 
curve  is  approximated  by  drawing 
straight  lines  between  points,  which 
are  separated  by  a  distance,  which  is 
on  the  order  of  the  resolution  of  the 
display  device. 

This  display  threshold  value  is  main¬ 
tained  in  the  variable  DPU.  To  arrive 
at  an  appropriate  value  for  DPU,  calcu¬ 
late  the  maximum  resolution  of  the 
screen  and  divide  that  by  the  size  of  the 
prototypical  font.  Because  the  DPU  de¬ 
pends  on  the  resolution  of  the  display 
device,  the  application  is  somewhat 
device-dependent. 

For  draw_bezier2( ),  the  display 
threshold  is  determined  by  the  func¬ 
tion  accurate( ).  In  this  implementa¬ 
tion,  how  you  determine  when  the  ap¬ 
proximation  is  accurate  enough,  is  to 
keep  a  simple  count  of  the  number  of 
times  the  curve  has  been  subdivided. 
The  variable  B_cutoffc ontains  the  num¬ 
ber  of  divisions,  which  are  considered 
accurate.  The  variable  B_level  contains 
the  current  division  count.  For  screens 
of  resolution  of  about  600  x  400,  a 
cut-off  of  3  is  quite  good  and  nearly  as 
accurate  as  the  literal  rendering  em¬ 
ployed  in  draiv_bezierl( ).  If  a  cut-off 
of  4  is  used,  the  resulting  characters  are 
indistinguishable  between  draw_be- 
zierl( )  and  draw_bezier2( ). 

To  make  drawing  a  particular  char¬ 
acter  easier,  I  included  a  function  called 
draw_letter(  ).  This  function  allows  you 
to  place  the  character  anywhere  on  the 
screen.  It  also  allows  you  to  define  the 
color  of  the  font  outline,  the  fill  color, 
the  desired  point  size  to  display  the 
character,  and  the  rendering  function. 

Another  argument  to  draw_letter( ) 
is  an  array  of  BEZIER_BOX  variables. 
This  should  contain  a  series  of  Bezier 
curve  definitions  which,  when  drawn 
collectively,  will  result  in  the  desired 
character.  The  array  of  curve  defini¬ 
tions  is  ended  by  a  sentinel  curve  defi¬ 
nition  whose  first  x  coordinate  is  set 
to  BFLAG.  The  second  xj'pair  of  this 
sentinel  curve  is  the  coordinates  of  a 
point  inside  the  character’s  outline.  This 
point  is  used  by  the  fill  function. 

When  you  run  the  program,  you  will 
see  a  series  of  “a”  letterforms  printed 
on  the  same  line  in  decreasing  size. 
You  can  choose  which  rendering 
method  you  would  like  by  supplying 
either  the  letter  “d"  (for  deCasteljau) 
or  the  letter  “1"  (for  literal)  as  the  first 
command-line  argument.  You  must  spec¬ 
ify  one  of  these. 

Timing 

Although  my  first  implementation  of 
drawing  fonts  with  Bezier  curves  used 
the  literal  rendering  method,  I  was 
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Method 

Cut-off 

Time  (sec) 

deCasteljau 

3 

6 

deCasteljau 

4 

11 

literal 

55 

Table  1:  Character  rendering  timings 


amazed  at  the  difference  in  speed  with 
which  the  characters  were  rendered 
with  the  deCasteljau  method.  At  the 
same  time,  the  quality  of  the  presenta¬ 
tion  was  the  same  as  with  the  literal 
method.  Table  1  presents  some  of  these 
timings. 

These  timings  were  performed  on  an 
AT  compatible  286  running  at  12.5  MHz 
with  a  Hercules  graphics  display  system. 

There  are  a  few  calls  in  the  source 
that  are  unique  to  Turbo  C.  These  are 
related  to  Turbo  C’s  graphics  library 
and  area:  closegraph(),Jloodfill(),  init- 
driverp ),  linetoO,  movetoO,  setcolorp), 
setfillstyle( ),  and  setlinestylef ).  One  call 
whose  arguments  may  need  changing 
is  initdriver( ).  The  last  argument  in 
this  call  is  the  path  to  where  the  device 
drivers  are  stored.  You  may  need  to 
change  this  to  match  your  system’s  con¬ 
figuration. 

Improvements 

There  is  a  lot  of  room  for  extending 
this  program.  The  most  obvious  is  that 
the  font  has  only  one  character  in  it  — 
the  letter  a.  This  allows  for  only  limited 
expression.  It  actually  took  me  a  cou¬ 
ple  of  hours  to  develop  the  letter  (from 
scratch)  to  an  acceptable  form.  Some 
letters  in  the  alphabet  should  be  easier 
and  a  few  would  be  harder. 

Another  improvement  would  be  to 
design  a  structure  that  would  contain 
character-width  information  for  an  en¬ 
tire  font.  I  chose  not  to  do  this  for 
reasons  of  simplicity. 

Other  possible  improvements  include 
speeding  up  the  Tenderer  and  improv¬ 
ing  quality  at  low-resolutions  by  add¬ 
ing  a  hinting  mechanism. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listing  begins  on  page  102.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  4. 
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Information  Models, 
Views,  and  Controllers 

The  key  to  reusability  in  Smalltalk-80  lies  within  MVC 

Adele  Goldberg 


We  have  all  experienced  the 
benefits  of  reuse  in  every 
aspect  of  life.  For  example, 
when  traffic  control  signs  are 
reused  throughout  a  city,  a 
state,  and  even  internationally,  our  abil¬ 
ity  to  navigate  streets  and  highways  is 
helped.  Reuse  of  text  editors  and  pic¬ 
ture  editors  across  applications  on  the 
same  or  different  hardware  systems  im¬ 
proves  our  ability  to  use  those  applica¬ 
tions.  The  value  of  a  graphing  or  dia¬ 
gramming  technique  increases  with  the 
number  of  ways  it  can  be  reused  on 
different  data,  thereby  improving  our 
ability  to  quickly  analyze  new  kinds  of 
data.  Reuse  benefits  the  user  as  well  as 
the  application  developer. 

In  the  context  of  software  applica¬ 
tions,  to  reuse  a  software  component 
generally  means  keeping  it  the  same, 
while  changing  the  context  or  style  in 
which  it  is  used.  Text,  for  example, 
might  stay  the  same,  while  the  fonts 
and  document  layout  containing  that 
text  might  vary;  data  might  stay  the 
same,  but  it  might  be  presented  differ¬ 
ently  in  terms  of  graphs,  pie  charts, 
tables,  or  animations;  or  the  ways  of 
presenting  information  might  stay  the 
same,  while  the  techniques  for  making 
selections  and  issuing  commands  might 
be  different. 


Adele  is  the  president  and  CEO  of 
ParcPlace  Systems.  She  can  be  reached 
at  1550  Plymouth  Street,  Mountain 
View,  CA  94043. 


One  major  area  of  software  develop¬ 
ment  that  can  benefit  from  reusable 
software  is  the  design  and  implementa¬ 
tion  of  applications  having  graphical 
user  interfaces.  As  a  consequence  of 
the  widespread  availability  of  bit¬ 
mapped  displays,  the  attention  of  many 
programmers  shifted  from  emphasis  on 
implementing  models  of  data,  transac¬ 
tions,  and/or  business  functions,  to  cre¬ 
ating  appealing  user  interfaces.  Require¬ 
ments  for  adhering  to  the  many  user 
interface  standards  have  not  decreased 
the  importance  of  seeking  innovative 


ways  to  present  information  on  the  dis¬ 
play  screen  and  to  support  users  in 
accessing  and  manipulating  that  infor¬ 
mation. 

Because  reusability  of  user  compo¬ 
nents  is  a  key  element  in  improving  the 
productivity  of  software  developers,  an 
important  question  to  answer  is  which 
software  components  should  be  tar¬ 
geted  for  reuse?  This  article  answers 
the  reuse  question  through  a  review 
of  the  implementation  architecture  called 
“Model-View-Controller”  (MVC)  that  is 
available  to  application  developers  us¬ 
ing  the  Objectworks  for  Smalltalk-80 
program  development  system  devel¬ 
oped  by  ParcPlace  Systems.  The  intent 
of  the  article  is  to  demonstrate  the  ad¬ 
vantages  of  this  architecture  in  devel¬ 
oping  graphical  interactive  applications. 

MVC 

The  Model-View-Controller  architecture 
for  the  Objectworks  for  Smalltalk-80 
system  was  designed  specifically  to  help 
programmers  create  graphical  user  in¬ 
terfaces  through  the  reuse  of  software 
components  that  represent  the  presen¬ 
tation  and  interaction  aspects  of  an 
application.  The  use  of  object-oriented 
software  was  essential  in  motivating 
the  design  for  MVC  and  was  the  basis 
for  its  implementation. 

One  way  to  improve  productivity  in 
software  development  is  to  reuse  user 
interface  designs  across  different  appli¬ 
cations.  Another  entails  leveraging  spe¬ 
cial  support  for  multiple  ways  of  view- 
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(continued  from  page  54) 
ing  and  interacting  with  an  information 
model  in  accordance  with  diverse  user 
preferences.  For  example,  some  users 
might  want  to  view  their  data  as  tables 
of  numbers,  while  others  might  prefer 
graphs,  descriptive  text,  or  animations. 
These  alternatives  might  be  mapped 
onto  a  set  of  software  components  that 
can  be  attached  interchangeably  to  a 
common  information  model.  The  in¬ 
formation  model  is  then  shared  among 
the  projects  requiring  the  different  gra¬ 
phical  interfaces.  The  development  ef¬ 
fort  and  cost  involved  in  implementing 
the  information  model  is  incurred  just 


MVC 


once.  Many  different  information  mod¬ 
els  can  be  presented  with  similar  user 
interfaces. 

Recognizing  and  exploiting  these  op¬ 
portunities  for  reuse  led  to  the  design 
of  two  kinds  of  elements  in  Objectworks 
for  Smalltalk-80  —  a  library  of  presen¬ 
tation  and  interaction  components,  and 
a  set  of  tools  supporting  a  methodol¬ 
ogy  for  linking  presentation  and  inter¬ 
action  components  to  underlying  infor¬ 
mation  models.  These  kinds  of  ele¬ 
ments  provide  the  basic  building  blocks 
for  the  MVC  architecture. 

“Model”  refers  to  a  representation 
of  the  application  domain  as  an  infor¬ 


mation  model,  while  “view”  is  a  speci¬ 
fication  of  how  aspects  of  a  model  are 
presented  to  the  user.  The  “controller” 
is  the  specification  of  how  the  user  can 
communicate  or  interact  with  the  ap¬ 
plication  in  order  to  request  changes 
in  the  view  or  in  the  underlying  model. 
Consider,  for  example,  a  real-time  clock 
that  is  to  appear  on  the  display  screen. 
The  information  model  is  an  object  rep- 

The  ability  to  reuse 
software  components 
depends ,  of  course,  on 
the  ability  of  the 
software  system 


resenting  DateAndTime ,  which  is  im¬ 
plemented  in  terms  of  the  computer 
hardware’s  built-in  clock.  Suppose 
DateAndTime  can  report  the  current 
time  of  day  and  the  name  of  the  current 
day  of  the  current  month.  On  the  screen, 
DateAndTime  might  appear  as  a  digital 
watch  in  which  the  day  and  month  are 
printed  on  one  text  line  and  the 
hours:minutes:seconds  appear,  con¬ 
stantly  updated,  on  a  second  text  line. 
This  text-oriented  presentation  is  the 
“view”  of  the  model  DateAndTime. 

Another  view  might  be  of  an  analog 
clock,  with  a  second  hand  moving 
around,  ticking  off  seconds.  Perhaps 
the  user  has  direct  access  to  resetting 
the  time  information.  In  the  textual  view, 
the  user  could  select  the  text  of 
hours:minutes:seconds  with  a  pointing 
device  such  as  a  mouse  and  then  use 
a  text  editor  to  modify  the  visible  infor¬ 
mation.  This  in  turn  would  modify  the 
underlying  DateAndTime  model,  and 
the  change  would  be  reported  back  to 
the  view  that  is  an  analog  clock  for 
immediate  update.  The  user’s  ability 
to  text  edit  is  handled  by  a  “controller.” 

The  design  of  the  MVC  roles  in  Small- 
talk-80  came  about  as  a  result  of  a 
two-stage  factoring.  First,  the  design 
and  implementation  of  the  domain- 
specific  aspects  (the  model)  is  sepa¬ 
rated  from  work  on  the  user  interface. 
Second,  the  user  interface  is  divided 
into  presentation  and  interaction  as¬ 
pects. 

The  ideal  scenario  for  the  construc¬ 
tion  of  application  software  under  the 
MVC  paradigm  begins  by  focusing  on 
the  design  and  implementation  of  the 
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information  model  components  of  an 
application.  (Even  here,  there  are  sub¬ 
stantial  opportunities  for  reuse  from 
previous  projects.)  Once  the  underly¬ 
ing  model  is  completed,  the  develop¬ 
ers  reach  into  a  library  of  reusable  user 
interface  components  and  select  (and 
tailor)  various  graphical  presentations 
and  styles  of  user  interaction  appropri¬ 
ate  for  the  target  users’  preferences.  In 
this  way,  it  is  possible  to  create  several 
implementations  quickly,  varying  the 
presentation  and  interaction  styles  accord¬ 
ing  to  user  needs.  In  our  experience,  it 
is  common  for  the  underlying  model 
and  presentation  style  to  stay  fixed 
across  a  broad  set  of  end  users,,  whereas 
interaction  style  (such  as  typing  com¬ 
mands  versus  command  keys,  or  the 
selection  of  icons)  varies  considerably. 
By  separating  the  notion  of  presenta¬ 
tion  from  interaction,  this  disparity  can 
be  accommodated. 

Reuse  Through  MVC 

The  ability  to  reuse  software  compo¬ 
nents  depends,  of  course,  on  the  abil¬ 
ity  of  the  software  system  or  language 
to  describe  and  maintain  identifiable 
modules.  The  current  wisdom  in  the 
software  industry  is  that  such  a  module 
is  a  packaging  of  behavior  (procedures) 
and  properties  that  both  describe  the 
module  and  comprise  the  data  required 
to  implement  the  behavior.  The  mod¬ 
ule  is  referred  to  as  an  object;  a  system 
that  supports  the  description,  implemen¬ 
tation,  and  testing  of  objects  is  said  to 
be  object  oriented.  Such  a  system  must 
also  provide  tools  for  factoring  and 
re-factoring  modules  in  terms  of  ab¬ 
stract  and  concrete  specifications  of  be¬ 
haviors  to  be  represented  by  modules 
of  various  scopes  and  complexities.  The 
software  developer  implements  an  ap¬ 
plication  by  creating  objects  that  com¬ 
bine,  refine  (or  specialize),  and/or  es¬ 
tablish  information  dependencies 
among  existing  (that  is,  reusable)  and 
newly  synthesized  object  types.  The 


MVC  approach  suggests  factoring  a  sys¬ 
tem  into  three  kinds  of  objects.  Model 
objects  share  a  generic  ability  to  inform 
views  and  controllers  of  changes  in 
their  state.  View  objects  understand  how 
to  draw  graphical  representations  of  a 
Model  within  an  identified  area  of  the 
display  screen  and  how  to  update  those 
representations  according  to  informa¬ 
tion  solicited  from  the  Model.  Control¬ 
ler  objects  support  a  variety  of  default- 
and  developer-defined  ways  of  han¬ 
dling  user  events,  scheduling  access 
to  Views  supporting  user  interaction 
via  input  devices,  and  sending  editing 
commands  to  Views  or  Models.  Each 
of  these  three  kinds  of  objects  is  de¬ 
fined  in  terms  of  a  hierarchy  of  object 
descriptions,  as  shown  in  Figure  1 . 

Reusing  the  Expertise  of  Others 

The  technical  history  of  MVC  is  tied  to 
the  idea  that  programmers  are  not  typi¬ 
cally  trained  as  graphic  artists  nor  as 
human-factor  engineers.  But  the  knowl¬ 
edge  of  such  experts  could  be  cap¬ 
tured,  in  the  form  of  presentation  tech¬ 
niques  and  interaction  frameworks,  and 
made  available  in  a  library  of  reusable 
software  components.  The  factoring  of 
MVC  draws  attention  to  particular  kinds 
of  components  that  should  be  made 
available  for  reuse  in  order  to  take  ad¬ 
vantage  of  the  knowledge  of  these  ex¬ 
perts. 

Two  programming  techniques  are 
needed  to  support  such  reuse:  Compo¬ 
sition  and  refinement.  Composition  en¬ 
tails  combining  existing  elements  to 
create  something  new.  Objectworks  for 
Smalltalk-80  supports  two  kinds  of  com¬ 
position:  Composition  via  delegation, 
stating  that  a  newly  created  object  has 
properties  that  refer  to  (instances  of) 
existing  classes  (an  action  that  requires 
manipulation  of  these  properties  is  dele¬ 
gated  to  the  appropriate  object);  and 
composition  via  dependency,  stating 
that  an  instance  of  one  class  depends 
on  the  change  in  behavior  of  (instances 
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Figure  1:  Hierarchy  of  Models,  Views,  and  Controllers  for  Text  (each  subclass 
adds  a  refinement  in  behavior) 
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of)  another  class. 

Additionally,  two  kinds  of  refinement 
are  supported:  Refinement  via  inheri¬ 
tance  (subclassing),  stating  that  a  newly 
created  object  acquires  the  properties, 
protocol,  and  implementation  of  the 
protocol,  of  an  existing  class;  and  re¬ 
finement  via  parametrization,  stating  that 
a  new  object  is  an  instance  of  an  exist¬ 
ing  class  of  objects  by  filling  in  details 
about  the  properties  that  distinguish 
this  instance  from  other  instances  of 
the  class. 

Through  composition,  you  can  reuse 
existing  models  (that  correspond  to  ge¬ 
neric  objects),  existing  views,  and  con¬ 
trollers  that  define  a  look  and  feel  for 
the  user  interface  and  existing  tools, 
for  example,  a  text  editor  or  document 
outline  browser. 

Through  refinement,  you  can  reuse 
existing  application-building  frame¬ 
works  that  encompass  sets  of  views 
and  controllers,  as  well  as  paramet- 
risizable  models.  You  can  also  reuse 
existing  parameterizable,  tailorable  com¬ 
plete  applications. 

Through  composition  and  refine¬ 


ment,  object-oriented  MVC  design  al¬ 
lows  the  software  analyst/designer  to 
focus  on  creating  components  that  are 
immediately  reusable  and  that  provide 
for  future  incorporation  of  new  views, 
controllers,  and/or  models. 

A  Model  for  Counting 

The  Smalltalk-80  code  in  Listing  One 
(page  106)  consists  of  a  simple  model 
for  maintaining  a  numeric  counter,  as¬ 
sociated  views,  and  controllers.  This 
model  is  called  “Counter.”  Using  a  va¬ 
riety  of  viewing  objects,  the  current 
value  of  the  counter  is  presented  on 
the  display  screen  in  five  different  ways. 
Two  viewing  classes  are  offered  in  the 
example:  CounterView  and  BarView. 
The  same  controller  is  used  for  all  of 
these  views.  It  specifies  that  the  user 
selects  a  menu  item,  either  “Increment” 
or  “Decrement,”  in  order  to  change  the 
numeric  value  by  an  increment  or  dec¬ 
rement  of  one.  Presentation  of  a  menu 
that  appears  when  the  user  presses  a 
mouse  button  is  handled  by  the  con¬ 
troller,  an  instance  of  class  Counter- 
Controller. 


1 .  CounterView  open:  aModel 

2.  CounterView  openWith  Graphical  Buttons:  aModel 

3.  CounterView  openWith  Text  Buttons:  aModel 

4.  BarView  open:  aModel 

5.  BarView  open:  aModel  withHeight:  20 
Where  aModel:  =  Counter  new 


Figure  2:  Five  possible  views  of  a  counter.  By  initializing  the  views  with  the 
same  model  of  a  counter ;  all  views  present  the  same  numeric  values,  and 
each  view  updates  whenever  the  counter  value  is  changed. 
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The  five  examples  are  shown  in  Fig¬ 
ure  2,  and  the  initialization  messages 
to  classes  CounterView  and  BarView 
are  given  in  the  comment  of  the  code 
for  the  classes. 

Note  that  in  the  Objectworks  for  Small¬ 
talk-80  system,  the  library  of  reusable 
components  includes  the  classes  shown 
in  Table  1,  in  addition  to  classes  Model , 
View ,  and  Controller. 

The  algorithm  for  displaying  a  view 
is  the  response  to  the  message  dis- 
playView  as  defined  in  classes  Coun¬ 
terView  and  BarView.  Note  that  in  List-- 

The  use  of  object- 
oriented  software  was 
essential  in  motivating 
the  design  for  MVC 
and  was  the 
basis  for  its 
implementation 


ing  One,  double  quote  marks  surround 
comments  that  are  dispersed  through¬ 
out  the  code.  Formatting  is  done  to  aid 
readability. 

By  initializing  each  view  with  the 
messages  shown  in  Figure  2  with  the 
same  model  of  a  counter  (that  is,  where 
aModel :  =  Counter  new),  all  the  views 
present  the  same  numeric  values  and 
each  view  updates  whenever  the 
counter  value  is  changed. 

Advantages  of  the  MVC  Approach 

Three  primary  advantages  derive  from 
adopting  the  MVC  approach  and  using 
it  to  factor  graphical  interactive  appli¬ 
cations.  The  advantages  are:  Multiple 
Viewing,  Development  Productivity, 
and  Quality.  Let’s  look  at  each  briefly. 

Multiple  Viewing.  Factoring  the  under¬ 
lying  model  from  its  graphical  presen¬ 
tation  and  interaction  allows  the  pro¬ 
grammer  to  couple  the  model  to  several 
alternative  interfaces.  Objectworks  for 
Smalltalk-80  provides  special  support  for 
objects  to  exchange  information  about 
changes.  Whenever  an  object  changes, 
it  broadcasts  a  message  that  it  has 
changed  and  what  aspect  (property) 
has  changed.  By  combining  this  sup¬ 
port  for  dependency  relationships  with 
the  factoring  of  views  and  controllers 
from  the  underlying  model,  several 
views  of  the  same  model  can  be  inter- 
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( continued  from  page  59) 

acted  with  simultaneously  on  the  same 

display. 

Development  Productivity.  As  noted 
eadier,  it  is  often  possible  to  create 
new  views  and  controllers  as  refine¬ 
ments  of  existing  ones,  while  retaining 
the  underlying  information  models.  It 
is  also  often  necessary  for  the  program¬ 
mer  only  to  implement  specific  kinds 
of  models  that  fit  into  existing  user 
interface  designs.  Therefore,  taking  ad¬ 
vantage  of  the  reusability  of  existing 
MVC  components  and  frameworks  can 
reduce  significantly  the  amount  of  pro¬ 
gramming  necessary  for  completing  an 
application  development  project. 

The  programmer  must  be  aware  of 
the  contents  of  the  available  libraries 
of  reusable  components  and  have  tools 
for  locating  and  experimenting  with 
those  components.  Objectworks  for 
Smalltalk-80,  for  example,  provides  the 
system  source  code  browser  with  MVC 
components  carefully  organized  into 
categories.  Each  of  the  program  devel¬ 
opment  tools  provided  with  the  prod¬ 
uct  are  created  using  the  MVC  approach. 
The  programmer  can  inspect  the  im¬ 
plementation  of  these  tools  using  the 
ParcPlace  debugger  and  special  MVC 
inspector. 

MVC  factoring  also  facilitates  the  pro¬ 
grammer’s  ability  to  respond  to  new 
technology  for  special  physical  needs 
or  interaction  media.  For  example,  this 
factoring  makes  it  a  simpler  task  to 
utilize  voice  output  instead  of  printed 
text  on  a  display  screen.  Only  the  pres¬ 
entation  aspects  of  an  MVC-style  appli¬ 
cation  would  change,  not  the  underly¬ 
ing  model. 

Quality.  Reusing  existing  components 
allows  those  components  to  become 
more  mature  and,  therefore,  more  ro¬ 
bust  as  they  are  tested  in  new  situ¬ 
ations.  Reusing  existing  designs  sup¬ 
ports  the  acquisition  of  the  expertise 
that  might  not  otherwise  be  available. 
And  improved  productivity  allows  for 
more  experimentation  and  testing. 

The  Future 

MVC  was  first  explored  and  tested  in 
earlier  versions  of  the  Objectworks  for 
Smalltalk-80  system.  It  was  designed  to 
enable  reuse  of  classes  representing  views 
and  controllers,  with  models  that  were 
otherwise  nongraphical.  The  current  im¬ 
plementation  was  designed  with  assump¬ 
tions  about  the  sophistication  of  the  pro¬ 
grammer  who  is  able  to  reuse  compo¬ 
nents  from  an  extensive  library.  The  de¬ 
sire  for  uniformity  of  software  architecture 
encouraged  the  application  of  the  MVC 
design  concepts  to  text  and  picture  edi¬ 
tors,  creating  considerable  experimen¬ 
tation  and  discussion  about  the  idea  of 


splitting  techniques  of  selection,  scroll¬ 
ing,  and  zooming  from  these  underlying 
graphical  entities.  The  original  MVC  was 
not  designed  to  deal  specifically  with 
underlying  models  that  are  themselves 
graphical  in  nature.  We  were  primarily 
trying  to  support  visualization  of  simu¬ 
lations  written  in  Smalltalk-80,  itself  de¬ 
signed  as  a  language  that  supports  general- 
simulation  descriptions.  Over  years  of 
use,  we  have  discovered  simplifications 
and  new  abstractions  that  make  these 
performance  and  implementation  issues 
easier  to  understand.  New  improvements 
will  appear  in  subsequent  releases  of 
Objectworks  for  Smalltalk-80. 


Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
online.  To  order  the  disk,  send  $14.95 
(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal ,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ). 

DDJ 

(Listing  begins  on  page  106.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  5. 
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PROGRAMMER'S  WORKBENC  H 


DOS  +  386  =  4 
Gigabytes! 

Directly  address  4  gigabytes  of 
memory  in  DOS  from  your  C 
or  assembly  language  applications 


Al  Williams 


Ever  since  Intel  introduced  the 
8088  and  8086,  programmers 
have  chafed  at  the  64K  limit  im¬ 
posed  by  the  8086’s  segmented 
architecture.  Dealing  with  data 
structures  greater  than  64K  has  required 
great  feats  of  legerdemain  and  been  all 
but  impossible  in  some  high-level  lan¬ 
guages.  The  80286  came  along,  but  it 
still  used  64K  segments;  and  though 
the  286  can  address  16  Mbytes  of  mem¬ 
ory,  DOS  knows  only  how  to  deal  with 
the  first  megabyte.  Then  the  80386  ar¬ 
rived  on  the  scene.  At  last,  program¬ 
mers  could  define  segments  ranging 
in  size  from  1  byte  to  4  gigabytes! 

Unfortunately,  DOS  still  limits  pro¬ 
grammers  to  1  Mbyte.  In  this  article,  I’ll 
show  a  method  for  accessing  the  entire 
80386  address  space  (4  gigabytes)  as 
one  flat  range  of  addresses.  I’ll  also 
provide  support  for  accessing  memory 
from  C,  controlling  the  80286/80386 
address  lines,  allocating  extended  mem¬ 
ory,  and  adding  assembly  language  to 
C  programs  without  an  assembler.  The 
programs  presented  all  compile  under 
Microsoft  C  5.1  with  or  without  the 
Microsoft  assembler,  MASM  5.1.  Mix’s 
PowerC  also  compiles  these  programs. 

Addressing  Revisited 

Recall  that  the  8086  uses  a  model  of 


While  Al’s  programming  endeavors 
range  from  AI  to  real-time  control  soft¬ 
ware,  he  specializes  in  system-level  soft¬ 
ware.  Be  sure  to  look  for  Al’s  386  DOS 
extender  in  an  upcoming  DDJ.  Al  can 
be  reached  via  CompuServe  (72010, 
3 5 74)  or  at  310  Ivy  Glen  Court,  League 
City,  TX  77573- 


memory  addressing  known  as  segmen¬ 
tation  to  break  memory  into  pieces  (or 
segments).  Inside  each  segment,  each 
particular  byte  has  a  unique  offset.  To 
address  a  byte  of  memory,  both  its 
segment  and  offset  must  be  known.  A 
full  address  is  usually  specified  as 
SSSSiOOOO,  where  SSSS  and  OOOO 
represent  the  segment  (or  segment  se¬ 
lector)  and  the  offset,  respectively.  The 
exact  interpretation  of  the  segment  se¬ 
lector  depends  on  the  operating  mode 
of  the  386. 

In  real  mode,  all  segments  are  ex¬ 
actly  64  Kbytes  long.  The  first  segment 
starts  at  the  bottom  of  memory,  and 
each  consecutive  segment  starts  l6  bytes 
after  the  previous  segment.  Because  a 
1 6-bit  number  (the  selector)  represents 
a  segment,  the  address  space  covers 
65,536  x  16  =  1,048,576  bytes  (or  1 
Mbyte).  Memory  above  1  Mbyte  is  nor¬ 
mally  not  accessible  in  real  mode. 

One  interesting  difference  between 
an  8086  and  an  80386  (or  80286)  in 
real  mode  is  the  handling  of  addresses 
at  the  1-Mbyte  boundary.  Generating 
an  address,  for  example,  of  FFFF:0011 
on  an  80386  actually  addresses  above 
the  1-Mbyte  limit.  An  8086  will  “wrap¬ 
around”  so  that  the  address  generated 
is  actually  the  same  as  0000:0001.  Since 
some  programs  may  depend  on  this 
wrap-around,  80286  and  80386  moth¬ 
erboard  designers  have  added  a  “gate” 
for  the  address  line  above  1  Mbyte  (the 
A20  line).  With  the  gate  turned  on, 
wrap-around  doesn’t  occur.  With  the 
gate  turned  off,  as  it  usually  is,  ad¬ 
dresses  appear  to  wrap  around  as  on 
an  8086. 

Protected  mode  treats  segments  dif¬ 


ferently.  In  protected  mode,  a  segment 
selector  contains  a  13-bit  number  that 
indexes  into  one  of  two  tables  known 
as  descriptor  tables.  One  bit  in  the  se¬ 
lector  determines  which  table  to  use, 
and  2  bits  control  segment  use  (the 
privilege  level,  which  we  won’t  use), 
for  a  total  of  16  bits.  The  descriptor 
table  stores  the  segment’s  start  address, 
length,  and  other  pertinent  data.  Figure 
1  shows  a  segment  selector  and  a  par¬ 
tial  descriptor  table.  For  our  purposes, 
we  need  only  part  of  the  information 
in  the  Global  Descriptor  Table  (GDT). 

Each  entry  in  the  GDT  is  8  bytes 
long.  If  the  80386  loaded  each  entry 
from  memory  every  time  it  accessed 
memory,  performance  would  suffer 
greatly.  To  prevent  this  from  happen¬ 
ing,  the  80386  caches  each  entry  inter¬ 
nally  whenever  the  program  loads  a 
segment  register.  In  real  mode,  the  pro¬ 
cessor  never  changes  the  cache,  be¬ 
cause  the  descriptor  tables  are  not  used. 

Note  that  in  real  mode,  any  two  num¬ 
bers  you  put  together  form  a  valid  ad¬ 
dress.  In  protected  mode,  however,  only 
certain  segment  selector  values  are  valid. 
In  protected  mode,  a  segment’s  length 
determines  which  offsets  are  legal.  If 
you  try  to  use  a  segment  improperly 
or  address  outside  of  its  range,  the 
80386  will  generate  an  error.  When 
switching  from  protected  mode  to  real 
mode,  Intel  recommends  setting  all  of 
the  segment  registers  to  selectors  that 
have  a  64K  limit  before  switching  to 
real  mode.  If,  however,  you  disregard 
the  documentation  and  set  the  seg¬ 
ment  registers  to  selectors  with  a  differ¬ 
ent  limit,  the  386  retains  that  limit  dur¬ 
ing  real  mode.  Set  up  protected-mode 


62 


Dr.  Dobb’s Journal,  July  1990 

613 


PROGRAMMER'S  WORKBENCH 


(continued  from  page  62) 

segment  registers  with  a  4  gigabyte  limit 

before  returning  to  real  mode. 

The  Plan 

To  successfully  address  the  entire  mem¬ 
ory  space  from  real  mode,  you  must 
perform  the  following  steps: 

1.  Disable  interrupts,  including  Non- 
Maskable  Interrupts  (NMI) 

2.  Switch  to  protected  mode 

3.  Load  one  or  more  segment  registers 
with  a  “big”  (4  gigabyte)  segment 

4.  Switch  back  to  real  mode 

5.  Enable  interrupts 

Once  these  steps  are  performed,  the 
segment  registers  remain  affected  until 
a  processor  reset  or  until  another  pro- 
tected-mode  program  reloads  them.  Be¬ 
cause  real  mode  does  not  use  segment 
descriptors,  the  descriptor  cache  is  never 
reloaded. 

For  DOS  use,  it  is  desirable  to  pro¬ 
vide  routines  to: 

•  Control  A20  gating 

•  Manage  allocation  of  extended  memory 

•  Move  data  by  using  the  new  segmen¬ 
tation  scheme  and  the  32-bit  registers 


Seg  Segment  Selector 


0 

Null  segment  (unusable) 

1 

Start 

Address 

Segment’s 

Limit 

Segment 

Type 

(Code,  Data,  etc.) 

System  Info. 

2 

Start 

Address 

Segment's 

Limit 

Segment 

Type 

(Code,  Data,  etc.) 

System  Info. 

:  1 

8191 

Start 

Address 

Segment's 

Limit 

Segment 

Type 

(Code,  Data,  etc.) 

1 

System  Info,  p 

j 

MHHI 

mmmmm 

Figure  1:  Segment  selector  and  descriptor  table 
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•  Convert  between  linear  addresses  and 
segmented  addresses 

Listings  One  through  Five  show  the 
SEG4G  library  that  performs  these  func¬ 
tions. 

Since  some 

programs  may  depend 
on  8086  wrap-around, 
80286  and  80386 
motherboard  designers 
have  added  a 
“gate”  for  the  address 
line  above  1  Mbyte 
(the  A20  line) 


Some  Assembly  Required 

Obviously,  to  switch  modes  and  per¬ 
form  other  386  magic,  we  need  some 
assembly  language  routines.  However, 
not  everyone  has  access  to  an  assem¬ 
bler  that  generates  80386  protected- 
mode  code.  Because  of  this,  you  may 
select  one  of  three  different  methods 
to  generate  the  assembly  language  code. 
The  first  method  uses  Microsoft’s  as¬ 
sembler  (MASM  Version  5.1).  The  sec¬ 
ond  and  third  methods  are  for  Micro¬ 
soft  C  Version  5.1  and  Mix’s  PowerC 
(see  Listing  Five,  page  112),  respec¬ 
tively,  and  do  not  require  an  assembler. 

While  PowerC  provides  an  asm( ) 
function,  Microsoft  does  not.  The  macro 
contained  in  ASMFUNC.H  (Listing  One, 
page  110)  remedies  this  absence.  This 
macro  allows  you  to  create  a  character 
array  containing  the  machine  code  you 
want  to  execute  and  then  call  it  as  a 
function,  complete  with  arguments  and 
an  integer  return  value. 

Before  compiling,  you  must  select 
one  of  the  assembly  methods  (ASM, 
DATA,  or  POWER)  at  the  top  of 
SEG4G.H  (Listing  Two,  page  110).  If 
you  pick  ASM,  you  must  assemble 
SEG51.ASM  (Listing  Four,  page  111) 
separately  and  link  it  with  SEG4G.  Be 
sure  to  change  the  .MODEL  directive 
at  the  top  of  SEG51  to  match  the  model 
you  are  using  for  your  C  programs.  In 
addition,  if  you  use  an  Intel  Inboard 
386/PC,  set  the  variable  inboard  to  1. 
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(Defined  near  the  top  of  SEG4G.C,  List¬ 
ing  Three,  page  110.) 

Using  the  SEG4G  Library 

To  force  the  segment  limit  on  the  GS 
and  ES  registers  to  4  gigabytes,  call  the 
extend_seg( )  routine.  This  call  modi¬ 
fies  the  registers  until  the  computer  is 
rebooted.  If  you  plan  to  access  ex¬ 
tended  memory,  you  must  also  enable 
the  A20  line  by  calling  the  a20(  )  func¬ 
tion.  The  call  a20(  1)  turns  on  A20,  and 
a20(0)  turns  it  off  again. 

The  library  defines  a  new  data  type, 
the  LPTR.  This  is  simply  a  32-bit  linear 


address  pointer  implemented  as  an  un¬ 
signed  long.  For  example,  the  start  of 
the  CGA  video  buffer  (B800:0000)  is 
equal  to  an  LPTR  of  0xB8000.  Two  of 
the  supplied  functions  convert  LPTRs 
to  C  far  pointers  and  vice  versa.  Call 
linear_to_seg( )  or  seg_to_linear( ),  as 
appropriate. 

While  preparing  to  access  memory, 
you  may  wish  to  allocate  extended  mem¬ 
ory.  The  most  common  method  for 
allocating  extended  memory  is  the  “top- 
down”  method.  This  method  tempo¬ 
rarily  reduces  the  amount  of  extended 
memory  reported  by  the  BIOS.  For  ex¬ 
ample,  if  you  have  1024K  of  extended 


memory  and  you  allocate  24K,  other 
programs  calling  the  BIOS  will  be  told 
that  only  1000K  of  memory  is  available. 
Because  extended  memory  always  starts 
at  the  same  place,  the  memory  is  allo¬ 
cated  top-down.  The  only  major  pro¬ 
gram  that  does  not  use  this  method  is 
DOS’s  VDISK  (or  RAMDRIVE).  It  uses 
a  peculiar  scheme  that  varies  from  ver¬ 
sion  to  version  of  DOS.  However,  be¬ 
cause  VDISK  uses  memory  from  the 
bottom  up,  you  can  control  allocation 
of  each  so  that  they  never  overlap. 

SEG4G  provides  several  functions  to 
manage  extended  memory  allocation. 
Most  of  these  functions  are  only  of 
interest  if  you  plan  to  stay  resident  or 
run  other  programs  that  use  extended 
memory  from  inside  your  program.  If 
you  don’t  do  either  of  these  things,  you 
can  simply  check  how  much  extended 
memory  is  available  and  then  use  it  as 
you  see  fit.  To  check  the  amount  of 
extended  memory  that  is  available,  call 
ext_size( ),  which  returns  the  number 
of  IK  pages  that  are  free. 

If  you  actually  need  to  allocate  ex¬ 
tended  memory,  you  may  use  the 
ext_alloc( )  and  ext_realloc( )  functions. 
These  functions  each  take  the  number 
of  IK  pages  desired  and  return  an  LPTR 
to  the  start  of  the  memory  block.  If  the 
request  cannot  be  honored,  the  rou¬ 
tines  return  (LPTR)-IL. 

Note  that  these  functions  are  not  like 
the  traditional  malloc( )  functions  found 
in  the  standard  C  libraiy.  You  should 
not  call  them  repeatedly  to  allocate 
small  chunks  of  memory  —  allocate  all 
of  the  extended  memory  you  need  in 
one  call.  This  is  especially  true  of  pro¬ 
grams  that  are  resident.  If  another  pro¬ 
gram  has  allocated  extended  memory 
after  your  first  call  to  ext_alloc( ),  you 
will  be  unable  to  expand  your  memory 
allocation. 

When  you  have  finished  using  the 
extended  memory  allocated,  free  it  with 
the  ext_free( )  function.  This  function 
frees  all  of  the  extended  memory  allo¬ 
cated  in  your  program.  Exercise  cau¬ 
tion  when  using  ext_free(  ,)with  other 
programs  that  use  extended  memory. 
ext  Jree(l)  forcibly  frees  all  extended 
memory  allocated  since  the  first  call  to 
ex t_alloc( ).  If  you  have  allocated  ex¬ 
tended  memory,  you  must  call 
ext_Jree(l)  before  you  exit  your  pro¬ 
gram.  Failure  to  do  so  will  lock  up  the 
computer.  Calling  ext_free(0)  attempts 
to  free  up  the  memory,  but  won’t  forc¬ 
ibly  do  so  if  another  program  has  also 
allocated  extended  memory. 

Once  you  have  done  all  of  the  re¬ 
quired  setup,  you  are  ready  to  access 
memory.  The  functions  big_read(  ),  big_ 
write( ),  and  big_xfer( dwill  read,  write, 
and  move  blocks  of  memory,  respec- 
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( continued  from  page  68) 
tively.  These  functions  do  not  have  to 
operate  on  extended  memory  —  they 
work  on  any  linear  address. 

The  use  of  big^_read(  Jand  big_write(  ) 
is  straightforward.  The  big_xfer( ) func¬ 
tion,  however,  becomes  more  efficient 
when  you  obey  certain  rules.  In  par¬ 
ticular,  performance  is  best  when  you 
move  32-bit  words  that  are  aligned  on 

If  another  program  has 
allocated  extended 
memory  after  your  first 
call  to  ext_alloc( ),  you 
will  he  unable  to  expand 
your  memory  allocation 


32-bit  boundaries.  For  example,  mov¬ 
ing  128  bytes  from  location  0x42050  to 
location  0xb8000  is  very  fast;  moving 
127  bytes  is  somewhat  less  efficient, 
and  moving  T28  bytes  from  location 
0x42051  to  location  0xb8000  is  also 
somewhat  slower.  The  big_xfer( )  func¬ 
tion  tries  to  optimize  transfers  by  mak¬ 
ing  as  many  full-word  moves  as  possi¬ 
ble.  It  also  attempts  to  move  as  much 
on  word  boundaries  as  possible. 

Examples 

TEST.C  (Listing  Six,  page  112)  shows 
an  example  program  using  the  SEG4G 
library.  (If  you  are  using  VDISK  or 
RAMDRIVE,  be  sure  that  you  have  at 
least  2K  of  extended  memory  not  be¬ 
ing  used  by  the  RAM  disk  before  run¬ 
ning  this  program.)  TEST  calls  ex- 
tend_seg()  to  set  up  the  4  gigabyte 
segments,  enables  A20,  and  then  at¬ 
tempts  to  allocate  IK  of  extended  mem¬ 
ory.  If  successful,  it  writes  a  data  byte 
to  the  entire  block  and  then  tries  to 
read  it  back.  Next,  the  block  is  ex¬ 
panded  to  2K  and  freed.  At  this  point 
a  loop  executes  so  you  can  examine 
memory  anywhere  in  the  computer’s 
address  range.  Figure  2  shows  a  ses¬ 
sion  with  the  test  program  and  the 
RAMDRIVE  driver  installed.  Notice  the 
RAMDRIVE  message  at  the  start  of  ex¬ 
tended  memory.  When  you  are  ready 
to  leave  the  program,  enter  a  Ctrl-Z. 

Listing  Seven,  page  115,  shows 
BLKTEST.C,  an  example  of  using 
big^_xfeif ).  Because  the  program  writes 
directly  to  the  screen,  you  must  change 
the  COLOR  define  to  match  the  type 
of  display  your  computer  has. 
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Conclusion 

The  SEG4G  library  offers  a  fast,  simple 
method  to  access  the  entire  386  mem¬ 
ory  range  from  DOS.  Even  programs 
that  are  not  running  on  a  386  can  make 
use  of  the  extended  memory  alloca¬ 
tion,  the  A20  control  routines,  and  the 
assembly  language  interface  macro  pre¬ 


sented  here.  SEG4G  can  help  imple¬ 
ment  memory  intensive  applications 
such  as  expanded  memory  drivers,  ram 
caches,  speech/video  buffers,  and  da¬ 
tabases. 

The  extended  memory  allocation  rou¬ 
tines  allow  SEG4G  to  coexist  peacefully 
with  other  extended  memory-aware  pro¬ 


grams,  but  they  won’t  protect  it  from 
applications  that  assume  they  own  all 
of  the  extended  memory  available.  In 
addition,  DOS  extenders,  multitaskers, 
memory  managers,  and  other  software 
that  use  protected  or  virtual  8086  mode 
may  not  be  compatible  with  SEG4G. 

As  with  any  undocumented  feature, 
this  one  could  vanish  at  any  time.  How¬ 
ever,  it  is  unlikely  that  the  segment 
cache  scheme  used  in  the  386  will 
change  any  time  soon.  While  SEG4G 
may  not  be  the  answer  to  all  of  your 
memory  problems,  it  can  provide  you 
with  more  usable  space  under  DOS, 
along  with  some  working  experience 
with  the  80386’s  protected  mode. 
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DDJ 

(Listings  begin  on  page  110.) 

Vote  for  your  favorite  feature/artiole. 

Circle  Reader  Service  No.  8. 


C : \SEG4G>SEG4G 

1280K  of  extended  memory  available 
IK  of  extended  memory  allocated  at 
Data  written  to  extended  memory 

10FC00.  1279K  remains . 

Data  read  back  OK . 

Expanding  allocation  to  2K 

2K  of  extended  memory  allocated  at  10F800.  1278K  remains . 
Extended  memory  freed.  1280K  Available . 

Enter  “Z  to  quit. 

Address  and  count?  0x100000  256 

MICROSOFT. EMM. CTRL. VERSION. 1.00. CONTROL. BLOCK  .  .  .  @  .  .  . 

Enter  "Z  to  quit . 

Address  and  count?  *Z 

C:\SEG4G> 

Figure  2:  Typical  session  using  TEST.C  with  the  RAMDRIVE  driver  installed 
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Earlier  this  year,  Borland  granted 
to  Bob  Zale,  creator  of  Turbo 
Basic,  rights  to  sell  future  ver¬ 
sions  of  his  compiler,  which  is 
now  being  marketed  by  Spectra 
Publishing  as  PowerBasic  (PB).  Power- 
Basic’s  designer  has  paid  primary  at¬ 
tention  to  the  needs  of  the  programmer 
while  providing  a  Basic  that  is  upwardly 
compatible  with  Turbo  Basic  1.0  and 
Microsoft’s  GWBasic. 

There  are  compromises  in  some  ar¬ 
eas,  but  there  are  very  few  when  it 
comes  to  making  programming  easier 
and  more  productive.  The  result  is  a 
worthwhile  and  unusual  version  of 
Basic  —  but  by  no  means  non-standard. 

Compromise  of  a  Sort 

Regardless  of  language,  most  program¬ 
mers  hate  reinventing  and  rewriting  the 
known.  With  languages  such  as  C  and 
Pascal,  quite  a  lot  of  money  goes  into 
programmer’s  toolkits.  Still,  many  com¬ 
mon  routines  fall  through  the  cracks: 
They’re  too  short  and  too  easy  to  be 
worth  putting  in  a  toolkit.  Worse,  some 
parts  of  the  language  itself  make  the 
programmer  do  more  work  —  with  no 
offsetting  gain  in  clarity. 

Consider  a  simple  sort  routine.  If  you 
were  sorting  many  items,  you’d  dig  out 
a  routine  from  your  favorite  toolkit. 


Bruce  develops  and  sells  software  for 
TRS-80  and  MS-DOS/PC-DOS  comput¬ 
ers.  He  can  be  reached  at  T.N.T.  Soft¬ 
ware  Inc.,  34069  Hainesville  Road, 
Round  Lake,  IL  60073 ■ 


The  Power  in 
PowerBasic 

This  new  compiler  may  seem 
like  an  old  friend 


Bruce  Tonkin 


Alas,  the  routine  might  be  too  general  — 
requiring  that  you  specify  a  sort  order, 
a  comparison  function,  data  types,  and 
so  on.  Modifying  to  sort  a  half  dozen 
strings  might  be  more  trouble  than  it’s 
worth.  So  you  rewrite  a  bubble  sort  for 
the  thousandth  time.  Sure,  it’s  only  a 
few  lines  of  code,  but  it  can  be  irritat¬ 
ing  (especially  if  you  make  a  mistake 
in  something  that  elementary). 

Or  suppose  you  need  a  large  text 
array  of  variable-length  strings.  I’ve  read 
quite  a  few  articles  about  managing 
such  things  in  C  and  Pascal,  and  I’ve 
reinvented  many  of  the  algorithms  in 
Knuth’s  books  for  managing  garbage 
collection.  Lately,  dynamic  string  librar¬ 
ies  have  begun  to  appear.  I  suppose 
they’re  useful,  but  I  think  the  need  for 
those  libraries  begs  the  question,  “Why 
isn’t  the  requisite  functionality  built  into 
the  language  or  the  standard  libraries 
already?” 

QuickBasic  and  Microsoft’s  excellent 
Basic  7.0  still  don’t  permit  dynamic 
strings  of  more  than  64K  at  one  time. 
Basic  7.0  dodges  the  question  some¬ 
what  by  allowing  the  user  to  have  sev¬ 
eral  arrays  of  as  much  as  64K  at  one 
time.  Still,  no  single  array  may  have 
more  than  64K  of  dynamic  strings. 

Fixed-length  strings  are  standard  for 
C  and  Pascal.  There’s  no  question  that 
fixed-length  strings  are  quite  useful  and 
even  preferable  to  dynamic  strings  in 
many  applications.  It  was  an  improve¬ 
ment  when  such  strings  were  added 
to  Basic.  However,  it’s  less  useful  if  the 
length  must  be  specified  at  compile¬ 


time  rather  than  at  run  time.  There  are 
far  too  many  instances  (file  utilities, 
sort  programs,  and  so  on)  where  the 
string  length  simply  cannot  be  known 
in  advance. 

PB  doesn’t  pretend  to  be  an  entirely 
new  language,  nor  does  it  claim  to 
solve  all  problems.  It’s  not  so  much  a 
paradigm  shift  as  an  exercise  in  prag¬ 
matism.  To  the  question,  “What  should 
Basic  be?”  Bob  Zale  has  answered:  “What¬ 
ever  Basic  programmers  want.”  He 
didn’t  implement  everything  I  would 
like  to  see,  but  then,  that  may  be  im¬ 
possible. 

Yes,  PB  includes  a  sort.  The  com¬ 
mand  will  sort  all  or  parts  of  arrays  of  all 
data  types  (the  default  is  plain  ASCII), 
using  any  collating  order  you  specify, 
either  directly  or  using  a  tag  array,  in 
ascending  or  descending  order,  The 
sorted  arrays  may  have  many  dimen¬ 
sions.  The  options  are  not  mandatory 
parts  of  the  command,  so  you  can  sort 
a  whole  array  in  ascending  ASCII  order 
simply  as:  ARRAY  SORT  A$(  ) 

That’s  useful  enough,  but  there’s 
more.  You  can  also  scan  all  or  part  of 
an  array  for  the  first  element  that 
matches  a  relation  you  specify  (<,  >, 
=  ,  etc.),  based  (for  string  arrays)  on 
any  collating  order  you  specify  —  in¬ 
cluding  case-insensitive  scans. 

You  can  also  insert  or  delete  an  array 
element  with  a  single  command.  No 
more  loops  or  swaps  are  needed.  It 
seems  an  enormous  understatement  to 
say  that  all  this  is  just  “useful”  —  it’s 
been  needed  for  years! 
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(continued  from  page  72) 

Language  Enhancements 

These  and  other  enhancements  are  dis¬ 
cussed  in  the  two  manuals  (User's Man¬ 
ual  and  Reference  Guide )  supplied  with 
PB.  The  documentation  is  thorough 
(more  than  700  pages),  clear,  and  well 
indexed  and  organized,  and  seems  to 
be  free  from  any  obvious  typos.  I  found 
no  errors  in  the  manuals  while  doing 
the  review,  but  I’d  suggest  that  later 
versions  of  the  manuals  devote  an  ap¬ 
pendix  to  the  differences  between  PB 
and  QB.  There  are  appendices  detail¬ 
ing  the  differences  between  PB  and 
GWBasic,  and  between  Turbo  Basic 
and  PB. 

Among  other  things,  PB  has  new 
data  types:  Floating-point  BCD,  fixed- 
point  BCD,  8-byte  integer,  and  10-byte 
extended  precision  floating-point  (na¬ 
tive  coprocessor  format  numbers).  8- 
byte  integers  can  have  as  many  as  18 
digits,  so  PRINT  USING  was  revamped. 

The  expanded  string  space  carries 
several  penalties.  Because  strings  can 
be  spread  over  more  memory,  there’s 
more  overhead  involved.  That  means 
string  operations  tend  to  be  slower  in 
PB  than  in  Microsoft  products.  But  if 
you  need  the  space,  the  small  penalty 
is  well  worth  it. 

In  addition,  the  FRE("  ")  function  re¬ 
turns  the  amount  of  space  remaining 
in  the  current  string  allocation  block. 
Once  you’ve  been  running  the  pro¬ 
gram  for  a  while,  there’s  no  easy  way 
for  you  to  tell  how  much  total  memory 
is  left  for  strings,  or  how  much  you’ve 
used  so  far.  You  must  calculate  the 
amount  of  available  memory  when  the 
program  first  starts  and  use  that  number 
as  the  baseline  for  future  calculations. 

Those  are  problems  to  be  noted,  but 
they  aren’t  serious,  especially  for  those 
of  us  who  find  the  unlimited  string 
space  to  be  a  big  advantage. 

As  with  Turbo  Basic,  PB  permits  the 
programmer  to  specify  where  segment 
boundaries  lie.  From  that,  you  can  avoid 
the  problems  created  by  programs  too 
large  to  fit  into  a  single-user  code  seg¬ 
ment.  However,  the  PB  editor  and  com¬ 
piler  limit  source  code  to  64K  bytes. 
This  is  less  of  a  problem  than  before 
because  PB  can  link  with  OBJ  files  and 
units  (resembling  Turbo  Pascal’s  units). 
It  can,  however,  be  somewhat  of  a 
bother. 

Options 

Compilation  options  allow  you  to  gen¬ 
erate  code  for  80286  and  80386  proces¬ 
sors;  use/emulate  a  math  coprocessor 
(or  ignore  the  coprocessor  and  go  for 
maximum  speed  with  a  procedural  math 
library);  turn  on  or  off  various  checks; 
and  reduce  code  size  by  eliminating 


support  for  unnecessary  library  mod¬ 
ules.  What  you  get  seems  very  similar 
to  the  options  provided  in  Microsoft’s 
Basic  7.0,  though  PB’s  EXE  files  are 
usually  larger  than  those  of  Basic  7.0. 

PB  permits  linking  OBJ  modules  in 
what  seems  to  me  a  more  natural  way 
than  with  the  Microsoft  compilers:  PB 
asks  that  you  include  the  names  of  the 
OBJ  modules  within  the  source  code 
of  your  program.  That  decreases  the 
length  of  the  command  line  and  the 

There’s  no  question 
that  fixed-length 
strings  are 
quite  useful  and 
even  preferable 
to  dynamic  strings  in 
many  applications 


possibility  of  errors.  The  compilation 
options  can  also  be  included  as  meta¬ 
commands  in  the  source  code.  Those 
enhancements  make  it  much  easier  to 
compile  PB  programs. 

There  is  a  drawback,  though.  PB  can¬ 
not  link  with  libraries,  as  QuickBasic 
can.  This  can  be  a  big  problem  if  you 
need  many  OBJ  files. 

Benchmarks 

While  doing  this  review,  I  churned  out 
my  usual  quantitative  comparisons. 
BENCHOLD.BAS  (Listing  One,  page 
116)  benchmarks  features  of  the  lan¬ 
guage  that  are  common  to  QuickBasic 
3.0  and  earlier,  while  BENCHNEW.BAS 
(Listing  Two,  page  119)  tests  the  newer 
features  of  the  language.  The  results 
are  shown  in  Tables  1  and  2.  Those 
numbers  are  not  completely  irrelevant, 
but  they  are  of  less  worth  than  usual: 
Power  Basic  breaks  new  ground  in  un¬ 


expected  ways,  and  the  overall  utility 
of  this  compiler  cannot  be  judged  by 
noting  the  relative  time  it  takes  to  per¬ 
form  a  string  concatenation  or  a  dou¬ 
ble  precision  add. 

True  compilation  is  faster  in  PB.  With 
the  Microsoft  products,  any  request  to 
create  an  EXE  will  result  in  a  call  to  the 
command  line  compiler  and  the  sepa¬ 
rate  linker.  PB  compiles  in  memory. 

If  you  ask  to  create  an  EXE  in  mem¬ 
ory,  the  Microsoft  products  are  faster; 
they’re  not  really  compiling  but  con¬ 
verting  the  program  to  a  tokenized  form. 
The  difference  shows  when  you  run 
the  result.  PB  programs  run  at  EXE 
speed,  even  in  the  environment.  PB 
compiles  slower  because  it’s  really  com¬ 
piling,  but  that  doesn’t  mean  it’s  a  slug. 
Where  QuickBasic  might  take  2  sec¬ 
onds  to  tokenize  and  start  running  a 
program,  PB  might  take  10.  The  QB 
program  might  take  20  seconds  to  run 
in  the  environment,  where  the  PB  ver¬ 
sion  might  run  in  5. 

So,  who’s  faster?  It  depends.  If  you 
often  need  to  stop  a  program  and  rerun 
it  with  minor  changes,  QB  might  be 
best.  But  if  the  program  is  complex 
enough,  PB  might  give  a  faster  turn¬ 
around.  The  more  complex  the  pro¬ 
gram,  the  bigger  the  advantage  for  PB. 
PB  permits  conditional  compilation,  too. 
This  is  a  feature  I’d  hoped  Microsoft 
would  include  in  Basic  7.0. 

Environmental  Issues 

PB’s  editor  is  much  better  than  Micro¬ 
soft’s.  The  user  interface  (in  my  opin¬ 
ion)  hurts  the  Microsoft  products.  The 
QB  editor  will  not  get  out  of  the  way, 
and  constantly  presents  dialog  boxes 
telling  you  of  syntax  errors  while  you’re 
doing  ordinary  editing  from  line  to  line. 

Another  problem  is  that  the  QB  edi¬ 
tor  has  no  line  continuation  character. 
Long  lines  must  be  viewed  in  parts  or 
split  into  sections.  This  can  be  a  nui¬ 
sance  because  the  QB  editor  insists  on 
inserting  spaces  at  nearly  every  oppor¬ 
tunity.  Even  modestly  complex  lines 
can  easily  become  too  wide  and  can’t 
be  split.  Additionally,  the  QB  editor 
will  not  permit  the  programmer  to  mark 


COMPILER 

PROGRAM 

SOURCE  SIZE 

EXE  SIZE 

POWER  BASIC 

BENCHNEW 

3400 

39296 

QB  4.5 

BENCHNEW 

3022 

34276  * 

BASIC  7.0 

BENCHNEW 

3418 

24848 

POWER  BASIC 

BENCHOLD 

8721 

46384 

QB  4.5 

BENCHOLD 

7746 

37722  * 

BASIC  7.0 

BENCHOLD 

8720 

32684 

* Supports  fewer  tests;  size  is  not  strictly  comparable,  but  is  provided  for  reference. 


Table  1:  Size  of  EXEs  generated  from  Listings  One  and  Two 
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(continued  from  page  74) 
a  block  of  code  and  write  it  to  a  disk 
file,  or  to  read  a  block  from  a  disk  file 
into  the  current  program. 

By  default,  the  QB  editor  saves  new 
programs  in  a  special  format.  The  for- 


PB  lacks  support 
for  OS/2  and  doesn’t 
have  the  ISAM 
file  capability  of 
Basic  7.0 


mat  varies  from  release  to  release,  and 
none  are  backwardly  or  upwardly  com¬ 
patible. 

In  contrast,  PB  works  with  and  saves 
plain  ASCII  files,  alters  nothing  you 
type,  permits  line  continuation  charac¬ 
ters,  and  allows  block  read  and  write. 
It’s  just  plain  easier  and  faster  to  type 
and  edit  code  with  PB. 

To  be  fair,  I  find  the  QB  help  system 
easier  to  use  than  PB’s.  That  may  be  a 
factor  for  beginners.  And,  QB’s  instant 
debugging  is  probably  better  for  pro¬ 
grammers  not  familiar  with  Basic.  Again, 
there  are  definite  trade-offs.  PB’s  editor 
is  perhaps  better  suited  to  program¬ 
mers  with  some  experience  in  Basic. 

PB’s  debugging  options  are  improved 
over  Turbo  Basic’s,  but  Microsoft  still 
has  a  clearly  better  approach.  PB's  de¬ 
bugger  is  competent  but  clumsier  and 
somewhat  more  difficult  to  use. 

PB’s  debugger  doesn't  permit  you 
to  use  function  calls,  but  only  to  change 
the  value  of  a  variable  or  an  expression 
that  evaluates  to  a  variable.  Further, 
PB  replaces  PRINT  USING  during  de¬ 
bugging  with  a  series  of  powerful  but 
arcane  formatting  commands.  The  re¬ 
sult  is  flexible  and  more  capable  than 
what  Microsoft  delivers,  but  I  found  it 
confusing.  The  commands  are  reminis¬ 
cent  of  Fortran  with  some  C  conventions. 
Fortunately,  for  most  debugging  ses¬ 
sions  you’ll  never  need  to  worry  about 
formatted  print  for  variables. 

Trade-offs 

Another  point  that  PB  has  in  its  favor 
is  the  physical  size  of  the  compiler 
environment.  PB  can  be  run  easily  on 
a  floppy  disk  system.  Many  beginners 
don’t  have  hard  disks.  Even  if  you  in¬ 
stalled  every  PB  file  on  your  hard  disk, 
the  total  would  come  to  just  about 


700K  —  much  less  than  QuickBasic  4.5, 
and  far  less  than  the  6  to  14  Mbytes 
required  for  Basic  7.0. 

Part  of  the  reason  for  the  size  differ¬ 
ence:  PB  lacks  support  for  OS/2  and 
doesn’t  have  the  ISAM  file  capability 
of  Basic  7.0.  Nor  does  PB  come  with 


the  equivalent  of  CodeView.  But  I  have 
yet  to  find  a  use  for  CodeView  when 
doing  Basic  programming. 

PB  doesn’t  support  record  or  file  lock¬ 
ing,  either.  Of  all  the  possible  disad¬ 
vantages  I  can  imagine,  this  is  probably 
the  most  serious.  While  OS/2  is  very 


Time,  in  seconds,  per  1 ,000,000  operations 


QB  3.0 

QB  4.0 

BASIC  6 

BASIC  7 

PB 

Integers: 

Empty  loop 

1.21 

1.21 

1.21 

1.20 

2.09 

assignment: 

1.15 

1.13 

1.13 

1.10 

1.02 

add: 

.30 

.49 

.50 

.27 

.47 

subtract: 

.33 

.46 

.49 

.16 

.77 

multiply: 

1.92 

2.45 

2.27 

2.25 

2.77 

divide: 

3.36 

3.43 

3.44 

3.90 

5.41 

comparison: 

2.58 

3.20 

2.58 

2.53 

2.91 

Conditional  assignment: 

4.51 

4.77 

4.67 

2.37 

2.31 

Conditional  assignment*: 

4.72 

4.88 

4.34 

1.70 

2.47 

Long  integers: 

Empty  loop 

— 

14.45 

14.28 

12.59 

10.49 

assignment: 

1.62 

1.71 

1.53 

1.67 

add: 

15.47 

15.26 

13.23 

11.73 

subtract: 

15.41 

15.21 

13.57 

12.22 

multiply: 

26.11 

25.82 

24.34 

25.35 

divide: 

33.76 

33.66 

31.70 

25.68 

comparison: 

10.81 

10.98 

10.48 

8.57 

Single-precision: 


assignment: 

5.71 

201.23 

20.40 

2.20 

1.98 

add: 

23.97 

128.83 

24.41 

42.45 

24.66 

subtract: 

24.80 

129.36 

25.87 

43.72 

26.34 

multiply: 

34.30 

-16.19 

35.50 

52.54 

36.02 

divide: 

35.98 

7.48 

47.68 

64.80 

47.02 

Error,  100K  mult/div: 

-1 .06E-05 

-1.19E-07 

-1.19E-07 

-1.19E-07 

-1.96E-5 

exponential: 

766.80 

3061 .84 

1296.36 

1309.90 

3373.80 

comparison: 

19.72 

402.00 

42.68 

42.58 

4.55 

Double-precision: 

assignment: 

6.26 

211.41 

23.06 

3.49 

49.10 

add: 

45.75 

143.28 

49.99 

68.80 

69.48 

subtract: 

47.19 

143.87 

51.52 

70.39 

69.43 

multiply: 

83.13 

199.49 

91.66 

109.60 

86.13 

divide: 

84.22 

226.45 

121.82 

142.57 

130.08 

Error,  100K  mult/div: 

-4.82E-13 

-2.22E-16 

2.22E-16 

2.22E-16 

-4.22E-15 

exponential: 

2491.80 

6377.23 

3046.33 

3240.62 

3326.56 

comparison: 

20.37 

412.89 

46.30 

46.37 

100.68 

Strings: 

assignment: 

77.09 

78.50 

79.04 

77.72 

72.56 

MID$  operation: 

20.78 

24.61 

25.20 

24.11 

81.93 

concatenation: 

1657.81 

954.84 

1661.15 

1662.48 

875.16 

Print  1 K  70-byte  strings**: 

26.47 

10.00 

10.05 

9.55 

9.61 

Fixed  string  assignment: 

52.38 

51.92 

51.68 

101.86 

Fixed  string  MID$  operation: 

23.44 

24.12 

23.74 

147.13 

Fixed  string  concatenation: 

24.61 

24.78 

21.01 

170.85 

Pr  IK  70-b  static  strings**: 

10.16 

10.10 

9.65 

9.60 

Table  2:  Timings  were  generated  using  a  Tandy  4000  ( 16-MHz  80386)  with 
an  MDA  video  adapter  card,  a  Casper  amber  monochrome  monitor,  and  no 
math  coprocessor.  For  each  compiler,  all  possible  stub  libraries  were  used ,  all 
error  checks  were  removed,  and  all  speed  optimizations  employed. 
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much  a  minor  market,  LANs  are  every¬ 
where  on  the  increase.  So  far,  though, 
fewer  than  20  percent  of  MS-DOS  ma¬ 
chines  are  part  of  a  network.  Of  that 
minority,  many  do  not  need  shared  file 
access  through  a  user-written  program; 
a  large  number  share  files  only  through 


networked  word  processors  or  the  like. 
Realistically,  PB’s  potential  market 
should  not  be  damaged  greatly  by  the 
lack  of  support  for  shared  data  files.  It 
is,  however,  something  that  I  recom¬ 
mend  be  added  soon. 

(continued  on  page  80) 


* One  of  the  ways  should  be  appreciatively  faster  if  short-circuit  optimization  is  being  done 
"To  the  screen.  Monochrome  display,  MDA  card 

Note:  the  negative  and  small  times  for  single-precision  multiply  and  divide  for  QB  4.0 
mean  that  they  took  less  time  to  execute  than  a  simple  assignment.  Perhaps  there  are 
unnecessary  checking  or  conversion  operations  going  on  during  the  simple  assignment. 
Considering  the  big  slow-down  from  QB  3.0,  that  seems  likely. 


Operation  speed  QuickBasic  3.0  =  100.0  (Lower  numbers  are  better) 


QB  4.0 

BASIC  6 

BASIC  7 

PB 

Empty  integer  loop 

100.0 

100.0 

99.2 

172.7 

Integer  assignment: 

98.3 

98.3 

95.7 

88.7 

Integer  add: 

163.3 

166.7 

90.0 

156.7 

Integer  subtract: 

139.4 

148.5 

48.5 

233.3 

Integer  multiply: 

127.6 

118.2 

117.2 

144.3 

Integer  divide: 

102.1 

102.4 

116.1 

161.0 

String  assignment: 

101.8 

102.5 

100.8 

94.1 

String  MID$  operation: 

118.4 

121.3 

116.0 

394.3 

String  concatenation: 

57.6 

100.2 

100.3 

113.1 

Single-precision  assignment: 

3524.2 

357.3 

38.5 

34.7 

Single-precision  add: 

537.5 

101.8 

177.1 

102.9 

Single-precision  subtract: 

521.6 

104.3 

176.3 

106.2 

Single-precision  multiply: 

-47.2 

103.5 

153.2 

105.0 

Single-precision  divide: 

7.4 

47.6 

180.1 

130.7 

Single-precision  exponential: 

399.3 

169.1 

170.8 

440.0 

Double-precision  assignment: 

3377.2 

368.4 

55.8 

784.3 

Double-precision  add: 

313.2 

109.3 

150.4 

151.9 

Double-precision  subtract: 

304.9 

109.2 

149.2 

147.1 

Double-precision  multiply: 

240.0 

110.3 

131.8 

103.6 

Double-precision  divide: 

268.9 

144.6 

169.3 

154.5 

Double-precision  exponential: 

255.9 

122.3 

130.1 

133.5 

Integer  comparison: 

124.0 

100.0 

98.1 

112.8 

Single-precision  comparison: 

402.0 

216.4 

215.9 

73.8 

Double-precision  comparison: 

2027.0 

227.3 

227.6 

494.3 

Conditional  int  assignment: 

105.8 

103.5 

52.5 

51.2 

Conditional  assignment*: 

103.4 

91.9 

36.0 

52.3 

Print  1 K  70-byte  strings**: 

37.8 

38.0 

36.1 

36.3 

Unweighted  average  performance: 

500.4 

136.4 

119.7 

176.8 

Operation  speed,  Basic  6.0  =  100.0 

QB  4.0  BASIC  7 

PB 

Empty  long  integer  loop 

101.2 

88.2 

73.5 

Long  integer  assignment: 

94.7 

89.5 

97.7 

Long  integer  add: 

101.4 

86.7 

76.9 

Long  integer  subtract: 

101.3 

89.2 

80.3 

Long  integer  multiply: 

101.1 

94.3 

98.2 

Long  integer  divide: 

100.3 

94.2 

76.3 

Fixed  string  assignment: 

100.9 

99.5 

196.2 

Fixed  string  MID$  operation: 

97.2 

98.4 

610.0 

Fixed  string  concatenation: 

99.3 

84.8 

689.5 

Long  integer  comparison: 

98.5 

95.4 

78.1 

Print  1 K  70-byte  static  strings**: 

100.6 

95.5 

95.0 

Unweighted  performance  average: 

99.7 

92.3 

197.4 
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(continued  from  page  77) 

Putting  It  to  Work 

To  demonstrate  some  of  PowerBasic’s 
new  features,  consider  the  simple  mail¬ 
ing  list  program  in  Listing  Three  (page 
120).  The  program  certainly  doesn’t  ex¬ 
ercise  all  the  capabilities  of  PB,  but  it 
should  be  enough  to  give  you  a  taste 
of  them. 

Listing  Three  doesn’t  contain  a  search 
function,  holds  all  data  in  memory,  and 
has  primitive  editing  capabilities  (you 
can  delete  a  record  and  insert  a  new 
one,  and  that’s  it).  You  can,  however, 


hold  more  than  3100  records  in  mem¬ 
ory  on  a  640K  machine  (473,176  bytes 
available  for  string  data).  The  sort  is 
fast,  record  insertion  is  nearly  instanta¬ 
neous,  and  it  would  be  trivial  to  add 
features  for  finding  a  record,  editing 
by  field,  sorting  by  additional  fields, 
retaining  a  backup  data  file,  and  so  on. 
In  fact,  most  things  you  might  want  to 
do  to  this  program  are  easy. 

Conclusion 

PB’s  new  features  are  a  strong  selling 
point.  Its  emphasis  on  genuinely  use¬ 


ful  enhancements,  the  nice  editor,  the 
faster  execution  in  the  environment, 
and  the  new  data  types  make  it  an 
essential  product  for  anyone  seriously 
interested  in  Basic. 

Neither  PB  nor  Microsoft’s  Basic  7.0 
is  the  “best”  Basic  compiler  in  every 
area.  PB  needs  support  for  libraries, 
file  and  record  locking,  larger  source 
files,  user-defined  types,  and  a  better 
debugger.  Microsoft  could  benefit  from 
PB’s  editor  and  environment,  new  func¬ 
tions,  larger  string  space,  link  and  meta¬ 
command  options,  conditional  compi¬ 
lation,  and  added  data  types. 

I  intend  to  convert  several  of  my 
programs  from  QB  and  Basic  7.0  to  PB. 
In  fact,  I  began  the  process  soon  after 
getting  my  review  copy  of  PB.  PB’s 
advantages  in  particular  areas  make  the 
conversion  attractive.  Other  programs 
will  remain  in  the  Microsoft  dialect.  I 
suspect  that  most  Basic  programmers 
will  have  the  same  experience. 

If  you’re  serious  about  Basic  pro¬ 
gramming,  you  really  ought  to  con¬ 
sider  having  both  PB  and  one  of  the 
Microsoft  products.  And  Turbo  Basic 
1.x  owners  will  find  the  $59  upgrade 
is  money  well  spent. 


Product  Information 

PowerBasic 
Spectra  Publishing 
1030-D  E.  Duane 
Sunnyvale,  CA  94086 
408-730-9291 
Price:  $129 

Upgrade  for  Turbo  Basic  users  $59 
Requirements:  IBM  PC/compatible 
MS-DOS  2.0  or  higher 
640K  RAM,  one  floppy  drive 


Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
online.  To  order  the  disk,  send  $14.95 
(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal ,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ). 

DDJ 


(Listings  begin  on  page  116.) 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  9. 
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VGA 


Listing  One  (Text  begins  on 

page  16.) 

0BIOS 

MACRO 

push 

func  / 

bp 

•Macro  to  use  BIOS  function  calls 
•Some  functions  destroy  bp 

svDefs.INC 

/ 

mov 

ah, func 

Copyright  (c)  Genus  Microprogramming,  Inc.  1988-89  All  Rights  Reserved.  ; 

int 

INT  BIOS 

.****************** 

******************* 

***************************************; 

bp 

This  file  contains  defines  for  Super  VGA  graphics  manipulation.  ; 

ENDM 

Microsoft  ASM  5.x 

version. 

Programmer:  Chris  Howard  ; 

****************** 

******************* 

***************************************; 

@@LoadSeg  MACRO 

seg,val  / 

•Macro  to  load  a  segment  reg 

mov 

ax, val 

/Display  Segments 

mov 

seg, ax 

EGAseg  equ 

OAOOOH 

/ EGA/VGA/SVGA  graphics  segment 

ENDM 

BlOSseg  equ 

0C000H 

/Graphics  BIOS  segment 

@@Data 

MACRO 

seg  / 

•Macro  to  load  data  seg  in  reg 

/EGA  defines 

ASSUME 

seg:@data 

EGAgraph  equ 

03CEH 

/EGA  Graphics  Register 

mov 

ax, @data 

EGAseq  equ 

03C4H 

/EGA  Sequencer  Register 

mov 

seg, ax 

ENDM 

•VGA  defines 

VGAsegsel  equ 

03CDH 

/VGA  Segment  select 

GSetMode 

MACRO 

mode  / 

•Macro  to  set  display  mode 

VGAmisci  equ 

03CCH 

/VGA  Mi sc  In 

IFDIFI 

<mode>, <al> 

VGAmisco  equ 

03C2H 

/VGA  Misc  Out 

mov 

a 1, mode 

END  IF 

•Paradise  defines 

0BIOS 

SETMODE 

parPROA  equ 

09H 

/proa  index  value 

ENDM 

parPR5  equ 

OFH 

/pr5  index  value 

par LOCK  equ 

0 

/Lock  pcoa  to  pr4  (write  to  pr5) 

0 Get Mode 

MACRO 

Macro  to  get  display  mode 

par UNLOCK  equ 

5 

/Unlock  proa  to  pr4  (write  to  pr5) 

0BIOS 

GETMODE 

parFUNC  equ 

6FH 

/Paradise  Function 

ENDM 

•Video  7  defines 

@Port 

MACRO 

portnum, portval  / 

Macro  to  set  a  port  to  a  value 

v7SR6  equ 

06H 

/sr6  index  value 

IFDIFI 

<portval>, <al> 

v7banksel  equ 

0F6H 

/Bank  select 

mov 

al, portval 

v7pagesel  equ 

0F9H 

/Page  select 

ENDIF 

v7enable  equ 

OEAH 

/Enable  extensions 

IFDIFI 

<portnum>, <dx> 

v7disable  equ 

OAEH 

/Disable  extensions 

mov 

dx, portnum 

v7modenum  equ 

06F05H 

/Number  to  use  for  mode  sets 

ENDIF 

out 

dx,  al 

Display  mode  numbers 

ENDM 

TEXTMODE  equ 

3 

/Text  mode  number 

@EGAPort 

MACRO 

portnum, port  reg,  portval  / 

Macro  to  set  an  EGA  port 

Display  mode  types 

IFDIFI 

<portreg>, <al> 

svTEXT  equ 

0 

/Text  mode 

mov 

al, port reg 

svGRAPH  equ 

1 

/Graphics  mode 

ENDIF 

IFDIFI 

<portnum>, <dx> 

/Display  types 

mov 

dx, portnum 

mindisp  equ 

0 

/Minimum  display  type 

ENDIF 

svDISP  2D  equ 

0 

/Tseng  2DH  (640x350x256) 

out 

dx,al 

svDISP  2E  equ 

1 

/Tseng  2EH  (640x480x256) 

inc 

dx 

svDISP  30  equ 

2 

/Tseng  30H  (800x600x256) 

mov 

al, portval 

svDISP  5E  equ 

3 

/Paradise  5EH  (640x400x256) 

out 

dx,  al 

svDISP  5F  equ 

4 

/Paradise  5FH  (640x480x256) 

ENDM 

svDISP  66  equ 

5 

/Video  7  66H  (640x400x256) 

svDISP  67  equ 

6 

/Video  7  67H  (640x480x256) 

0TsengSeg  MACRO 

seg  / 

Macro  to  set  the  Tseng  VGA  seg 

svDISP  69  equ 

7 

/Video  7  69H  (800x600x256) 

push 

ax 

maxdisp  equ 

7 

/Maximum  display  type 

IFDIFI 

<seg>, <al> 

mov 

al, seg 

/Logical  Operations 

ENDIF 

RMWbits  equ 

18H 

/Read-Modify-Write  bits 

mov 

ah,al  / 

Save  a  copy 

svOpREP  equ 

00000000B 

/SET  pixel  value  directly 

shl 

ah,  1  / 

Rotate  up  (Bits  0-2  =  write  seg 

svOpAND  equ 

00000001B 

/AND  pixel  value  with  data 

shl 

ah,  1  / 

3-5  =  read  seg 

svOpOR  equ 

00000010B 

/OR  pixel  value  with  data 

shl 

ah,l  / 

6-7  =  seg  cnfg) 

svOpXOR  equ 

00000011B 

/XOR  Dixel  value  with  data 

or 

al,ah  / 

Combine  read  and  write  segs 

or 

al, 01000000B 

and  set  to  configuration  2 

/Chipsets 

@Port 

VGAsegsel, al  / 

Now  set  it 

SVUNKNOWN  equ 

0 

/Unknown  chip  set 

pop 

ax 

svTSENG  equ 

1 

/Tseng  Labs  chip  set 

ENDM 

svPARA  equ 

2 

/Paradise 

svV7  equ 

3 

/Video  7 

0ParSeg 

MACRO 

seg  //Macro  to  set  Paradise  VGA  seg 

push 

cx 

Masks 

IFDIFI 

<seg>, <ch> 

capmask  equ 

11011111B 

/To  convert  letters  to  caps 

mov 

ch, seg 

ENDIF 

/Error  codes 

mov 

cl, 4  /Turn  4K  window  into  64K  window 

svSUCCESS  equ 

0 

/Success 

shl 

ch,cl  / 

by  multiplying  by  16 

svBADMODE  equ 

-1 

/Bad  display  mode 

@EGAPort 

EGAgraph, parPROA, ch  / 

and  set  the  new  index 

pop 

cx 

Internal  Constants 

ENDM 

unknown  equ 

-1 

/A  constant  is  unknown 

bytesrow  equ 

80 

/CGA  bytes  per  full  row 

@V7Seg 

MACRO 

seg  //Macro  to  set  the  V7VGA  segment 

bitsbyte  equ 

8 

/Bits  per  byte 

push 

ax 

push 

bx 

/Display  structure 

IFDIFI 

<seg>, <bh> 

svstruc  STRUC 

mov 

bh, seg 

svtype  db 

? 

/Display  type 

ENDIF 

svmode  db 

? 

/Display  mode 

mov 

bl,bh 

svfunc  dd 

? 

/Display  function 

and 

bl, 00000001B 

Mask  for  bank  bit  0 

svstruc  ENDS 

@EGAPort 

EGAseq, V7pagesel,bl  / 

Set  the  bit 

End  Listing  One 

mov 

and 

bl,bh  / 

bl, 000000010B 

Get  a  copy  of  seg  again 

Mask  for  bank  bit  1 

shl 

bl,  1 

Shift  it  up 

Listing  Two 

shl 

shl 

bl,  1 
bl,  1 

svMacs . INC 

; 

shl 

bl,  1 

Copyright  (c)  Genus  Microprogramming 

Inc.  1988-89  All  Rights  Reserved.  / 

mov 

dx, VGAmisci  //Read  the  Misc  In  reg 

****************** 

******************* 

*************************************** 

in 

ai,dx 

This  file  contains  macros  for  Super  VGA  graphics  manipulation.  / 

and 

al,NOT  00100000B  //Make  sure  bit  is  clear 

Microsoft  ASM  5.x 

version. 

Programmer:  Chris  Howard  / 

****************** 

******************* 

A*************************************. 

@Port 

VGAmisco, bl  //Write  to  Misc  Out 

Interrupts 

@Port 

EGAseq, v7banksel 

INT  BIOS  equ 

10H 

/BIOS  (video) 

dx 

INT  DOS  equ 

21H 

/DOS  Functions 

al,  dx 

mov 

bl,bh 

Get  a  copy  of  seg  again 

BIOS  Functions  (int  10H) 

shr 

bl,  1 

Dupe  bit  2  to  bit  0  (r/w  equal) 

SETMODE  equ 

00H 

/Set  the  Display  mode 

shr 

bl,  1 

GETMODE  equ 

OFH 

/Check  the  Display  mode 

not 

bl 

Macros 

and 

bl,  5 

@DOS  MACRO 

func 

//Macro  to  use  DOS  function  calls 

and 

al, 11110000B 

Clear  bank  select  bits 

mov 

ah, func 

or 

al,bl 

out 

dx,  al 

ENDM 

(Listing  continued  on  page  84.) 
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i*  Two  ( Listing  continued,  ti 

pop 

bx 

pop 

ENDM 

ax 

MACRO 

mode  ; 

IFDIFI 

<mode>, <bl> 

mov 

END  IF 

bl , mode 

mov 

ax,v7modenum  ; 

int 

INT_BIOS 

ENDM 

MACRO 

splocal  ; 

push 

bp  ; 

mov 

bp,  sp 

sub 

sp, splocal  ; 

push 

ds 

push 

es 

push 

si 

push 

di 

GGData 

ENDM 

ds 

MACRO 

retcode, splocal  ; 

mov 

ax, retcode  ; 

pop 

di 

pop 

si 

pop 

es 

pop 

ds 

mov 

sp,bp  i 

pop 

bp  i 

ret 

ENDM 

splocal  ; 

MACRO 

retcode, errcode 

mov 

ENDM 

WORD  PTR  retcode, errcode 

;Macro  to  set  Video7  mode 


(•Indicate  Video7  mode  set 


;Macro  for  entering  routine 
;  and  setting  up  frame 


(•Allocate  local  space 


;Macro  for  setting  return  code 
;  and  restoring  regs 


;Remove  local  space 
/Restore  frame 
/Remove  parms 


End  Listing  Two 


Listing  Three 


;  svQC .  ASM 

;  Copyright  (c)  Genus  Microprogramming,  Inc.  1988-89  All  Rights  Reserved. 


;  This  file  contains  procedures  for  identifying  various  Super  VGA  adapters. 
;  Procedures:  svQueryChipset 

;  Microsoft  ASM  5.x  version.  Programmer:  Chris  Howard 


Include  files 
INCLUDE  svDefs.inc 
INCLUDE  svMacs.inc 


.model  small 

.data 

.code 

PUBLIC  svQueryChipset 


;  This  procedure  attempts  to  determine  the  type  of  VGA  chip  set. 
;  Calling:  retcode  =  pcxQueryChipset {) 


/Define  variable  locations  on  the  stack 
qcparm  equ  0 

/Define  local  variables 
qcret  equ  <[bp-  2)> 

qclocal  equ  2 


svQueryChipset 

@Entry 

mov 

0BIOS 

xor 

cmp 

jne 

GSetRet 

jmp 


PROC  FAR 
qclocal 
al,  0 
parFUNC 
al,  al 
bx, '  V7' 
svQC_Para 
qcret, svV7 
svQC  exit 


(pascal  model) 


/return  code 

;Total  local  space  needed 


;Set  up  frame  and  save  regs 
; Look  for  a  V7VGA 


/Clear  al 

;Is  this  a  Video7? 


(■Indicate  that  this  is  a  Video7 


GGLoadSeg  es,BIOSseg 
mov  di ,  0 

mov  cx,500 

mov  al,'P' 


svQC_Parafind: 

repne 

jcxz 

cmp 

jne 


scasb 

svQC_Tseng 

BYTE  PTR  es: [di  ) , ' A' 
svQC_Parafind 

BYTE  PTR  es: [di+1] , 'R' 

svQC_Paraf ind 

BYTE  PTR  es: [di+2],'A' 

svQC_Paraf ind 

BYTE  PTR  es: [di+3] , ' D' 

svQC_Parafind 

BYTE  PTR  es: [di+4] , ' I' 

svQC_Parafind 

BYTE  PTR  es: [di+5], 'S' 

svQC_Parafind 

BYTE  PTR  es: [di+6] , 'E' 

svQC_Parafind 


GSetRet  qcret, svPARA 
jmp  SHORT  svQC_exit 


;Point  to  the  BIOS  location 


;Search  the  first  500  bytes 
;Look  for  'PARADISE' 


;Next  Letter? 

;  Compare  one  at  a  time,  so 
;  we  can  avoid  static  data  ...) 

;  If  not  a  match,  continue  search 


;We  found  the  Paradise  name 
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svQC_Tseng : 


@@LoadSeg  es,BIOSseg 

/Point  to  the  BIOS  location 

mov 

di,  0 

mov 

cx, 500 

/Search  the  first  500  bytes 

mov 

al,  'T' 

/Look  for  'Tseng' 

svQC  Tsfind: 

repne 

jcxz 

scasb 

svQC_unknown 

/ Search 

cmp 

BYTE  PTR  es: [di  ], 

'  s' 

/Next  Letter? 

jne 

svQC  Tsfind 

/  Compare  one  at  a  time,  so 
/  we  can  avoid  static  data  . . . ) 

cmp 

BYTE  PTR  es: [di+1] , 

'e' 

jne 

svQC  Tsfind 

/  If  not  a  match,  continue  search 

cmp 

jne 

BYTE  PTR  es: [di+2] , 
svQC  Tsfind 

'  n' 

cmp 

jne 

BYTE  PTR  es: [di+3] , 
svQC  Tsfind 

'g' 

@SetRet 

jmp 

qcret, svTSENG 

SHORT  svQC_exit 

/We  found  the  Tseng  name 

svQC  unknown: 

GSetRet 

qcret, svUNKNOWN 

/We  did  not  find  anything 

svQC  exit: 

@Exit 

svQueryChipset 

qcret, qcparm 

ENDP 

/ Return 

END 


End  Listing  Three 


Listing  Four 


svPA.ASM 

Copyright  (c)  Genus  Microprogramming,  Inc.  1988-89  All  Rights  Reserved. 


This  file  contains  procedures  for  calculating  a  pixel's  address  for  any 
given  display  mode.  These  are  INTERNAL  routines. 

Procedures:  svPixelAddr2D  svFixelAddr30  svPixelAddr5F 
Microsoft  ASM  5.x  version.  Programmer:  Chris  Howard 


Include  files 
INCLUDE  svDefs.inc 
INCLUDE  svMacs.inc 


.model  small 

.data 

.code 

PUBLIC  svPixelAddr2D 
PUBLIC  svPixelAddr30 


This  function  determines  the  address  of  a  pixel  in  SVGA  256  color 
modes : 


2DH 

640x350x256  Tseng 

2EH 

640x480x256  Tseng 

66H 

640x400x256  Video7 

67H 

640x480x256  Video7 

5EH 

640x400x256  Paradise 

5FH 

640x480x256  Paradise 

Calling: 

AX 

=  y-coordinate 

BX 

=  x-coordinate 

Returns : 

ES:BX 

=  pixel  pointer 

DX 

=  video  segment 

svPixelAddr2D 


PROC  FAR 


mov  dx, 640 

mul  dx 

add  bx,ax 

adc  dx, 0 

@@LoadSeg  es,EGAseg 
ret 

svPixelAddr2D  ENDP 


/Multiply  y*BytesPerLine 

/Add  in  x  coordinate 
/  and  any  carry 

;ES:BX  =  byte  address  of  pixel 


This  function 
30H 
69H 

Calling:  AX 
BX 

Returns:  ES:BX 
DX 


determines  address  of  pixel  in  SVGA  800x600x256  color  modes: 
800x600x256  Tseng 
800x600x256  Video7 
=  y-coordinate  (0-599) 

=  x-coordinate  (0-799) 

=  pixel  pointer 
=  video  segment 


svPixelAddr30 


PROC  FAR 


mov  dx,800 

mul  dx 

add  bx,ax 

adc  dx, 0 

@@LoadSeg  es,EGAseg 
ret 


/Multiply  y*bytesrow 


Add  in  x  coordinate 
and  any  carry 

ES:BX  =  byte  address  of  pixel 


svPixelAddr30  ENDP 


END 


End  Listing  Four 

(continued  on  page  86) 
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Listing  Five  (Listings  continued,  text  begins  on  page  16.)  I  svsetDispiay  proc  far 


;  svPP.ASM 

/  Copyright  (c)  Genus  Microprogramming,  Inc.  1988-89  All  Rights  Reserved. 
.************************************************************************* 
;  This  file  contains  procedures  for  putting  (displaying)  a  pixel  for  any 
;  given  display  mode.  ; 

;  Procedures:  svPutPixel 

;  Microsoft  ASM  5.x  version.  Programmer:  Chris  Howard 


/  Include  files 
INCLUDE  svDefs.inc 
INCLUDE  svMacs.inc 

.model  small 
.data 

svDisplay  svstruc  <svDISP_2D, 2DH, svPutPixel2D>  ; Tseng  Labs 

svlen  EQU  $-svDisplay 

svstruc  <svDISP_2E, 2EH, svPutPixel2D> 
svstruc  <svDISP_30, 30H, svPutPixel30> 
svstruc  <svDISP_5E, 5EH, svPutPixel5F>  /Paradise 

svstruc  <svDISP_5F, 5FH, svPutPixel5F> 

svstruc  <svDISP_66, 1AH, svPutPixel67>  ;Video7 

svstruc  <svDISP_67» 1BH, svPutPixel67> 
svstruc  <svDISP_69, 1DH, svPutPixel69> 


PUBLIC  svCurDisp, svLogOp 


svCurDisp  dw 

SvDISP  2D 

/Current  display  type 

svPixFunc 

dd 

? 

/Current  pixel  function 

svBank 

db 

-1 

/Current  window  bank 

svLogOp 

db 

svOpREP 

/Logical  operation 

EXTRN 

svPixelAddr2D 

:  FAR 

EXTRN 

svPixelAddr30 

:  FAR 

.code 

PUBLIC 

svSetDisplay 

PUBLIC 

svSetMode 

PUBLIC 

svSetOp 

PUBLIC 

svPutPixel 

;  This  function  sets  the  display  type  by  selecting  the  correct  pixel 
;  function  for  all  svPutPixel  calls. 


/Define 

variable  locations  on  the  stack 

(pascal  model) 

sddisp 

equ  <[bp+  6]> 

/Display  type 

sdparm 

equ  2 

/Define 

local  variables 

sdret 

equ  < [bp-  2]> 

/return  code 

sdlocal 

equ  2 

/Total  local  space  needed 

©Entry  sdlocal  /Set  up  frame  and  save  regs 

©©Data  es  /Point  to  table 

mov  ax,sddisp  /Get  the  display  type 

mov  svCurDisp, ax  /Assume  valid,  and  store 

mov  bx, svlen  /Get  offset  into  table 

mul  bx 

mov  di, OFFSET  svDisplay  /Add  starting  location  of  table 

add  di,ax 

mov  ax, WORD  PTR  es : [di] . svfunc [2]  /Store  current  function 

mov  WORD  PTR  svPixFunc [2] , ax  /  for  fast  reference 

mov  ax, WORD  PTR  es : [di] . svfunc (0] 

mov  WORD  PTR  svPixFunc [0] , ax 

©SetRet  sdret, svSUCCESS 

svSD_exit: 

©Exit  sdret, sdparm 

svSetDisplay  ENDP 


/  This  function  sets  graphics  mode  for  the  currently  selected  display  type. 


/Define 

variable  locations  on  the  stack 

(pascal  model) 

smmode 

equ 

<[bp+  6]> 

/Flag  for  TEXT  or  GRAPHICS  mode 

smparm 

equ 

2 

/Define 

local  variables 

smret 

equ 

<[bp-  2] > 

/return  code 

smlocal 

equ 

2 

/Total  local  space  needed 

svSetMode 

PROC  FAR 

©Entry 

smlocal 

/Set  up  frame  and  save  regs 

mov 

svBank, -1 

/Initialize  bank 

mov 

ax, smmode 

/Get  requested  "mode" 

cmp 

ax, svGRAPH 

/Setting  to  graphics? 

je 

svSM  graph 

©SetMode 

TEXTMODE 

/Set  to  text  mode 

©SetRet 

smret, svSUCCESS 

jmp 

SHORT  svSM_exit 

svSM  graph: 

©©Data 

es 

/Point  to  table 

mov 

ax, svCurDisp 

/Get  the  display  type 

mov 

bx, svlen 

/Get  offset  into  table 

mul 

bx 

mov 

di, OFFSET  svDisplay 

/Add  starting  location  of  table 

add 

di,  ax 

©SetMode 

es: [di] .svmode 

/Set  to  correct  graphics  mode 

©GetMode 

/Make  sure  it  stuck 
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cmp 

al,es: [di] .svmode 

je 

svSM  ok 

@SetRet 

smret , svBADMODE 

;No,  so  return  error 

jmp 

SHORT  svSM_exit 

svSM  ok: 

GSetRet 

smret, svSUCCESS 

svSM  exit : 

@Exit 

smret, smparm 

svSetMode 

ENDP 

.********** 

;  This  function  sets  the  logical  operation  for  all  svPutPixel  calls. 

/Define  variable  locations  on  the  stack 

(pascal  model) 

soop  equ 

<[bp+  6)> 

/Logical  Operation 

soparm  equ 

2 

/Define  local  variables 

soret  equ 

<[bp-  2] > 

/return  code 

solocal  equ 

2 

/Total  local  space  needed 

svSetOp 

PROC  FAR 

@Entry 

solocal 

/Set  up  frame  and  save  regs 

mov 

ax, soop 

/Get  the  logical  operation 

cmp 

ax,  svOpXOR 

/Check  range 

jbe 

svSO  store 

fiSetRet 

soret, svBADMODE 

/ Error 

jmp 

SHORT  svSO_exit 

svSO  store: 

mov 

svLogOp, al 

/Store  it 

@SetRet 

soret, svSUCCESS 

svSO  exit: 

@Exit 

soret, soparm 

svSetOp 

ENDP 

. ********** 

/  This  function  is 

the  main  entry  point 

to  all  of  the  specific  PutPixel 

/  routines.  It  sets  up  the  appropriate  parameters,  then  branches  to  the 

;  correct  routine 

for  the  current  display  device. 

/Define  variable  locations  on  the  stack 

(pascal  model) 

ppx  equ 

<[bp+10]> 

/Pixel  coordinate 

PPY  equ 

<[bp+  8]> 

ppcolor  equ 

<[bp+  6]> 

/Color 

ppparm  equ 

6 

/Define  local  variables 

ppret  equ 

< [bp-  2] > 

/return  code 

pplocal  equ 

2 

/Total  local  space  needed 

svPutPixel 

PROC  FAR 

@Entry 

pplocal 

/Set  up  frame  and  save  regs 

mov 

ax, ppx 

/Call  pixel  function 

push 

ax 

mov 

ax,ppy 

push 

ax 

mov 

ax, ppcolor 

push 

ax 

call 

DWORD  PTR  svPixFunc 

fiSetRet 

ppret, ax 

svPP  exit: 

@Exit 

ppret, ppparm 

svPutPixel 

ENDP 

•  ********** 

;  NOTE:  The  stack 

frame  is  defined  in  svPutPixel 

svPutPixel2D 

PROC  FAR 

0 Entry 

pplocal 

mov 

ax,ppy 

/Set  up  call  to  address  routine 

mov 

bx,ppx 

call 

svPixelAddr2D 

/ES:BX  ->  buffer,  DL  ->  seg 

cmp 

dl, svBank 

/Is  bank  currently  selected? 

je 

svPP2D  op 

@TsengSeg  dl 

svPP2D  op: 

mov 

al, ppcolor 

/Get  color 

mov 

dl, svLogOp 

/Get  operation 

cmp 

dl, svOpRep 

jz 

svPP2D  rep 

/  (fastest  if  replace) 

cmp 

dl, svOpXOR 

/Is  this  XOR? 

je 

svPP2D  xor 

cmp 

dl, svOpAND 

/Is  this  AND? 

je 

svPP2D  and 

svPP2D  or: 

or 

es: [bx] , al 

/Or  the  pixel 

jmp 

short  svPP2D  ok 

svPP2D  and: 

and 

es : [bx] , al 

/And  the  pixel 

jmp 

short  svPP2D  ok 

svPP2D  xor: 

xor 

es: [bx] ,al 

/Routine  to  XOR 

jmp 

short  svPP2D  ok 

(Listing  continued  on  page  88.) 
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Listing  Five  (Listing  continued,  text  begins  on  page  16.) 


svPP2D  rep: 

mov 

es : [bx] , al 

/Set  the  pixel  value 

svPP2D  ok: 

@TsengSeg 

0 

/Reset 

@SetRet 

ppret, svSUCCESS 

@Exit 

ppret, ppparm 

svPutPixel2D 

ENDP 

;********** 

/  NOTE:  The  stack  frame  is  defined  in 

svPutPixel 

svPutPixel30 

PROC  FAR 

@Entry 

pplocal 

mov 

ax,ppy 

/Set  up  call  to  address  routine 

mov 

bx,ppx 

call 

svPixelAddr30 

/ES:BX  ->  buffer,  DL  ->  seg 

cmp 

dl, svBank 

/Is  bank  currently  selected? 

je 

svPP30  op 

@TsengSeg  dl 

svPP30  op: 

mov 

al,ppcolor 

/Get  color 

mov 

dl, svLogOp 

/Get  operation 

cmp 

dl, svOpRep 

jz 

svPP30  rep 

/  (fastest  if  replace) 

cmp 

dl, svOpXOR 

/Is  this  XOR? 

je 

svPP30  xor 

cmp 

dl, svOpAND 

/Is  this  AND? 

je 

svPP30  and 

svPP30  or: 

or 

es : [bx] , al 

/Or  the  pixel 

jmp 

short  svPP30_ok 

svPP30  and: 

and 

es:  [bx] ,al 

/And  the  pixel 

jmp 

short  svPP30  ok 

svPP30  xor : 

xor 

es: [bx] , al 

/Routine  to  XOR 

jmp 

short  svPP30  ok 

svPP30  rep: 

mov 

es : [bx] , al 

/Set  the  pixel  value 

svPP30  ok: 

STsengSeg 

0 

/Reset 

@SetRet 

ppret, svSUCCESS 

@Exit 

ppret, ppparm 

svPutPixel30  ENDP 


;  NOTE:  The  stack  frame  is  defined  in  svPutPixel 
svPutPixe!5F  PROC  FAR 


@Entry  pplocal 

@EGAPort  EGAgraph,parPR5,parUNLOCK  ;Unlock  proa  to  pr4 


mov 

mov 

cmp 

je 

call 

@ParSeg 


ax,ppy 

bx,ppx 

dl, svBank 

svPP5F_op 

svPixelAddr2D 

dl 


;Set  up  call  to  address  routine 
;Is  bank  currently  selected? 
;ES:BX  ->  buffer,  DL  ->  seg 


svPP5F_op: 


mov 

al, ppcolor 

/Get  color 

mov 

dl, svLogOp 

/Get  operation 

cmp 

dl, svOpRep 

jz 

svPP5F  rep 

/  (fastest  if  replace) 

cmp 

dl, svOpXOR 

/Is  this  XOR? 

je 

svPP5F  xor 

cmp 

dl, svOpAND 

/Is  this  AND? 

je 

svPP5F_and 

or 

es: [bx] , al 

/Or  the  pixel 

jmp 

short  svPP5F_ok 

i: 

and 

es: [bx],al 

/And  the  pixel 

jmp 

short  svPP5F  ok 

xor 

es: [bx] , al 

/Routine  to  XOR 

jmp 

short  svPP5F_ok 

i: 

mov 

es: [bx] , al 

/Set  the  pixel  value 

@EGAPort 

EGAgraph, parPROA, 0 

/Zero  out  proa 

@EGAPort  EGAgraph,parPR5,parL0CK  ;Lock  proa  to  pr4 
@SetRet  ppret, svSUCCESS 
@Exit  ppret, ppparm 


svPutPixel5F 


ENDP 


;  NOTE:  The  stack  frame  is  defined  in  svPutPixel 
svPutPixel67  PROC  FAR 


@Entry  pplocal 

@EGAPort  EGAseq, v7SR6, v7enable  /Enable  Video  7  extensions 


mov 

ax, ppy 

/AX  =  y 

mov 

bx, ppx 

/BX  =  x 

call 

svPixelAddr2D 

/ ES : BX  ->  buffer,  DL  ->  seg 

cmp 

dl, svBank 

/Is  bank  currently  selected 

je 

svPP67  op 

mov 

cl,  dl 

@V7Seg 

cl 

svPP67  op: 

mov 

al, ppcolor 

/Get  color 

mov 

dl, svLogOp 

/Get  operation 

cmp 

dl, svOpRep 

jz 

svPP67  rep 

/  (fastest  if  replace) 

cmp 

dl, svOpXOR 

/Is  this  XOR? 

je 

svPP67_xor 

cmp 

dl, svOpAND 

/Is  this  AND? 

je 

svPP67  and 

svPP67  or: 

or 

es : [bx] , al 

/Or  the  pixel 

jmp 

short  svPP67_ok 

svPP67  and: 

and 

es: [bx] , al 

/And  the  pixel 

jmp 

short  svPP67_ok 

svPP67  xor: 

xor 

es: [bx] , al 

/Routine  to  XOR 

jmp 

short  svPP67  ok 

svPP67  rep: 

mov 

es: [bx] , al 

/Set  the  pixel  value 

svPP67  ok: 

@V7Seg 

0 

/Reset 

@EGAPort 

EGAseq, v7SR6, v7disable 

/Disable  Video  7  extensions 

@SetRet 

ppret, svSUCCESS 

@Exit 

ppret, ppparm 

svPutPixel67  ENDP 


;  NOTE:  The  stack  frame  is  defined  in  svPutPixel 


svPutPixe!69  PROC  FAR 


@Entry  pplocal 

@EGAPort  EGAseq, v7SR6, v7enable  /Enable  Video  7  extensions 


(Listing  continued  on  page  90.) 
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Listing  Five  (Listing  continued,  text  begins  on  page  16.) 


mov 

ax,ppy 

;Set  up  call  to  address  routine 

mov 

bx,ppx 

call 

svPixelAddr30 

; ES : BX  ->  buffer,  DL  ->  seg 

cmp 

dl, svBank 

;Is  bank  currently  selected? 

je 

svPP69  op 

mov 

cl,dl 

@V7Seg 

cl 

svPP69  op: 

mov 

al,ppcolor 

;Get  color 

mov 

dl, svLogOp 

;Get  operation 

cmp 

dl , svOpRep 

jz 

svPP69  rep 

;  (fastest  if  replace) 

cmp 

dl , svOpXOR 

; Is  this  XOR? 

je 

svPP69  xor 

cmp 

dl , svOpAND 

; Is  this  AND? 

je 

svPP69  and 

svPP69  or: 

or 

es: [bx] , al 

;0r  the  pixel 

jmp 

short  svPP69_ok 

svPP69  and: 

and 

es: [bx] ,al 

;And  the  pixel 

jmp 

short  svPP69_ok 

svPP69  xor: 

xor 

es: [bx] ,al 

/Routine  to  XOR 

jmp 

short  svPP69_ok 

svPP69  rep: 

mov 

es: [bx] , al 

/Set  the  pixel  value 

svPP69  ok: 

@V7Seg 

0 

; Reset 

@EGAPort 

EGAseq, v7SR6, v7disable 

/Disable  Video  7  extensions 

@SetRet 

ppret, svSUCCESS 

@Exit 

ppret,ppparm 

svPutPixel69 

ENDP 

END 


End  Listing  Five 

Listing  Six 

/*  svLib.H  */ 

/*  Copyright  (c)  Genus  Microprogramming,  Inc.  1988-89  All  Rights  Reserved.  */ 

Function  declarations  for  the  Super  VGA  Library,  for  C. 

Microsoft  C  version  5.1  Programmer:  Chris  Howard 

*****************************************************************************/ 


/*  Display  modes  */ 
♦define  svTEXT 

0 

/* 

Text  mode 

*/ 

♦define  svGRAPHICS 

1 

/* 

Graphics  mode 

V 

/*  Display  types  */ 
♦define  svMINDISP 

0 

♦define  svDISP_2D 

0 

/* 

Tseng  2DH 

(640x350x256) 

*/ 

♦define  svDISP_2E 

1 

/* 

Tseng  2EH 

(640x480x256) 

*/ 

♦define  svDISP  30 

2 

/* 

Tseng  30H 

(800x600x256) 

*/ 

♦define  svDISP_5E 

3 

/* 

Paradise  5EH 

(640x400x256) 

*/ 

♦define  svDISP_5F 

4 

/* 

Paradise  5FH 

(640x480x256) 

*/ 

♦define  svDISP_66 

5 

/* 

Video  7  66H 

(640x400x256) 

*/ 

♦define  svDISP_67 

6 

/* 

Video  7  67H 

(640x480x256) 

*/ 

♦define  svDISP_69 

7 

/* 

Video  7  69H 

(800x600x256) 

*/ 

♦define  svMAXDISP 

7 

/*  Logical  Operations  */ 

♦define  svSET 

0 

/* 

SET  pixel  value  directly 

*/ 

♦define  svAND 

1 

/* 

AND  pixel  value  with  data 

*/ 

♦define  svOR 

2 

/* 

OR  pixel  value  with  data 

*/ 

♦define  svXOR 

3 

/* 

XOR  pixel  value  with  data 

*/ 

/*  Chip  sets  */ 
♦define  svUNKNOWN 

0 

/* 

Unknown  chip 

set 

*/ 

♦define  svTSENG 

1 

/* 

Tseng  Labs 

*/ 

♦define  svPARA 

2 

/* 

Paradise 

*/ 

♦define  svV7 

3 

/* 

Video  7 

*/ 

/*  Error  Codes  */ 
♦define  svSUCCESS 

0 

/* 

Successful 

*/ 

♦define  svBADMODE 

-1 

/* 

Bad  display  mode 

*/ 

/*  Functions  */ 


extern 

int 

far  pascal 

svSetDisplay 

(int)  / 

extern 

int 

far  pascal 

svSetMode 

(int) ; 

extern 

int 

far  pascal 

svSetOp 

(int) / 

extern 

int 

far  pascal 

svPutPixel 

(int,  int, int) 

extern 

int 

far  pascal 

svQueryChipset 

(void) / 

End  Listing  Six 


Listing  Seven 

/*  svTest.C 

/*  Copyright  (c)  Genus  Microprogramming,  Inc.  1988-89  All  Rights  Reserved. 


This  is  a  simple  test  program,  for  testing  the  Super  VGA  QueryChipset 
and  PutPixel  functions. 

Compile:  CL  /c  /AS  svTest.C 
link  svTest, , , svLib; 

Microsoft  C  version  5.1  Programmer:  Chris  Howard 


*/ 

*/ 
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♦include  <stdio.h> 

♦include  <conio.h> 

♦include  "svlib.h" 

/*  Global  data  */ 

static  char  *chip[]  =  (" [Unknown] ", "Tseng  Labs", "Paradise", "Video7") ; 
/**********/ 

/*  This  is  a  crude  box  drawing  routine.  Uses  the  svPutPixel  function  to  draw*/ 
void  svPutSquare(x,y,w,c) 
int  x,y,w,c; 

{ 

int  i; 

for  (i=0;  i<w;  i++)  { 
svPutPixel (x+i,  y,  c)  ; 
svPutPixel (x+i, y+w, c) ; 
svPutPixel (x,  y+i,c); 

svPutPixel (x+w, y+i,  c) ; 

} 

}  /*  end  of  svPutSquare  */ 

/**********/ 
void  main (void) 

{ 

int  i,  j,k, chipset, svdisplay, retcode; 

/*  Display  a  header  */ 

printf ("\n\nSuper  VGA  Test  Program\n\n") ; 

/*  Query  the  chipset,  and  see  what  we  have  */ 
chipset  *  svQueryChipset () ; 

printf ("Your  Super  VGA  chipset  is:  %s\n\n", chip [chipset] ) ; 
printf ("Press  any  key  to  continue  ...\n\n"j; 
getch'O  ; 

/*  If  we  have  a  chipset  we  recognize,  keep  going  */ 
if  (chipset  !=  svUNKNOWN)  { 

/*  Based  on  the  chipset,  select  a  display  type  for  256  colors  */ 
switch  (chipset)  { 
case  svTSENG: 

/*  640x480x256  */ 
svdisplay  =  svDISP_2E; 
break; 

case  svPARA: 

/*  640x400x256  */ 
svdisplay  =  svDISP_5E; 
break; 
case  svV7 : 

/*  640x480x256  */ 
svdisplay  =  svDISP_67; 
break; 

) 

/*  Set  the  display  and  mode  */ 
retcode  -  svSetDisplay (svdisplay) ; 
retcode  =  svSetMode (svGRAPHICS) ; 

/*  If  the  mode  was  set  successfully,  try  displaying  some  pixels  */ 
if  (retcode  ==  svSUCCESS)  { 

/*  Display  a  rainbow  bar,  a  few  lines  thick  */ 
for  (j=0;  j<10;  j++)  ( 
for  (i=0;  i<256;  i++) 
svPutPixel (200+i, 200+ j, i) ; 

) 

/*  Demonstrate  logical  operations  by  XORing  a  'square'  across  rainbow  */ 
retcode  =  svSetOp (svXOR) ; 
for  ( i=0 ;  i<256;  i++)  { 

svPutSquare (200+i, 200,  10, 15)  ; 

/*  Dummy  delay  */ 
for  (j*0;  j < 5 0 0 0 ;  j++) 
k  -  j; 

svPutSquare (200+i, 200, 10, 15) ; 

) 

/*  Wait  for  a  key  */ 
getch ( ) ; 

/*  Return  to  text  mode,  and  display  completion  message  */ 
svSetMode (svTEXT) ; 

printf ("svTest  completed\n\n") ; 

) 

) 

else  ( 

/*  We  could  not  recognize  the  chip,  so  suggest  something  */ 
printf ("No  test  can  be  run  ...\n\n"); 

printf ("If  you  are  sure  of  your  chipset,  try  changing  the  program  so\n"); 
printf ("the  chip  type  is  forced. \n\n") ; 

) 

)  /*  end  of  main  */ 


End  Listing  Seven 

Listing  Eight 

♦  svLIB  Make  File 

# 

♦  Copyright  (c)  Genus  Microprogramming,  Inc.  1988-89  All  Rights  Reserved.  # 

(Listing  continued  on  page  92.) 
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Listing  Eight  (Listing  continued,  text  begins  on  page  16.) 

#  This  make  file  is  for  making  the  Super  VGA  Library.  # 

#  Usage:  Make  svLib  /I  # 

#  Microsoft  ASM  5.1  Programmer:  Chris  Howard  # 

############################################################################## 

#  Compiler  and  linker  flags 
AFLAGS  =  /DLINT_ARGS  /W2  /B63  /ZI 

#  /D  =  Define  /W2  =  Max  ASM  warnings  /B  =  Buffer  size 

CFLAGS  =  /GO  /AS  /Os  /c  /Zi 

/GO  =  8088  code  /AS  =  Small  model  /Os  =  Optimize  Size 

#  /c  =  Compile  only 
DFLAGS  =  /DLINT_ARGS  /W3 

#  /D  =  Define  /W3  =  Max  C  warnings 


#  Compiler  Programs 

CC  =  cl  $ (CFLAGS)  $  (DFLAGS) 

ASM  =  masm  $ (AFLAGS) 

LINK  =  link  $ (LFLAGS) 

LIB  =  lib 

#  ASM  Include  files 

SVDEFS  =  svDefs.inc 

SVMACS  =  svMacs.inc 

#  Libraries 
SVLIB  =  svLib 


$*  =  Base  name  of  the  outfile  (without  extension) 

$@  =  Complete  outfile  name 

$**  =  Complete  list  of  infiles 


############ 

#  Query  Chipset 

svQC.obj :  $* .asm  $ (SVDEFS)  $ (SVMACS) 
$ (ASM)  $*, $@; 

$ (LIB)  $ (SVLIB)  -$*  +$@; 

#  Pixel  Addressing 

svPA.obj :  $* .asm  $ (SVDEFS)  $ (SVMACS) 
$ (ASM)  $*, $@; 

$ (LIB)  $ (SVLIB)  -$*  +$@; 

#  Put  Pixel 

svPP.obj :  $* .asm  $ (SVDEFS)  $ (SVMACS) 
$ (ASM)  ; 

$ (LIB)  $ (SVLIB)  -$*  +$@; 


Listing  Nine 


End  Listing  Eight 


#  svTest  Make  File  # 

#  Copyright  (c)  Genus  Microprogramming,  Inc.  1988-89  All  Rights  Reserved.  # 
###############*#################################f###################f######## 

#  This  make  file  is  for  making  the  Super  VGA  Test  program.  # 

#  Microsoft  C  5.1  Programmer:  Chris  Howard  # 

############################################################################## 

#  Compiler  and  linker  flags 


CFLAGS 

=  /GO  /AS  /Os  /c 

# 

/GO  =  8088  code 

/AS 

# 

/c  =  Compile  only 

DFLAGS 

=  /DLINT_ARGS  /W3  /Zi 

# 

/D  =  Define 

/W3 

LFLAGS 

=  / 

# 

/CO  =  Codeview 

/Os  =  Optimize  Size 


:  Max  C  warnings 


#  Compiler  Programs 

CC  =  cl  $ (CFLAGS)  $ (DFLAGS) 

ASM  =  masm 

LINK  =  link  $ (LFLAGS) 

#  Include  files 

SV  =  svlib.h 

#  Libraries 

SVLIB  =  svlib.lib 

############ 

#  The  Test  program 

svtest.obj:  $*.c  $(SV) 

$(CC)  $* . c 

#  Now  link  it  all  together 
svtest.exe:  $*.obj  $ (SVLIB) 

$ (LINK)  $*,,,$ (SVLIB); 


End  Listings 
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Listing  One  (Text  begins  on  page  30.) 

♦include  <graph.h> 

♦include  <math.h> 

int  xbase,  ybase; 
unsigned  xAspect,  yAspect; 

void  SetAspect (double  aspect) 

{ 

xAspect  =  0; 
yAspect  =  0; 
aspect  =  fabs (aspect) ; 
if  (aspect  !=  1.0) 
if  (aspect  >  1.0) 

yAspect  =  65536.0  /  aspect; 
else 

xAspect  =  65536.0  *  aspect; 


void  plot (int  x,  int  y) 

{ 

if  (xAspect  ==  0) 
if  (yAspect  ==  0) 

_setpixel (x+xbase,  y+ybase) ; 
else 

_setpixel (x+xbase,  ybase  +  (((long)  y  *  (long)  yAspect)  »  16)); 

else 

_setpixel (xbase  +  (((long)  x  *  (long)  xAspect)  »  16),  y+ybase); 


void  plot8(int  x,  int  y) 
{ 

plot (x,y) ; 
plot (-x,y) ; 
plot  (x, -y) ; 
plot (-x, -y) ; 
plot (y, x) ; 
plot (-y,x) ; 
plot (y,-x) ; 
plot (-y,-x) ; 


D  D  A 


void  circle (int  radius) 

{ 

int  x,y,sura; 
x  =  0; 

y  =  radius  «  1; 
sum  =  0; 

while  (x  <=  y) 

{ 

if  {  ! (x  &  1)  )  /*  plot  if  x  is  even  */ 

plot8(  x  »  1,  (y+1)  »  1); 
sum  +=  (x  «  1)  +  1; 
x++; 

if  (sum  >  0) 

{ 

sum  -=  (y  «  1)  -  1; 

y— — ; 

) 

} 

) 

int  main ( ) 

{ 

_setvideomode (_VRES2COLOR) ; 
xbase  =  320; 
ybase  =  240; 

SetAspect (1.0) ; 
circle (100) ; 

SetAspect (2.0) ; 
circle  (100) ; 

SetAspect (0.5) ; 
circle (100) ; 

) 


End  Listing 
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Listing  One  (Text  begins  on  page  36.) 

/*  Created  by  Victor  J.  Duvanenko.  Straight  forward  implementation  of  the 
Cohen-Sutherland  line  clipping  algorithm.  */ 


♦define  BOOLEAN  int 

♦define  TRUE  1 

♦define  FALSE  0 

♦define  OK  ^  0 

♦define  NOT_OK  -1 

♦define  ACCEPT  TRUE 

♦define  REJECT  FALSE 


/*  Clipping  rectangle  boundaries  -  accessable  to  all  routines  */ 
extern  double 

y_bottom, 

_  y_top, 

x_right, 

x_left, 

z_front, 

z_back; 


*/ -  Cohen-Sutherland  2D  algorithm  - 

Procedure  that  sets  four  bits,  and  outcode,  to  designate  a  region  of 

point  existance  relative  to  the  clipping  rectangle.  For  a  full  explanation 

see  Foley  and  Van  Dam  p.146  Fig.  4.5 

Bit  0  -  point  is  above  window 

Bit  1  -  point  is  below  window 

Bit  2  -  point  is  to  right  of  window 

Bit  3  -  point  is  to  left  of  window 

The  algorithm  is  border  inclusive  -  border  is  included  in  the  window. 

- */ 

static  void  outcodes{  x,  y,  outcode  ) 
double  x,  y; 
int  *outcode; 


) 

/' 


♦outcode  =  0; 

if  (  y  >  y_top  )  *outcode 
if  (  y  <  y_bottom  )  *outcode 
if  (  x  >  x_right  )  *outcode 
if  (  x  <  x_left  )  *outcode 


1, 

2, 

4, 

8, 


Procedure  that  checks  for  trivial  rejects  -  if  both  end  points  are  above, 
below,  to  the  right,  or  to  the  left  of  the  window. 

This  procedure  can  be  converted  into  a  macro,  for  performance  improvement. 
- */ 


static  reject_check(  outcodel,  outcode2  ) 
int  outcodel,  outcode2; 

( 

if  (  outcodel  &  outcode2  ) 
return (  TRUE  ) ; 
return  (  FALSE  ) ; 


Procedure  that  checks  for  trivial  accept  -  if  both  end  points  are  within 
the  window.  This  procedure  can  also  be  replaced  by  a  macro,  for  speed. 


static  accept_check (  outcodel,  outcode2  ) 
int  outcodel,  outcode2; 

{ 

if  {(  ! outcodel  )  &&  (  !outcode2  )) 
return!  TRUE  ); 
return  (  FALSE  ) ; 

} 

/* - 

Procedure  that  exchanges  the  endpoints  and  their  outcodes. 


static  void  swap_pts(  xO,  yO,  outcodeO,  xl,  yl,  outcodel  ) 

double  *x0,  *y0; 

int  *outcode0; 

double  *xl,  *yl; 

int  * outcodel;* 

{ 

double  tmp; 
int  tmp_i; 


tmp  =  *x0; 
*x0  =  *xly 

*xl  =  tmp; 
tmp  =  *y0; 
*y0  =  *yl; 
*yl  =  tmp; 
tmp_i 

♦outcodeO  = 
♦outcodel  = 

} 

/* - 


/*  exchange  the  x's  */ 
/*  exchange  the  y's  */ 


♦outcodeO;  /*  exchange  the  outcodes 

♦outcodel; 

tmp_i; 


*/ 


7 


7 


Procedure  that  clips  in  2D  using  Cohen-Sutherland  algorithm.  The  algorithm 
has  been  modified  to  separate  the  drawing  function  from  clipping.  This  way 
clipping  is  one  of  the  pipelined  processes.  This  procedure  lets  the  calling 
routine  know  whether  the  line  has  been  accepted  or  rejected,  so  that  the 
caller  knows  whether  to  draw  it,  with  possibly  modified  points,  or  not. 
- */ 


clip_2d_cs(  xO,  yO,  xl,  yl  ) 
double  *x0,  *y0;  /*  first  end  point  */ 

double  *xl,  *yl;  /*  second  end  point  */ 

( 


int  outcodeO,  outcodel; 

/*  Adjust  end  points  until  it's  possible  to  trivially  accept  or  reject  ♦/ 
while!  TRUE  )  /*  one  adjustment  per  iteration  */ 

{ 


outcodes!  *x0,  *y0,  SoutcodeO  ); 
outcodes!  *xl,  *yl,  soutcodel  ); 
if  (  re ject_check (  outcodeO,  outcodel  )) 
return!  REJECT  ); 

if  (  accept_check (  outcodeO,  outcodel  )) 
return!  ACCEPT  ); 


/*  subdivide  line  since  at  most  one  endpoint  is  inside  */ 
/♦  First,  if  P0  is  inside  window,  exchange  points  P0  and  PI  ♦/ 
/♦  and  their  outcodes  to  guarantee  that  P0  is  outside  window  */ 


if  (  ! outcodeO  ) 

swap_pts(  xO,  yO,  SoutcodeO,  xl,  yl,  soutcodel  ) ; 

/*  Now  perform  a  subdivision,  move  P0  to  the  intersection  point, 
use  the  formulas  y  =  yl  +  slope  ♦  (x  -  xl) 
x  =  xl  +  (1/slope)  *  (y  -  yl) 

Note  that  we  don't  have  to  worry  about  division  by  0  in  any  of 
these  cases.  If  a  line  is  horizontal,  then  if  any  of  its  end 
points  were  above  the  window,  it  would  have  been  trivially  rejected. 
So,  the  only  case  possible  is  that  the  end  points  are  left  or 
right  of  the  window  (outcodeO  &  (4  or  8)).  */ 

if  (  outcodeO  &  1  ) 

( 

♦xO  +=  (  *xl  -  *x0 
♦yO  =  y_top; 

) 

else  if  (  outcodeO  &  2 

{ 

♦xO  +=  (  *xl  -  *x0 
♦yO  =  y_bottom; 

} 

else  if  (  outcodeO  &  4 

{ 

♦yO  +=  (  *yl  -  *y0 
♦xO  =  x_right; 

) 

else  if  (  outcodeO  &  8 

{ 

*y0  +=  (  *yl  -  *y0  ) 

♦xO  «  x_left; 

) 

) 

I 

/*  - END  of  2D  CS  algorithm - - */ 

End  Listing  One 


/*  divide  line  at  top  of  window  */ 

)  *  (  y_top  -  *y0  )  /  (  *yl  -  *y0  ) ; 


) 

/*  divide  line  at  bottom  of  window  */ 

)  *  (  y_bottom  -  *y0  )  /  (  *yl  -  *y0  ) ; 


) 

/*  divide  line  at  right  edge  of  window  */ 
)  *  (  x_right  -  *x0  )  /  (  *xl  -  *x0  ); 


) 

/*  divide  line  at  left  edge  of  window  */ 
*  (  x_left  -  *x0  )  /  (  *xl  -  *x0  ); 


Listing  Two 

/*  Created  by  Victor  J.  Duvanenko  An  improved  implementation  of  the 
Cohen-Sutherland  line  clipping  algorithm.  */ 


♦define  BOOLEAN  int 

♦define  TRUE  1 

♦define  FALSE  0 

♦define  OK  0 

♦define  NOT_OK  -1 

♦define  ACCEPT  TRUE 

♦define  REJECT  FALSE 


/*  Clipping  rectangle  boundaries  -  accessable  to  all  routines  ♦/ 
extern  double 

y_bottom, 

y_top, 

x_right, 

x_left, 

z_front, 

z_back; 


/* -  Cohen-Sutherland-Duvanenko  2D  and  3D  algorithms  -  */ 

Procedure  that  sets  four  bits,  and  outcode,  to  designate  a  region  of 

point  existance  relative  to  the  clipping  rectangle.  For  a  full  explanation 

see  Foley  and  Van  Dam  p.146  Fig.  4.5 

Bit  0  -  point  is  above  window 

Bit  1  -  point  is  below  window 

Bit  2  -  point  is  to  right  of  window 

Bit  3  -  point  is  to  left  of  window 

The  algorithm  is  border  inclusive  -  border  is  included  in  the  window. 
Defining  the  procedure  as  a  macro  removes  the  need  to  pass  the  data  on 
the  stack  -  and  gains  additional  speed. 

Note,  that  top  and  bottom  (and  right  and  left)  are  mutually  exclusive 
areas.  That's  the  reason  for  else's  -  reduces  compares  4  down  to  3. 
- */ 


♦define  OUTCODES_CSD (  X,  Y,  OUTCODE  )  \ 

(  OUTCODE  )  =  0;  \ 

if  ( (Y)  >  y_top  )  OUTCODE  !=  1;  \ 

else  if  ( (Y)  <  y_bottom  )  OUTCODE  :=  2;  \ 
if  ( (X)  >  x_right  )  OUTCODE  :=  4;  \ 

else  if  ( (X)  <  x_left  )  OUTCODE  1=  8; 

/* - - - 


Procedure  that  exchanges  the  endpoints  and  their  outcodes. 

Defining  the  procedure  as  a  macro  removes  the  need  to  pass  the  data  on 
the  stack  -  and  gains  additional  speed. 
- */ 


♦define  SWAP_PTS_CSD (  XO,  YO,  OUTCODEO,  Xl,  Yl,  OUTCODE1  )  \ 

tmp  =  *X0;  /*  exchange  the  x's  */  \ 

*X0  =  *X1;  \ 

♦Xl  =  tmp;  \ 

tmp  =  *Y0;  /*  exchange  the  y's  */  \ 

*Y0  =  *Y1;  \ 

♦Yl  =  tmp;  \ 

tmp_i  =  OUTCODEO;  /*  exchange  the  outcodes  */  \ 

OUTCODEO  =  OUTCODE 1;  \ 

OUTCODE 1  =  tmp_i ; 

/* - 


Procedure  that  clips  in  2D  using  Cohen-Sutherland  algorithm.  The  algorithm 
has  been  modified  to  separate  the  drawing  function  from  clipping.  This  way 
clipping  is  one  of  the  pipelined  processes.  This  procedure  lets  the  calling 
routine  know  whether  the  line  has  been  accepted  or  rejected,  so  that  the 
caller  knows  whether  to  draw  it,  with  possibly  modified  points,  or  not. 
- */ 


clip_2d_csd(  xO,  yO,  xl,  yl  ) 
double  *x0,  *y0;  /*  first  end  point  */ 

double  *xl,  *yl;  /*  second  end  point  */ 

{ 


register  unsigned  outcodeO,  outcodel; 


(Listing  continued  on  page  100) 


98 

634 


Dr.  Dobb’s  Journal,  July  1990 


LINE  CUPPING 


listing  Two  ( Listing  continued,  text  begins  on  page  36.) 

double  dx,  dy;  /*  change  in  x  and  change  in  y  */ 

BOOLEAN  intersect; 

double  tmp;  /*  needed  for  the  SWAP  procedure  */ 

int  trap_i;  /*  needed  for  the  SWAP  procedure  */ 

OUTCODES_CSD (  *x0,  *y0,  outcodeO  ); 

OUTCODES_CSD (  *xl,  *yl,  outcodel  ); 

if  (  outcodeO  &  outcodel  )  /*  trivial  reject  */ 

return (  REJECT  ) ; 

if  (  !  {  outcodeO  !  outcodel  ))  /*  trivial  accept  */ 

return  (  ACCEPT  )? 

/*  Calculate  the  subproducts  of  the  slope  only  once.  */ 

/*  These  must  be  calculated  in  all  cases.  */ 
dx  =  *xl  -  *x0; 
dy  =  *yl  -  *y0; 
intersect  =  FALSE; 

/*  Adjust  end  points  until  it's  possible  to  trivially  accept  or  reject  */ 
while (  TRUE  )  /*  one  adjustment  per  iteration  */ 

{ 

/*  subdivide  line  since  at  most  one  endpoint  is  inside  */ 

/*  First,  if  PO  is  inside  window,  exchange  points  PO  and  PI  */ 

/*  and  their  outcodes  to  guarantee  that  PO  is  outside  window  */ 
if  (  ! outcodeO  ) 

{ 

SWAP_PTS_CSD (  xO,  yO,  outcodeO,  xl,  yl,  outcodel  ); 
intersect  =  TRUE;  /*  the  line  intersects  the  window  */ 

} 

/*  Now  perform  a  subdivision,  move  PO  to  the  intersection  point, 
use  the  formulas  y  =  yl  +  slope  *  (x  -  xl) 
x  =  xl  +  (1/slope)  *  (y  -  yl) 

Note  that  we  don' t  have  to  worry  about  division  by  0  in  any  of 
these  cases.  If  a  line  is  horizontal,  then  if  any  of  its  end 
points  were  above  the  window,  it  would  have  been  trivially  rejected. 
So,  the  only  case  possible  is  that  the  end  points  are  left  or 
right  of  the  window  (outcodeO  &  (4  or  8) ) .  */ 

if  (  outcodeO  &  1  ) 

{  /*  divide  line  at  top  of  window  */ 

*x0  +=  dx  *  (  y_top  -  *y0  )  /  dy; 

*y0  =  y_top; 

outcodeO  *  0; 

if  (  *x0  >  x_right  )  outcodeO  !=  4; 

else  if  (  *x0  <  x_left  )  outcodeO  !=  8; 

} 

else  if  (  outcodeO  4  2  ) 

{  /*  divide  line  at  bottom  of  window  *7 

*x0  +=  dx  *  (  y_bottom  -  *y0  )  /  dy; 

*y0  =  y_bottom; 

outcodeO  =  0; 

if  (  *x0  >  x_right  )  outcodeO  1=  4; 

else  if  (  *x0  <  x_left  )  outcodeO  !=  8; 


) 

/* 


) 

else  if  (  outcodeO  4  4  ) 

{  /*  divide  line  at  right  edge  of  window  */ 

*y0  +=  dy  *  (  x_right  -  *x0  )  /  dx; 

*x0  =  x_right; 

outcodeO  =  0; 

if  (  *y0  >  y_top  )  outcodeO  !■  1; 

else  if  (  *y0  <  y_bottom  )  outcodeO  !*  2; 

} 

else  if  (  outcodeO  4  8  ) 

(  /*  divide  line  at  left  edge  of  window  */ 


) 


) 

if 


if 


*y0  +=  dy  *  (  x_left  -  *x0  )  /  dx; 

*x0  =  x_left; 

outcodeO  =  0; 

if  (  *y0  >  y_top  )  outcodeO  !=*  1; 

else  if  (  *y0  <  y_bottom  )  outcodeO  !=  2; 


(  outcodeO  4  outcodel  )  /*  trivial  reject  */ 

return (  REJECT  ) ; 

(  !  (  outcodeO  !  outcodel  ) )  /*  trivial  accept  */ 

return (  ACCEPT  ) ; 


END  of  2D  CSD  algorithm 


End  Listing  Two 


Listing  Three 

/*  Created  by  Victor  J.  Duvanenko  Program  that  generates  random  3D  points, 
that  will  be  used  for  testing  performance  of  line  clipping  algorithms.  */ 


♦include  <stdio.h> 
♦include  <stdlib.h> 


♦define  BOOLEAN  int 

♦define  TRUE  1 

♦define  FALSE  0 

♦define  OK  0 

♦define  NOT_OK  -1 

♦define  NUM_LINES  1000 
♦define  ROUND (x)  ( (x)  > 

♦define  DEBUG  FALSE 


0.0 


/*  generate  this  many  lines  */ 

?  (int) ( (x)  +  0.5)  :  (int) ( (x)  -  0.5)) 
/*  en(dis)able  debug  sections  */ 


/* - 

Procedure  that  generates  any  number  of  3D  points  -  randomly. 


generate_vertex_data (  num_points  ) 

{ 

register  i; 
double  x,  y,  z; 
char  *fname; 

FILE  *fp; 


/*  Fix  the  file  name,  since  performance  benchmarks  are  required.  */ 
/*  Therefore,  user  interaction  should  be  completely  eliminated.  */ 
fname  =  "clipl.dat"; 

if  ( (  fp  =  fopen(  fname,  "w"  ))  ==  NULL  ) 

{ 

printf ("Couldn' t  open  file  %s.\n",  fname  ); 
return (  TRUE  ); 

) 

for(  i  =  0;  i  <  num_points;  i++  ) 

{ 

/*  center  the  values  around  0.0,  so  as  to  have  an 
/*  of  negative  and  positive  values, 
x  =  (double) rand ()  /  (double) RAND_MAX  *  64000.0  - 

y  =  (double) rand ()  /  (double) RAND_MAX  *  64000.0  - 

z  =  (double) rand ()  /  (double) RAND_MAX  *  64000.0  - 

fprintf (  fp,  "%12 . 2 1 f  %12.21f  %12.21f\n",  x,  y, 

) 

f close (  fp  ) ; 

} 

/* - MAiEN - */ 

main(  argc,  argv  ) 
int  argc; 
char  **argv; 

{ 

generate_vertex_data (  NUM_LINES  «  1  ) ; 

return (  0  );  /*  everything  went  fine  */ 

) 


equal  number  */ 
*/ 

32000.0; 
32000.0; 
32000.0; 
z  ); 


End  Listings 
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B  E  ZIER  CURVES 


Listing  One  (Text  begins  on  page  46.) 

- */ 

draw  letter (at  x,  at  y,  letter,  size, 

1* - 

outline  color,  fill  style,  fill  color,  draw  bezier) 

BEZIER. C  An  application  which  draws  characters  (or  anything  else) 

float  at  x,  at  y; 

defined  as  a  collection  of  Bezier  curves.  As  is  this  programs 

BEZIER  BOX  letter []; 

works  fine  on  all  displays  except  CGA  in  the  320x200  mode  since 

it  expects  a  screen  that  is  640x200.  To  also  use  the  deCasteljau  method. 
- */ 

int  outline  color; 
int  fill  style; 

#include  <graphics.h> 

int  fill_color; 
int  draw  bezier(); 

♦include  <conio.h> 

( 

int  i  =  0; 

BEZIER_BOX  bline; 

/*  Definitions  for  defining  fonts  */ 

♦define  POINT  DEF  1000.0  /*  The  point  size  fonts  are  defined 

in  */ 

float  scale; 

♦define  BFLAG  -POINT  DEF  -  1  /*  A  Special  flag  used  as  a  sentinal 

*/ 

scale  =  size  /  POINT_DEF; 

♦define  BNULL  0.0  /*  For  readability  */ 

float  DPU  =  600.0  /  POINT_DEF;  /*  The  step  between  pixels  */ 

setcolor (outline  color); 

/*  Paramters  for  controlling  the  deCasteljau  rendering  method  */ 

setfillstyle(fill  style,  fill  color); 

int  B  cutoff  =  3; 

setlinestyle (SOLID_LINE,  0,  NORM  WIDTH) ; 

int  B  level  =  0; 

while (letter [i] .a.x  !=  BFLAG)  { 

/*  Structures  for  defining  Bezier  bounding  boxes  */ 

bline. a. x  =  at_x  +  (letter [i] .a.x  *  scale); 

bline. a. y  =  at  y  -  (letter [i] .a. y  *  scale); 

bline. b.x  =  at  x  +  (letter [ij .b.x  *  scale); 

bline. b.y  =  at  y  -  (letter [ij .b.y  *  scale); 

bline. c.x  =  at_x  +  (letter [ij .c.x  *  scale); 
bline. c.y  =  at  y  -  (letter [ij .c.y  *  scale); 

bline. d.x  =  at  x  +  (letter [ij .d.x  *  scale); 

)  BEZIER  BOX; 

bline. d.y  =  at  y  -  (letter [ij .d.y  *  scale); 

draw  bezier (sbline) ; 

/*  Do  a  little  letter  doodling  */ 

i++; 

main(argc,  argv) 

int  argc; 
char  *argv [ ] ; 

( 

floodfill ( (int) (at  x  +  letter [i] .b.x  *  scale), 

(int) (at  y  -  letter [ij .b.y  *  scale), 

int  draw  bezierl(); 

fill_color) ; 

int  draw_bezier2 () ; 

} 

int  (*draw_fun) {) ; 
char  label [80]; 

/* - 

int  gdriver  =  DETECT,  gmode; 

Draws  a  bezier  curve  as  defined  by  the  passed  Bezier  bounding  box. 

BEZIER  BOX  lower  a []  =  ( 

- 

{  {  0.0,  591. 0} ,  {  0.0,  864.0},  (1000.0,  864.0},  (1000.0, 

591.0}  }, 

draw_bezierl (bcurve) 

{  (1000.0,  591.0},  (1000.0,  591.0),  (1000.0,  45.0},  (1000.0, 

45.0}  }, 

BEZIER_BOX  *bcurve; 

(  (1000.0,  45.0},  (1000.0,  45.0},  {  727.0,  45.0},  {  727.0, 

45.0}  }, 

float  x,  y; 

(  (  727.0,  45.0},  (  727.0,  45.0},  (  727.0,  136.0},  (  727.0, 

136.0}  }, 

(  {  727.0,  136.0},  (  727.0,  0.0},  (  0.0,  0.0),  (  0.0, 

227.0}  }, 

float  tm; 

(  (  0.0,  227.0},  (  0.0,  545.0},  {  727.0,  545.0},  (  727.0, 

364.0}  }, 

float  t; 

(  {  727.0,  364.0},  {  727.0,  500.0},  {  727.0,  500.0},  {  727.0, 

545.0}  }, 

moveto( (int)bcurve->a.x,  (int)bcurve->a.y) ; 

(  {  727.0,  545.0),  {  727.0,  727.0},  {  272.0,  727.0},  {  272.0, 

592.0}  }, 

(  {  272.0,  592.0},  (  272.0,  592.0),  {  0.0,  592.0},  {  0.0, 

592.0}  }, 

for (t  =  0.0;  t  <=  1.0;  t  +=  0.01)  ( 

(  {  636.0,  280.0},  (  636.0,  90.0},  (  136.0,  119.0},  (  136.0, 

250.0}  }, 

(  {  136.0,  250.0},  (  136.0,  437.0),  (  636.0,  437.0},  {  636.0, 

280.0}  }, 

x  =  (1  -  t)  *  (1  -  t)  *  (1  -  t)  *  bcurve->a.x 

(  f  BFLAG,  BNULL},  (  909.0,  228.0),  {  BNULL,  BNULL},  (  BNULL, 

BNULL}  } 

+  3  *  t  *  (t  -  1)  *  (t  -  1)  *  bcurve->b.x 

}; 

+  3  *  t  *  t  *  ( 1  -  t )  *  bcurve->c.x 

if (argc  !=  2)  ( 

+  t  *  t  *  t  *  bcurve->d.x; 
y  =  (1  -  t)  *  (1  -  t)  *  (1  -  t)  *  bcurve->a.y 

print  usage  (); 

+3*t*  (t-1)  *  (t  —  1 )  *  bcurve->b.y 

} 

+  3  *  t  *  t  *  { 1  -  t )  *  bcurve->c.y 

/*  Check  options  */ 

+  t  *  t  *  t  *  bcurve->d.y; 
lineto( (int)x,  (int)y); 

switch (argv[l] [0] )  { 

} 

case  'd' :  /*  deCasteljau  rendering  */ 

} 

case  'D' : 

strcpy (label,  "deCasteljau  rendering:"); 

/* - 

draw  fun  =  draw  bezier2; 

Draws  a  bezier  curve  as  a  series  of  line  segments. 

break; 

This  uses  the  deCasteljau  algorithm. 

case  '1':  /*  Literal  rendering  */ 

- v 

case  ' L' : 

draw  bezier2 (bcurve) 

strcpy (label,  "Literal  rendering:"); 

BEZIER_BOX  *bcurve; 

draw  fun  =  draw  bezierl; 

( 

break; 

extern  int  B  level; 

default : 

print f ("Unknown  option:  %c\n",  argv[l][0]); 

BEZIER  BOX  b  box; 

print  usage (); 

XY  aO,  dO; 

break; 

XY  al,  a2,  a3; 

} 

XY  bl,  b2; 

/*  NOTE:  the  following  pathname  may  need  to  be  modified  for  your  system.  */ 

XY  cl; 

initgraph (Sgdriver,  sgmode,  "C: Wturboc") ; 

if (accurate (bcurve)  ==  1)  ( 

if (gdriver  <  0  )  ( 

draw  hull (bcurve) ; 

printf ("Unable  to  initialize  graphics,  error  code:  %d",  gdriver) 

return (0) ; 

exit (0) ; 

) 

} 

B_level++; 

/*  Now  draw  the  letters  with  both  rendering  methods  */ 

aO.x  =  bcurve->a.x; 

outtextxy(l,  1,  label); 

aO.y  =  bcurve->a.y; 

draw  letter(30.0,  160.0,  lower  a,  180.0, 

dO.x  =  bcurve->d.x; 

WHITE,  SLASH  FILL,  WHITE,  draw  fun); 

dO.y  =  bcurve->d.y; 

draw  letter(220.0,  160.0,  lower  a,  120.0, 

WHITE,  SOLID  FILL,  WHITE,  draw  fun); 

al.y  =  aO.y  +  (bcurve->b.y  -  a0.y)/2; 

draw  letter (350.0,  160.0,  lower  a,  90.0, 

BLUE,  LINE  FILL,  BLUE,  draw  fun); 

bl.x  =  bcurve->b.x  +  (bcurve->c.x  -  bcurve->b.x) /2; 

draw  letter (450.0,  160.0,  lower  a,  40.0, 

bl.y  =  bcurve->b.y  +  (bcurve->c.y  -  bcurve->b.y) /2; 

WHITE,  SOLID_FILL,  WHITE,  draw_fun) ; 
draw  letter(500.0,  160.0,  lower  a,  20.0, 

cl.x  =  bcurve->c.x  +  (bcurve->d.x  -  bcurve->c.x) /2; 

WHITE,  LINE  FILL,  WHITE,  draw  fun); 

cl.y  =  bcurve->c.y  +  (bcurve->d.y  -  bcurve->c.y) /2; 

draw_letter (530.0,  160.0,  lower  a,  10.0, 

WHITE,  SOLID_FILL,  WHITE,  draw_fun) ; 

a2.x  =  al.x  +  (bl.x  -  al.x)/2; 
a2.y  =  al.y  +  (bl.y  -  al.y)/2; 

outtextxy(l,  190,  "Press  any  key  to  continue..."); 

b2.x  =  bl.x  +  (cl.x  -  bl.x) /2; 

getch() ; 

b2.y  =  bl.y  +  (cl.y  -  bl.y)/2; 

closegraph() ; 

} 

a3.x  =  a2.x  +  (b2.x  -  a2.x)/2; 

a3.y  =  a2.y  +  (b2.y  -  a2.y)/2; 

Draws  a  letter  at  a  given  location  of  a  given  size.  The 
outline  color,  fill  color  and  fill  style  are  also  specified. 

(Listing  continued  on  page  104.) 
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Listing  One  (Listing  continued ,  text  begins  on  page  46.) 


b_box.a.x  = 

aO.x; 

b  box . a . y  = 

aO  .y; 

b_box.b.x  = 

al  .x; 

b_box.b.y  = 

al  .y; 

b  box.c.x  - 

a2.x; 

b_box.c.y  = 

a2  .y; 

b  box.d.x  - 

a3.x; 

b  box.d.y  = 

a3.y; 

draw_bezier2 (&b  box) 

b  box.a.x  = 

a3.x; 

b  box.a.y  = 

a3  .y; 

b  box.b.x  = 

b2.x; 

b  box.b.y  = 

b2.y; 

b  box.c.x  = 

cl  .x; 

b  box.c.y  = 

cl  .y; 

b  box.d.x  = 

dO .  x  ; 

b  box.d.y  = 

dO.y; 

draw_bezier2 (&b  box) 

B_level — ; 
return  (0) ; 

/* - 

Determines  if  the  bezier  curve  has  been  determined  with  enough  accuracy. 
Returns  1  if  the  passed  Bezier  bounding  box  is  accurate  enough,  0  otherwise. 

- */ 

accurate (b_box) 

BEZIER_BOX  *b_box; 

{ 

extern  int  B_level; 
extern  int  B_cutoff; 

if(B_level  >=  B_cutoff)  { 
return (1) ; 

}  else  { 
return (0) ; 

} 

} 


/* - 

Draws  a  hull  as  defined  by  a  Bezier  bounding  box. 


draw_hull (b_box) 

BEZIER_BOX  *b_box; 

{ 

moveto((int)  b_box->a.x, 
lineto((int)  b_box->b.x, 
lineto((int)  b_box->c.x, 
lineto((int)  b_box->d.x, 

} 


(int)  b_box->a.y); 
(int)  b_box->b.y); 
(int)  b_box->c.y); 
(int)  b_box->d.y); 


*/ 


/* - 

Prints  the  usage  message  then  exits. 

- */ 

print_usage() 

{ 

printf ("Prints  a  series  of  lower  case  'a's  in  decreasing  size.  You  may\n"); 
printf ("select  between  deCasteljau  or  literal  rendering  methods . \n") ; 
printf ("Proper  usage :\n"); 
printf  ("\n") ; 

printf("  bezier  dl l\n") ; 
printf ("\n") ; 

printf  ("If  'd'  option  is  specified  the  deCasteljau  rendering  method\n"); 
printf  ("is  used.  If  '1'  option  is  specified  a  literal  Bezier  rendering\n") ; 
printf ("method  is  used.Xn"); 
exit (0) ; 


End  Listing 
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Listing  One  ( Text  begins  on  page  54.) 

View  subclass:  IBarView 

instanceVariableNames:  'maximumValue  ' 
classVariableNames:  " 
poolDictionaries :  '' 
category:  'Demo-Counter' ! 

IBarView  methodsFor:  'accessing'! 

barFrame 

Aself  insetDisplayBox  insetBy:  (50  @  10  corner:  10  @  10) ! 
labelCount 
A5 ! 

maximumValue 

AmaximumValue ! 
maximumValue:  anlnteger 

maximumValue  _  anlnteger! 
positionFor:  value 

Aself  barFrame  height  *  value  /  self  maximumValue!  ! 

IBarView  methodsFor:  'displaying'! 
clearBar 

!  height  bar  corner  I 

corner  _  self  barFrame  bottomLeft. 
height  _  self  positionFor:  self  model  value  +  1. 
height  _  height  min:  (self  insetDisplayBox  height-10) . 
bar  _  corner  -(00  height)  extent:  self  barFrame  width  @  height. 
Display  white:  bar.! 
displayBar 

!  height  bar  corner  ! 

corner  _  self  barFrame  bottomLeft. 

height  _  self  positionFor:  self  model  value. 

height  _  height  min:  (self  insetDisplayBox  height-10) . 

bar  _  corner  -  (0  @  height)  extent:  self  barFrame  width  @  height. 

Display  black:  bar. 

Display  fill:  (bar  insetBy:  2  @  2) 
mask:  Form  darkGray.! 

displayView 

self  displayYLabels . 
self  displayBar! 
displayYLabels 

!  count  label  increment  I 

count  _  self  labelCount. 

increment  _  self  maximumValue  /  count. 

label  _  0. 

(count+1)  timesRepeat: 

[label  printstring  displayAt:  (self  barFrame  bottomLeft  - 

(35  0  ((self  positionFor:  label) +8))). 
label  _  label  +  increment] ! 
update:  aParameter 

self  clearBar. 
self  displayBar.!  ! 

IBarView  methodsFor:  'controller  access'! 
defaultControllerClass 

"Answer  the  class  of  a  typically  useful  controller." 

ACounterController !  ! 


BarView  class 

instanceVariableNames:  "! 

IBarView  class  methodsFor:  'instance  creation'! 

newWithHeight:  aNumber 

"Create  a  new  BarView  for  displaying  value  between  0  and  aNumber" 
Asuper  new  maximumValue:  aNumber! 

open :  aModel 

"Open  a  view  for  a  new  counter." 

"BarView  open:  Counter  new." 

!  aBarView  topView  ! 

aBarView  _  (BarView  newWithHeight:  10)  model:  aModel. 
aBarView  borderWidth:  2. 
aBarView  insideColor:  Form  white. 

topView  _  StandardSystemView  new  label:  'Counter'. 
topView  minimumSize:  80040. 
topView  addSubView:  aBarView. 

topView  controller  open! 

open:  aModel  withHeight:  anlnteger 

"Open  a  view  for  a  new  counter." 

"BarView  open:  Counter  new  withHeight:  20." 

!  aBarView  topView  I 

aBarView  _  (BarView  newWithHeight:  anlnteger)  model:  aModel. 
aBarView  borderWidth:  2. 
aBarView  insideColor:  Form  white. 

topView  _  StandardSystemView  new  label:  'Counter'. 
topView  minimumSize:  80040. 
topView  addSubView:  aBarView. 

topView  controller  open!  ! 

View  subclass:  #CounterView 

instanceVariableNames:  '' 
classVariableNames:  " 
poolDictionaries:  '' 
category:  'Demo-Counter' ! 

! CounterView  methodsFor:  'displaying' ! 
displayView 

"Display  the  value  of  the  model." 


I  box  pos  ! 

"Position  the  text  at  the  left  side  of  the  display  area." 
box  _  self  insetDisplayBox.  "get  the  view's  box" 

pos  _  box  origin  +  (4  0  (box  extent  y  /  3)) . 

"put  the  text  1/3  of  the  way  down  to  the  left" 
"Concatenate  the  components  of  the  output  string  and  display  them." 
('val:  ',  self  model  value  aslnteger  printstring,  '  ') 

asDisplayText  displayAt:  pos.!  ! 

iCounterView  methodsFor:  'updating'! 
update:  aParameter 

"Simply  redisplay  everything." 
self  display!  ! 

iCounterView  methodsFor:  'controller  access'! 
defaultControllerClass 

"Answer  the  class  of  a  typically  useful  controller." 

ACounterController !  ! 


CounterView  class 

instanceVariableNames:  ''! 

iCounterView  class  methodsFor:  'instance  creation'! 
open:  aModel 

"Open  a  view  for  a  new  counter." 

"CounterView  open:  Counter  new." 

!  aCounterView  topView  ! 

aCounterView  _  CounterView  new  model:  aModel. 
aCounterView  borderWidth:  2. 
aCounterView  insideColor:  Form  white. 

topView  _  StandardSystemView  new  label:  'Counter'. 
topView  minimumSize:  80040. 
topView  addSubView:  aCounterView. 

topView  controller  open! 

openWithGraphicalButtons:  aModel 

"Open  a  view  for  a  new  counter  that  has  fixed  graphical  buttons  for 

incrementing  and  decrementing  the  value." 
"CounterView  openWithGraphicalButtons:  Counter  new" 

i  aCounterView  topView  switch  aSwitchView  ! 

aCounterView  _  CounterView  new  model:  aModel. 
aCounterView  insideColor:  Form  white. 

topView  _  StandardSystemView  new  label:  'Counter'. 
topView  minimumSize:  120  0  80. 
topView  maximumSize:  400  0  300. 


topView  addSubView:  aCounterView 

in:  (0.4  @  0  extent:  0.6  0  1) 
borderWidth:  (0  @  2  extent:  201). 

switch  _  Button  newOff.  "add  increment  button" 

switch  onAction:  [aCounterView  model  increment] . 
aSwitchView  _  SwitchView  new  model:  switch. 
aSwitchView  label:  ('+'  asDisplayText  form  magnifyBy:  202). 
aSwitchView  insideColor:  Form  lightGray. 
topView  addSubView:  aSwitchView 

in:  (000  extent:  0.4  @  0.5) 
borderWidth:  (2  @  2  extent:  000). 

switch  _  Button  newOff.  "add  decrement  button" 

switch  onAction:  [aCounterView  model  decrement]. 
aSwitchView  _  SwitchView  new  model:  switch. 
aSwitchView  label:  ('-'  asDisplayText  form  magnifyBy:  202). 
aSwitchView  insideColor:  Form  lightGray. 
topView  addSubView:  aSwitchView 

in:  (0  0  0.5  extent:  0.4  0  0.5) 
borderWidth:  (2  @  1  extent:  002). 
topView  controller  open! 

openWithTextButtons :  aModel 

"Open  a  view  for  a  new  counter  that  has  fixed  text  buttons  for 

incrementing  and  decrementing  the  value." 
"CounterView  openWithTextButtons:  Counter  new" 

!  aCounterView  topView  switch  aSwitchView  ! 

aCounterView  _  CounterView  new  model:  aModel. 
aCounterView  insideColor:  Form  white. 

topView  _  StandardSystemView  new  label:  'Counter' . 
topView  minimumSize:  160  0  60. 
topView  addSubView:  aCounterView 

in:  (000  extent:  1  0  0.6) 
borderWidth:  2. 

switch  _  Button  newOff.  "increment  button" 

switch  onAction:  [aCounterView  model  increment] . 
aSwitchView  _  SwitchView  new  model:  switch. 
aSwitchView  label:  (Text  string:  'increment'  emphasis: 

2)  asDisplayText. 

aSwitchView  insideColor:  Form  white. 
topView  addSubView:  aSwitchView 

in:  (0  0  0.6  extent:  0.5  @  0.4) 
borderWidth:  (2  @  0  extent:  002). 
switch  _  Button  newOff.  "decrement  button" 

switch  onAction:  [aCounterView  model  decrement] . 
aSwitchView  _  SwitchView  new  model:  switch. 
aSwitchView  label:  (Text  string:  'decrement'  emphasis: 

2)  asDisplayText. 

aSwitchView  insideColor:  Form  white. 
topView  addSubView:  aSwitchView 
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in:  (0.5  @  0.6  extent:  0.5  @  0.4) 
borderWidth:  (060  extent:  2  @  2). 
topView  controller  open!  ! 

MouseMenuController  subclass:  #CounterController 
instanceVariableNames :  ' ' 
classVariableNames:  '' 
poolDictionaries :  " 
category:  'Demo-Counter'! 

ICounterController  methodsFor:  ' initialize-release' ! 
initialize 

"Initialize  a  pop-up  menu  of  commands  for  changing  the  value 

of  the  model.  " 

super  initialize. 

self  yellowButtonMenu:  (PopUpMenu  labelList:  #( (Increment  Decrement  )  )) 
yellowButtonMessages:  # (increment  decrement  )!  ! 

!CounterController  methodsFor:  'control  defaults'! 
isControlActive 

"Take  control  when  the  blue  button  is  not  pressed." 

Asuper  isControlActive  &  sensor  blueButtonPressed  not!  ! 

!CounterController  methodsFor:  'menu  messages' ! 
decrement 

"Subtract  1  from  the  value  of  the  counter." 
self  model  decrement ! 
increment 

"Add  1  to  the  value  of  the  counter." 
self  model  increment!  ! 

Model  subclass:  #Counter 

instanceVariableNames:  'value  ' 
classVariableNames:  " 
poolbictionaries:  " 
category:  'Demo-Counter'! 

! Counter  methodsFor:  'initialize-release'! 
initialize 

"Set  the  initial  value  to  0." 
self  value:  0!  ! 

! Counter  methodsFor:  'accessing'! 
getValue 

"Return  the  current  value  of  'value'" 

Avalue! 

setValue:  aNumber 

"Set  the  value  of  'value'  to  be  aNumber" 
value  :=  aNumber! 

value 

"Answer  the  current  value  of  the  receiver." 

Avalue! 

value:  aNumber 

"Set  the  counter  to  aNumber." 
value  _  aNumber. 
self  changed!  ! 

[Counter  methodsFor:  'operations'! 
decrement 

"Subtract  1  from  the  value  of  the  counter." 
self  value:  self  value  -  1! 

increment 

"Add  1  to  the  value  of  the  counter." 
self  value:  self  value  +  1! 

printOn:  aStream 

aStream  nextPutAll:  'a  CounterHolder  with  value  ',  self  value  printstring!  ! 

! Counter  methodsFor:  'printing'!  ! 


Counter  class 

instanceVariableNames:  "! 

! Counter  class  methodsFor:  'instance  creation'! 
new 

"Answer  an  initialized  instance  of  the  receiver." 
Asuper  new  initialize!  ! 


End  Listing 
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Listing  One  ( Text  begins  on  page  62. ) 

/************************************************************************** 

*  The  SEG4G  Library  by  A1  Williams.  ASMFUNC.H — This  header  allows  an  array  to 

*  be  executed  as  assembly  code.  The  routine  is  called  in  far  model  regardless 

*  of  the  model  the  C  program  is  compiled  in. 

♦define  asmfunc  Mint  (far  *)()) 

End  Listing  One 


/*  unusable  GOT  slot  0  */ 
/*  4  Gig  data  segment  */ 


/*  FWORD  pointer  to  GDT  */ 
struct  fword 
I 

unsigned  int  limit; 
unsigned  long  linear_add; 
}; 


static  struct  _GDT  GDT [2]  = 

{ 

(0,0,0,01, 

|0xFFFF,0, 0x9200, 0x8F} 

}; 


Listing  Two 

/********************************************************************** 

*  SEG4G.H — Header  for  SEG4G  Library  —  Williams  * 

typedef  unsigned  long  LPTR; 

/*  set  this  variable  to  0  for  normal  386,  1  for  Intel  INBOARD  386/PC  */ 
extern  int  inboard; 

/*  Function  prototypes  */ 

LPTR  seg_to_linear (void  far  *p) ; 

void  far  *linear_to_seg (LPTR  lin); 

void  extend_seg (void) ; 

void  a20(int  flag); 

unsigned  int  big_read(LPTR  address); 

void  big_write (LPTR  address, unsigned  int  byte); 

void  big_xfer (LPTR  src,  LPTR  dst,  unsigned  long  count); 

unsigned  int  ext_size (void) ; 

LPTR  ext_alloc (unsigned  size); 

LPTR  ext_realloc (unsigned  size); 
int  ext_free(int  exitflag) ; 

End  Listing  Two 


Listing  Three 


*  The  SEG4G  Library  by  A1  Williams.  SEG4G.C — These  subroutines  will  allow 

*  a  386  to  access  a  linear  address  space  of  4  Gigabytes.  You  may  select  * 

*  one  of  three  methods  for  incorporating  assembly  language  subroutines 

*  into  the  C  programs.  The  three  methods  are: 

*  ASM  -  Use  Microsoft's  MASM  5.1 

*  DATA  -  Use  the  asmfunc  macro  defined  in  ASMFUNC.H 

*  POWER  -  Use  the  asm  function  present  in  POWER  C 

*  You  must  select  one  of  the  three  methods  below: 

♦define  ASM  1 
♦define  DATA  2 
♦define  POWER  3 

/*  make  your  selection  here:  */ 

♦define  METHOD  DATA 


/*  If  using  an  INTEL  INBOARD  386/PC  set  this  variable  to  1  */ 
int  inboard=0; 


♦include  <dos.h> 

♦include  "seg4g.h" 

/*  Only  include  asmfunc. h  if  required  */ 
♦if  METHOD==DATA 
♦include  "asmfunc. h" 

♦endif 


/*  Keyboard  controller  defines  */ 

♦define  RAMPORT  0x70 

♦define  KB_PORT  0x64 

♦define  PCNMIPORT  OxAO 

♦define  INBA20  0x60 

♦define  INBA20ON  OxDF 

♦define  INBA20OFF  OxDD 

/*  Redefinitions  for  POWERC  */ 

♦ifdef  _ POWERC 

♦define  _enable  enable 
♦define  _disable  disable 
♦endif 


convert  a  far  pointer  to  a  linear  address 


LPTR  seg_to_linear (void  far  *p) 

{ 

return  (((unsigned  iong)FP_SEG(p)  )«4)+FP  OFF(p); 

) 


*  convert  a  linear  address  to  a  far  pointer 

void  far  *linear_to_seg (LPTR  lin) 

( 

void  far  *p; 

FP_SEG (p)  =  (unsigned  int)  (lin»4); 

FP_OFF (p)  =  (unsigned  int)  (lin&OxF) ; 
return  p; 

} 

/*  Global  descriptor  table  */ 
struct  _GDT 
{ 

unsigned  int  limit; 
unsigned  int  base; 
unsigned  int  access; 
unsigned  int  hi_limit; 

)? 


static  struct  fword  gdtptr;  /*  fword  ptr  to  gdt  */ 
♦  if  METHOD==POWER  I  I  METHOD==DATA 


/*  Protected  mode  assembly  language  routine  */ 
static  unsigned  char  code[]={ 

♦if  METHOD==DATA 


♦else 


♦endif 

♦endif 

/*****, 


0x55, 

/*  PUSH  BP 

*/ 

0x89, 

0xe5, 

/*  MOV  BP, SP 

*/ 

Oxle, 

/*  PUSH  DS 

*/ 

0xc5, 

0x5e,  0x06, 

/*  LDS  BX, [BP+6] 

*/ 

OxOF, 

0x01,  0x17, 

/*  LGDT  FWORD  PTR  [BX] 

*/ 

Oxlf , 

/*  POP  DS 

*/ 

OxOf , 

0x20,  OxcO, 

/*  MOV  EAX, CR0 

*/ 

0x0c, 

0x01, 

/*  OR  AL, 1 

*/ 

OxOf, 

0x22,  OxcO, 

/*  MOV  CR0,  EAX 

*/ 

Oxeb, 

0x00, 

/*  JMP  SHORT  00 

*/ 

Oxbb, 

0x08,  0x00, 

/*  MOV  BX, 8 

*/ 

0x8e, 

Oxeb, 

/*  MOV  GS, BX 

*/ 

0x8e, 

0xc3, 

/*  MOV  ES, BX 

*/ 

0x24, 

Oxfe, 

/*  AND  AL, 0FEH 

*/ 

OxOf, 

0x22,  OxcO, 

/*  MOV  CR0, EAX 

*/ 

0x5d, 

/*  POP  BP 

*/ 

Oxcb) ; 

/*  RETF 

*/ 

OxOf, 

0x01,  0x17, 

/*  LGDT  [BX] 

*/ 

OxOf, 

0x20,  OxcO, 

/*  MOV  EAX, CR0 

*/ 

0x0c, 

0x01, 

/*  OR  AL, 1 

*/ 

OxOf, 

0x22,  OxcO, 

/*  MOV  CR0, EAX 

*/ 

OxEB, 

0x00, 

/*  JMP  SHORT  0 

*/ 

Oxbb, 

0x08,  0x00, 

/*  MOV  BX, 8 

*/ 

0x8e, 

Oxeb, 

/*  MOV  GS, BX 

*/ 

0X8e, 

0xc3, 

/*  MOV  ES, BX 

*/ 

0x24, 

Oxfe, 

/*  AND  AL, 0FEH 

*/ 

OxOf, 

0x22,  OxcO, 

/*  MOV  CR0, EAX 

*/ 

0xC3  } 

/*  RETN 

*/ 

****** 

************* 

...... 

Adjust  the  ES  and  GS  registers'  limit  to  4GB 


void  extend_seg() 
{ 


/*  compute  linear  address  and  limit  of  GDT  */ 
gdtptr. linear_add=seg_to_l inear ( (void  far  *)GDT) ; 
gdtptr . limit=15; 

/*  disable  regular  interrupts  */ 

_disable () ; 

/*  disable  NMI  */ 
if  (inboard) 
outp (PCNMIPORT, 0) ; 
else 

outp (RAMPORT, inp (RAMPORT) :0x80); 

/*  call  protected  mode  code  */ 

♦if  METHOD==ASM 
protsetup (&gdtptr) ; 

♦elif  METHOD==DATA 

(asmfunc  code) ( (void  far  *)&gdtptr); 

♦else 

asm (code, figdtptr) ; 

♦endif 

/*  Turn  interrupts  back  on  */ 

_enable () ; 

/*  Turn  NMI  back  on  */ 
if  (inboard) 

outp (PCNMIPORT,  0x80)  ; 
else 

outp (RAMPORT, inp (RAMPORT) &0x7F) ; 

) 


/*  macro  to  clear  keyboard  port  */ 

♦  define  keywaitO  {  while  (inp  (KB_PORT)  &2) ;  } 


/*********************************************************************** 
*  General  purpose  routine  to  allow  A20  (flag=l)  or  disable  A20  (flag=0) 
*********************************************************************** 
void  a20 (int  flag) 

{ 

if  (inboard) 

( 

outp ( INBA20, f lag?INBA20ON : INBA20OFF) ; 

) 

else 


key wait () ; 

outp (KB_PORT, flag?0xbc:0xb4) ; 
key wait  () ; 

outp (KB_PORT,  flag?0xbc:0xb4) ; 
keywait () ; 

) 


no 

640 


Dr.  Dobb's  Journal,  July  1990 


#if  METHOD==DATA  I !  ME T HOD==POWER 
/*  Assembly  code  to  read  a  byte  */ 
static  unsigned  char  rcode[]={ 

#if  METHOD==DATA 


0x55, 

/* 

PUSH  BP 

*/ 

0x89, 

0xe5, 

/* 

MOV  BP, SP 

*/ 

0x33, 

OxcO, 

/* 

XOR  AX, AX 

*/ 

0x8e, 

0xe8, 

/* 

MOV  GS, AX 

*/ 

0x66, 

0x8b, 

0x46,  0x06, 

/* 

MOV  EAX, [BP+6] 

*/ 

0x65, 

0x67, 

0x8a,  0x00, 

/* 

MOV  AL,GS: [EAX) 

*/ 

0x32, 

0xe4, 

/* 

XOR  AH, AH 

*/ 

0x5d, 

/* 

POP  BP 

*/ 

Oxcb} 

: 

/* 

RETF 

*/ 

0x31, 

OxCO, 

/* 

XOR  AX, AX 

*/ 

0x65, 

0x8e, 

OxCO, 

/* 

MOV  GS, AX 

*/ 

0x66, 

0x8b, 

0x07, 

/* 

MOV  EAX, [BX] 

*/ 

0x65, 

0x67, 

0x8a,  0x00, 

/* 

MOV  AL, GS : [EAX] 

*/ 

0xC3 

}; 

/* 

RETN 

*/ 

#endif 

/*  Assembly  code  to  write  a  byte  */ 
static  unsigned  char  wcode[]={ 


#if  METHOD==DATA 

0x55, 

/* 

PUSH  BP 

*/ 

0x89, 

0xe5, 

/* 

MOV  BP, SP 

*/ 

0x33, 

OxcO, 

/* 

XOR  AX, AX 

*/ 

0x8e, 

0xe8, 

/* 

MOV  GS, AX 

*/ 

0x66, 

0x8b, 

0x46, 

0x06, 

/* 

MOV  EAX, [BP+6] 

*/ 

0x8b, 

0x5e, 

0x0a, 

/* 

MOV  BX, [BP+10] 

*/ 

0x65, 

0x67, 

0x88, 

0x18, 

/* 

MOV  GS: [EAX] , BL 

*/ 

0x5d, 

/* 

POP  BP 

*/ 

Oxcb) 

/* 

RETF 

*/ 

♦else 

0x31, 

OxCO, 

/* 

XOR  AX, AX 

*/ 

0x65, 

0x8e, 

OxCO, 

/* 

MOV  GS, AX 

*/ 

0x66, 

0x8b, 

0x07, 

/* 

MOV  EAX, [BX] 

*/ 

0x65, 

0x67, 

0xc6, 

0x00,  0x00, 

/* 

MOV  GS: [EAX],?? 

*/ 

0xC3 

); 

/* 

RETN 

*/ 

♦endif 

Read  a  single  byte  from  extended  memory  given  a  linear  address 


unsigned  int  big_read(LPTR  address) 

{ 

#if  METHOD==DATA 

return  (asmfunc  rcode) (address) ; 
#else 

return  asm (rcode, saddress) &0xFF; 
lendif 
} 


*  Write  a  single  byte  to  extended  memory  given  a  linear  address 


void  big_write (LPTR  address, unsigned  int  byte) 
{ 

#if  METHOD==DATA 

(asmfunc  wcode) (address, byte) ; 

#else 

wcode [12] =byte; 
asm (wcode, Saddress) ; 

#endif 

) 


*  Block  move  a  number  of  bytes  from  one  area  to  another 


void  big_xfer (LPTR  src,LPTR  dst, unsigned  long  count) 

( 

#if  METHOD==DATA 

(asmfunc  xcode) (src, dst, count) ; 

♦else 

*(LPTR  *) Sxcode [10]=src; 

*(LPTR  *) &xcode [16]=dst; 

‘(unsigned  long  *) &xcode[22]=count; 
asm (xcode, (void  *)0); 

#endif 

) 


***/ 


/*  Assembly  code  to  block  move  bytes  */ 
static  unsigned  char  xcode []={ 

#if  METHOD==DATA 


0x55, 

/* 

PUSH  BP 

*/ 

0x89,  0xe5, 

/* 

MOV  BP, SP 

*/ 

0x06, 

/* 

PUSH  ES 

*/ 

0x56, 

/* 

PUSH  SI 

■*/ 

0X57, 

/* 

PUSH  DI 

*/ 

0x33,  OxcO, 

/* 

XOR  AX, AX 

*/ 

0x8e,  OxCO, 

/* 

MOV  ES, AX 

*/ 

0X66,  0X8B,  0X76,  0X06, 

/* 

MOV  ESI, [BP+6] 

*/ 

0X66,  0X8B,  0X7E,  0X0A, 

/* 

MOV  EDI, [BP+0A] 

*/ 

0X66,  0X8B,  0X4E,  0X0E, 

/* 

MOV  ECX, [BP+0E] 

*/ 

0XFC, 

/* 

CLD 

*/ 

0X67,  0XE3,  0X29, 

/* 

JECX  XEXIT 

*/ 

0XF7,  0XC6,  0X03,  0X00, 

/* 

TEST  SI, 3 

*/ 

0x74,  OxOD, 

/* 

JZ  XMAIN 

*/ 

0XF7 ,  0XC7,  0X03,  0X00, 

/* 

TEST  DI, 3 

*/ 

0x74,  0x07, 

/* 

JZ  XMAIN 

*/ 

0X67,  0X26,  0XA4, 

/* 

MOVSB  ES: 

*/ 

0x66,  0X49, 

/* 

DEC  ECX 

*/ 

0XEB,  0XEA, 

/* 

JMP  XTEST 

*/ 

0X51, 

/* 

PUSH  CX 

*/ 

0X66,  0XC1,  0XE9,  0X02, 

/* 

SHR  ECX, 2 

*/ 

0XF3,  0X67,  0X66,  0X26,  0XA5, 

/* 

REP  MOVSD  ES: 

*/ 

0X59, 

/* 

POP  CX 

*/ 

0X80,  0XE1,  0X03, 

/* 

AND  CX, 3 

*/ 

0XE3,  0X06, 

/* 

JCXZ  XEXIT 

*/ 

0X67,  0X26,  0XA4, 

/* 

MOVSB  ES: 

*/ 

0X49, 

/* 

DEC  CX 

*/ 

0XEB,  0XF8, 

/* 

JMP  XBYTE 

*/ 

0X5F, 

/* 

POP  DI 

*/ 

0X5E, 

/* 

POP  SI 

*/ 

0x07, 

/* 

POP  ES 

*/ 

0X5D, 

/* 

POP  BP 

*/ 

OXCB}; 

/* 

RETF 

*/ 

0x55, 

/* 

PUSH  BP 

*/ 

0x89,  0xe5, 

/* 

MOV  BP, SP 

*/ 

0x06, 

/* 

PUSH  ES 

*/ 

0x33,  OxcO, 

/* 

XOR  AX, AX 

*/ 

0x8E,  OxCO, 

/* 

MOV  ES, AX 

*/ 

0X66,  0XBE, 

/* 

MOV  ESI, 

*/ 

0X00,  0X00,  0x00,  0x00, 

/* 

SRC  ADDRESS 

*/ 

0x66,  OxBF, 

/* 

MOV  EDI, 

*/ 

0x00,  0x00,  0x00,  0x00, 

/* 

DST  ADDRESS 

*/ 

0x66,  0xB9, 

/* 

MOV  ECX, 

*/ 

0x00,  0x00,  0x00,  0x00, 

/* 

COUNT 

*/ 

0XFC, 

/* 

CLD 

*/ 

0X67,  0XE3,  0X29, 

/* 

JECX  XEXIT 

*/ 

0XF7,  0XC6,  0X03,  0X00, 

/* 

TEST  SI, 3 

*/ 

0x74,  OxOD, 

/* 

JZ  XMAIN 

*/ 

0XF7,  0XC7,  0X03,  0X00, 

/* 

TEST  DI, 3 

*/ 

0x74,  0x07, 

/* 

JZ  XMAIN 

*/ 

0X67,  0X26,  0XA4, 

/* 

MOVSB  ES: 

*/ 

0x66,  0X49, 

/* 

DEC  ECX 

*/ 

0XEB,  0XEA, 

/* 

JMP  XTEST 

*/ 

0X51, 

/* 

PUSH  CX 

*/ 

0X66,  0XC1,  0XE9,  0X02, 

/* 

SHR  ECX, 2 

*/ 

0XF3,  0X67,  0X66,  0X26,  0XA5, 

/* 

REP  MOVSD  ES: 

*/ 

0X59, 

/* 

POP  CX 

*/ 

0X80,  0XE1,  0X03, 

/* 

AND  CX, 3 

*/ 

0XE3,  0X06, 

/* 

JCXZ  XEXIT 

*/ 

0X67,  0X26,  0XA4, 

/* 

MOVSB  ES: 

*/ 

0X49, 

/* 

DEC  CX 

*/ 

0XEB,  0XF8, 

/* 

JMP  XBYTE 

*/ 

0x07, 

/* 

POP  ES 

*/ 

0X5D, 

/* 

POP  BP 

*/ 

0xC3, 

/* 

RETN 

*/ 

#endif 


lendif 


End  Listing  Three 


Listing  Four 

.MODEL  LARGE, C 

.  386P 

.CODE 

;  SEG51 . ASM 

;  Routine  to  goto  protected  mode  and  reset  ES  and  GS  registers  to  4GB 
IF  @DataSize 

protsetup  proc  f pointer :dword, c 
push  ds 

Ids  bx, fpointer 


ELSE 

protsetup  proc  fpointer :word, c 


mov  bx, fpointer 

END  IF 

lgdt  fword  ptr  [bx] 

;  Load 

GDT 

IF  @DataSize 

pop  ds 

END  IF 

mov  eax,cr0 

;  Goto 

prot  mode 

or  al,l 
mov  crO,eax 


jmp  short  nxtlbl 

;  Purge  instruction 

nxtlbl:  mov  bx,  8 

;  prefetch 

mov  gs,bx 

;  Load  gs/es 

mov  es,bx 
and  al, Ofeh 

;  Go  back  to 

real  mode 

mov  cr0,eax 
ret 

protsetup  endp 

;  Read  a  byte  from  an  LPTR 
big_read  proc  address :dword,c 
xor  ax, ax 

;  zero  GS 

mov  gs , ax 
mov  eax, address 

;  Load  LPTR 

mov  al, gs : [eax] 

;  Load  byte 

xor  ah, ah 

;  Zero  AH 

ret 

big  read  endp 

;  Write  a  byte  to  an  LPTR  address 
big  write  proc  address :dword,  byt:word, 

c 

xor  ax, ax 

;  Zero  GS 

mov  gs,ax 
mov  eax, address 

;  Load  LPTR 

mov  bx,byt 

;  Load  byte 

mov  byte  ptr  gs:[eax],bl 

;  Store  byte 

->  LPTR 

ret 

big  write  endp 

;  Block  move  bytes  between  LPTR' s 
big  xfer  proc  source :dword,  dest:dword, 

count :dword, c 

push  es 
push  si 
push  di 
xor  ax, ax 

;  Zero  ES 

(Listing  continued  on  page  112.) 
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Listing  Four  (Listing  continued,  text  begins  on  page  62.) 


mov  es,ax 
mov  esi, source 
mov  edi,dest 
mov  ecx, count 
cld 

;  The  following  code  tries  its  best  to  make  efficient  moves 
;  by  trying  to  move  bytes  until  word  alignment  is  achived 
xtest : 

jecxz  xexit 
test  si, 3 
jz  short  xmain 
test  di,3 
jz  short  xmain 

movs  es: [esi] , byte  ptr  es:[edi] 
dec  ecx 

jmp  short  xtest 


load  source  buffer 
load  dest  buffer 
load  count 


;  done? 

;  SI  word  aligned? 

;  DI  word  aligned? 

;  Move  a  byte 
;  update  count 
;  Recheck  alignments 


xmain : 


xbyte: 


xexit : 


push  cx 

shr  ecx,  2  Calculate  number  of  dwords 

;  And  move  all  of  them 

rep  movs  dword  ptr  es: [esi] ,dword  ptr  es:[edi] 
pop  cx 

and  cl, 3  ;  Move  left  over  bytes 

jcxz  xexit  ;  If  any 

movs  es: [esi] , byte  ptr  es:[edi] 
dec  cx 

jmp  short  xbyte 


pop  di 
pop  si 
pop  es 
ret 

big_xfer  endp 
end 


End  Listing  Four 


Allocate  memory  in  IK  blocks,  returns  start  address  of  block  or 
(LPTR)  -1  if  unable  to  allocate  memory 


LPTR  ext_alloc (unsigned  size) 

{ 

if  (installed) 

return  ext_realloc (size+e_alloc)  ; 
e_alloc=size; 
e_size=ext_size()  ; 
if  (e_size<size)  return  (LPTR)  -1L; 
e_size-=size; 
oldl5=_dos_getvect (0x15) ; 
_dos_setvect (0x15,  trapl5) ; 
installed=l; 

return  0xl00000+e_size*1024; 

) 


Attempt  to  change  the  size  of  an  allocated  block  (size  in  K) . 
Returns  start  address  or  (LPTR)  -1  if  unsuccessful 


LPTR  ext_realloc (unsigned  size) 

{ 

if  ([installed) 

return  ext_alloc (size)  ; 
if  (size>e_alloc+e_size)  return  (LPTR)-IL; 
if  (size<e_alloc) 

{ 

e_size+=e_alloc-size; 

e_alloc=size; 

} 

else  if  (size>e_alloc) 

{ 

if  (_dos_getvect (0x15) !=trapl5) 
return  (LPTR)  -1L; 
e_size-=size-e_alloc; 
e_alloc=size; 

} 

return  0xl00000+e_size*1024; 

} 


Listing  Five 

/*************************************************************************** 

*  The  SEG4G  Library  by  A1  Williams.  EXTMEM.C — These  subroutines  manage  * 

*  top  down  allocation  of  extended  memory.  * 

♦include  <dos.h> 

♦include  "seg4g.h" 

static  void  far  *oldl5; 
static  int  installed=0; 
static  unsigned  e_size,  e_alloc; 

/*  redefinitions  for  POWERC  */ 

#ifdef  _ POWERC 

♦define  _FAR 

♦define  _dos_getvect (n)  getvect(n) 

♦define  _dos_setvect (n, p)  setvect(n,p) 

/*  This  is  a  kludge  to  get  POWERC  to  chain  to  the  next  level  of  interrupt  */ 

unsigned  _ chain[14]=  (  0x559c, 0xe589,  0xb850, 0,  0x4687,  0x87fe,  0x46, \ 

0xb850,  0,  0x4687,  0x5d00,  Oxeafa,  0,  0  ); 

void  far  * _ cptr; 

♦define  _chain_intr (ptr)  {  _ cptr=(void  far  *) _ chain;  \ 

_ chain [12]=FP_OFF (ptr) ;  \ 

chain [13] =FP  SEG(ptr) ;  _ chain[3]=Rip;\ 

_ chain[8]=Rcs;  Rcs=FP_SEG( _ cptr) ;\ 

Rip=FP_OFF ( _ cptr) ;\ 

return;  ] 


♦define 

INTREGS  unsiqned 

Rbp, 

unsiqned 

Rdi, 

\ 

unsigned 

Rsi, 

unsigned 

Rds, 

\ 

unsigned 

Res, 

unsigned 

Rdx, 

\ 

unsigned 

Rex, 

unsigned 

Rbx, 

\ 

unsigned 

Rax, 

unsigned 

Rip, 

\ 

unsigned 

Res, 

unsigned 

Rf lags 

♦else 

♦define 

_FAR  far 

♦define 

INTREGS  unsigned 

Res, 

unsigned 

Rds, 

\ 

unsigned 

Rdi, 

unsigned 

Rsi, 

\ 

unsigned 

Rbp, 

unsigned 

Rsp, 

\ 

unsigned 

Rbx, 

unsigned 

Rdx, 

\ 

unsigned 

Rex, 

unsigned 

Rax 

♦endif 

/*  private  routine  to  capture 

requests 

for 

extended  memory  size 

static  void  interrupt  _FAR  trapl5 (INTREGS) 

( 

if  ( (RaxiOxFFOO)  !=  0x8800) 

_chain_intr (oldl5) ; 

Rax=e_size; 

return; 

) 

/*************************************************************************** 
*  Get  extended  memory  size  (in  K)  from  BIOS  * 

unsigned  int  ext_size() 

( 

union  REGS  r; 
r.h.ah=0x88; 
int86 (0x15,  &r,  &r) ; 
return  r.x.ax; 

} 


*  Free  the  extended  block.  Always  call  before  exiting  your  program!  * 

*  If  exitflag  is  set,  the  INT  15  trap  will  be  reset.  If  another  program  * 

*  has  captured  INT  15,  ext_free  will  return  a  -1.  If  you  call  with  * 

*  exitflag  ==  0,  and  another  program  has  captured  INT  15,  the  vector  is  * 

*  not  reset  and  ext_free  returns  a  1.  Otherwise,  ext_free  returns  0  and  * 

*  releases  INT  15  * 

***************************************************************************/ 

int  ext_free(int  exitflag) 

( 

int  rc=0; 

if  ([installed)  return  rc; 
if  (_dos_getvect (0x15) ==trapl5 ! lexitflag) 

{ 

if  (_dos_getvect (0x15) !=trapl5)  rc=-l; 
installed=0; 

_dos_setvect (0x15,  oldl5) ; 

} 

else 

{ 

e_size+=e_alloc; 

e_alloc=0; 

rc=l; 

) 

return  rc; 

} 

End  Listing  Five 


Listing  Six 


TEST.C — Example  program  for  the  SEG4G  library 


♦include  <stdio.h> 

♦include  <ctype.h> 

♦include  <signal.h> 

♦include  "seg4g.h" 
main  () 

{ 

LPTR  ad,aptr; 
int  ct=1024,i; 
int  data=0xAA; 

/*  Ignore  breaks  */ 

signal (SIGINT, SIG_IGN) ; 

printf("%dK  of  extended  memory  available\n", ext_size () ) ; 
/*  allocate  IK  of  extended  */ 
ad=ext_alloc (1) ; 
if  (ad==-lL) 


{ 

printf("Not  enough  extended  memory.  Only  %dK  available . \n", ext_size () ) ; 
exit  (1)  ; 


} 

print f(n IK  of  extended  mem  allocated  at  %81X.  %dK  remains . \n" , ad, ext_size ()) ; 
/*  Make  4GB  segments  */ 
extend_seg ( ) ; 

/*  Turn  on  A20  */ 
a20  (1) ; 

/*  Write  data  to  block  */ 
aptr=ad; 

for  (i=0;i<ct;i++) 

{ 

big_write (aptr++,  data) ; 

) 

printf ("Data  written  to  extended  memory\n\n") ; 

/*  Read  it  back  */ 


(Listing  continued  on  page  115.) 
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Listing  Six  (Listing  continued,  text  begins  on  page  62.) 

aptr=ad; 

for  (i=0;i<ct;i++) 

{ 

if  {big_read(aptr++) !=data) 

{ 

printf ("Error  reading  extended  memory\n\n") ; 
ext_free (1) ; 
a20 (0) ; 
exit  (1) ; 

} 

) 

printf ("Data  read  back  OK. \nExpanding  allocation  to  2K\n"); 

/*  Expand  memory  allocation  for  no  good  reason  */ 
ad=ext_realloc  (2) ; 
if  (ad==-lL) 

{ 

printf ("Not  enough  extended  memory.  Only  %dK  is  available. \n", ext_size ()) ; 
exit (1) ; 

} 

printf ("2K  of  extended  mem  allocated  at  %81X.  %dK  remains. \n", ad, ext_size ()) ; 
/*  Free  memory  */ 
ext_free (1) ; 

printf ("Extended  memory  freed.  %dK  Available. \n", ext_size ())  ; 

/*  Enter  memory  examine  loop  */ 
while  (1) 

{ 

printf ("Enter  AZ  to  quit . \nAddress  and  count?  "); 
if  (scanf("%li  %i", &ad, &ct) !=2) 

{ 

a20 (0) ; 
exit (0) ; 

} 

while  (ct — ) 

{ 

data=big_read(ad++) ; 

printf ("%c", isgraph(data) ?data: ' . ' ) ; 

} 

printf ("\n\n") ; 

) 

} 

End  Listing  Six 


Listing  Seven 

/************************************************************************* 
*  BLKTEST . C — Example  block  move  program  for  the  SEG4G  library  * 

♦include  <stdio.h> 

♦include  <dos.h> 

♦include  "seg4g.h" 

/*  Set  COLOR  to  0  if  you  have  a  monochrome  monitor  */ 

♦define  COLOR  1 

♦define  SCREEN_SIZE  4000 
♦define  ALIGN_SIZE  3 

unsigned  char  pattern (SCREEN_SIZE+ALIGN_SIZE) ; 

main  () 

{ 

LPTR  data, screen; 
unsigned  char  far  *p; 
int  i; 

extend_seg() ; 

♦if  COLOR 

screen=0xb8000; 

♦else 

screen=0xb0000; 

♦endif 

p=pattern; 

/*  align  to  nearest  4  byte  boundry  */ 

/*  This  isn't  required,  but  does  make  big_xfer()  more  efficient  */ 
while  (FP_OFF (p) & 3 )  p++; 
data=seg_to  linear (p); 
for  (i=0; i<SCREEN_SIZE; i+=4) 

{ 

p[i]='A' ; 

p[i+3)=p[i+l]=0x70; 

p[i+2)='B'; 

} 

big_xfer (data, screen, (unsigned  long) SCREEN_SIZE) ; 

} 


End  Listings 
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Listing  One  (Text  begins  on  page  72.) 

DEFINT  A-Z 
DIM  t!  (28) 

OPEN  "basoldpb.tim"  FOR  OUTPUT  AS  #1 

'time  for  a  raw  integer  loop,  executed  1,000,000  times. 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 

FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
NEXT  j 
NEXT  i 

t ! (0)  =  TIMER  -  t! 

'time  for  a  integer  assignment  loop,  executed  1,000,000  times, 
y  =  5:  z  =  -5 
PRINT  "Int  ="; 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
x  =  y 
x  =  z 
NEXT  j 
NEXT  i 

t! (1)  =  (TIMER  -  t!  -  t! (0) )  /  2 

'time  for  1,000,000  integer  adds 

y  =  5:  z  =  -5 

PRINT 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
x  =  x  +  y 


X  =  x  +  z 
NEXT  j 
NEXT  i 

t ! (2)  =  (TIMER  -  t!  -  t !  (0) )  /  2  -  t! (1) 

'time  for  1,000,000  integer  subtracts 
PRINT 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
x  =  x  -  y 
x  =  x  -  z 
NEXT  j 
NEXT  i 

t ! (3)  =  (TIMER  -  t!  -  t !  (0) )  /  2  -  t ! (1) 

'time  for  1,000,000  integer  multiplies 

k  =  7 

PRINT 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
x  =  k  *  j 
NEXT  j 
NEXT  i 

t! (4)  =  TIMER  -  t!  -  t! (1) 

'time  for  1,000,000  integer  divides 
PRINT  "\" 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
x  =  i  \  j 
NEXT  j 
NEXT  i 

t! (5)  =  TIMER  -  t!  -  t! (1) 


'time  for  100,000  string  assignments 
PRINT  "String="; 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  -  1  TO  1000 
FOR  j  =  1  TO  100 

x$  =  "abcdefghi jklmnopqrstuvwxyz" 
x$  =  "zyxwvutsrqponmlk jihgfedcba" 

NEXT  j 
NEXT  i 

t ! (6)  =  (TIMER  -  t!  -  t !  (0)  /  10)  /  2 


'time  for  100,000  string  MID$  operations 
x$  =  "abcdefghi jklmnopqrstuvwxyz" 
k  =  17 

PRINT  "Mid$"; 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  100 
MID$(x$,  k,  1)  =  "d" 

NEXT  j 
NEXT  i 

t! (7)  =  TIMER  -  t!  -  t!  (0)  /  10 

'time  for  10,000  string  concatenations 
x$  =  "" 

PRINT  "+" 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  10000 
x$  =  x$  +  "a" 

NEXT  i 

t ! (8)  =  TIMER  -  t!  -  t ! (6)  /  10  -  t !  (0)  /  100 

'time  for  a  single-precision  assignment  loop,  executed  1,000,000  times, 
y!  =  5! :  z!  =  -5! 

PRINT  "Single="; 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
x!  =  y ! 
x !  =  z ! 

NEXT  j 
NEXT  i 

t! (9)  =  (TIMER  -  t!  -  t!  (0))  /  2 

'time  for  1,000,000  single-precision  adds 
PRINT 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
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FOR  j  =  1  TO  1000 
x!  =  x!  +  y! 

x!  =  x!  +  z! 

NEXT  j 
NEXT  i 

t !  (10)  =  (TIMER  -  t!  -  t ! (0) )  /  2  -  t!(9) 

'time  for  1,000,000  single-precision  subtracts 
x!  =  0! 

PRINT 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
x!  =  x!  -  y! 

x!  =  x!  -  z! 

NEXT  j 
NEXT  i 

t !  (11)  =  (TIMER  -  t!  -  t !  (0) )  /  2  -  t ! (9) 

'time  for  100,000  single-precision  multiplies 
x!  =  1! 

PRINT 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  -  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  100 
x!  =  x!  *  1.00001 
NEXT  j 
NEXT  i 

t !  (12)  =  TIMER  -  t!  -  t !  (0)  /  10  -  t! (9)  /  10 

'time  for  100,000  single-precision  divides 
PRINT 

t!  =  TIMER:  WHILE  t!  -  TIMER:  WEND:  t!  -  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  -  1  TO  100 
x!  =  x!  /  1.00001 
NEXT  j 
NEXT  i 

t !  (13)  =  TIMER  -  t!  -  t !  (0)  /  10  -  t !  (9)  /  10 

'error  in  single-precision  mult iply/di vide 
t!  (14)  =  x!  -  1! 

'time  for  10,000  single-precision  exponentiations 
x!  =  100! 

PRINT  "A" 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  “  TIMER 
FOR  i  =  1  TO  10000 
x!  =  x!  A  .999999 
NEXT  i 

t ! (15)  =  TIMER  -  t!  -  t !  (0)  /  100  -  t !  (9)  /  100 

'time  for  a  double-precision  assignment  loop,  executed  1,000,000  times, 
y#  =  5.5#:  z#  =  -5.5# 

PRINT  "Double="; 


t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
x#  =  y# 
x#  =  z# 

NEXT  j 
NEXT  i 

t! (16)  =  (TIMER  -  t!  -  t! (0))  /  2 

'time  for  1,000,000  double-precision  adds 
t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
PRINT  "+" ; 

FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
x#  =  x#  +  y# 

NEXT  j 
NEXT  i 

t !  (17)  =  TIMER  -  t!  -  t !  (16)  -  t!(0) 

'time  for  1,000,000  double-precision  subtracts 
x#  =  0# 

PRINT 

t!  -  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
x#  =  x#  -  y# 

NEXT  j 
NEXT  i 

t !  (18)  =  TIMER  -  t!  -  t ! (16)  -  t ! (0) 

'time  for  100,000  double-precision  multiplies 
x#  =  1# 

PRINT  " * " ; 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  *  1  TO  1000 
FOR  j  =  1  TO  100 
x#  =  x#  *  1.00001# 

NEXT  j 
NEXT  i 

t ! (19)  =  (TIMER  -  t!  -  t ! (0)  /  10)  -  t ! (16)  /  10 

'time  for  100,000  double-precision  divides 
PRINT 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  -  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  100 
x#  =  x#  /  1.00001# 

NEXT  j 
NEXT  i 

t !  (20)  =  (TIMER  -  t!  -  t !  (0)  /  10)  -  t!  (16)  /  10 
'error  in  double-precision  multiply/divide 

t!  (21)  =  x#  -  1#  .  .  .  ,  „  „  _  , 

(Listings  continued  on  page  118.) 
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Listing  One  (Listing  continued ,  text  begins  on  page  72.) 

'time  for  10,000  double-precision  exponentiations 
x#  =  100# 

PRINT  "A" 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  10000 
x#  =  x#  A  .999999# 

NEXT  i 

t ! (22)  =  (TIMER  -  t!  -  t ! (0)  /  100)  -  t !  (16)  /  100 


NEXT  i 

t!  (26)  =  TIMER  -  t!  -  t! (0) 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 

IF  j  <  10  AND  i  <  0  THEN  x  =  1 
NEXT  j 
NEXT  i 

t!  (27)  =  TIMER  -  t!  -  t! (0) 

'Note:  if  the  two  times  are  appreciably  different,  some  optimization  has  been 
'done.  The  first  time  should  be  shorter  than  the  second. 


' following  are  logical  comparisons  and  operators 

'time  for  1,000,000  integer  comparisons 
x  =  0 

PRINT  "Int  compar" 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  -  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
IF  i  <  x  THEN  x  =  1 
NEXT  j 
NEXT  i 

t!  (23)  =  TIMER  -  t!  -  t! (0) 

'time  for  1,000,000  single-precision  comparisons 
x!  -  5! :  y!  =  3.333 
PRINT  "Single  compar" 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  *  1  TO  1000 

IF  x!  <  y!  THEN  x  -  1 
NEXT  j 
NEXT  i 

t!  (24)  =  TIMER  -  t!  -  t! (0) 

'time  for  1,000,000  double-precision  comparisons 
x#  =  5#:  y#  =  3.333# 

PRINT  "Double  compar" 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  -  1  TO  1000 
FOR  j  =  1  TO  1000 

IF  x#  <  y#  THEN  x  =  1 
NEXT  j 
NEXT  i 

t! (25)  =  TIMER  -  t!  -  t! (0) 


'is  there  short-circuit  expression  evaluation? 
'integer  loop,  1,000,000  times 
PRINT  "Short" 

t!  -  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  -  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 

IF  i  <  0  AND  j  <  10  THEN  x  =  1 
NEXT  j 


'screen  output:  print  1,000  70-byte  strings 
x$  =  STRINGS (70,  66) 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
PRINT  x$ 

NEXT  i 

t !  (28)  =  TIMER  -  t!  -  t !  (0)  /  1000 


'print  results  of  benchmark 

"Empty  integer  loop,  1,000,000  iterations:";  TAB (46);  t!(0) 
"1,000,000  integer  assignments:";  TAB(46);  t ! ( 1 ) 

"1,000,000  integer  additions:";  TAB(46);  t!(2) 

"1,000,000  integer  subtractions:";  TAB(46);  t ! (3) 

"1,000,000  integer  multiplications:";  TAB(46)';  t!(4) 

"1,000,000  integer  divisions:";  TAB (46);  t!(5) 

"100,000  string  assignments:";  TAB(46);  t!{6) 

"100,000  string  MID$  operations:";  TAB(46);  t!(7) 

"10,000  string  concatenations:";  TAB (46);  t ! ( 8 ) 

"1,000,000  single-precision  assignments:";  TAB(46);  t!(9) 
"1,000,000  single-precision  additions:";  TAB(46);  t !  (10) 
"1,000,000  single-precision  subtractions:";  TAB (46) ;  t ! (11) 
"100,000  single-precision  multiplications: ";  TAB(46);  t ! ( 12 ) 
"100,000  single-precision  divisions:";  TAB (46);  t !  ( 13 ) 

"Error  in  100,00*0  single-precision  mult/div:";  TAB(46);  t !  (14) 
"10,000  single-precision  exponentiations:";  TAB(46);  t !  ( 15 ) 
"1,000,000  double-precision  assignments:";  TAB (46) ;  t ! (16) 
"1,000,000  double-precision  additions:";  TAB (4 6);  t !  ( 17 ) 
"1,000,000  double-precision  subtractions:";  TAB (46) ;  t !  ( 18 ) 
"100,000  double-precision  multiplications:";  TAB (46);  t ! (19) 
"100,  000  double-precision  divisions:";  TAB (46);  t !  (20 ) 

"Error  in  100,000  double-precision  mult/div:";  TAB(46);  t !  (21 ) 
"10,000  double-precision  exponentiations:";  TAB(46);  t !  (22 ) 
"1,000,000  integer  comparisons:";  TAB(46);  t !  (23) 

"1,000,000  single-precision  comparisons:";  TAB (46);  t !  (24 ) 
"1,000,000  double-precision  comparisons:";  TAB(46);  t !  (25) 
"1,000,000  conditional  integer  assignments:";  TAB (46);  t ! (26) 
"1,000,000  conditional  assignments  (reversed):";  TAB (46) ;  t !  (27 ) 
"Print  1,000  70-byte  strings  to  the  screen:";  TAB(46);  t ! (28) 


PRINT 

#1, 

PRINT 

#1, 

PRINT 

#1, 

PRINT 

#1, 

PRINT 

#1, 

PRINT 

#1, 

PRINT 

#1, 

PRINT 

#1, 
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#1, 
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#1, 
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#1, 
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#1, 
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#1, 

PRINT 

#1, 
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#1, 
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#1, 

PRINT 

#1, 

PRINT 

#1, 

PRINT 

#1, 

PRINT 

#1, 
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#1, 
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#1, 

PRINT 

#1, 

PRINT 

#1, 

PRINT 

#1, 

PRINT 

#1, 

PRINT 

#1, 

PRINT 

#1, 

PRINT 

#1, 

END 

End  Listing  One 
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Listing  Two  (Text  begins  on  page  72.) 

DEFLNG  A-Z 
DIM  t!  (28) 

OPEN  "basnewpb.tim"  FOR  OUTPUT  AS  #1 

MAP  xl$$  *  1 

MAP  x26$$  *  26 

MAP  x70$$  *  70 

MAP  xl0000$$  *  10000 

'time  for  a  raw  long  integer  loop,  executed  1,000,000  times, 
t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
NEXT  j 
NEXT  i 

t!  (0)  =  TIMER  -  t! 

'time  for  1,000,000  long  integer  assignments, 
y  =  54:  2  =  -5fi:  PRINT  "Long  int=" 
t!  -  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  *  1  TO  1000 
x  =  y 
x  =  z 
NEXT  j 
NEXT  i 

t!  (1)  =  (TIMER  -  t!  -  t! (0) )  /  2 

'time  for  1,000,000  long  integer  adds 
PRINT  "+" 

t!  -  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  »  TIMER 
FOR  i  *  1  TO  1000 
FOR  j  -  1  TO  1000 
x  =  x  +  y 
NEXT  j 
NEXT  i 

t!  (2)  =  TIMER  -  t!  -  t! (1) 

'time  for  1,000,000  long  integer  subtracts 

x  =  0 

PRINT 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  *  TIMER 
FOR  i  °  1  TO  1000 
FOR  j  =  1  TO  1000 
x  =  x  -  y 
NEXT  j 
NEXT  i 

t! (3)  =  TIMER  -  t!  -  t! (1) 

'time  for  1,000,000  long  integer  multiplies 
PRINT 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
x  =  i  *  j 
NEXT  j 
NEXT  i 

t!  (4)  =  TIMER  -  t!  -  t! (1) 

'time  for  1,000,000  long  integer  divides 
PRINT  "/" 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 
x  =  i  \  j 
NEXT  j 
NEXT  i 

t!  (5)  =  TIMER  -  t!  -  t! (1) 

'time  for  100,000  fixed  string  assignments 
PRINT  "Fixed  string=" 

t!  =  TIMER:  WHILE  t!  -  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  100 

x26$$  =  "abcdefghi jklmnopqrstuvwxyz" 
x26$$  =  "zyxwvutrsqponmlk jihgfedcba" 

NEXT  j 
NEXT  i 

t ! (6)  -  (TIMER  -  t!  -  t ! (0)  /  10)  /  2 

'time  for  100,000  fixed  string  MID$  operations 
k  =  17 
PRINT  "Mid$" 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  100 

MID$(x26$$,  k,  1)  =  "d" 

NEXT  j 
NEXT  i 

t! (7)  =  TIMER  -  t!  -  t!  (0)  /  10 

'time  for  10,000  fixed  string  "concatenations" 
x$  =  "" 

PRINT  "+" 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  10000 

MID$ (xl0000$$,  i,  1)  =  "a" 

NEXT  i 

t! (8)  =  TIMER  -  t!  -  t!  (0)  /  100 

' following  are  logical  comparisons  and  operators 

'time  for  1,000,000  long  integer  comparisons 
x  =  5& :  y  =  -5& 

PRINT  "Long  int  compar" 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
FOR  j  =  1  TO  1000 

IF  i  <  y  THEN  x  =  1 

(Listing  continued  on  page  120.) 
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Listing  Two  (Listing  continued,  text  begins  on  page  12.) 

NEXT  j 
NEXT  i 

t!  (23)  =  TIMER  -  t!  -  t! (0) 

'screen  output:  print  1,000  70-byte  fixed  strings 
x70$$  =  STRING? (70,  66) 

t!  =  TIMER:  WHILE  t!  =  TIMER:  WEND:  t!  =  TIMER 
FOR  i  =  1  TO  1000 
PRINT  x70$$ 

NEXT  i 

t!  (28)  =  TIMER  -  t!  -  t !  (0)  /  1000 


'print  results  of  benchmark 

PRINT  #1,  "Raw  long  integer  loop,  1,000,000  iterations:";  TAB(45);  t ! (0) 
PRINT  #1,  "1,000,000  long  integer  assignments:";  TAB(45);  t! (1) 

PRINT  #1,  "1,000,000  long  integer  additions:";  TAB(45);  t! (2) 

PRINT  #1,  ”1,000,000  long  integer  subtractions:";  TAB(45);  t ! (3) 

PRINT  #1,  "1,000,000  long  integer  multiplications:";  TAB(45);  t ! ( 4) 

PRINT  #1,  "1,000,000  long  integer  divisions:";  TAB(45);  t ! (5) 

PRINT  #1,  "100,000  fixed  string  assignments:";  TAB(45);  t ! ( 6) 

"100,000  fixed  string  MID$  operations:";  TAB(45);  t ! (7) 

"10,000  fixed  string  concatenations:";  TAB(45);  t ! (8) 
"1,000,000  long  integer  comparisons:";  TAB(45);  t !  (23) 

"Print  1,000  70-byte  strings  to  the  screen:";  TAB(45);  t ! (28) 


PRINT  #1, 
PRINT  #1, 
PRINT  #1, 
PRINT  #1, 
END 


End  Listing  Two 


Listing  Three 

defint  a-z 
els 

recordlength=152 

print"Sample  in-memory  mailing  list  program  demo  for  Dr.  Dobbs  Magazine." 
open"r", 1, "sample.dat", recordlength 
field  #1, recordlength  as  w$ 

'set  up  a  flex  string  variable  to  hold  the  data  fields 

map  rec$$ ‘recordlength, 10  as  dte$$,25  as  last$$,l  as  middle$$,_ 

20  as  first$$, 25  as  addressl$$, 25  as  address2$$, 25  as  city$$, 

2  as  state$$, 9  as  zip$$,10  as  phone$$ 


print"Please  wait: reading  the  data  file."; 
propellor$=" l/-\":where=pos (9) 
for  i=l  to  total 

locate  csrlin, where:print  mid? (propellor?, 1+i  mod  4,1); 
get  1 , i 
records $ (i) =w$ 

next  i 
close  1 
current=l 


while  1 

els 

print  total;"  total  records  of  a  maximum  of";y 
print "Current  record  is  #"; current 
locate.  4,1 

rec$$=records$ (current) 

print  "Date  entered:  ";dte$$;"  Phone: ";phone$$ 
print  "Name:  ";rtrim$ (first??) ; "  " ;middle??; "  ";last?? 
print  "Address:  ";addressl$$ 
print  "Address:  ";address2$$ 

print  "City,  state,  zip:  ";rtrim$ (city$$) ;"  ";state$$;"  ";zip$$ 
locate  12,1 

print "E=enter  new  record  D=delete  current  record  Q=quit  without  saving" 
print"S=sort  records  J=jump  to  record  X=save  and  exit" 


wend 


while  not  instat :wend:cmd$=inkey$ 
locate  15, 1 :cmd$=ucase$ (cmd$) 

select  case  cmd? 


case 

-E" 

gosub 

entry 

case 

"D" 

gosub 

deleterec 

case 

"Q" 

gosub 

quit 

case 

"S" 

gosub 

sortrecs 

case 

"J" 

gosub 

jump 

case 

"X" 

gosub 

exitprog 

end  select 


total=lof (1) \recordlength  'number  of  records  in  the  sample  file 
y= (f re (-1) -32000) \recordlength  'number  of  records  that  will  fit  in  memory 
if  total>y  then  print"Not  enough  room  for  this  file. ": close: end 

dim  records$ (l:y)  'ordinary  string  array  will  hold  the  records. 


entry: 

'insert  new  record  at  current  position 
dte$$=date$ 

line  input"First  name:  ";first$$ 
line  input "Middle  initial:  ", -middle?? 
line  input "Last  name:  ";last$$ 
line  inpuf’Address  #1:  ";addressl$$ 
line  input "Address  #2:  ";address2$$ 
line  input"City:  ";city$$ 
line  input "State:  ";state$$ 
line  input"Zip:  ";zip$$ 
w$=rec$$ 

array  insert  records? (current ), w$ 

total=total+l 

return 


deleterec: 

'get  rid  of  current  record 
array  delete  records? (current) 

total=total-l:if  totaKcurrent  then  current=total 

if  currentcl  then  current=l 

return 


quit: 

end 

sortrecs: 

' sort  by  last  name . 

array  sort  records? (1)  for  total,  from  11  to  35 
return 


jump: 

input "Jump  to  record:  "; current 
if  current>total  then  current=total 
if  currentcl  then  current=l 
return 

exitprog: 

print"Saving  data  file.  "; 
open"o", 1, "sample.dat" 
close  1 

open"r", 1, "sample.dat", recordlength 
field  #1, recordlength  as  w? 
where=pos (9) 
for  i=l  to  total 

lset  w?=records? (i) 
put  l,i 

locate  csrlin, where:print  mid? (propellor?, 1+i  mod  4,1); 

next  i 

close:print 

end 


End  Listings 
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Cooperation  and 
Competition 


This  month  I  report  on  my  visit  to 
the  April  MacWorld  Expo;  raise 
some  questions  about  Glasnost 
programming,  ruminate  on  recent 
issues  in  chaos  theory,  fractals,  and 
neural  networks,  and  just  barely  justify 
the  title  of  this  month’s  column. 

On  (he  Paradigms  Beat  at 
MacWorld  '90 

The  MacWorld  show  has  now  reached 
the  same  state  that  Comdex  has  been 
in  for  five  years.  Practically  all  the  ap¬ 
plications  and  development  tools  you 
could  reasonably  ask  for  are  there,  so 
the  only  question  is,  are  they  any  good? 
That’s  not  a  question  you  can  easily 
answer  on  the  exhibit  floor,  so  you 
collect  the  press  kits,  go  to  the  parties, 
and  schmooze.  The  show  gave  eve, 
evidence  of  a  healthy  market,  ample 
opportunities  for  schmoozing,  but  few 
surprises. 

Well,  maybe  object-oriented  Prolog 
is  a  surprise.  Quintus  Computer  Sys¬ 
tems,  of  Mountain  View,  California,  an¬ 
nounced  Version  3.0  of  its  Prolog  com¬ 
piler  for  the  Mac,  along  with  an  object- 
oriented  Prolog  package.  Prolog++/ 
MacObject  has  objects,  inheritance,  meth¬ 
ods,  attributes,  and  daemons. 


Michael  Swaine 


Apple  announced  Developer  Tools 
Express,  a  mail-order  service  that  al¬ 
lows  developers  to  purchase  release 
versions  of  Apple  development  tools 
without  paying  the  APDA  membership. 
To  find  out  more  about  it,  call  or  write 
Apple  Developer  Channels,  Apple  Com¬ 
puter  Inc.,  20525  Mariani  Avenue,  MS 
33G,  Cupertino,  CA  95014-6299;  1-800- 
282-2734  (toll-free  US);  1-800-637-0029 


(toll-free  Canada);  1-  408-562-3910  (in¬ 
ternational). 

Apple  also  announced  Version  2.0 
of  MacApp,  the  object-oriented  appli¬ 
cation  framework.  It  should  be  more 
robust  than  Version  1.0,  which  was 
really  Version  2.0  of  the  product  —  the 
original  being  the  Lisa  Toolkit.  At  the 
Addison- Wesley  booth,  David  Wilson, 
Larry  Rosenstein,  and  Dan  Shafer  were 
signing  copies  of  their  Programming 
with  MacApp,  in  the  Macintosh  Inside 
Out  series  edited  by  Scott  Knaster.  The 
book  is  based  on  Dave  Wilson’s  courses 
on  MacApp  and  object-oriented  pro¬ 
gramming,  and  it  looks  good.  You  will 
need  MacApp  2.0  to  use  the  tutorial 
disk  included  with  the  book. 

Roaming  the  aisles,  I  ran  into  a  famil¬ 
iar  Mac  programmer  who  quoted  new 
Apple  COO  Michael  Spindler  that  there 
will  be  no  more  prima  donnas  at  Ap¬ 
ple.  I  said  it  showed  that  Spindler  knew 
his  limits  in  the  charisma  department, 
vis-a-vis  Jean-Louis  Gasse,  and  my  pro¬ 
grammer  friend  said  no,  it  showed  that 
Spindler  didn’t  know  anything  about 
programmers. 

A  charisma  gap  at  Apple  could  be  a 
problem  for  the  company.  The  Moscow 
model  suggests  that  if  you  want  your 
dictatorship  to  be  perceived  as  benevo¬ 
lent,  a  little  charisma  doesn’t  hurt. 

The  2-1 /2-th  Party  Developer 

Given  that  1.  Apple  makes  it  clear  to  its 
third-party  developers  that  deviations 
from  the  party  line  in  matters  such  as 
the  user  interface  are  unwise,  and  2.  it 
expects  the  developers  to  see  how  this 
control  benefits  the  developers  them¬ 
selves,  it’s  not  unfair  to  say  that  Apple 
wants  its  dictatorship  to  be  perceived 
as  benevolent.  Apple  isn’t  following 
any  Moscow  model,  but  it  is  pushing 


for  a  kind  of  Glasnost  programming,  a 
new  openness  that  is  supposed  to  re¬ 
sult  in  cooperation  within  a  competi¬ 
tive  free  market. 

This  new  openness  is  the  paradigm 
of  cooperative  programming,  in  which 
programs  written  by  different  compa¬ 
nies  work  together  harmoniously  and 
communicate  smoothly  while  the  com¬ 
panies  that  produce  them  fight  to  drive 
each  other  out  of  business.  There  is 
some  irony  in  such  a  plan  coming  along 
at  the  same  time  Apple  is  apparently 
fostering  competition  within  the  com¬ 
pany  by  creating  two  distribution  chan¬ 
nels  for  developer  tools,  but  no  doubt 
APDA  and  Developer  Tools  Express 
will  coexist  amicably.  Cooperative  pro¬ 
gramming  is  not,  of  course,  the  exclu¬ 
sive  province  of  the  Mac’s  niche.  (Ap¬ 
ple  may  object  that  the  Mac  is  not  a 
niche  product.  Macht  nichts.)  But  a 
benevolent  dictatorship  with  control 
over  the  hardware  platform  and  the 
operating  system  is  in  a  better  position 
than  IBM  or  Microsoft  to  make  it 
happen. 

The  basis  for  this  new  paradigm  for 
Macintosh  software  development  is  Ver¬ 
sion  7  of  the  Mac  operating  system, 
due  out  later  this  year.  Version  7  will 
support  several  levels  of  inter-applica¬ 
tion  communication,  from  the  existing 
copy  and  paste  buffer  to  live  copy  and 
paste,  network  support,  and  store-and- 
forward  communication.  Apple  argues 
that  the  rich  set  of  interapplication  com¬ 
munication  tools  in  System  7  will  lead 
to  a  new  kind  of  software;  to  smaller, 
targeted  tools  that  do  one  thing  well, 
rather  than  massive  integrated  applica¬ 
tions  that  try  to  do  everything. 

Apple  believes  that  this  will  happen, 
is  convinced  that  it  had  better  happen, 
and  is  doing  a  lot  to  make  it  happen. 
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Claris  has  been  talking  up  the  new 
approach,  saying  in  guest  editorials  in 
computer  magazines  that  Macintosh  soft¬ 
ware  developers  need  to  learn  a  new 
way  of  operating  —  a  new  cooperative 
spirit;  the  word  Glasnost  may  not  ap¬ 
pear  explicitly,  but  it’s  there  between 
the  lines.  All  this  sounds  better,  one 
might  argue,  coming  from  a  third-party 
developer  rather  than  just  from  Apple. 
That  is,  if  Apple  software  spinoff  Claris 
can  be  called  a  third-party  developer. 
The  term  “stalking  horse”  trots  to  mind. 

Is  Apple/Claris  right?  Is  cooperative 
programming  going  to  work?  And  if 
so,  what  will  this  cooperative  program¬ 
ming  be  like? 


Getting  the  Message 

Here’s  what  Apple’s  interapplication  sup¬ 
port  under  System  7  will  include: 

•  The  current  copy  and  paste  facility, 
restricted  to  data  only,  supporting  vari¬ 
ous  formats.  The  Scrap  Manager  will 
continue  to  provide  this  basic  form  of 
interapplication  communication. 

•  Live  copy  and  paste,  in  which  changes 
made  to  the  original  (after  copying  and 
pasting)  are  reflected  in  all  the  copies. 
This  is  a  new  facility,  provided  by  the 
Edition  Manager  in  System  7. 

•  Message  passing.  Changes  to  the  Event 
Manager  will  allow  messages  to  be 
passed  between  applications  rather  than 


just  within. 

•  AppleEvents.  This  is  an  Apple-defined 
set  of  standard  messages  that  all  appli¬ 
cations  will  be  expected  to  handle  and 
that  all  are  permitted  to  send.  Message 
passing  between  applications  will  not 
be  limited  to  AppleEvents,  but  Ap¬ 
pleEvents  will  provide,  in  effect,  a  lan¬ 
guage  for  interapplication  communica¬ 
tion.  It  will  also  serve  as  the  enabling 

Who  invented  the 

Mandelbrot  set? 

There  is  a  surly 
controversy  brewing 
over  credit 
in  the  field 


technology  for  a  future  user  scripting 
language.  The  user  scripting  language 
will  allow  users  to  control  applications 
and  the  system  itself  with  unprece¬ 
dented  (for  the  Macintosh)  flexibility 
and  power,  and  with  a  single,  universal 
user  interface. 

•  Lower-level  tools  for  interapplication 
communication,  including  separate  tool¬ 
boxes  for  immediate  and  store-and- 
forward  communication.  Store-and-for- 
ward  will  allow  the  user  or  an  applica¬ 
tion  to  leave  a  message  for  another 
application  to  handle  even  if  the  other 
application  is  currently  in  use  or  not 
running  or  temporarily  in  an  inaccessi¬ 
ble  corner  of  a  network. 

The  low-level  interapplication  commu¬ 
nication  facilities  may  be  most  useful 
between  applications  from  a  single  ven¬ 
dor,  but  it  seems  likely  that  only  Ap¬ 
pleEvents,  with  its  high  level  of  control 
from  Apple,  will  have  the  power  to 
make  cooperative  programming  be¬ 
tween  vendors  work. 

AppleEvents  may  also  present  a  new 
kind  of  pressure  to  adapt.  It  could  be 
the  best  tool  Apple  has  for  getting  third- 
party  developers  to  add  interapplica¬ 
tion  communication  features  to  their 
software  fast.  Here’s  a  (perhaps)  fanci¬ 
ful  account  of  how  that  might  work: 

If  another  application  sends  your's 
an  AppleEvents  message  for  which  you 
haven’t  written  a  handler,  what  hap- 
(continued  on  page  127) 
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(continued  from  page  124) 
pens  is  up  to  the  system  or  to  the  mes¬ 
saging  application,  but  not  to  you.  In 
effect,  part  of  the  (extended)  interface 
to  your  application  has  been  taken  out 
of  your  hands.  An  unanswered  mes¬ 
sage  to  your  spreadsheet  application 
triggered  from  within  a  competitor's 
word  processing  application  could  con¬ 
ceivably  result  in  a  message  to  the  user 

One  mathematician 
quoted  lays  all 
the  blame  for  the 
controversy  at  IBM 
mathematician  Benoit 
Mandelbrot’s  feet 


your  code,  it  nags  you  to  make  it  real, 
as  other  people  in  your  company  are 
going  to  nag  you  to  do  the  same. 

Then  there’s  user  scripting.  Apple 
has  pushed  back  its  attack  on  user  script¬ 
ing  to  Version  8.0,  but  others  are  not 
waiting  for  8.0:  Manufacturers  of  appli¬ 
cations  that  already  have  user  scripting 
will  explore  ways  to  incorporate  Ap- 
pleEvents  into  their  scripting  languages. 
Shortly,  users  are  going  to  start  sending 
messages  to  your  application. 

So  yes,  it  looks  like  Apple’s  interap¬ 
plication  communication  is  going  to 
catch  on  quickly,  and  it  looks  like  co¬ 
operative  programming  will  become  a 
fact  of  life.  And  that  is  going  to  raise 


such  as  “Sorry.  That  spreadsheet  pro¬ 
gram  is  too  dumb  to  handle  this  simple 
request.  Maybe  you  should  consider  buy¬ 
ing  our  spreadsheet  program,  which 
always  works  smoothly  with  our  word 
processor.  And  if  you  send  in  your  copy 
of  that  worthless  spreadsheet  program, 
we’ll  give  you  a  20  percent  discount.  ” 

Maybe  it  won’t  work  that  way,  but  it 
is  true  that  the  mere  existence  of  in¬ 
terapplication  communication  will  cre¬ 
ate  a  new  window  into  every  existing 
application.  And  it  is  true  that  the  con¬ 
trol  over  this  window,  this  extension 
to  the  application’s  interface,  will  be 
in  the  hands  of  the  developer  of  the 
application  only  if  the  application  sup¬ 
ports  AppleEvents. 

In  any  case,  if  your  application  is 
going  to  fail  to  handle  these  messages, 
it’s  much  nicer  if  it  can  fail  gracefully 
to  handle  them.  This  should  be  fairly 
easy.  The  set  of  AppleEvents  messages 
will  be  well  defined,  and  handling  an 
AppleEvents  message  doesn’t  mean  that 
you  really  have  to  do  something  with 
it.  You  can  simple  acknowledge  it  and 
do  nothing,  or  send  back  some  mes¬ 
sage  of  your  own.  That’s  code  that 
could  be  written  overnight. 

Here  comes  the  real  pressure.  What 
was  formerly  a  large  task,  upgrading 
your  application  to  take  full  advantage 
of  a  major  new  release  of  the  operating 
system,  has  now  become  a  collection 
of  small  features  to  add.  The  insidious 
aspect  of  this  is  that,  once  you’ve  got  a 
(dummy)  handler  for  the  message  in 
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some  new  problems,  not  all  of  which 
are  technical. 

Back  to  the  Future 

Here  are  some  follow-up  observations 
on  some  of  the  more  futuristic  subjects 
I’ve  discussed  here  recently:  chaos  the¬ 
ory,  neural  networks,  and  fractals. 

Recently,  I  wrote  here  about  chaos 
theory  in  human  physiology,  and  sug¬ 
gested  that  the  combination  of  neural 
nets  and  chaos  theory  could  produce 
a  powerful  tool  for  exploring  the  be¬ 
havior  of  certain  types  of  complex  sys¬ 
tems.  At  the  EURASIP  Workshop  on 
Neural  Networks  in  Portugal  this  year, 
Steve  Renals  of  Edinburgh  University 
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(continued  from  page  127) 
presented  some  results  of  work  on 
chaos  theory  and  neural  networks.  One 
of  his  conclusions  was  that  chaos  could 
fulfill  an  important  role  in  associative 
memory  systems  by  providing  a  “don’t 
know”  state.  The  conference  papers 
are  collected  in  “Neural  Networks:  EU- 
RASIP  Workshop  1990  Proceedings,” 
Springer- Verlag,  1990. 

The  April  issue  of  Scientific  Ameri¬ 
can  contained  a  piece  on  the  use  of 
neural  networks  in  determining  the  struc¬ 
ture  of  complex  protein  molecules.  It’s 
apparently  no  longer  particularly  diffi¬ 
cult  to  map  out  the  sequence  of  amino 
acids  that  make  up  a  protein  molecule, 
but  the  three-dimensional  twists  and 
turns  of  the  chain-like  molecule  are 
very  hard  to  identify.  The  twisting  struc¬ 
ture,  which  determines  the  properties 
of  the  protein,  depends  on  the  electri¬ 
cal  forces  between  individual  amino 
acids  in  the  chain.  A  brute-force  ap¬ 
proach  to  determining  the  structure 
would  simply  examine  all  forces  be¬ 
tween  all  pairs  of  amino  acids;  and 
with  very  short  chains,  the  brute-force 
approach  works. 

For  most  interesting  proteins,  though, 
the  brute-force  approach  is  useless.  Ter¬ 
rence  Sejnowski  and  Ning  Qian  of  Johns 
Hopkins  University  have  tackled  the 
problem  with  a  neural-network  ap¬ 
proach  first  used  by  Sejnowski  and  Char¬ 
les  Rosenberg  in  NETtalk,  a  neural  net 
that  learns  to  pronounce  English  words. 
NETtalk  uses  context  to  determine  the 
pronunciation  of  individual  phonemes 
(units  of  sound  very  roughly  compara¬ 
ble  to  letters  in  written  English).  NET¬ 
talk  has  had  some  impressive  success, 
and  Sejnowski  and  Qian  thought  that 
the  electrical  interactions  among  seg¬ 
ments  of  a  protein  could  be  modeled 
very  much  like  context  effects  on  pho¬ 
nemic  units.  The  results,  though  lim¬ 
ited,  look  promising,  and  Sejnowski 
thinks  that  neural  nets  have  a  real  fu¬ 
ture  in  molecular  biology. 

The  April  issue  of  Scientific  Ameri¬ 
can  also  asks  the  question,  Who  in¬ 
vented  the  Mandelbrot  set?  There  is  a 
surly  controversy  brewing  over  credit 
in  the  field  of  fractals  and  particularly 
for  this  set,  which  has  been  called  “the 
most  complex  object  in  mathematics.” 
You  compute  the  Mandelbrot  set  from 
the  formula  z2  +  c,  where  z  and  c  are 
complex  numbers,  by  assigning  a  con¬ 
stant  value  to  c,  setting  z  initially  to  0, 
and  feeding  the  output  of  the  formula 
back  into  z  iteratively.  Pictures  of  the 
Rorschach-like  Mandelbrot  set  have  ap¬ 
peared  here  and  elsewhere,  and  are 
distinctive,  if  only  arguably  attractive. 
Whatever  its  aesthetic  merits,  the  Man¬ 
delbrot  set’s  discovery  is  an  important 


event  in  the  history  of  mathematics,  as 
the  set  has  many  applications,  espe¬ 
cially  in  the  testing  of  complex  dy¬ 
namical  systems.  The  study  of  such 
systems  is  the  aforementioned  chaos 
theory. 

One  mathematician  quoted  in  the 
Scientific  American  piece  lays  all  the 
blame  for  the  controversy  at  IBM  mathe¬ 
matician  Benoit  Mandelbrot’s  feet.  Ap¬ 
parently  all  of  the  following  people 
deserve  some  credit  in  the  discovery 
and  exploration  of  the  Mandelbrot  set: 
Pierre  Fatou,  who  defined  the  set  mathe¬ 
matically;  Gaston  Julia,  Mandelbrot’s 
teacher,  who  defined  the  Julia  set,  of 
which  the  Mandelbrot  set  is  a  generali¬ 
zation;  John  H.  Hubbard  and  Adrien 
Douady,  who  have  done  much  work 
on  the  set,  Hubbard  having  produced 
Mandelbrot  pictures  three  years  before 
Mandelbrot;  Robert  Brooks  and  J.  Peter 
Matelski,  who  published  both  an  ex¬ 
plicit  mathematical  formulation  and  a 
computer  printout  showing  the  famil¬ 
iar  image  of  the  set  before  Mandelbrot; 
and  F.  Riesz,  who  did  related  work 
about  40  years  ago.  No  one  challenges 
the  importance  of  Mandelbrot’s  own 
contribution,  but  many  are  put  off  by 
Mandelbrot’s  aggressive  self-promotion 
as  the  sole  discoverer  of  the  set.  For¬ 
mer  DDJ  editor  Randy  Sutherland  and 
I  joined  the  put-off  when  we  dealt  with 
Mandelbrot  while  trying  to  get  permis¬ 
sion  to  reproduce  a  picture  of  the  Man¬ 
delbrot  set  in  DDJ  a  few  years  ago.  As 
Douady  said,  “He  loves  to  quote  him¬ 
self  and  he  is  very  reluctant  to  quote 
others  who  aren’t  dead.” 

John  Horgan,  who  wrote  the  Scien¬ 
tific  American  piece,  suggests  that  the 
controversy  may  in  part  be  evidence 
of  paradigm  clash.  Mandelbrot  is  an 
applied  mathematician  and  many  of 
his  critics  are  pure  mathematicians,  with 
different  ideas  about  allocating  credit 
for  work.  Horgan’s  suggestion  places 
this  coolness  among  Mandelbrot  mathe¬ 
maticians  in  the  context  of  a  larger 
iceberg,  which  also  includes  the  near- 
universal  confusion  in  the  public  mind 
between  the  conduct  and  goals  of  pure 
and  applied  science,  and  between  the 
ditto  of  science  and  engineering;  it 
touches  the  glacial  spread  of  university 
involvement  in  industry,  the  conse¬ 
quences  of  which  nobody  seems  to  be 
examining  very  closely.  What  it  doesn’t 
do  is  to  warm  the  aforementioned  cool¬ 
ness  among  Mandelbrot  mathematicians. 

Maybe  Michael  Spindler  could  ex¬ 
plain  to  them  about  prima  donnas  and 
cooperation  among  competitors. 

DDJ 
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MIDI,  Turbo  C++, 
Token  Pasting,  and 
PC  Hot  Keys 


1am  writing  this  month  from  Red¬ 
ding,  California,  where  the  annual 
Redding  Jazz  Festival  is  underway. 
My  other  life  often  finds  me  at  these 
events  seated  at  a  different,  wider  key¬ 
board.  This  acoustic  form  of  jazz  that  I 
know  has  not  yet  given  way  to  technol¬ 
ogy.  We  use  computers  to  keep  track 
of  bookings,  income  (what  little  there 
is),  and  such,  but  we  do  not  play  this 
style  of  music  with  machines.  Other 
forms  of  music,  including  some  newer 
forms  of  jazz,  are  using  synthesizers, 
sequencers,  samplers,  and  an  interface 
called  “MIDI”  that  computer  manufac¬ 
turers  could  learn  from.  I  have  no  ear 
for  the  sounds  and  am  certainly  no 
expert  in  the  technology,  but  it  is  fasci¬ 
nating.  Jim  Conger  has  written  two 
books  named  MIDI  Sequencing  in  C 
and  C  Programming  for  MIDI.  Both  are 
published  by  M&T  Books  (Redwood 
City,  Calif.)  and  both  address  aspects 
of  MIDI  programming  that  a  C  pro¬ 
grammer  can  use  on  a  PC  with  a  MIDI 
interface  and  Microsoft  or  Turbo  C. 

Conger  explains  what  MIDI  is  and 
how  it  works,  and  he  provides  ample 
C  code  to  achieve  the  effects  he  de¬ 
scribes.  I  do  not  have  any  MIDI  equip¬ 
ment,  so  I  did  not  try  to  run  the  pro¬ 
grams,  but  the  text  in  the  books  is 
understandable  and  the  code  is  read¬ 
able,  although  the  small,  pale  typeface 


Al  Stevens 


that  the  publisher  uses  for  code  makes 
it  hard  to  read.  I  used  the  diskettes  to 
read  the  code  instead.  Maybe  it’s  a  way 
to  get  us  to  buy  the  diskettes,  which 
anyone  who  gets  a  book  for  its  code 
ought  to  do  anyway. 

The  author  says  that  musicians  are 
being  threatened  by  synthesized  mu¬ 
sic.  This  is  true.  Many  of  my  colleagues 
in  music  feel  that  threat;  some  of  them 


have  been  touched  by  it.  But  Conger 
goes  further  and  speculates  that  hu¬ 
man  composition,  conducting,  and  per¬ 
formance  can  eventually  be  replaced 
by  technology.  He  conjures  an  image 
of  a  digitized  wire-frame  model  of 
Leonard  Bernstein  conducting  a  bank 
of  synthesizers.  Add  an  audience  of 
rows  and  rows  of  nothing  but  digital 
audio  tape  recorders,  and  the  picture 
would  be  complete. 

Turbo  C++ 

The  news  this  month  is  Turbo  C++. 
Following  their  success  with  object- 
oriented  Pascal  5.5,  Borland  has  as¬ 
saulted  the  C++  object-oriented  market 
with  guns  drawn  and  blazing.  Origi¬ 
nally  intended  to  be  an  adjunct  to  Turbo 
C  3-0,  the  C++  face  of  Borland’s  com¬ 
piler  is  now  at  its  forefront.  By  empha¬ 
sizing  the  object-oriented  side  of  their 
most  popular  compiler  product,  Borland 
has  made  a  policy  commitment  to  object- 
oriented  programming  as  the  paradig¬ 
matic  wave  of  tomorrow. 

Included  with  Turbo  C++  are  a  C++ 
compiler,  an  ANSI-conforming  standard 
C  compiler,  and  a  completely  over¬ 
hauled  Integrated  Development  Envi¬ 
ronment.  The  C++  compiler  conforms 
to  the  AT&T  2.0  language  specifica¬ 
tion,  a  standard  of  sorts  but  still  a  mov¬ 
ing  target.  ANSI  has  launched  its  X3J16 
C++  standards  committee  and  we’ll  be 
hearing  more  about  that  undertaking 
in  the  months  and  years  to  come.  Until 
then,  purveyors  of  C++  language  prod¬ 
ucts  have  the  AT&T  reference  manual 
and  the  AT&T  implementation  of  C++ 
to  aim  at. 

Most  of  the  C++  programming  sys¬ 
tems  available  to  PC  users  are  ports  of 
AT&T’s  cfront  program,  the  translator 
that  reads  C++  source  code  and  emits 
C  language  source  code.  The  notable 
exception  until  now  was  Zortech  C++, 
an  implementation  that  is  C++  2.0  in 


spirit  but  that  has  numerous  departures 
from  the  AT&T  implementation.  Borland 
has  attempted  to  adhere  closely  to  the 
AT&T  reference  manual. 

I  am  writing  this  column  in  April,  a 
month  before  the  scheduled  announce¬ 
ment  of  Turbo  C++.  You  are  reading  it 
sometime  near  the  middle  of  June,  a 
month  after  the  announcement,  assum¬ 
ing  no  delays.  There  are  always  im¬ 
pediments  to  timely  reporting  when 
you  work  within  this  kind  of  schedule. 
My  experience  with  Turbo  C++  has 
been,  therefore,  gained  only  in  beta- 
land.  For  that  reason  I  can  report  no 
problems  with  the  product.  Sure,  there 
have  been  problems,  but  this  is  a  beta 
copy,  and  that’s  what  a  beta  test  is  for. 

I  just  finished  writing  a  book  called 
Teach  Yourself  C++.  By  the  time  you 
read  this,  Herb  Schildt  will  no  doubt 
be  writing  one  with  the  same  title.  Don’t 
be  fooled  by  imitations.  Mine  has  a 
yellow  cover.  (Sorry,  Herb.)  My  book 
has  about  130  exercise  programs.  Each 
exercise  demonstrates  a  specific  fea¬ 
ture  of  the  C++  language.  As  such,  the 
book  is  something  of  a  minor  C++  tor¬ 
ture  test,  and  I  used  two  ports  of  the 
AT&T  cfront  program  to  validate  the 
exercises.  Turbo  C++,  not  a  cfront  port, 
passed  with  flying  colors  even  in  its 
beta  configuration. 

There  are  two  different  compilers  in 
the  product  called  Turbo  C++.  The  other 
compiler  is  a  full  ANSI  C  compiler. 
Both  compilers  execute  from  within 
the  Integrated  Development  Environ¬ 
ment  or  from  the  command  line.  The 
program  figures  out  what  kind  of  pro¬ 
gram  it  is  compiling  based  on  the  ex¬ 
tension  of  the  source  file.  A  .C  file  is  a 
C  program.  A  .CPP  file  is  a  C++  pro¬ 
gram.  The  compiler  needs  to  know  the 
difference  to  know  how  to  handle  cer¬ 
tain  subtle  differences  in  the  languages. 
One  of  those  differences  involves  “type- 
safe  linkages.” 
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Type- Safe  Linkages 

Type-safe  means  that  a  function’s  dec¬ 
laration  and  its  callers  use  compatible 
types  for  the  parameters.  There  has 
been  a  measure  of  type  checking  in  C 
for  a  while.  A  C  program  specifies  a 
function’s  return  type  and  parameter 
list  in  the  function  prototype.  If  the 
function  declaration  or  a  call  to  the 
function  does  not  match  the  prototype 
specification,  the  compiler  declares  an 
error.  In  the  old  days  before  prototypes 
a  function  was  assumed  to  return  an 
integer  unless  it  was  declared  to  return 
something  else.  You  could  pass  it  any 
number  and  types  of  parameters  re¬ 
gardless  of  what  it  was  expecting.  The 
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compiler  did  not  care.  The  program¬ 
mer  had  to  wrestle  with  the  bugs  that 
resulted  when  the  program  passed  one 
thing  and  the  function  expected  some¬ 
thing  else.  C++  needs  stronger  typing 
and  so  its  designer  created  the  function 
prototype,  which  was  adopted  by  many 
C  compilers  and  eventually  by  the  ANSI 
C  standards  committee.  The  prototype 
allows  the  compiler  to  insure  that  calls 
to  a  function  match  the  function’s  dec¬ 
laration  with  respect  to  its  return  type 
and  parameter  list. 

The  C  prototype  is  an  effective  meas¬ 
ure  as  long  as  the  source  file  that  de¬ 
clares  the  function  and  the  one  that 
calls  it  are  using  the  same  copy  of  the 


prototype.  By  convention,  most  pro¬ 
grammers  will  put  the  prototype  in  a 
header  file  and  include  the  header  in 
the  source  file  that  declares  the  func¬ 
tion  and  all  others  that  call  the  func¬ 
tion.  But  this  practice  is  only  a  conven¬ 
tion  and  nothing  in  the  C  language 
enforces  it.  If  you  use  different  proto¬ 
types  for  the  same  function  in  different 
source  files,  the  calls  to  the  function 
can  have  different  configurations  with 
the  same  undesirable  results  that  we 

Most  of  the  C++ 
programming  systems 
available  to  PC  users 
are  ports  of  AT&T’s 
cfront  program,  the 
translator  that  reads 
C++  source  code  and 
emits  C  language 
source  code 


had  before  prototypes.  The  problem  is, 
of  course,  that  you  compile  the  source 
files  independently,  and  the  linker  has 
no  way  to  reconcile  different  function 
prototypes  between  independently  com¬ 
piled  object  modules.  The  traditional 
method  for  controlling  this  situation  is 
to  use  the  header  file  convention  men¬ 
tioned  above  and  a  well-defined  make 
file  that  assures  that  all  affected  source 
files  compile  when  a  header  file  they 
include  changes. 

C++  requires  stronger  type  checking 
across  linked  modules  because  much 
of  the  integrity  of  a  program  depends 
upon  the  correct  use  of  overloaded 
functions.  Therefore,  C++  2.0  introduces 
a  feature  called  “type-safe  linkage”  to 
guarantee  that  function  prototypes  are 
consistent  across  independently  com¬ 
piled  source  files.  To  achieve  this  guar¬ 
antee,  the  C++  compiler  translates  func¬ 
tion  names  into  “mangled”  names.  The 
translator  adds  characters  to  the  func¬ 
tion  name  to  encode  the  parameter  list. 
For  example,  the  following  function 
prototype  would  generate  the  follow¬ 
ing  mangled  function  name. 

long  foofint,  char  *,  struct  tm); 

//  mangled  name:  _foo _ FiPc2tm 

The  mangled  name  specifies,  in  cryp¬ 
tic  notation,  the  types  of  the  parame- 
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(continued  from  page  132) 
ters.  An  external  function  does  not, 
therefore,  have  the  name  you  gave  it. 
If  you  prototype  it  differently  in  a  re¬ 
mote  source  file,  the  mangled  name 
will  be  different,  and  you  will  get 
unresolved  symbols  when  you  link  the 
program.  Thus  you  have  type-safe  link¬ 
age  at  the  parameter  list  level.  For  some 
reason,  this  technique  does  not  simi¬ 
larly  encode  the  function’s  return  type. 

These  mangled  names  are  usually 
invisible  to  the  programmer  unless  you 
read  the  linkage  memory  map,  but  you 
must  know  about  them  because  the 
unresolved  symbol  errors  will  report 
the  mangled  names  rather  than  the  ones 


you  lovingly  bestowed  and  you  need 
to  find  the  original  name  among  the 
mangled  mess.  There  will  be  times  when 
you  need  to  tell  C++  not  to  mangle. 

Suppose  your  C++  program  calls  a 
function  that  was  compiled  by  a  C  com¬ 
piler.  That  is  not  an  unusual  thing  to 
do.  The  entire  standard  C  function  li¬ 
brary  is  available  to  C++  programs.  So, 
unless  you  tell  the  C++  compiler  other¬ 
wise,  it  will  mangle  the  function  name 
in  the  call,  and  the  linker  will  not  find 
a  matching  function.  Therefore,  the  C++ 
compiler  needs  a  way  to  know  that  a 
named  function  was  compiled  by  a  C 
compiler.  C++  uses  this  construct  to 
achieve  that  purpose. 


extern  "C" 

( 

//  C  things 


You  can  put  prototypes  between  the 
curly  braces,  and  the  compiler  knows 
that  calls  to  those  functions  must  be 
made  without  mangled  names.  C++  com¬ 
pilers  usually  include  standard  C  header 
files  that  already  have  the  extern  “C” 
statement  built  in. 

If  you  surround  an  entire  function 
with  the  extern  “C”  braces,  that  func¬ 
tion  will  compile  with  C  linkages.  You 
would  need  to  do  that  in  the  case  where 
you  are  using  a  C  library  function  that 
requires  your  program  to  provide  a 
named  function.  Of  course,  such  func¬ 
tions  do  not  enjoy  the  same  type-safe 
linkage  that  regular  C++  functions  have. 

ANSI  C  Token  Pasting 

A  few  months  ago  I  wondered  about 
the  ANSI  C  preprocessor  ##  token  past¬ 
ing  operation.  If  you  code  the  ##  op¬ 
erator  in  a  macro  replacement  list,  it 
replaces  the  two  parameters  that  sur¬ 
round  it  by  “pasting”  the  two  argu¬ 
ments  together  into  one  argument  and 
then  continuing  with  preprocessing.  For 
example: 

^define  pasteup(a,b)  a  ##  b 

foo(pasteup(12,  34)); 

The  resulting  statement  would  be: 

foo(l  234); 

One  is  hard  pressed  to  imagine  a  use 
for  this  feature.  Necessity  being  the 
mother  she  is,  we  can  only  speculate 
that  the  invention  of  ##  sprang  from 
the  loins  of  need.  The  behavior  of  ##  is 
more  peculiar  when  you  consider  this: 

pasteup(hello,dolly)(  ); 

The  effective  statement  is: 

hellodollyf  ); 

which  makes  us  suspect  that  ##  could 
be  of  some  use  in  the  preprocessor 
fabrication  of  identifiers. 

The  ##  behavior  is  well  documented 
in  the  ANSI  C  standard,  but  there  are 
no  good  examples  of  its  use  or  clues 
to  its  purpose.  That  bothered  me  be¬ 
cause  I  couldn’t  come  up  with  a  good 
use  for  it.  So,  as  an  experiment,  I  went 
looking  for  an  application  for  the  odd 
little  critter.  It  would  have  been  un¬ 
sporting  to  call  someone  on  the  X3J 1 1 
committee  and  ask  what  it  was  for  but 
I  wanted  to  find  a  real  use  for  token 
pasting,  and  eventually  1  did.  What  I 
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found,  however,  was  not  code  that  used 
the  ANSI  token  paster  at  all.  In  fact, 
what  I  found  was  not  in  a  C  program. 
Instead,  I  found  a  contrivance  in  the 
generic. h  header  file  that  comes  with 
C++  2.0  compilers.  The  following  con¬ 
struct  works  with  pre-ANSI  C  and  C++ 
preprocessor  programs: 

#define  name2(a,b)  a\ 

b 

The  purpose  of  this  macro  and  oth¬ 
ers  like  it  are  to  paste  type  and  class 
names  together  to  form  what  has  been 
called  a  “parameterized”  class  from  a 
generic  one.  In  Programming  in  C++, 
Prentice  Hall,  1989,  Dewhurst  and  Stark 
describe  what  they  call  “genericity,” 
still  another  abominable  non-word  that 
someone,  out  of  generosity  and  in  the 
true  spirit  of  computer  literature,  has 
contributed  to  the  English-speaking 
world.  There  they  observe  that  ANSI- 
conforming  compilers  could  achieve 
the  same  thing  with  this: 

^define  name2(a,b)  a##b 

Eureka!  Now  a  quick  look  at  the  ge¬ 
neric. h  of  Turbo  C++  reveals  that  they 
do  indeed  use  the  ##  operator  in  just 
that  fashion  and  my  quest  is  complete. 


My  original  comments  about  ##  came 
in  a  review  of  Rex  Jaeschke’s  book, 
Mastering  Standard  C.  Some  readers 
called  to  say  that  they  could  not  locate 
the  book  or  the  publisher.  Here  is  the 
address:  Professional  Press,  101  Witmer 
Rd.,  Horsham,  PA  19044,  215-957-1500. 

The  C++  dialect  is 
destined  to  replace  C 
as  the  language  of 
choice  for  developers  of 
software  systems 


The  Future  of  C 

Turbo  C++  marks  the  dawn  of  an  era. 
C++  proponents  would  say  that  the  era 
started  a  long  time  ago,  but  from  my 
view,  the  era  began  when  a  well-estab¬ 
lished  and  leading  language  vendor 
such  as  Borland  bet  the  farm  and  came 
out  full-bore  with  a  complete  C++  de¬ 
velopment  environment.  You  can  bet 
that  Microsoft  is  not  far  behind. 

The  C++  dialect  is  destined  to  re¬ 


place  C  as  the  language  of  choice  for 
developers  of  software  systems.  The 
combination  of  objects,  user-defined 
data  types  (same  thing,  only  different), 
and  the  C  syntax  makes  C++  a  natural 
heir  to  the  throne.  But  there  is  at  least 
one  category  of  program  that  will  never 
switch  to  C++.  Developers  of  utility 
and  systems  programs  will  stick  with 
C  for  its  freedom  and  close-to-the- 
metal  feel  and  for  its  lean  and  mean 
executables.  C++  programs  can  have 
those  qualities,  but  at  the  expense  of 
extensibility.  Add  all  those  extensible 
data  types  and  your  programs  will  spend 
time  and  memory  with  layers  of  con¬ 
structors  and  destructors  and  class  hi¬ 
erarchies.  Leave  them  out  and  you  are 
using  a  C++  compiler  to  develop  a  C 
program.  C  lives. 

By  the  way,  if  you  want  Turbo  C 
without  C++,  you  can  still  buy  Turbo 
C  2.0.  Borland  will  continue  to  market 
and  support  that  version  of  the  com¬ 
piler  as  the  C  language  entry-level  com¬ 
piler  to  compete  with  Microsoft  QuickC. 

I  do  not  know  prices  just  now,  but  you 
should  expect  Turbo  C  2.0  to  be  a  bit 
cheaper  than  when  it  was  this  year’s 
snappy  model.  I  would  have  preferred 
to  see  a  TC  3.0  that  fixed  the  ANSI 
incompatibilities  and  the  bugs  and  used 
the  new,  improved  IDE,  but  apparently 
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Borland  decided  to  invest  their  resources 
in  the  C++  package  and  leave  2.0  the 
way  it  is  for  those  who  want  it. 

Hot  Keys 

We’ve  all  used  programs  that  employ 
hot  keys.  On  the  PC,  hot  keys  are  key 
combinations  that  a  program  uses  to 
cause  things  to  happen.  The  most  typi- 

C++  requires  stronger 
type  checking  across 
linked  modules  because 
much  of  the  integrity 
of  a  program  depends 
upon  the  correct  use  of 
overloaded  functions 


cal  use  is  to  make  a  TSR  pop  up.  By 
definition,  a  hot  key  should  be  a  key 
combination  that  applications  do  not 
use  in  their  normal  command  set.  By 
convention,  hot  keys  are  combinations 
that  do  not  produce  anything  on  the 
screen  in  normal  DOS  use  and  that  are 
not  one  of  the  generic  function  keys. 
Sidekick  uses  the  Ctrl-Alt  combination. 
Ready  uses  the  5  on  the  numeric  key¬ 
pad  (with  NumLock  off). 

A  programmer  has  three  problems 
to  solve  with  respect  to  hot  keys.  First, 
how  do  you  read  one  from  the  key¬ 
board  to  let  the  user  change  the  hot 
key  setting?  Second,  how  do  you  trans¬ 
late  that  into  a  meaningful  display  to 
tell  the  user  what  the  key  combination 
is?  Third,  how  do  you  know  when  the 
hot  key  has  been  pressed?  The  code 
that  accompanies  this  month’s  column 
addresses  those  problems. 

Listing  One,  page  146,  is  hotkey.h,  a 
header  file  that  an  application  program 
will  include  to  use  the  hot  key  func¬ 
tions.  It  contains  the  prototypes. 

Listing  Two,  page  146,  is  testhk.c,  a 
program  that  demonstrates  the  use  of 
the  hot  key  functions.  Hot  keys  are 
described  in  terms  of  their  keyboard 
scan  code  and  the  BIOS  shift  key  mask. 
Each  key  on  the  keyboard  sends  a 
unique  scan  code  to  the  computer  when 
you  press  a  key.  These  codes  are  not 
ASCII,  and  you  will  find  them  docu¬ 
mented  in  many  books  about  program¬ 
ming  the  PC.  The  BIOS  shift  key  mask 
is  a  byte  in  low  RAM  that  represents  the 
current  status  of  the  Shift,  Ctrl,  and  Alt 
keys.  The  hot  key  software  takes  care 
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of  the  translation  of  the  codes  to  the 
key  values. 

The  testhk.c  program  begins  by  dis¬ 
playing  these  messages  to  describe  what 
it  expects  you  to  do: 

Press  a  hot  key 

Press  Esc  to  keep  the  one  you  have 

Press  the  Space  Bar  to  clear  the  one 
you  have 

Press  Enter  to  use  the  new  one 

Then  it  calls  the  hotkey  function,  pass¬ 
ing  the  addresses  of  an  integer  for  the 
scan  code  and  one  for  the  shift  key 
mask.  The  hotkey  function  lets  the  user 
press  different  hot  key  combinations, 
displaying  each  one  until  the  user 
presses  Enter,  Esc,  or  the  Spacebar. 

Once  the  user  has  selected  a  hot 
key,  the  testhk  program  displays  its 
value  by  calling  the  showkey  function, 
which  displays  something  like  Ctrl-X 
on  the  screen.  Then  testhk  calls  initkey 
to  initialize  testing  for  the  hot  key.  The 
iskeyhit  function  returns  nonzero  if  the 
hot  key  has  been  pressed  and  zero  if 
not.  The  testhk  program  loops  waiting 
for  a  press  of  the  hot  key.  Then  it  calls 
endkey. 

It  is  important  that  the  program  calls 
initkey  before  testing  for  the  hot  key 
press  and  endkey  afterwards.  Don’t 
leave  them  out. 

Listing  Three,  page  146,  is  hotkey. c, 
the  functions  that  manage  hot  key  pro¬ 
gramming  for  your  application.  The 
initkey  function  attaches  the  keyboard 
interrupt  vector  to  the  newkh  interrupt 
service  routine.  That  function  simply 
reads  the  keyboard  input  port  into  a 
variable  named  kbval  and  chains  to  the 
old  interrupt  vector.  On  some  PCs  you 
do  not  need  the  interrupt  service  rou¬ 
tine.  Anywhere  the  program  examines 
the  value  in  kbval  you  could  simply 
read  the  keyboard  input  port  0x60. 
Other  computers  do  not  work  that  way. 
The  input  port  delivers  a  meaningful 
value  only  after  an  interrupt  9.  There¬ 
fore,  the  program  attaches  to  interrupt 
vector  9  to  read  the  value  of  the  key¬ 
board  port. 

The  iskeyhit  function  accepts  a  scan 
code  and  shift  key  mask  and  tests  them 
against  the  current  values  of  kbval  and 
the  BIOS  shift  key  mask.  The  function 
returns  true  if  the  values  match  and 
false  otherwise. 

The  hotkey  function  programs  a  hot 
key.  When  the  user  presses  a  valid  hot 
key  combination,  the  function  displays 
an  ASCII  representation  of  it  on  the 
screen  and  waits  for  another  key  press. 
When  the  user  presses  Enter,  the  scan 
and  shift  mask  values  associated  with 
the  most  recent  key  are  returned  to  the 
caller.  If  the  user  presses  the  Esc  key, 


the  caller’s  original  values  are  returned. 
If  the  user  presses  the  Spacebar,  zeros 
are  returned. 

Reading  a  hot  key  is  no  cake  walk. 
Neither  DOS  nor  BIOS  return  anything 
when  you  press  one  of  the  key  combi¬ 
nations  that  we  have  said  are  valid  hot 
keys.  What  you  must  do  is  examine  the 
input  from  the  keyboard  port  and  react 
according  to  the  scan  codes  that  come 
in.  The  first  thing  to  do  is  wait  until  the 
user  gets  off  the  keyboard.  The  most 
significant  bit  (0x80)  of  the  scan  code 
will  be  zero  if  any  key  is  being  held 
down.  Otherwise  it  will  be  one.  Next, 
you  must  clear  the  BIOS  read-ahead 
buffer  and  keep  it  clear.  Every  time  the 
user  presses  a  valid  BIOS  key,  BIOS 
adds  an  entry  to  a  circular  read-ahead 
buffer.  By  clearing  that  buffer,  you  pre¬ 
vent  BIOS  from  beeping  when  the  buffer 
is  full.  Then  you  go  into  a  loop  reading 
the  keyboard  port  waiting  for  a  key  to 
be  pressed.  If  that  key  is  the  scan  code 
for  the  Esc,  Enter,  or  Spacebar  key,  you 
are  done.  Otherwise,  it  must  be  the 
Ctrl,  Alt,  or  a  Shift  key.  After  that  you 
wait  for  another  key  to  be  pressed. 
Then  you  wait  for  a  third  key  press  or 
a  key  release  at  which  time  you  have 
the  two  or  three  scan  codes  that  consti¬ 
tute  the  hot  key.  From  them  it  is  a  simple 
matter  to  validate  the  combination. 

The  user  might  try  to  program  an 
invalid  hot  key.  You  would  not  want 
to  use  the  letter  A  or  the  Home  key  as 
hot  keys,  for  example.  A  hot  key  must 
be  a  combination  that  includes  one  or 
more  of  the  Shift,  Ctrl,  and  Alt  keys  and 
another  key.  Or  a  valid  hot  key  can  be 
any  two  or  more  of  the  Shift,  Ctrl,  and 
Alt  keys.  If  the  user  selects  anything 
else,  the  hotkey  program  buzzes  and 
rejects  the  selection. 

The  showkey  function  returns  a 
pointer  to  a  display  string  that  it  con¬ 
structs  from  its  scan  code  and  shift  key 
mask  parameters.  You  can  use  this  string 
to  display  the  name  of  the  hot  key. 

These  functions  compile  with  Turbo 
C.  To  use  them  with  another  compiler, 
you  must  use  that  compiler’s  version 
of  the  setvect,  getvect,  sound ,  delay , 
and  nosound  functions.  Most  compil¬ 
ers  have  variations  on  the  first  two. 
Microsoft  C  uses  _dos_getvect  and 
_dos_setvect,  for  example.  The  other 
three  are  Turbo  C  specific.  You  can  use 
whatever  method  your  compiler  has 
to  make  a  noise  through  the  speaker 
or  you  can  stub  out  the  buzz  function. 

DDJ 
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The  Just  One  Thing 
Dilemma 


Arizona!  Carol  and  I  rolled  into 
Phoenix  in  the  middle  of  a  furi¬ 
ous  windstorm,  packed  into  the 
Magic  Van  along  with  dogs,  as¬ 
sorted  succulents,  and  a  truncated  fi¬ 
cus,  as  well  as  anything  Allied  Van 
Lines  had  forgotten  to  pack  the  previ¬ 
ous  Wednesday. 

Rolling  clouds  of  trendy  Santa-Fe  style 
dust  were  blowing  off  the  parched  land 
and  making  visibility  difficult  in  the 
Safeway  Parking  lot  somewhere  near 
Bell  Road  and  19th  Avenue.  I  was  pick¬ 
ing  my  way  carefully  through  the  gloom 
when  something  large  and  brown 
bounded  in  out  of  nowhere,  caromed 
off  a  Jeep  Wrangler  and  crossed  the 
lane  immediately  in  front  of  me  at  con¬ 
siderable  speed.  I  hit  the  brakes  and 
watched  as  it  wedged  itself  solidly  un¬ 
der  a  USA  Today  newspaper  rack. 

“I  bet  that’s  a  tumbleweed!”  Carol 
said  with  some  excitement. 

“But  this  is  a  supermarket  parking 
lot!”  I  objected,  feeling  all  the  romanti¬ 
cism  of  the  Wild,  Wild  West,  including 
images  of  singing  cowboys,  tumbling 
tumbleweeds,  and  wild  coyotes  (now 
made  mostly  of  marine  plywood  and 
sold  in  Hallmark  stores)  take  a  sharp 
turn  south  and  vanish  into  the  Nostal¬ 
gia  Zone. 

These  days,  I  guess  one  escapes  from 
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dust  storms  by  taking  refuge  in  the 
nearest  Circle-K.  The  cowboys  all  wear 
feed  caps  and  listen  to  rap  tapes  in 
their  jacked-up  Ranchero  4x4s.  But  by 
gully,  those  tumbleweeds  have  refused 
to  sell  out  —  even  if  it  means  tumbling 
right  in  the  front  door  of  K-Mart. 

The  world  —  and  Phoenix  —  are  full 
of  surprises.  What’s  true  of  Phoenix  is 
true  of  the  structured  programming 


world  as  well.  I  like  surprises,  and  there 
have  been  a  bunch  of  them  in  recent 
months. 

The  most  striking  is  the  sudden  ap¬ 
pearance  of  three  brand  new  Pascal 
compilers.  I’d  gotten  used  to  thinking 
of  Turbo  Pascal  as  unassailable  in  the 
marketplace  when  QuickPascal  ap¬ 
peared  and  did  quite  well,  thank  you. 
I  then  assumed  that  two  major  Pascal 
compilers  was  a  mighty  crowded  field  — 
and  now,  perhaps,  I  may  be  wrong  in 
that  as  well. 

I’ve  just  made  contact  with  the 
QuickByte  Pascal  people,  so  we’ll  push 
them  on  the  stack  until  a  future  col¬ 
umn.  The  other  two  Pascal  products 
come  from  Jensen  Partners  and  Stony 
Brook.  I’ll  be  testing  them  thoroughly 
in  coming  months,  and  you’ll  get  a 
report  when  the  testing’s  done. 

Crossing  a  Banana  with  a  Gorilla 

JPI’s  new  Pascal  is  notable  for  support¬ 
ing  objects  with  multiple  inheritance. 
Multiple  inheritance  is  one  of  those 
sleeper  concepts  that  (in  my  opinion) 
nobody  in  this  business  quite  under¬ 
stands  as  yet.  Intuition  tells  me  that  it 
represents  a  radically  different  way  of 
thinking  about  object  design.  I’ll  know 
when  I’ve  spent  some  time  with  it  — 
and  I’ll  be  asking  some  largish  ques¬ 
tions  including  whether  it  is  in  fact  a 
good  thing  at  all.  In  the  meantime,  let 
me  take  a  little  time  to  explain  what 
multiple  inheritance  means. 

In  single-inheritance  systems  such 
as  Smalltalk,  Actor,  and  Turbo/Quick- 
Pascal,  a  class  (object  type  in  Turbo 
Pascal  jargon)  may  have  only  one  par¬ 
ent  class.  Pretty  obviously,  multiple  in¬ 
heritance  allows  a  class  to  inherit  from 
more  than  one  parent  class. 

Think  for  a  bit  about  that  catering 
truck  that  blows  into  your  office  com¬ 
plex  parking  lot  at  10  A.M.  sharp,  most 


appropriately  playing  “La  Cucaracha” 
at  70  dB  on  its  electronic  horn.  A  cater¬ 
ing  truck  is  a  truck:  It  has  wheels,  an 
engine,  a  steering  mechanism,  and  a 
power  train.  A  catering  truck,  however, 
is  also  a  kitchen:  It  has  a  stove,  a  sink, 
a  refrigerator,  cabinets  full  of  food,  and 
a  microwave  oven.  In  the  grand  object 
hierarchy  describing  our  wonderfully 
surprising  world,  the  class  Cater- 
ingTruck  inherits  from  both  Truck  and 
Kitchen. 

Now,  we’ve  been  talking  about  ob¬ 
jects  for  most  of  a  year  as  though  any 
given  class  can  only  be  a  more  specific 
offshoot  of  its  parent  class.  A  menu  is 
a  specific  kind  of  window,  which  is  a 
specific  kind  of  rectangular  area  on  the 
screen,  and  so  forth.  A  menu  may  touch 
on  many  areas  of  the  system  at  large, 
allowing  you  to  choose  files,  or  paral¬ 
lel  ports,  or  customer  numbers.  None¬ 
theless,  at  the  heart  of  it  a  menu  is  a 
kind  of  window.  It  pops  up,  does  its 
thing,  and  then  vanishes. 

Applying  that  logic  to  class  Cater¬ 
ingTruck  is  not  so  clean.  In  a  single¬ 
inheritance  system,  you  have  to  make 
a  choice:  Is  CateringTruck  fundamen¬ 
tally  a  truck  or  a  kitchen? 

You  Choose,  You  Lose 

OK,  let’s  choose,  and  draw  it  all  out  in 
Figure  1.  If  pressed,  I’d  say  CateringTruck 
was  more  fundamentally  a  truck  than  a 
kitchen,  so  we’d  place  CateringTruck 
beneath  Truck  in  the  object  hierarchy. 
Truck ,  in  turn,  is  a  child  class  of  the 
SelfPropelledVehicle,  which  in  turn  is  a 
child  of  base  class  Vehicle ,  as  is  Rail- 
roadCar.  Vehicle  defines  those  few  meth¬ 
ods  common  to  all  vehicles,  such  as 
Stop.  (The  expected  Start  method  is  not 
defined  until  the  SelfPropelledVehicle 
class.  A  truck  can  put  itself  in  gear  and 
move  forward  .  .  .  but  a  railroad  car  can 
only  put  on  its  brakes.) 
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Kitchen  is  defined  in  a  separate  small 
hierarchy  and  is  the  child  of  base  class 
ChemLab.  (Think  about  it .  .  .)  Kitchen’s 
methods  include  WashDishes,  Prepare- 
NextMeal,  and  so  on. 

Adding  kitchen  capabilities  to  vehi¬ 
cles  is  done  by  adding  objects  of  class 
Kitchen  to  the  definitions  of  Cater- 


ingTruck  and  DiningCar  as  ordinary 
fields,  in  the  same  way  that  you  would 
add  an  integer  or  a  string  field.  The  fact 
that  Kitchen  is  an  object  class  is  inci¬ 
dental.  The  notation  for  invoking  the 
WashDishes  method  would  be  ADin- 
ingCar. Kitchen.  WashDishes  or  ACater- 
ingTruck.Kitchen.Washdishes.  Now,  is 


this  such  a  bad  thing?  The  vehicles  still 
roll.  The  kitchens  still  cook.  But  .  .  . 
polymorphism  only  operates  along  the 
line  of  inheritance. 

What  this  means  is  that,  whereas  you 
could  invoke  a  method  like  StopMotion 
on  any  child  class  of  Vehicle ,  you  could 
not  invoke  the  PrepareNextMeal method 
belonging  to  Kitchen  upon  an  object 
accessed  polymorphically  through  a 
pointer  to  class  Vehicle ,  even  though 
both  CateringTruck  and  DiningCar  de¬ 
scend  from  Vehicle.  The  problem  is 
that  no  common  ancestor  of  Cater- 
ingTntck  and  DiningCar  contains  the 
Kitchen  object  —  certainly  not  Vehicle. 

We  could,  of  course,  add  the  Kitchen 
field  to  the  definition  of  type  Vehicle. 
That,  however,  defeats  the  whole  pur¬ 
pose  of  object-oriented  design:  To  dis¬ 
tribute  functionality  across  an  object  hi¬ 
erarchy  as  appropriate.  All  vehicles  do 
not  contain  kitcheas,  so  forcing  a  kitchen 
field  into  the  Vehicle  class,  while  syn¬ 
tactically  correct,  is  semantically  absurd. 

The  Just  One  Thing  Dilemma 

What  we’re  seeing  here  is  a  problem 
I’m  calling  the  “Just  One  Thing  di¬ 
lemma.”  If  object-oriented  design  is  a 
process  of  modelling  some  portion  of 
reality  in  logical  abstractions,  then  single¬ 
inheritance  systems  impose  an  artificial 
limitation  on  the  modelling  process: 
The  assumption  that  all  objects  are  fun¬ 
damentally  Just  One  Thing  —  that  one 
aspect  of  a  modelled  object  is  neces¬ 
sarily  deeper  than  all  others,  and  that 
that  aspect  is  the  only  one  through 
which  the  polymorphism  mechanism 
operates. 

Still  not  convinced  that  this  is  a  prob¬ 
lem?  Let’s  return  to  the  Metaphor  Zone 
for  a  moment.  Suppose  we’re  mod¬ 
elling  a  major  sports  event  in  a  stadium 
in  Baltimore.  Some  people  are  coming 
down  from  New  York  by  train,  and 
will  arrive  just  before  the  game  begins. 
Others  are  driving  in,  and  will  be  mill¬ 
ing  around  in  the  parking  lots  before 
game  time.  Everybody  needs  to  be  fed 
in  time  to  be  finished  before  the  game 
begins.  So  at  5:00  sharp,  we  issue  a 
command  to  all  vehicles  capable  of 
providing  food:  PrepareNextMeal.  Each 
type  of  vehicle  responds  in  its  own 
appropriate  fashion,  according  to  the 
principles  of  polymorphism.  The  por¬ 
ters  in  the  Metroliner  begin  preparing 
quiche  in  the  dining  car,  and  the  own¬ 
ers  of  the  fleet  of  catering  trucks  cruis¬ 
ing  the  stadium  parking  lots  begin  put¬ 
ting  hot  dogs  on  to  grill.  One  way  or 
another,  everybody  waiting  to  get  in 
to  see  the  big  game  gets  fed  —  and  all 
at  the  direction  of  a  single  command 
common  to  all  food  providers. 

With  single  inheritance,  there  is  no 


There  is  no  way  to  polymorphically  invoke  a  method 
defined  in  Kitchen  from  a  common  ancestor  to  both 
CateringTruck  and  DiningCar. 


Figure  1:  The  need  for  multiple  inheritance 


Figure  2:  The  multiple  inheritance  solution 
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(continued  from  page  140) 
way  to  issue  that  single  PrepareNextMeal 
command  to  both  the  catering  trucks 
and  the  dining  cars.  We  have  decided 
that  catering  trucks  and  dining  cars  are 
fundamentally  vehicles,  and  the  only 
aspects  the  two  have  in  common  are 
those  inherited  from  their  common  an¬ 
cestor,  Vehicle.  The  fact  that  both  con¬ 
tain  a  field  named  Kitchen  is  inciden¬ 
tal.  They  did  not  inherit  their  kitchen- 
ness  —  it  was  just  sort  of  glued  on  after 

In  most 

implementations, 
whereas  colliding 
identifiers  are  made 
invisible,  they  still  exist 
within  an  object 


the  fact.  And  polymorphism  operates 
only  through  inheritance. 

If  object-oriented  design  is  to  be  a 
modeling  process,  then  we  have  to  face 
up  to  the  fact  that  real-world  objects 
are  often  mongrels  with  conceptual  par¬ 
entages  going  off  in  every  direction  at 
once.  The  more  complex  the  system, 
the  less  likely  that  any  given  element 
in  the  system  will  be  Just  One  Thing. 

The  Multiple  Inheritance  Solution 

The  solution  is  to  let  dining  cars  and 
catering  trucks  inherit  their  vehicle- 
ness  from  class  Vehicle ,  and  their  kitchen- 
ness  from  class  Kitchen.  Figure  2  shows 
the  classes  of  Figure  1  redrawn  to  indi¬ 
cate  this  new  set  of  relationships.  Din- 
ingCar  and  CateringTruck  are  now 
equally  descended  from  Vehicle  and 
from  Kitchen.  Each  has  everything  that 
a  Kitchen  object  has,  and  each  has 
everything  that  a  Vehicle  object  has. 

Polymorphic  method  calls  are  no 
longer  a  problem.  CateringTruck  can 
be  addressed  as  easily  as  a  Vehicle 
object  as  it  can  be  addressed  as  a  Kitchen 
object.  To  direct  all  food  service  vehi¬ 
cles  to  stop  their  motion,  you  gather 
the  food  service  vehicles  into  a  linked 
list  of  Vehicle  objects  and  simply  call 
Vehicle.  Stop  for  each  vehicle  on  the 
list. 

On  the  other  hand,  to  direct  all  food 
service  vehicles  to  prepare  the  next 
meal,  you  gather  the  same  food  service 
vehicles  into  a  linked  list  of  Kitchen 
objects  instead  —  and  then  call  the  Pre-  I 


pareNextMeal  method  for  every  object 
on  the  list. 

When  Fields  Collide 

One  major  semantic  problem  with  mul¬ 
tiple  inheritance  occurs  when  a  class 
inherits  the  same  identifier  from  more 
than  one  parent.  For  example,  a  Vehi¬ 
cle  object  might  have  a  data  field  called 
Door —  and  so  might  Kitchen ,  since  the 
two  concepts  we’re  modelling,  vehicles 
and  kitchens,  both  have  doors.  So  if  you 
want  to  call  the  method  MyCater- 
ingTruck.OpenDoor,  which  method  is 
called:  The  OpenDoor  method  inher¬ 
ited  from  Kitchen,  or  the  OpenDoor 
method  inherited  from  Vehicle ?  Or,  for 
that  matter,  which  Door  field  is  acted 
upon? 

Different  languages  treat  this  prob¬ 
lem  in  slightly  different  ways,  but  in 
general,  when  two  inherited  identifiers 
collide,  both  are  rendered  invisible 
within  the  scope  of  the  class  that  inher¬ 
its  them.  In  other  words,  when  it  inher¬ 
its  two  different  Door  fields,  Cater¬ 
ingTruck  objects  lose  the  ability  to  ma¬ 
nipulate  either. 

Then  again,  if  the  Kitchen  stove 
catches  fire,  you’re  going  to  want  to 
manipulate  the  door  in  one  helluva 
hurry.  CateringTruck  objects  may  le¬ 
gitimately  have  doors.  The  question 
you  the  designer  must  answer  is,  which 
door  field  will  be  used  within  Cater¬ 
ingTruck  Your  implementation  of  the 
CateringTruck  object  might  be  such 
that  the  doors  are  nothing  more  than 
the  same  doors  defined  in  the  Vehicle 
object.  You  must  then  explicitly  spec¬ 
ify  that  the  Door  field  that  will  be  vis¬ 
ible  within  CateringTruck  will  be  the 
Door  field  inherited  from  Vehicle. 

This  can  be  done  in  many  ways,  and 
I’ll  explain  how  it’s  done  in  TopSpeed 
Pascal  once  I  actually  receive  a  copy 
of  the  product.  (At  this  writing  I  have 
only  seen  the  documentation.)  The  im¬ 
portant  thing  to  understand  is  that  you 
the  designer  make  the  choice,  at  com¬ 
pile  time,  which  of  two  colliding  iden¬ 
tifiers  will  remain  visible. 

Weaving  a  Tangled  Wet 

A  lot  of  researchers  are  uncomfortable 
with  multiple  inheritance  because  it  can 
easily  become  a  creator  of  far  more 
complexity  than  it  manages  as  a  struc¬ 
tured  tool.  The  simple  metaphor  of  the 
CateringTruck  and  DiningCar  classes 
works  tolerably  well  because  there  is 
no  more  connection  between  two  oth¬ 
erwise  independent  object  hierarchies 
than  there  must  be  to  do  the  job.  It 
doesn’t  take  a  lot  of  imagination  to  see 
what  might  happen  when  7  or  8  or  20 
complicated  object  hierarchies  begin 
mixing  it  up  in  a  big  way. 
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In  most  implementations,  whereas 
colliding  identifiers  are  made  invisible, 
they  still  exist  within  an  object,  taking 
up  memory  even  if  they  are  not  acces¬ 
sible.  In  other  words,  if  a  class  inherits 
six  colliding  identifiers  called  Doorand 
only  uses  one  of  them,  you  still  have 
five  invisible  (and  useless)  Door  fields 
inside  every  instance  of  that  class.  (I 
think  there  is  a  mechanism  built  into 
C++  2.0  to  ensure  that  only  one  of  a  set 
of  colliding  members  is  physically  pre¬ 
sent  within  an  object  instance,  but  it  is 
a  measure  of  the  difficulty  of  C++  that 
I  can’t  really  tell  as  yet.) 

I  suspect  that  over  time  a  new  kind 
of  coupling  will  be  recognized  in  OOP 
design:  The  degree  to  which  two  or 
more  object  hierarchies  are  intercon¬ 
nected  via  multiple  inheritance.  I  fur¬ 
ther  suspect  that  less  will  be  more  here, 
both  to  keep  object  instances  small 
and  efficient,  and  also  (at  a  higher  level) 
to  keep  the  whole  conceptual  nature 
of  the  object  hierarchy  from  turning 
into  something  the  color  of  Arizona 
mud.  And  while  a  given  concept  being 
modeled  as  an  object  may  be  more 
than  Just  One  Thing,  it  is  just  as  cer¬ 
tainly  not  Ten  or  Twelve  Things,  either. 

Remember:  Moderation  in  all  things 
.  .  .  er .  .  .  objects. 

Out  of  Sight,  Out  of  Mind 

Of  course,  it’s  easy  to  talk  about  cater¬ 
ing  trucks  and  dining  cars  and  things 
that  bear  no  relationship  to  the  situ¬ 
ations  we  encounter  as  DOS  program¬ 
mers,  right?  Well,  let’s  bring  the  multi¬ 
ple  inheritance  question  a  little  closer 
to  home,  by  asking,  “What  is  a  menu, 
really?” 

An  Ivory  Soap  majority  (99.44/100%) 
would  say  that  a  menu  is  a  screen 
mechanism  through  which  you  choose 
one  item  from  a  displayed  list  of  sev¬ 
eral.  The  underlying  assumption  is  that 
the  screen  mechanism  is  the  essential 
aspect  of  the  menu.  Data?  What’s  data? 
Oh  .  .  .  that  stuff.  .  .  . 

I  guess  it’s  human  nature  to  assume 
that  what  is  visible  is  most  important. 
But  consider:  There  would  still  be  data 
without  menus,  but  a  menu  without 
data  would  be  useless  and  futile.  Let’s 
move  data  back  to  the  true  center  of 
things  and  define  a  menu  as  an  array 
whose  index  is  directly  controlled  by 
the  user  through  the  keyboard  and 
screen.  You  could  also  call  it  a  list 
whose  current  pointer  is  directly  con¬ 
trolled  by  the  user,  depending  on  the 
implementation.  (Let’s  take  a  step  back 
from  the  nature  of  the  implementation 
and  call  any  class  that  consists  of  more 
than  one  data  item  a  collection .) 

This  isn’t  sophistry,  but  an  issue  that 
strikes  to  the  heart  of  object-oriented 


design.  Writing  a  menu  object  and  pass¬ 
ing  it  an  array  or  list  as  a  parameter  is 
the  Old  Way.  In  keeping  with  the  ob¬ 
ject  metaphor  of  active  data,  each  col¬ 
lection  class  should  contain  its  own 
menuing  method.  In  other  words,  when 
we  want  to  choose  one  item  out  of  a 
collection  named  MyCollection,  we 
should  be  able  to  make  a  call  some¬ 
thing  like  this: 

Chosenltem  :=  MyCollection. Choose; 

To  get  you  comfortable  with  this  no¬ 
tion  at  the  source-code  level,  I’ve  writ¬ 
ten  a  very  simple  demonstration  unit 
for  Listing  One  (ARROBJ.PAS),  page 


149,  that  implements  a  string  array  class 
in  Turbo  Pascal  5.5.  Class  StringArray 
follows  the  strict  interpretation  of  object- 
orientation:  That  a  class’  internal  fields 
are  private  and  may  be  accessed  only 
through  function  calls.  This  imposes  a 
certain  performance  hit,  but  in  return  it 
allows  the  physical  implementation  of 
internal  data  to  be  anything  at  all.  For 
example,  you  could  actually  store  the 
elements  of  StringArray/ s  “array”  as  re¬ 
cords  in  a  random-access  file,  with  the 
index  of  the  array  acting  as  the  random 
file  pointer.  Obviously  this  makes  ac¬ 
cess  time  dependent  on  the  disk  speed, 
but  would  allow  you  32,767  elements 
of  any  reasonable  size  —  something  you 
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simply  can’t  do  when  limited  by  Turbo 
Pascal’s  single  64K  data  segment. 

(Note  that  other  changes  would  be 
required  to  support  an  array  larger  than 
15  items  or  so,  because  in  this  simple 
implementation  there  is  no  scrolling 
logic,  and  the  entire  array  must  be  small 
enough  to  be  displayed  on  the  screen 
at  once.) 

Listing  Two  (page  150)  is  a  simple 
demonstration  program  that  creates  an 
instance  of  StringArray ,  fills  it  with 

I  guess  it’s 
human  nature 
to  assume  that 
what  is  visible 
is  most  important 


strings  of  random  characters,  and  then 
invokes  the  Choose  method  to  display 
the  built-in  menu  and  allows  the  user 
to  choose  one  of  the  15  elements  in 
My  Array.  There  is  also  a  Display  method 
that  simply  puts  the  contents  of  the 
array  up  in  a  window  for  inspection, 
without  any  opportunity  to  select  and 
return  an  individual  element. 

The  important  thing  to  understand 
about  the  StringArray  class  is  that  it  is 
first  and  foremost  an  array,  to  be  used 
where  an  array  should  be  used.  The 
menuing  mechanism  is  a  convenience, 
and  can  simply  be  ignored  if  you  don’t 
happen  to  need  a  menu. 

Not  My  Yob,  Mon 

In  my  view  of  an  object-oriented  world, 
all  collection  classes  should  contain  both 
browsing  and  menuing  methods.  In 
very  simple  classes  such  as  StringAr¬ 
ray,  this  doesn’t  involve  a  lot  of  compli¬ 
cated  code.  On  the  other  hand,  in  an 
application  written  around  an  elabo¬ 
rate  text  windowing  scheme,  having 
collection  classes  implement  their  own 
menuing  and  browsing  code  is  waste¬ 
ful  and  redundant. 

So  who  should  make  the  menu?  In 
an  ambitious  application  with  an  object- 
oriented  user  interface,  making  menus 
is  not  the  job  of  a  collection  class. 
Worse,  when  important  polymorphic 
method  calls  must  be  made  to  all  active 
windows  (like  ReDraui)  a  menu  must 
be  descended  from  the  abstract  win¬ 
dow  class,  which  defines  the  ReDraw 
method.  On  the  other  hand,  gluing  a 
collection  class  onto  a  menu  object  as 
an  ordinary  field  forbids  polymorphic 


access  to  the  menuing  method  from  a 
collection  class  ancestor. 

This  is  where  multiple  inheritance 
earns  its  keep:  By  allowing  object  hier¬ 
archies  to  specialize  without  forcing 
object  classes  into  unnatural  unions  — 
like  making  collection  classes  descen¬ 
dants  of  screen  window  classes.  In  a 
multiple-inheritance  environment,  the 
collection  classes  inherit  fundamental 
menuing  methods  from  the  user-inter- 
face  hierarchy  without  losing  their  true 
heritage  as  collections. 

We'll  See 

Needless  to  say,  this  is  all  background 
information.  In  a  future  column  I’ll  give 
you  some  real  code  in  TopSpeed  Pas¬ 
cal  to  show  you  how  multiple  inheri¬ 
tance  works.  As  I’ve  tried  to  show  here, 
the  concept  seems  to  solve  a  couple 
of  really  knotty  reservations  I’ve  had 
about  objects  all  along.  This  isn’t  to  say 
it  won’t  uncover  half  a  dozen  more. 
(Life  is  like  that.)  I’ll  let  you  know  as 
soon  as  I  know  myself. 

Odd  Lots 

Traffic  from  earlier  columns  has  been 
piling  up  during  our  mad  dash  to  the 
desert.  Let’s  read  the  mail.  .  .  . 

First  of  all,  I  need  to  back  away  from 
an  assertion  I  made  last  year  about 
Smalltalk/V  PM.  The  way  it  was  ex¬ 
plained  to  me,  Smalltalk  is  almost  by 
definition  an  interpreted  system,  and 
while  the  interpreter  can  be  hidden 
inside  a  “sealed  off”  application,  it’s 
still  gotta  be  in  there  somewhere.  The 
explanation  is  complicated,  but  suffice 
it  to  say  that  Jim  Anderson  and  his  crew 
of  wizards  have  shown  me  to  my  own 
satisfaction  that  they  have  in  fact  made 
a  compiling  Smalltalk  that  loses  noth¬ 
ing  functional  —  and  gains  them  an 
immense  performance  edge  over  inter¬ 
preted  implementations.  Sooner  or  later, 
when  I  find  a  version  of  OS/2  PM  that 
will  make  friends  with  my  machine,  I’ll 
probe  further. 

And  while  I’m  backing  away  from 
that  one,  I’ll  keep  going  and  admit  that 
my  gripes  about  Modula-2’s  limited  set 
size  are  way  behind  the  reality  of  to¬ 
day’s  commercial  compilers,  as  numer¬ 
ous  readers  have  pointed  out.  In  fact, 
with  the  TopSpeed  and  Stony  Brook 
compilers,  not  only  can  you  have  SET 
OF  CHAR,  but  you  can  have  a  set  of 
CARDINAL  —  with  up  to  65,536  ele¬ 
ments.  If  anything,  Wirth  erred  here 
by  giving  compiler  implementors  too 
much  leeway  to  decide  the  size  of  sets. 
Had  he  said  flat-out  up  front  that  sets 
must  support  256  or  65,536  elements, 
we’d  have  a  less  ambiguous  standard 
and  I’d  have  less  opportunity  to  be 
wrong. 
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Several  people  have  pointed  out  in 
letters  that  TopSpeed  Modula-2  adds 
two  operators  to  the  language  for  bit- 
shifting.  The  »  operator  shifts  to  the 
right  and  «  shifts  to  the  left.  Missed 
that  somehow,  but  it’s  an  extension 
well  worth  having. 

Steve  McMahon  wrote  to  warn  against 
using  global  variables  in  Modula-2  mod¬ 
ules  (as  I  did  in  BITWISE. MOD,  pre¬ 
sented  in  March  1990)  whenever  possi¬ 
ble.  Modula-2  is  a  multitasking  language, 
and  global  variables  make  modules  point¬ 
edly  non-reentrant,  since  the  interrup- 
tor  can  futz  a  global  that  the  interruptee 
isn’t  through  with  yet.  Hoo-boy;  hadn’t 
thought  of  that  one.  Fortunately,  my 
understanding  of  reentrancy  indicates 
that  making  both  variables  local  to  the 
procedures  in  which  they  are  used  will 
solve  the  problem,  because  each  entry 
of  a  procedure  creates  its  own  stack 
frame,  where  local  variables  live  their 
short  lives. 

I’ve  very  recently  received  a  damned 
fine  Modula-2  communications  library 
from  a  very  small  company  in  Ohio. 
Solid  Software's  Solid  Link  supports  in¬ 
terrupt-driven  communications  via 
COM1  through  COM4,  with  buffered 
input  and  output.  It  also  has  the  dis¬ 
tinction  of  being  the  only  toolbox  on 
my  shelf  for  any  language  that  sup¬ 
ports  the  notoriously  difficult-to-imple- 
ment  ZModem  file  transfer  protocol.  (It 
also  supports  XModem,  YModem, 
YModem-G,  TeLink  and  SEALink,  plus 
some  variations  on  the  above.)  The 
library  is  implemented  entirely  in  as¬ 
sembler,  and  claims  to  be  able  to  com¬ 
municate  at  19,200  baud  or  faster.  (I 
haven’t  done  any  speed  tests  as  of  yet.) 

The  manual  is  fairly  terse,  but  it  has 
the  virtue  of  containing  numerous  code 
examples  including  a  complete  and  thor¬ 
oughly  nontrivial  terminal  program.  Cer¬ 
tainly  if  you  need  to  implement  any  file 
transfer  protocols  in  Modula,  you  can 
save  yourself  a  titanic  amount  of  work 
by  letting  someone  else  do  the  hard 
stuff.  Highly  recommended. 


Products  Mentioned 

TopSpeed  Pascal 

Jensen  &  Partners  International 

1101  San  Antonio  Rd.,  Ste.  301 

Mountain  View,  CA  94043 

415-967-3200 

Price:  Contact  Vendor 

Solid  Link 
Solid  Software  Inc. 

P.O.  Box  8132 
West  Chester,  OH  45069 
513-777-1414 
Price:  $199 


Plenty  of  Here  Here 

I  believe  it  was  Gertrude  Stein  who 
said  of  Oakland,  “There’s  no  there 
there.”  Not  so  —  the  real  problem  with 
California  is  that  there’s  not  enough 
There  to  go  around.  She  should  have 
tried  Arizona.  There’s  so  much  here 
here  that  that  won’t  be  a  problem  for 
some  time  to  come.  The  sky  seems  so 
enormous  as  to  swallow  you  whole, 
out  on  the  high  desert  north  of  Cave 
Creek,  where  I  expect  to  live  someday. 
People  warn  me  of  those  days  when  it 
gets  down  to  108  degrees  after  mid¬ 
night.  I  guess.  But  then  again,  you  don’t 
have  to  shovel  heat  out  of  your  drive¬ 
way.  In  the  meantime,  Mr.  Byte  has 


learned  that  you  can  in  fact  lift  your  leg 
on  a  saguaro  cactus  ...  if  you’re  careful. 

Maybe  twelve  years  of  wandering 
are  enough. 

Maybe  I’ve  come  home. 

Contact  Jeff  Duntemann  on  MCI  Mail 
as  JDuntemann,  or  on  CompuServe 
through  ID  761 1 7, 1426. 

DDJ 

(Listings  begin  on  page  149.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  14. 
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C  PROGRAMMING 


Listing  One  ( Text  begins  on  page  131.) 

/* - hotkey. h - */ 

char  *showkey (unsigned  keyscan,  unsigned  keymsk) ; 
int  iskeyhit (char  keyscan,  char  keymsk) ; 
void  hotkey (unsigned  *keyscan,  unsigned  *keymsk) ; 
void  initkey (void) ; 
void  endkey (void) ; 


End  Listing  One 


Listing  Two 

/* - testhk.c - */ 


/* 

*  A  program  to  demonstrate  the  use  of  the  hotkey  programmer 
*/ 

♦include  <stdio.h> 

♦include  "hotkey. h" 


void  main () 

( 

unsigned  scan  =  0; 
unsigned  mask  =  0; 


printf ("\nPress 
printf ("\nPress 
printf ("\nPress 
printf ("\nPress 


a  hot  key"); 

Esc  to  keep  the  one  you  have"); 

the  Space  Bar  to  clear  the  one  you  have"); 

Enter  to  use  the  new  one\n"); 


/* - program  the  hot  key - */ 

hotkey (&scan,  &mask) ; 


if  (scan  !  mask)  ( 

/* - display  the  programmed  hot  key - */ 

printf ("\nThe  new  hot  key  is  %s  (%02x,  %02x)\n", 
showkey (scan,  mask),  scan,  mask); 


initkey () ; 

while  (! iskeyhit (scan,  mask)) 

printf ("\rWaiting  for  you  to  press  the  hot  key.."); 
endkey ( ) ; 

printf ("\n%s  was  pressed",  showkey (scan,  mask)); 

) 

else 

printf ("\nNo  hot  key  programmed"); 


End  Listing  Two 


Listing  Three 

/* - hotkey. c - */ 

♦include  <stdio.h> 

♦include  <conio.h> 

♦include  <bios.h> 

♦include  <dos.h> 

♦include  <string.h> 

♦include  "hotkey. h" 

♦define  KYBRD  9 

/* 

*  Program  a  hot  key 
*/ 

static  char  hotky[50]; 

static  int  multibits (int  k) ; 
static  void  clearkb (void) ; 
static  void  buzz (void); 

char  *scodes[]  =  { 


"Esc", 

"1",  "2", 
"M", 

"3", 

"4", 

"5", 

"6", 

"7", 

"8", 

"9", 

"0", 

"[=]", 

"Bksp", 

"Tab", 

" Q " ,  "W", 

"E", 

"R", 

"T", 

"Y", 

"U", 

"I", 

"0", 

"P",  " 

[",  "1". 

"Enter", 
"Ctrl", 
"A",  "S", 

"D", 

"F", 

"G\ 

"H", 

"J", 

"K", 

"L", 

"[;]"» 

"  [  \  "  ]  \ 

"LShift", 

"Z",  "X",  "C",  "V",  "B",  "N",  "M", 

"[,)% 

"RShift", 

"PrtSc", 

"Alt", 


"FI",  "F2",  "F3" ,  "F4",  "F5",  "F6",  "F7",  "F8",  "F9",  "F10", 

"Home", 

"Up", 

"PgUp", 

"[5]", 

"(+]", 

"End", 

"Dn", 

"PgDn", 

"Ins", 

"Del" 

); 

static  void  (interrupt  *oldkb) (void) ; 
static  void  interrupt  newkb(void); 
static  int  kbval  =  0; 

/* - keyboard  ISR - */ 

static  void  interrupt  newkb(void) 

{ 

kbval  =  inportb (0x60) ; 

(*oldkb) (); 

) 

/* - initialize  for  hot  key  test - */ 

void  initkey (void) 

{ 

/* - attach  to  keyboard  interrupt - */ 

oldkb  =  get vect (KYBRD) ; 
setvect (KYBRD,  newkb) ; 

) 

void  endkey (void) 

{ 

setvect (KYBRD,  oldkb); 

) 

/* - test  for  a  specified  keystroke - */ 

int  iskeyhit (char  keyscan,  char  keymsk) 

I 

char  far  *bp  =  MK_FP(0,  0x417); 
int  rtn; 

/* - if  no  key  is  depressed,  bail  out - */ 

if  ((kbval  &  0x80)  !=  0) 
rtn  =  0; 

else  if  (keyscan  &&  kbval  !=  keyscan) 
rtn  =  0; 

else 

rtn  =  (keymsk  ==  ( ( *  bp )  &  Oxf)); 
return  rtn; 

) 

/* - program  the  user  hot  key - */ 

void  hotkey (unsigned  *keyscan,  unsigned  *keymsk) 

( 

int  keyl,  key2  =  0,  key3,  k  =  0; 
char  svbios; 

char  far  *bp  =  MK_FP(0,  0x417); 

/* - attach  to  keyboard  interrupt - */ 

initkey () ; 

/* - first,  we  need  to  be  off  the  keyboard - */ 

kbval  =  0x80; 

while  ( (kbval  &  0x80)  ==  0) 


/* - clear  the  BIOS  readahead  buffer - */ 

clearkb  ()  ; 
svbios  =  *bp; 
while  (1)  { 

keyl  =  0x80; 
key3  =  0; 

/* - wait  for  a  key  press - */ 

while  (keyl  &  0x80) 
keyl  =  kbval; 

/* - if  Spacebar,  Enter  or  Esc,  drop  out - */ 

if  (keyl  ==57  ! !  keyl  ==  1  ! !  keyl  ==  28) 
break; 

/* - must  be  /y.t(  Ctrl,  or  Shift - */ 

if  (keyl  !=  56  &&  keyl  !=  29  && 

keyl  !=  42  &&  keyl  !=  54)  { 

buzz  () ; 
continue; 

} 

/* - wait  for  a  second  key  press - */ 

while  ( (key2  =  kbval)  ==  keyl) 

if  (key 2  &  0x80) 

break; 

key2  &=  0x7f; 
k  =  0; 

if  (keyl  ==  key2) 

/* - released  the  first  key - */ 

continue; 

/*  -  wait  for  key  release  or  key  change  -  */ 

while  ( ( (key3  =  kbval)  &  0x80)  ==  0) 
if  (key3  !=  key2  &&  key3  !=  keyl) 
break; 

key3  &=  0x7 f; 

if  (key 3  ==  key2  ! :  key3  ==  keyl) 
key3  =  0; 

/* - clear  the  bios  readahead  buffer - */ 

clearkb () ; 

*bp  =  svbios; 
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/* - l00k 

switch'  (keyl) 
case  56: 
case  29 
case  42 
case  54 
default: 

) 

switch  (key2)  { 


at  the  keystrokes 


=  8;  break; 
=  4;  break; 
=  2;  break; 
=  1;  break; 


case  56 

k  1=  8; 

key2 

= 

0; 

break; 

case  29 

k  !=  4; 

key2 

= 

0; 

break; 

case  42 

k  :=  2; 

key2 

= 

0; 

break; 

case  54 

k  !=  1; 

key2 

= 

0; 

break; 

default 

break; 

ch  (key3)  ( 

case  56 

k  :=  8; 

key3 

= 

0; 

break; 

case  29 

k  !=  4; 

key3 

= 

0; 

break; 

case  42 

k  :=  2; 

key3 

= 

0; 

break; 

case  54 

k  !=  1; 

key3 

= 

0; 

break; 

default 

break; 

if  (key2  !=  1  &&  key2  !=  28)  { 

if  (key2  ==70  ! 1  key3  ==  70)  { 

/* - can't  use  the  Break  key - */ 

buzz  () ; 

) 

else  { 

if  (key 2  ==  0) 
key2  =  key3; 

/*  -  shift  Function  keys  allowed  -  */ 

if  ( (k<4  &&  key2)  &&  (key2  <  59  \ \  key2  >  68)) 
buzz () ; 

else  if  (!(k  &&  (key2  !!  multibits (k) )) ) 
buzz () ; 

else 

printf ("\r%s  " 

showkey (key2 ,  k) ) ; 

} 


/* - wait  for  the  key  release 

while  ( (kbval  &  0x80)  ==  0) 


} 

if  (keyl  ==  57  &&  k  ==  0) 
*keymsk  =  *keyscan  =  0; 
if  (keyl  ==  28  &&  k  !=  0) 
*keymsk  =  k; 

*keyscan  =  key2; 

} 

clearkbO  ; 

*bp  =  svbios; 

endkey ( ) ; 
kbval  =  0; 


/*  -  test  a  nybl  for  multiple  bits 

static  int  multibits (int  k) 

{ 

int  ct  =  0,  i; 

for  (i  =  1;  i  <  16;  i  *=  2) 
if  (k  &  i) 
ct++; 

return  (ct  >1); 


show  the  hot  key 


*/ 


char  *showkey (unsigned  keyscan,  unsigned  keymsk) 


( 


*hotky  =  '\0'; 
if  (keymsk  &  8) 

strcat (hotky,  "Alt-"); 
if  (keymsk  &  4) 

strcat (hotky,  "Ctrl-"); 
if  (keymsk  &  2) 

strcat (hotky,  "LShift-"); 
if  (keymsk  &  1) 

strcat (hotky,  "RShift-"); 
if  (keyscan) 

strcat (hotky,  scodes [keyscan-1] ) ; 

else 

* (hotky  +  strlen (hotky)  -  1)  =  '\0' 
return  hotky; 


/*  -  clear  the  BIOS  keyboard  read-ahead  buffer  -  */ 

static  void  clearkb(void) 

{ 

int  far  *nextoff  =  MK_FP (0x40, Oxla) ; 
int  far  *nexton  =  MK_FP (0x40, Oxlc) ; 

*nextoff  =  *nexton; 

} 


static  void  buzz (void) 

{ 

sound (100) ; 
delay (250) ; 
nosound ( ) ; 

} 


End  Listings 
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STRUCTURED  PROCRAMMINC 


Listing  One  (Text  begins  on  page  139.) 

UNIT  ArrObj; 

{  A  simple  string  array  object  } 

{  with  display  and  menu  methods  } 

{  to  demonstrate  one  need  for  } 

{  multiple  inheritance.  Needs  } 

{  Turbo  Pascal  5.5.  ) 

{  By  Jeff  Duntemann  } 

{  Presented  in  DDJ  for  July  1990  } 


INTERFACE 

USES  Crt, BoxStuff ; 
CONST 

LowBounds  =  0; 
HighBounds  =  14; 


TYPE 

String40  =  STRING [40] ; 

StringArray  =  OBJECT 

Data  :  ARRAY [LowBounds. .HighBounds]  OF  String40; 
Index  :  Integer; 

CONSTRUCTOR  Init; 

PROCEDURE  Set Index (Newlndex  :  Integer); 

FUNCTION  Getlndex  :  Integer; 

PROCEDURE  SetCurrent (NewString  :  String40); 
FUNCTION  GetCurrent  :  String40; 

PROCEDURE  Display (X,Y  :  Integer); 

FUNCTION  Choose (X,Y  :  Integer)  :  String40; 

END; 


IMPLEMENTATION 

VAR 

I  :  Integer; 

MyArray  :  StringArray; 


PROCEDURE  ShowReverse (X, Y  :  Integer;  Target  :  String40); 
VAR 

Save  :  Word; 

BEGIN 

Save  TextAttr; 

TextColor (Black) ; 

TextBackground(LightGray) ; 

GotoXY (X, Y) ;  Write (Target ) ; 

TextAttr  :=  Save; 

END; 


PROCEDURE  ShowNormal (X, Y  :  Integer;  Target  :  String40) ; 
VAR 

Save  :  Word; 

BEGIN 

Save  :=  TextAttr; 

TextColor (LightGray) ; 

TextBackground (Black) ; 

GotoXY (X,Y);  Write (Target) ; 

TextAttr  :=  Save; 

END; 


PROCEDURE  Uhuh; 

VAR  I  :  Integer; 
BEGIN 

FOR  I  :=  1  TO  2  DO 
BEGIN 

Sound (50) ; 
Delay  (100) ; 
NoSound; 

Delay  (50) ; 

END; 

END; 


1 - } 

(  Method  definitions  follow:  ) 

1 - 1 

CONSTRUCTOR  StringArray. Init; 

VAR 

I  :  Integer; 

BEGIN 

(  Clears  the  strings  in  the  array  to  null:  ) 
FOR  I  :=  LowBounds  TO  HighBounds  DO 
BEGIN 

Set Index (I) ; 

SetCurrent  ('');. 

END; 

END; 


PROCEDURE  StringArray. Set Index (Newlndex  :  Integer); 

BEGI1)  (Listing  continued  on  page  150.) 
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STRUCTURED  PROGRA M MING 


Listing  One  (Listing  continued,  text  begins  on  page  139  ) 

Index  :=  Newlndex; 

END; 


FUNCTION  StringArray .Getlndex  :  Integer; 
BEGIN 

Getlndex  :=  Index; 

END; 


PROCEDURE  StringArray.SetCurrent (NewString  :  String40); 
BEGIN 

Data [Index]  :=  NewString; 

END; 


FUNCTION  StringArray.GetCurrent  :  String40; 
BEGIN 

GetCurrent  :=  Data [Index]; 

END; 


PROCEDURE  StringArray .Display (X, Y  :  Integer); 
VAR 

I  :  Integer; 

BEGIN 

MakeBox (X, Y, 42 , HighBounds+3, GrafChars) 

FOR  I  :=  LowBounds  TO  HighBounds  DO 
BEGIN 

GotoXY (X+l , Y+l+I) ;  Write (Data [ I ] ) ; 

END; 

END; 


{  This  is  a  VERY  simple  bounce-bar  menuing  method  for  } 
{  the  string  array  object.  No  scrolling  is  done;  if  you  } 
(  define  more  elements  that  will  fit  on  the  screen,  you  } 
(  must  allow  for  the  user's  scrolling  the  list  up  and  } 
(  down  within  the  window  defined  by  the  line  character  } 
{  box .  } 

FUNCTION  StringArray. Choose (X, Y  :  Integer)  :  String40; 

VAR 

I  :  Integer; 

Done,EscPressed  :  Boolean; 

Ch  :  Char; 


{  Show  a  box  ) 

(  and  display  the  strings  } 
{  inside  it.  } 


BEGIN 

Display (X, Y) ; 

{  Highlight  the  element  at  Index:  } 

ShowReverse (X+l,  Y+l+Index, Data [ Index] ) ; 

I  :=  Index;  Done  :=  False;  EscPressed  :=  False; 

{  Get  user  input  until  Enter  or  Esc  is  pressed:  } 

REPEAT 

REPEAT  (Null)  UNTIL  KeyPressed; 

Ch  :=  ReadKey; 

CASE  Ch  OF 

#0  :  BEGIN  (  0  means  an  extended  key  code  follows:  } 

Ch  :=  ReadKey; 

CASE  Ch  OF 

#72  :  BEGIN  (  Up  arrow  } 

ShowNormal (X+l, Y+l+I, Data [I] ) ; 

IF  I  =  LowBounds  THEN  UhUh  (  Up  Arrow  } 
ELSE  Dec ( I ) ; 

ShowReverse (X+l, Y+l+I, Data[I] ) ; 

END; 

#80  :  BEGIN  (  Down  arrow  } 

ShowNormal (X+l, Y+l+I, DatafI] ) ; 

IF  I  =  HighBounds  THEN  UhUh  (  Down  Arrow  } 
ELSE  Inc (I) ; 

ShowReverse (X+l, Y+l+I, Data[I] ) ; 

END; 

END;  {  CASE  } 

END; 

#13  :  Done  :=  True;  {  Enter  pressed;  we're  done  } 

#27  :  BEGIN 

EscPressed  :=  True;  {  Don't  change  anything  } 

Done  :=  True; 

END; 

END;  {  CASE  } 

UNTIL  Done; 

IF  EscPressed  THEN  (  Put  things  back  as  they  were:  } 

BEGIN 

ShowNormal (X+l, Y+l+I, Data [I] ) ; 

ShowReverse (X+l, Y+l+Index, Data [Index] ) ; 

END 

ELSE 

BEGIN 

Index  :=  I;  [I  becomes  the  new  index  } 

Choose  :=  Data [Index];  {  and  we  return  the  string  at  Index  ) 
END 

END; 

END. 


Listing  Two 

PROGRAM  MenuArray; 

(  Demonstrates  a  string  array  object  ) 
(  with  its  own  built-in  menuing  method  } 
(  By  Jeff  Duntemann  > 

f  From  DDJ  for  July  1990  } 


End  Listing  One 


USES  Crt, ArrObj; 

VAR 

I  :  Integer; 

MyArray  :  StringArray; 
MyString  :  STRING; 


FUNCTION  PullRandomString (DoLength  :  Integer)  :  STRING; 

VAR 

I  :  Integer; 

TempString  :  STRING; 

FUNCTION  Pull (Low, High  :  Integer)  :  Integer; 

VAR 

I  :  Integer; 

BEGIN 

REPEAT  (  Keep  requesting  random  integers  until  } 

I  :=  Random (High  +1);  (  one  falls  between  Low  and  High  } 

UNTIL  I  >=  Low; 

Pull  :=  I 
END; 

BEGIN 

FOR  I  :=  1  TO  DoLength  DO 

TempString [I]  :=  Chr (Pull (32,  125) ) ; 

TempString [0]  :=  Chr (DoLength) ; 

PullRandomString  :=  TempString; 

END; 


BEGIN 

ClrScr; 

MyArray . Init;  {  Set  up  the  object  ) 

FOR  I  :=  0  TO  14  DO  (  Fill  the  array  with  random  strings  } 

BEGIN 

MyArray. Setlndex (I) ; 

MyArray. SetCurrent (PullRandomString (40) ) ; 

END; 

MyArray .Setlndex (7) ;  {  Point  the  index  to  element  7  } 

MyString  :=  MyArray .Choose (5,2) ;  (  Invoke  menu  method  } 

GotoXY (6, 22) ;  Writeln (MyString) ;  (  Display  the  chosen  string  } 

Readln; 

END. 

End  Listings 
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Version  2.1  of  the  Zortech  C++  Devel¬ 
opment  System  for  MS-DOS  and  OS/2 
should  be  available  this  month  from 
Zortech.  Version  2.1  includes  improve¬ 
ments  in  compilation  speed,  optimiza¬ 
tion,  and  generated  code  quality. 

Zortech  claims  that  with  this  version 
they  have  overcome  the  DOS  memory 
limitations  by  combining  their  Virtual 
Code  Management  (VCM)  technology 
with  the  DOS  extender  technology  of 
Rational  Systems.  VCM  allows  MS-DOS 
applications  to  contain  up  to  4  Mbytes 
of  code  and  still  run  in  real  mode.  The 
VCM  system  requires  changes  only  to 
assembly  language  code. 

Applications  with  large  and  complex 
class  hierarchies  can  now  be  compiled 
on  PCs  with  80286/386  or  486  proces¬ 
sors.  You  can  also  use  the  compiler  to 
develop  applications  using  the  Rational 
Systems  DOS  extender.  They’ve  used 
the  same  technology  in  the  debugger  — 
it  relocates  itself  into  extended  mem¬ 
ory,  allowing  large  programs  to  be  de¬ 
bugged.  A  virtual  8086  debugger  for 
386-based  systems  is  provided,  and  re¬ 
quires  little  conventional  memory. 

Zortech  is  also  developing  versions 
of  the  C++  Developers  Edition  for  Xenix 
and  Unix  386.  The  32-bit  compiler  will 
be  compatible  with  the  Phar  Lap  386/ 
DOS  Extender. 

Contact  Zortech  for  pricing  informa¬ 
tion  on  C++  2.1.  Reader  service  no.  34. 
Zortech  Inc. 

4C  Gill  St. 

Woburn,  MA  01801 

617-646-6703 

800-848-8408 

Graphics  programmers  who  manage 
megabyte-hungry  images  can  turn  to 
the  ECOMP  software  module  from  EFI 
(Electronics  for  Imaging)  for  help. 
With  ECOMP,  details  and  colors  in  dif¬ 
ferent  image  areas  undergo  different 
levels  of  compression  by  using  algo¬ 
rithms  that  analyze  spatial  frequencies; 
the  compression  algorithm  selectively 
preserves  coefficients  and  approximates 
or  drops  others.  Images  are  then  re¬ 
constructed  from  these  coefficients,  but 


changes  from  the  originals  are  those 
the  eye  is  least  likely  to  detect.  The 
level  of  filtering  is  controlled  by  user- 
specified  quality  factors. 

In  high-quality  electronic  publishing, 
typical  images  can  undergo  a  compres¬ 
sion  ratio  of  20:1  without  noticeable 
difference  in  image  quality.  The  soft¬ 
ware  is  supplied  in  C  source  code  and 
is  operational  on  Mac  IIs  with  Syman¬ 
tec’s  Think  C,  on  IBM  PC/ATs  and  com¬ 
patibles  with  Borland’s  Turbo  C,  and 
on  Sun  Microsystems  Sun/4  with  the 
Sun  C  compiler.  Compression  speed 
averages  5  to  20  Kbytes  of  image  data 
per  second,  depending  on  computer 
architecture.  The  package  includes  pro¬ 
grams  in  TIFF  file  format,  which  are 
portable  to  other  file  formats  such  as 
TARGA  and  PICT2.  EFI  provides  the 
product  as  C  source  code,  so  you  can 
integrate  it  with  other  programs  and 
as  part  of  a  developed  system.  Contact 
EFI  for  licensing  information.  Reader 
service  no.  20. 

EFI 

950  Elm  Ave. 

San  Bruno,  CA  94066 
415-742-3400 

New  from  Borland  comes  Turbo  C++, 
a  full  implementation  of  AT&T’s  C++ 
2.0.  Turbo  C++  includes  a  standalone 
compiler  and  a  compiler  within  Borland’s 
new  user  interface,  Programmer’s  Plat¬ 
form.  Turbo  C++  includes  mouse  sup¬ 
port,  multiple  overlapping  windows,  a 
multifile  editor,  an  intelligent  project 
manager,  an  integrated  debugger,  and 
transfer  capability  for  accessing  other 
programs. 

Also  included  is  VROOMM,  the  vir¬ 
tual  run-time  object-oriented  memory 
manager  that  lets  you  overlay  your  code 
without  complexity;  acommand-line  com¬ 
piler,  linker,  and  tools;  online  hypertext 
help  with  copy  and  paste  examples; 
and  libraries  such  as  heap-checking 
functions  and  a  set  of  complex  and 
BCD  math  functions.  All  this  comes  in 
the  Turbo  C++  package  for  $199.  If  you 
order  Turbo  C++  Professional  you  also 
get  Turbo  Debugger  2.0,  Turbo  Assem¬ 
bler  2.0,  and  Turbo  Profiler  1.0  for  $299- 
Reader  service  no.  22. 

Borland  International 
1800  Green  Hills  Rd. 

P.O.  Box  660001 
Scotts  Valley,  CA  95066 
408-439-1619 

If  you  want  8514/A  compatibility,  you 
can  save  lots  of  money  by  purchasing 
the  RIXAI  video  driver  from  RIX  Soft- 
works.  The  RIXAI  video  driver  is  a  soft¬ 
ware-based  8514/A  emulator  that  is  com¬ 
patible  with  any  extended  VGA  board. 
This  product  accounts  not  only  for  the 


8514/A  video  board  and  compatible 
display,  but  also  for  the  8514/A  driver, 
the  HDILOAD  Adapter  Interface  (AI). 

Because  hardware  specs  were  un¬ 
available  from  IBM,  RIX  had  to  pro¬ 
gram  through  the  HDILOAD  driver  and 
create  an  AI  for  extended  VGA  boards 
that  would  appear  as  a  hardware  im¬ 
plementation  of  the  8514/A  Adapter 
Interface. 

RIXAI  will  benefit  application  devel¬ 
opers  and  board  manufacturers  by  re¬ 
ducing  the  software  development  ef¬ 
forts  required  for  extended  VGA  boards. 
If  the  user’s  display  is  8514/A-compat- 
ible,  all  software  that  supports  the  8514/ 
A  adapter  interface  will  get  immediate 
access  to  all  of  the  VGA  boards  sup¬ 
ported  by  RIXAI.  RIXAI  does  not  sup¬ 
port  scissors  or  plane-enable  functions 
due  to  the  high  memory  and  perfor¬ 
mance  overhead  associated  with  these 
functions.  In  16-color  mode,  the  emu¬ 
lator  does  not  support  color  mixing. 

The  RIXAI  video  driver  has  been  suc¬ 
cessfully  tested  with  all  the  major  “non- 
Windows”  applications  that  offer  8514/ 
A  support.  All  standard  8514/A  display 
resolutions  (640  x  480  and  1024  x  768 
with  256  colors,  and  1024  x  768  in  16 
colors)  are  provided  by  RIXAI.  The 
RIXAI  video  driver  is  available  free  to 
ClubRIX  extended  support  members 
(714-476-0728).  Otherwise  the  cost  is 
$100.  Doc  Livingston  told  DDJihaX  “this 
is  more  than  $1,000  less  than  the  cost 
of  an  8514/A  video  board.”  Reader  ser¬ 
vice  no.  40. 

RIX  Softworks 

18552  MacArthur  Blvd.,  Ste.  200 
Irvine,  CA  927715 
714-476-8266 

Other  Mac  news:  Pixar  has  announced 
MacRenderMan,  the  Mac  version  of  Pho- 
toRealistic  RenderMan.  Pixar  intends 
for  RenderMan  to  be  the  standard  for 
3-D  scene  description.  MacRenderMan 
accepts  data  in  the  RIB  (RenderMan 
interface  byte  stream)  file  format  from 
Mac-based  3-D  design  applications.  Ap¬ 
plications  spool  RIB  files  into  a  MacRen¬ 
derMan  folder  and  MultiFinder  pro¬ 
cesses  them  in  the  background,  similar 
to  the  printing  process.  Rendered  im¬ 
ages  are  then  output  to  a  color  display 
or  a  file.  MacRenderMan  can  output 
images  in  PICT,  EPS,  and  TIFF  file  for¬ 
mats;  these  images  can  then  be  used 
by  Mac-based  3-D  design  and  multime¬ 
dia  applications. 

DDJ  spoke  with  Sean  McKenna  of 
Paracomp,  which  produces  3-D  mod¬ 
eling  packages  for  presentations,  prod¬ 
uct  design,  and  graphic  arts.  About 
MacRenderMan,  he  said  “our  company 
is  real  excited.  This  is  a  completely 
(continued  on  page  1 58) 
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( continued  from  page  1 53) 
new  category  for  the  Mac  —  nothing 
like  this  was  available  before.  It  lets 
our  objects  and  models  look  more  real¬ 
istic  than  ever.  Whereas  before  we 
needed  a  large  machine  to  produce 
images  of  this  quality,  we  can  now  do 
them  on  the  desktop,  though  they  still 
take  a  long  time.” 

Mac  application  developers  can  either 
embed  MacRenderMan  in  their  soft¬ 
ware  or  offer  a  shrink-wrapped  version 
with  the  product.  MacRenderMan  in¬ 
cludes  a  RenderMonitor  for  managing 
jobs  in  a  background  queue,  an  appli¬ 
cation  for  viewing  images  on  a  color 
Mac  and  for  managing  the  display  and 
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conversion  of  TIFF  or  PICT  files,  picture¬ 
making  software  for  generating  ren¬ 
dered  3-D  images,  ShaderApp  for  com¬ 
piling  and  managing  shaders  written 
in  the  RenderMan  shading  language, 
and  a  sample  library  of  RIB  files,  shad¬ 
ers,  and  texture  maps.  You’ll  need  a 
Mac  SE  30.  II,  IIx,  or  Ilci  running  Sys¬ 
tem  6.0.3  or  later  with  MultiFinder  and 
32-bit  QuickDraw,  8-  or  24-bit  color 
display,  4  Mbytes  of  disk  storage,  and 
at  least  4  Mbytes  of  memory.  Reader 
service  no.  28. 

Pixar 

3240  Kerner  Blvd. 

San  Rafael,  CA  94901 
415-258-8100 


Grasp,  the  animation  language  and  paint 
program  for  IBM  PCs  and  compatibles, 
is  now  multimedia.  Paul  Mace  Soft¬ 
ware’s  new  version  offers  CD  sound 
control  and  special  animation  effects. 
Other  enhancements  include  direct  mem¬ 
ory  management,  file  handling  capa¬ 
bilities,  math  and  string  operators,  and 
differential  animation  techniques. 

Steve  Grumette,  of  Artificial  Intelli¬ 
gence  Research  Group,  is  a  big  Grasp 
fan.  He  does  computer  effects  for  the 
film  industry,  and  told  DZ)/ that  he  uses 
Grasp  to  generate  effects  for  the  televi¬ 
sion  show  Alien  Nation.  A  programmer 
who  is  also  a  graphics  artist,  Gatmette 
likes  the  “easy-to-code  animation  tech¬ 
niques  and  the  ability  to  do  real-time 
animation.  You  can  create  a  picture 
with  a  paint  program  and  manipulate 
it  with  the  Grasp  language.  One  of  the 
improvements  in  this  new  package  is 
the  addition  of  variables  in  the  pro¬ 
gram.”  These  give  Grasp  the  computa¬ 
tional  power  of  languages  such  as  C 
and  Pascal. 

Grasp  supports  the  following  sys¬ 
tems:  IBM  compatible  XT/AT/PS2  with 
hard  drive  (640K  RAM  suggested);  CGA, 
EGA,  VGA,  Hercules,  and  other  display 
cards  up  to  1024  x  768;  PC  Paintbrush, 
Gem  IMG,  CompuServe  GIF,  Basic 
BSAVE  image  formats,  Video  capture/ 
overlay  boards,  printers,  CD-ROM 
drives,  and  more.  It  retails  for  $199. 
Reader  service  no.  29. 

Paul  Mace  Software 
400  Williamson  Way 
Ashland,  OR  97520 
503-488-2322 

Version  5  of  the  TIFF  Development 
Library  for  PCs  is  now  available  from 
Image  Software.  This  new  version  in¬ 
cludes  full  support  for  reading  and  writ¬ 
ing  images  in  the  TIFF  Level  5  format 
and  also  reads  images  stored  in  Level 
4  format.  Level  5  support  includes  sev¬ 
eral  compression  schemes,  such  as  LZW, 
Packbits,  CCITT  Group  3,  bilevel,  and 
gray  scale,  and  supports  all  TIFF  classes. 
The  Library  is  compatible  with  Micro¬ 
soft  Windows  or  DOS  applications,  and 
was  developed  in  Microsoft  C. 

The  Development  Library  contains  a 
dump  utility  for  analyzing  TIFF  files 
and  for  debugging  applications  that  im¬ 
port  images  from  other  programs.  Ver¬ 
sion  5  comes  with  two  sample  programs 
for  demonstration.  It  sells  for  $95.  Reader 
service  no.  31- 
Image  Software 
P.O.  Box  1634 
Danville,  CA  94526 
415-838-4244 
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Caution!  Man  At  Work 

his  month’s  “Flames"  is  a  rare  watch  at  the  artist  at  work,  showing  how  I  write  this  column 
every  month. 

Mike  and  Nancy’s  machine  here.  Start  talking. 

Hi  Cuz,  this  is  Corbett.  Listen,  if  you’re  still  planning  to  flame  about  the  misuse  of  the  word 
“product,”  don’t  do  it.  I  looked  into  it  and  “product”  without  a  preceding  article  is  not  an  error.  In 
fact  it  makes  a  useful  distinction.  “A  product”  is  something  produced  for  sale,  but  “product”  without 
the  “a”  is  stuff  produced  for  sale.  With  “a  product,”  you  conceive  of  the  thing  before  you  write  the 
marketing  plan,  and  with  “product,”  it’s  the  other  way  around.  Take  a  look  at  David  Gerrold’s  piece 
in  the  New  York  Times  Book  Review,  I  think  it’s  the  April  29th  issue.  He  sort  of  says  that  a  science 
fiction  novel  is  “a  product,”  while  a  fantasy  novel  is  “product.”  Although  we’re  hearing  the  usage 
more  all  the  time  in  the  software  industry,  it  probably  just  represents  wishful  thinking  on  the  part 
of  sales  types  who  wish  they  were  peddling  something  as  ephemeral  as  Andre  Norton  novels. 
Later,  man. 

Beep. 

Mike  and  Nancy’s  machine  here.  Start  talking. 

Michael.  This  is  Stan.  I  heard  that  you  were  going  to  be  writing  about  assigning  credit  for  the 
discovery  of  the  Mandelbrot  set,  which  would  seem  to  be  the  same  species  of  question  as  who’s 
buried  in  Grant’s  Tomb  or  who  writes  “Swaine’s  Flames.”  But  if,  in  discussing  Mandelbrots  and 
fractals  and  chaos  theory,  you  get  around  to  assigning  credit  for  the  invention  of  chaos,  you  might 
consider  Mr.  Pournelle.  He’s  brought  more  than  his  share  of  chaos  into  our  industry,  in  a  Manor  of 
speaking,  and  I  understand  he’s  in  the  Soviet  Union  now,  so  you  can  defer  repercussions,  should 
he  be  unamused.  Jerry  Pournelle  in  the  Soviet  Union  is  itself  an  amusing  concept,  don’t  you  think? 
I  have  it  on  good  authority  that  he  gave  as  his  reason  for  going  that  he  wanted  to  go  there  before 
the  only  place  a  communist  could  be  found  was  on  an  American  university  campus.  Must  go;  I 
have  some  deviltry  to  advocate.  Take  care. 

Beep. 

Mike  and  Nancy's  machine  here.  Start  talking. 

Mike,  it’s  Oliver.  Dig  this:  Now  that  the  sordid  saga  of  est  and  the  founding  of  Computerland  is 
being  serialized  in  PC  Computing  and  a  biography  of  Philippe  Kahn  is  in  the  works,  it’s  time  to  do 
the  blockbuster  Silicon  Valley  movie.  It’s  a  great  subject,  better  than  Wall  Street,  better  than  Vietnam. 
I  see  it  as  a  pretentious  big-budget  epic  with  a  lot  of  box-office  stars  and  dialog  straight  out  of  the 
soaps,  and  I’ve  got  some  thoughts  about  plotlines  and  casting  that  I’m  hoping  you  can  run  by  your 
readers.  Like,  picture  Tom  Cruise  and  Rick  Moranis  as  two  kids  who  build  a  computer  in  a  garage, 
right?  They  become  insanely  rich,  but  it  goes  to  their  heads.  The  Moranis  character  tries  to  produce 
a  rock  concert,  but  he  has  a  nerd’s  taste  in  music.  The  Cruise  character  throws  tantrums  and  bullies 
everybody  but  has  incredible  charisma  and  personal  magnetism.  Eventually  he’s  kicked  out  of  the 
company  but  comes  back  by  inventing  a  sexy  black-box  computer,  which  will  be  played  by  a 
Cromemco  Z2D.  In  a  separate  plotline,  what’s  his  name,  you  know,  the  nerdy  kid  who  plays  Paul 
Pfeiffer  in  The  Wonder  Years,  is  a  software  magnate  who’s  always  in  these  heavy  meetings  with 
three-piece  suits  from  IBM.  But  at  the  same  time  he’s  battling  it  out  with  John  Candy,  who  plays  a 
rogue,  try-anything-once  software  developer  selling  compilers  on  street  corners.  He  plays  sax  at 
Moranis’  rock  concert,  so  there’s  a  tie-in  there.  Then  we’ve  got  Bill  Murray  drifting  in  and  out  of 
things  as  a  disk  jockey  who  gets  into  software  and  becomes  the  spreadsheet  king,  but  he  runs 
around  in  a  Hawaiian  shirt  all  the  time,  and  toward  the  end  of  the  film  he’s  giving  peptalks  on 
software  design.  Suck  in  those  guts,  guys,  we’re  Software  Designers.  You  get  the  idea.  He  represents 
the  creative  spirit.  Oops.  Got  another  call.  Let’s  do  lunch. 

Beep. 

Mike  and  Nancy’s  machine  here.  Start  talking. 

Michael.  This  is  Stan  again.  It  occurred  to  me  after  my  last  call  that  there  is  in  fact  some  question 
regarding  who  writes  “Swaine’s  Flames.”  You  should  know  that  someone  is  circulating  the  rumor 
that  you  compile  the  column  by  transcribing  answering  machine  messages.  I  suspect  your  cousin 
Corbett  of  starting  that  one.  A  more  disturbing  one  is  that  your  cousin  Corbett  has  himself  been 
writing  the  column  for  the  past  year,  and  that  it’s  entirely  fictional.  Since  I  have  made  one  or  two 
appearances  in  “Swaine’s  Flames,”  would  that  make  me  a  fictional  character?  That  would  be  a 
shallow  existence,  to  live  only  in  prose.  The  only  consolation  would  be  to  have  the  last  word. 

Beep. 
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Bill  shares  his  experiences  and  suggestions  for  porting  large  C  programs  to  80386  protected 
mode. 

ENCAPSULATING  C  MEMORY  ALLOCATION  24 

by  Jim  Schimandle 

Encapsulating  memory  routines  gives  you  control  over  memory  allocation.  Jim  presents  a 
memory  shell  that  does  this. 

AWK  AS  A  C  CODE  GENERATOR  36 

by  Wahhab  Baldwin 

When  you  need  to  perform  tasks  such  as  converting  data  from  one  format  to  another  —  and 
generate  C  code  in  the  process  —  AWK  may  be  the  tool  for  you. 
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Raymond  and  Denise  mix  and  match  C  and  Lisp  to  generate  a  spline  function  that  uses  the 
Macintosh  Toolbox  to  draw  a  smooth  curve. 

EXTENDING  printf()  60 

by  Jim  Mischel 

Here’s  an  easy-to-use  variation  on  printff )  that  utilizes  variable  arguments  so  you  can 
output  formatted  numbers. 

PARALLEL  EXTENSIONS  TO  C  70 

by  Graham  K.  Ellis 

Ken  discusses  concurrency  functions  for  parallel  C  compilers  and  describes  how  to  build 
transputer-based  parallel  systems. 

DEBUGGING  MEMORY  ALLOCATION  ERRORS  80 
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Larry  tackles  C  memory  allocation  using  functions  that  serve  as  a  bookkeeping  layer 
between  programs. 

HANDLING  OS/2  ERROR  CODES  1 34 

by  Nico  Mak 

Here’s  how  to  squeeze  more  information  out  of  OS/2’s  cryptic  error  messages. 
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OPTIMIZING  WITH  MICROSOFT  C  6.0 

by  Scott  Robert  Ladd 

Scott  examines  the  most  recent  version  of  Microsoft’s  C  compiler,  focusing  on  global 
optimization,  while  Bruce  Schatzman  provides  additional  comments  on  based  pointers. 

PROGRAMMER'S  WORKBENCH _ 

COLLECTIONS  IN  TURBO  C++ 

by  Bruce  Eckel 

Collections  are  classes  that  hold  a  number  of  object  types.  Bruce  uses  Borland’s  Turbo  C++ 
to  create  this  class  and  analyzes  the  C++  2.0  specification. 

COLUMNS 


PROGRAMMING  PARADIGMS  1 37 

by  Michael  Swaine 

What  do  Windows  3.0,  HyperCard  2.0,  and  Norman  Mailer  1.0  have  in  common?  Michael 
ponders  this  and  other  questions. 

C  PROGRAMMING  149 

by  Al  Stevens 

Al  mulls  over  C’s  past  and  future  before  exploring  the  NetWare  programming  environment. 

STRUCTURED  PROGRAMMING  1 6 1 

by  Jeff  Duntemann 

Jeff  creates  a  Turbo  Pascal  object  to  solve  a  recent  data-entry  problem. 


DEPARTMENTS . 

EDITORIAL . 6 

by  Jonathan  Erickson 

LETTERS . 8 

by  you 

SWAINE’S  FLAMES . 184 

by  Michael  Swaine 

PROGRAMMER'S 
SERVICES _ 

ADVERTISER  INDEX . 184 

where  to  go  for  more  information 
on  products 

OF  INTEREST  185 

compiled  by Janna  Custer 

PROGRAMMER’S 
MARKETPLACE . 186 

classified  ads 

SOURCE  CODE  AVAILABILITY 

As  a  service  to  our  readers,  all  source  code 
is  available  on  a  single  disk  and  online.  To 
order  the  disk,  send  $14.95  (Calif,  residents 
add  sales  tax)  to  Dr.  Dobb's Journal ,  501 
Galveston  Drive,  Redwood  City,  CA  94063, 
or  call  800-356-2002  (inside  Calif.)  or  800- 
533-4372  (outside  Calif.).  Specify  issue  num¬ 
ber  and  disk  format.  Code  is  also  available 
through  the  DDJ  listing  service  (415-364- 
8315)  and  through  the  DDJ  Forum  on 
CompuServe  (type  GO  DDJ). 


NEXT  ISSUE _ 

September’s  Structured  Language  issue 
puts  Pascal,  Modula-2,  Fortran,  and  other 
languages  to  work  solving  a  variety  of  pro¬ 
gramming  problems. 


Dr.  Dobb’s  Journal,  August  1990 

674 


3 


E  D  I  T  0  R  I 


Our  1991 
Editorial 
Calendar 


A  L 


The  future  is  now,  or  so  it  seems  as  we  begin  planning  next  year’s  editorial  line  up.  Thanks  in 
part  to  the  thousands  of  you  who  responded  to  our  call  for  1991  article  topic  suggestions, 
we’ve  settled  on  the  following  monthly  themes  for  the  upcoming  year. 


January 

Software  Design 

February 

Data  Compression 

March 

Assembly  Language  Programming 

April 

Biocomputing 

May 

Programming  for  Coprocessors 

June 

Structured  Languages 

July 

Graphics  Programming 

August 

C  Programming 

September 

Little  Languages,  Big  Engines 

October 

Object-Oriented  Programming 

November 

Operating  Systems 

December 

User  Interfaces 

Before  going  any  further,  I’ll  quickly  throw  in  my  standard  caveat.  These  aren’t  the  only  topics 
we’ll  be  discussing;  in  most  issues  of  DDJ,  we  try  to  devote  at  least  half  the  magazine  to  non-theme 
topics.  Among  those  “other”  subjects  we’ll  be  covering  are  embedded  systems  programming,  data 
structures,  32-bit  programming,  communications,  scientific  and  engineering  programming,  windowing 
systems,  software  engineering,  and  just  about  any  efficient  implementation  of  an  algorithm. 

Keep  in  mind  that  we  prefer  advance  notice  on  all  articles,  particularly  if  you  want  to  match  your 
article  with  a  specific  monthly  theme.  However,  we’ll  run  a  good  technical  article  on  any  aspect  of 
programming  in  any  month.  And  remember,  the  more  source  code  (in  any  language),  the  better. 

If  you  have  an  article  in  mind  but  want  some  guidance  on  how  to  prepare  the  proposal  and 
article,  give  us  a  call  or  drop  us  a  letter  and  we’ll  get  you  going. 


A  special  thanks  to  Terry  Vaughn  of  West  Covina,  California,  the  first  reader  to  make  a  donation 
to  the  Kent  Porter  Scholarship  Fund.  In  his  note,  Terry  says  “  ...  if  everyone  does  the  same,  it’ll 
add  up.”  We’ve  received  numerous  requests  for  applications  and  we’re  looking  forward  to  sharing 
Terry’s  goodwill  with  others. 


Those  of  you  who’ve  been  using  the  DDJ  listing  service  should  note  that  the  system  has  moved 
from  New  Hampshire,  to  California,  with  the  phone  number  changing  to  415-364-8315.  David  Betz 
will  continue  development  work  from  New  Hampshire  while  Keith  Lyon  will  be  the  programmer 
on  this  coast. 


And  at  least  one  software  company  took  to  heart  my  mention  a  few  months  back  of  Dr.  Dobbs, 
the  race  horse  we  adopted  as  our  official  mascot.  A  recent  letter  from  the  company  in  question  was 
addressed  to  “Mr.  Jon  Erickson,  Ed.”  but,  mailmerge  programs  being  what  they  are,  the  note  began 
“Dear  Mr.  Ed,”.  No,  it  didn't  hurt  my  feelings  (I’ve  been  called  a  lot  worse).  I  just  whinnied,  stamped 
my  foot  on  the  floor  three  times,  and  made  my  way  out  to  pasture 


Jonathan  Erickson 
editor-in-chief 
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Dining  Philosophers  Discussion 

Dear  DDJ, 

In  “Programming  Paradigms,”  DDJ  is¬ 
sue  #1 64,  entitled  “Complex  Systems, 
Fractals,  and  Chaos,”  Michael  Swaine 
briefly  discusses  a  problem  known  as 
the  “Dining  Philosophers”  problem.  This 
problem  was  first  stated  and  solved  by 
E.  W.  Dijkstra  in  “Cooperating  Sequen¬ 
tial  Processes”  (Technical  Report  EWD- 
123.  Eindhoven,  The  Netherlands:  Tech¬ 
nological  University,  1965).  Since 
Dijkstra’s  original  paper,  this  problem 
has  been  considered  a  classic  process 
synchronization  problem,  not  because 
it  has  practical  importance,  but  because 
it  is  an  example  for  a  large  class  of 
concurrency  control  problems. 

The  problem  may  be  stated  as  fol¬ 
lows,  derived  from  the  description  in 
Operating  Systems  Concepts  by  James 
L.  Peterson  and  Abraham  Silberschatz, 
(Reading,  Massachusetts:  Addison- 
Wesley,  1985).  Five  philosophers  spend 
their  entire  lives  thinking  and  eating. 
These  philosophers  share  a  circular  ta¬ 
ble  with  five  place  settings.  The  table 
is  set  with  five  plates  of  rice,  and  five 
chopsticks.  When  a  philosopher  thinks, 
he  does  not  interact  with  the  other  four 
philosophers.  On  occasion,  a  philoso¬ 
pher  gets  hungry  and  tries  to  pick  up 
the  chopsticks  to  his  left  and  right,  in 
either  order,  so  that  he  can  eat  a  plate 
of  rice.  A  philosopher  may  only  take 
one  chopstick  at  a  time,  and,  obvi¬ 
ously,  cannot  take  a  chopstick  that  is 
in  use  by  one  of  his  neighbors.  When 
a  hungry  philosopher  has  both  of  his 
chopsticks,  he  eats  without  releasing 
his  chopsticks  until  he  finishes.  When 
finished  eating,  a  philosopher  puts  both 
of  his  chopsticks  back  on  the  table  and 
starts  thinking  again. 

In  reference  to  this  problem,  Mr. 
Swaine  makes  the  following  statement 
on  page  123, 

8 
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The  Dining  Philosophers  problem,  dis¬ 
cussed  here  and  more  fully  in  David 
Harel’s  book,  Algorithmics  (Addison- 
Wesley,  1987),  is  a  classic  case  of  dead¬ 
lock  that  cannot  be  resolved  without 
introducing  an  element  of  randomness. 
Any  strictly  deterministic  solution  to  the 
Dining  Philosophers  problem  is  guaran¬ 
teed  to  fail. 

Apparently,  either  Mr.  Swaine  or  Mr. 
Harel  has  not  done  his  homework  thor¬ 
oughly  enough,  as  this  assertion  is  at 
odds  with  the  information  to  be  found 
in  the  relevant  literature.  Since  the  col¬ 
umn  is  not  specific  as  to  whether  Mr. 
Harel’s  book  makes  this  same  assertion 
or  not,  I  cannot  tell  whose  homework 
did  not  get  done. 

This  assertion  is  also  at  odds  with  the 
concepts  taught  at  the  university  level. 

I  received  a  Bachelor  of  Science  in 
Information  and  Computer  Science  from 
the  Georgia  Institute  of  Technology  in 
1987.  This  curriculum  included  a  senior- 
level  operating  systems  course,  in  which 
each  student  must  solve  the  dining  phi¬ 
losophers  problem  in  a  manner  that  is 
both  deterministic  and  provably  free 
of  both  deadlocks  and  starvation.  Fur¬ 
ther,  each  student  must  provide  a  proof 
of  correctness  with  the  solution.  My 
own  class  implemented  the  solution 
using  Logitech  Modula-2  and  an  in¬ 
structor-provided  module  allowing  pre¬ 
emptive  multitasking  of  multiple  in¬ 
stances  of  a  single  procedure.  The  Pe¬ 
terson  and  Silberschatz  book  was  the 
text  for  this  course  when  I  attended  it, 
and  was  the  genesis  of  our  program¬ 
ming  assignment. 

Peterson  and  Silberschatz  provide 
three  solutions  which  are  guaranteed 
to  be  free  of  deadlocks: 

1.  Allow  at  most  four  of  the  philoso¬ 
phers  to  be  seated  at  the  table  simulta¬ 
neously. 

2.  Force  each  philosopher  to  take  his 
chopsticks,  eat,  and  release  his  chop¬ 
sticks,  within  a  critical  section,  thus 
allowing  only  a  single  philosopher 
to  eat  at  any  instant. 

3.  Use  asymmetry:  Odd  numbered  phi¬ 
losophers  take  one  chopstick  first 
(e.g.,  the  one  on  the  right)  while 
even  numbered  ones  take  the  other 
(e.g.,  the  left). 

All  of  these  solutions  can  be  proven 
to  be  free  of  deadlocks.  The  correct¬ 
ness  proofs  for  these  three  solutions 
are  not  provided  in  the  text,  because, 
unfortunately,  none  of  them  meets  the 
additional  criterion  that  starvation  must 
be  avoided.  The  author  indicates  that 
a  deadlock-  and  starvation-free  solu¬ 
tion  is  possible  but  leaves  the  develop¬ 


ment,  implementation,  and  proof  of 
correctness  of  the  solution  as  an  exer¬ 
cise  for  the  reader. 

The  discussion  of  this  problem  in 
Operating  Systems:  Design  and  Im¬ 
plementation  by  Andrew  S.  Tanenbaum 
(Englewood  Cliffs,  New  Jersey:  Prentice- 
Hall,  1987)  casts  it  in  a  slightly  different 
light,  but  differing  from  the  characteri¬ 
zation  of  Peterson  and  Silberschatz  in 
details  only:  In  Tanenbaum  the  phi¬ 
losophers  are  trying  to  eat  very  slip¬ 
pery  spaghetti  which  requires  two  forks. 
Mr.  Tanenbaum  goes  into  more  depth 
with  his  discussion  of  the  possible  so¬ 
lutions.  The  following  quotation  is  from 
page  77  of  Tanenbaum’s  book  (the  fig¬ 
ures  mentioned  are  included  at  the  end 
of  this  letter,  following  the  references). 
[Editor’s  Note.  See  Examples  1  and  2.] 

Now  you  might  think,  “If  the  philoso¬ 
phers  would  just  wait  a  random  [amount 
of]  time  instead  of  the  same  [amount  of] 
time  after  failing  to  acquire  the  right- 
hand  fork  [chopstick],  the  chance  that 
everything  would  continue  in  lock  step 
for  even  an  hour  is  very  small.”  Of  course 
this  is  true,  but  in  some  applications  one 
would  prefer  a  solution  that  always  works 
and  cannot  fail  due  to  an  unlikely  series 
of  random  numbers.  (Think  about  safety 
control  in  a  nuclear  power  plant.) 

One  improvement  to  Fig.  2-19  [see  Ex¬ 
ample  1]  that  has  no  deadlock  and  no 
starvation  is  to  protect  the  five  state¬ 
ments  following  the  call  to  think  by  a 
binary  [mutual  exclusion]  semaphore.  .  . . 

From  a  theoretical  viewpoint,  this  solu¬ 
tion  is  adequate.  From  a  practical  one, 
it  has  a  performance  bug  [inefficiency]: 
Only  one  philosopher  can  be  eating  at 
any  instant.  With  five  forks  [chopsticks] 
available  we  should  be  able  to  allow 
two  philosophers  to  eat  at  the  same 
time. 

The  solution  presented  in  Fig.  2-20 
[see  Example  2]  is  correct  and  also  al¬ 
lows  the  maximum  parallelism  for  an 
arbitrary  number  of  philosophers. 

The  net  result  of  this  discussion  is 
that  Mr.  Swaine’s  assertion  is  false.  The 
problem  can  be  solved  in  a  determinis¬ 
tic  manner.  Additionally,  it  must  be 
solved  in  a  deterministic  manner  in 
order  for  the  solution  to  be  provably 
correct.  I  know  this  is  true  both  from 
the  literature  and  from  the  experience 
of  having  developed,  implemented,  and 
proven  correct  a  deterministic  solution 
devoid  of  deadlocks  and  starvation. 

I  find  it  quite  disturbing  that  Mr. 
Swaine  would  assert  that  a  sequencing 
problem  of  this  sort  can  be  solved  with 
randomness.  Nondeterminism  can  defi¬ 
nitely  solve  the  problem,  since  a  non- 
deterministic  solution  can  be  found  to 
(continued  on  page  12) 
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(continued  from  page  12) 
be  further  optimized: 

cmp  al,  1-0 
sbb  al,  69h 
das 

which  is  one  byte  shorter  and  four 
cycles  faster  on  an  8088  (although  with 
the  8088’s  prefetch  queue,  maybe  I 
should  say  “one  byte  faster,”  not  one 
byte  shorter  .  .  .  ).  Thanks  again  for  a 
great  magazine. 

Tim  Lopez 

San  Jose,  California 

OOP  ASM  Recommendations 

Dear  DDJ 

I  was  pleased  to  see  the  article  in  the 
March  1990  DDJ  about  OOP  assembly 
language.  I  was  surprised,  though,  to 
see  that  messaging  was  not  imple¬ 
mented  by  the  author.  I  used  the  same 
techniques  as  Mr.  Hyde  as  far  as  struc¬ 
tures  go,  but  in  addition  I  added  mes¬ 
saging  as  a  simple  jump  table.  Each 
object  handled  its  own  messages,  elimi¬ 
nating  the  need  for  the  caller  to  know 
the  procedure  name  of  the  desired 
method. 

Greg  Messer 
Houston,  Texas 

Setting  the  Mandelbrot  Straight 

Dear  DDJ 

I  enjoyed  Michael  Swaine’s  “Program¬ 
ming  Paradigms”  column  on  fractals 
in  the  May  1990  DDJ.  For  the  record, 
however,  I  would  like  to  mention  that 
by  no  means  is  Benoit  Mandelbrot  the 
“discoverer”  of  fractals.  Indeed,  Man¬ 
delbrot  deserves  credit  for  studying 
them,  popularizing  them,  and  coining 
the  term  “fractal.”  But  von  Koch  had 
discovered  the  snowflake  curve  by  1904, 
and  Hausdorff  defined  and  studied  frac¬ 
tional-dimensional  sets  in  1919. 

Also,  to  get  slightly  technical,  self¬ 
similarity  is  not  a  requirement  for  a  set 
to  be  fractal,  at  least  not  in  Mandel- 
brot’f  own  definition;  the  set  must  only 
have  fractional  Hausdorff  dimension. 

These  facts  are  all  extracted  from 
Mandelbrot’s  Fractal  Geometry  of  Na¬ 
ture  (Freeman,  1982),  albeit  with  diffi¬ 
culty. 

Daniel  Asimov 
Berkeley,  California 

Parental  Guidance 

Dear  DDJ, 

I  read  with  interest  Jeff  Duntemann's 
column  “Grinding  the  Speckled  Axe” 
(DDJ,  May  1990)  in  which  he  talks  about 
the  difficulty  of  drawing  the  line  be¬ 
tween  parent  and  child.  He  gave  two 
object  hierarchies  for  accepting  user 
input: 


1.  Parent  Field,  child  objects  StringField, 
IntegerField,  and  DateField, 

2.  Parent  StringField ,  child  objects  Integer - 
Field  and  DateField.  The  second  hier¬ 
archy  is  more  code  efficient,  but  pre¬ 
cludes  character-by-character  entry 
validation. 

What  interests  me  is  that  this  situ¬ 
ation  is  not  specific  to  OOP,  but  actu¬ 
ally  occurs  in  any  language  that  sup¬ 
ports  functions  or  procedures.  The  first 
hierarchy  is  roughly  equivalent  to  writ¬ 
ing  functions  GetStringField(  ),  Getln- 
tegerField(  ),  and  GetDateFieldl  ).  (Ad¬ 
mittedly,  the  common  code  would  have 
to  be  copied  manually  rather  than  neatly 
encapsulated  as  in  the  Field  object.) 
The  second  hierarchy  is  equivalent  to 
writing  a  function  GetStringField(  ),  and 
then  writing  functions  GetIntegerField(  ) 
and  GetDateField  that  call  GetString- 
Field( )  to  get  raw  data,  and  then  vali¬ 
date  it  appropriately.  The  first  solution 
duplicates  a  lot  of  code,  but  it  allows 
each  character  to  be  validated  as  the 
user  types.  The  second  solution  is  code¬ 
efficient,  but  the  user’s  errors  aren’t 
detected  until  <Enter>  is  pressed.  Which 
is  better?  I  don’t  know,  either.  There’s 
still  no  firm  answer  after  all  these  years 
of  procedural  languages,  and  I  suspect 
there  never  will  be. 

Steve  Corwin 
Shelton,  Connecticut 

TopSpeed  Replies 

Dear  DDJ, 

This  is  in  response  to  the  April  1990  “C 
Programming”  column  by  Al  Stevens. 

I  was  gratified  to  see  that  Mr.  Stevens 
likes  TopSpeed  C,  and  does  not  hesi¬ 
tate  to  recommend  it  to  others.  How¬ 
ever,  Mr.  Stevens  does  raise  several 
points  about  TopSpeed  C  to  which  I’d 
like  to  respond. 

TopSpeed  C  does  allow  an  applica¬ 
tion  to  call  INTERRUPT functions .  How¬ 
ever,  it  must  be  done  through  the  li¬ 
brary’s  _CHAIN_INTR  ( )  function. 

While  TopSpeed  C  does  not  provide 
the  _FLAGS  pseudovariable,  it  is  fairly 
easy  to  implement  such  a  function. 


Example  3 


Example  4 


TopSpeed  C  allows  the  programmer 
to  control  many  aspects  of  how  func¬ 
tions  are  called.  This  function  declara¬ 
tion  allows  the  CPU’s  flags  to  be  read, 
as  in  Example  3.  Similarly,  this  function 
declaration  allows  the  CPU’s  flags  to  be 
set,  as  in  Example  4.  In  these  two  exam¬ 
ples,  compiler  pragmas  are  used  to: 

1.  Save  the  state  of  the  pragmas; 

2.  Specify  that  functions  will  preserve 
a  specific  list  of  registers; 

3.  Specify  that  functions  are  to  be  ex¬ 
panded  in-line;  and 

4.  Restore  the  saved  state  of  the  prag¬ 
mas.  The  functions  themselves  are 
specified  as  a  sequence  of  machine 
code  values.  (I  have  given  these  two 
definitions  in  a  form  which  allows 
them  to  be  passed  directly  into  a 
header  file  for  inclusion  into  a  pro¬ 
gram.) 

As  you  can  see,  TopSpeed  C  pro¬ 
vides  the  programmer  with  a  consider¬ 
able  amount  of  power.  Since  no  C  com¬ 
piler  could  possibly  provide  intrinsic 
functions  for  everything  that  every  pro¬ 
grammer  would  want  to  do,  we  de¬ 
signed  TopSpeed  C  to  allow  the  pro¬ 
grammer  to  define  functions  which  are 
called  with  the  same  efficiency  as  those 
which  are  intrinsic  to  the  compiler. 

Mr.  Stevens’s  comments  on  the  docu¬ 
mentation  are  correct.  Fortunately,  we 
only  made  a  small  print  run  of  this  set 
of  manuals.  We  will  make  corrections 
to  the  manuals  for  inclusion  in  the  next 
print  run,  and  will  make  the  corrected 
manuals  available  to  customers  with 
an  older  set. 

Mr.  Stevens  has  provided  us  with 
useful  recommendations  on  how  to  im¬ 
prove  the  WATCH  utility.  While  a  fully 
configurable  utility  (as  Mr.  Stevens 
wishes  WATCH  was)  could  be  mar¬ 
keted  as  a  product  all  by  itself,  we  will 
continue  to  provide  WATCH  as  a  utility 
within  the  TopSpeed  products  and  are 
working  to  expand  its  capabilities. 

Don  Dumitru 
JPI 

Mountain  View,  California 


♦pragma  save 

♦pragma  call (reg_saved=> (bx, cx, dx, si, di, ds, es, stl, st2) ,  inline=>on) 
static  int  _f lags (void)  =  (0x9c  /*  pushf  */, 

0x58  /*  pop  ax  */); 

♦pragma  restore 

/*  usage:  i  =  _flags();  */ 


♦pragma  save 

♦pragma  call (reg_saved=> (ax,bx, cx,dx, si, di, ds,es, stl, st2) , 
inline=>on) 

static  void  _set_f lags (int  i)  =  (0x50  /*  push  ax  */, 

0x9d  /*  popf  */!; 

♦pragma  restore 

/*  usage:  _set_flags (i) ;  */ 
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Porting  C  Programs 

to  80386  Protected  Mode 

When  you  need  more  speed  and  greater  capacity 


William  F.  Dudley,  Jr. 


As  one  of  the  programmers  at  a  developer  of  CAD 
software  for  printed  circuit-board  design,  I  was 
assigned  the  job  of  porting  our  CAD  programs 
from  Microsoft  C  4.0  to  an  80386  protected-mode 
compiler.  After  making  a  quick  study  of  the  three 
available  compilers  that  support  the  80386  —  NDP  from 
Microway,  High-C  386  from  Meta  Ware,  and  Watcom  7.0/386 
from  Watcom  —  we  chose  the  Watcom  compiler.  This  article 
describes  the  problems  and  solutions  we  encountered  in  the 
process  of  porting  75,000  lines  of  C. 

We  had  two  programs  to  port,  the  autorouter  and  the 
graphical  editor.  The  autorouter,  called,  oddly  enough, 
ROUTER,  was  the  first  candidate  for  porting  for  two  reasons: 
It  was  written  by  a  very  small  team  so  it  was  a  lot  “cleaner,” 
and  because  it  was  not  interactive,  the  speed  of  its  graphics 
output  was,  for  the  time  being,  not  important.  The  second 
program  to  port  was  the  graphical  editor,  Draftsman-EE 
(called  DM).  In  this  case,  video  display  graphics  speed  is 
very  important,  so  we  expected  to  spend  more  development 
work  here. 

We  had  two  goals  when  we  began  the  port:  Achieving 
greater  speed  and  increased  capacity.  First  of  all,  we  figured 
that  accessing  data  in  one  large  (multi-megabyte)  array 
would  be  faster  than  all  the  rinky-dink  calculations  we  were 
doing  to  calculate  which  EMS  page  the  data  was  in,  and  then 
get  it  in  the  real-mode  version  of  our  product.  Secondly, 
we  felt  that  the  real-mode  product  was  limited  by  the  size 
of  an  unsigned  int.  The  protected  mode  (32  bit)  advantage 
is  obvious. 


Bill  is  director  of  engineering  for  Design  Computation  Inc., 
a  vendor  of  CAD  software  for  printed  circuit  design.  Bill  has 
a  masters  in  electrical  engineering  from  Cornell  University. 
When  not  programming  for  profit  or  fun,  he  can  be  found 
riding  his  Norton  Commando  (on  nice  days)  or  working 
on  that  or  one  of  his  other  bikes  (on  less  nice  days).  He  can 
be  reached  at  RD5,  Box  239,  Jackson,  N.  J.  0852 7. 
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In  an  attempt  to  quantify  the  speed  improvement,  we 
simulated  it  by  making  a  small  model  version  of  ROUTER 
that  had  no  paging  to  EMS  of  data  elements.  It  ran  about  25 
percent  faster  than  the  normal  real-mode  ROUTER,  so  that 
was  what  we  expected.  (See  the  “Summary”  at  the  end  of 
this  article  for  the  surprising  result.) 

Moving  to  an  ANSI  Compiler 

This  is  probably  old  news  to  everybody  now,  but  I  thought 
I’d  bring  up  the  ANSI  compiler  issue  and  attempt  to  explain 
it  again  for  those  of  you  who  are  out  of  touch.  The  big  deal 
in  moving  to  an  ANSI  compiler  is  that  the  function  headers 
change  from: 


Increased  Memory  Usage 

An  obvious  side  effect  of  moving  to  protected-mode  opera¬ 
tion  is  that  integers  are  now  32  bits  unless  declared  “short." 
The  non-obvious  result  is  that  structures  containing  inis 
grow,  memory  usage  increases,  and  any  code  that  hard¬ 
coded  the  size  of  the  struct  breaks  horribly.  I  know,  we 
shouldn’t  have  hardcoded  them,  but  we  did,  and  we  had  a 
reasonably  good  excuse. 

Now  I  have  a  hairy  preprocessor  macro  that  computes  the 
size  of  a  “data  element,”  which  is  really  the  biggest  of  any 
of  several  different  structs.  Some  judicious  juggling  of  the 
struct  contents  also  reduced  the  maximum  struct  size  to  save 
some  memory. 


integer_fn(i,  f,  c)  int  i;  float  f;  char  c;  I  ...  I 


to: 


int  integer_fn(int  i,  float  f,  char  c)  (  .  .  .  I 

This  would  be  harmless  enough  in  itself,  except  for  the 
following  gotcha:  Pre-ANSI  compilers  always  promoted floats 
to  doubles  in  function  argument  lists.  ANSI  compilers  pass 
floats  as  floats  if  you  so  declare.  And  here  is  what  caused 
me  a  few  interesting  hours:  The  ANSI  compiler  will  pass 
floats  to  the  function  when  it  is  called,  but  the  function  will 
expect  doubles  when  it  runs,  unless  you  use  the  new  style 
function  header.  The  moral  of  this  story  is  that  you  may 
continue  to  use  old  function  headers  in  your  code,  except 
for  functions  that  expect  doubles  or  floats  as  arguments,  in 
which  case  you  must  use  the  new  style  headers. 


The  Programming  Challenges 

Our  CAD  programs  required  some  special  services  that  are 
not  available  from  DOS.  The  first  one  was  the  ability  to  talk 
to  a  “security  device,"  more  popularly  known  as  a  “parallel 
port  dongle.”  This  really  presented  two  problems:  How  to 
link  a  real-mode  module  to  a  protected-mode  program,  and 
how  to  pass  the  character  string  data  from  the  protected- 
mode  application  to  the  real-mode  dongle  code. 

The  second  service  —  not  available  from  DOS  — -  is  de¬ 
vice  independent  video  graphics.  We  solved  this  problem 
in  our  real-mode  programs  by  supplying  a  family  of  video 
driver  TSR  (terminate  and  stay  resident)  programs.  Now  we 
needed  to  figure  out  how  to  talk  to  our  video  drivers  from 
protected  mode. 

Talking  to  Real-Mode  Assembly  Code  Modules 

The  manufacturer  of  our  dongle,  Rainbow  Technologies, 
supplies  an  assembly  language  module  that  talks  to  the 
dongle,  and  can  be  linked  to  a  Microsoft  C  program.  This 
enables  you  to  interrogate  the  dongle  from  C  without  get¬ 
ting  your  hands  dirty.  A  protected-mode  program,  however, 
needs  some  tricks  in  order  to  link  it  with  the  supplied 
real-mode  module. 

The  code  in  Listing  One  (page  104)  is  a  stripped-down 
version  of  the  assembly  code  dongle  module.  Notice  that  I 
chose  to  pass  the  arguments  directly  in  the  registers  instead 
of  on  the  stack.  This  is  because  I  have  to  use  Phar  Lap’s 
facility  for  calling  real-mode  code,  which  allows  me  to  use 
the  registers  easily. 

The  other  noteworthy  item  is  that  the  data  buffer  is  in  the 
real-mode  code  segment.  This  was  done  because  it  was 
simpler  than  figuring  out  how  to  have  a  real-mode  data 
segment  and  getting  it  to  link  in  the  proper  order. 

The  code  in  Listing  Two  (page  104)  is  the  C  module  that 
talks  to  the  assembly  module  of  Listing  One.  It  has  two 
functions:  Initializing  variables  to  point  to  the  various  parts 
of  the  real-mode  code  and  doing  the  actual  call  to  interro¬ 
gate  the  dongle. 

Three  locations  in  the  real-mode  code  are  directly  ac¬ 
cessed  from  protected  mode  as  shown  in  Example  1.  The 
linker  allows  us  to  know  the  address  of  anything  in  the 
real-mode  section,  so  that  gives  us  the  protected-mode 
version  of  those  addresses.  The  Phar  Lap  DOS  extender  has 
a  function  for  finding  out  the  equivalent  real-mode  address 
of  any  protected-mode  address,  so  the  subroutine  pr2real( ) 
returns  the  real-mode  address  at  the  start  of  the  real-mode 
code  as  a  (32  bit)  integer.  Subroutine  real_setup( )  uses  this 
result  to  initialize  real_addr,  real_seg,  and  real_off. 

The  actual  dongle  communication  occurs  in  the  subroutine 
COMPUTE ( ),  which  uses  Phar  Lap  function  0x25 10  to  call  the 
real-mode  routine  QUERY_FAR.  Before  the  call  is  made,  the 
blk_mv _pr( )  routine  copies  the  string  to  be  tested  to  the  buffer 
in  the  real-mode  code  segment.  Blk_mv J?r( )  and  its  sinister 
twin,  blk_mv_rp( )  are  shown  in  Listing  Three  (page  105). 
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PORTING 


Passing  Data  Between  Real-  and  Protected-Mode  Code  Sections 

The  second  challenge  is  that  of  passing  chunks  of  data 
between  real-  and  protected-mode  code  sections.  When 
you  request  a  DOS  service,  for  example  writing  to  the  disk, 
the  Phar  Lap  DOS  extender  handles  this  by  copying  the  disk 
data  from  your  buffer  in  protected  mode  to  another  buffer 
in  real  mode,  and  then  running  DOS.  This  happens  trans¬ 
parently  so  that  you  never  know  how  messy  it  is. 

An  obvious  side  effect  of  moving  to 
protected-mode  operation  is  that 
integers  are  now  32  bits  unless 
declared  “short” 


If  you  are  doing  something  abnormal,  however,  you 
quickly  find  out  how  messy  it  can  get.  Our  video  drivers 
need  to  exchange  data  with  the  application  in  two  cases: 
Telling  the  application  what  the  palette  of  the  video  board 
is  (so  the  user  can  change  color  assignments)  and  passing 
large  blocks  of  pixels  to  and  from  the  application  for  screen 
save/restore  operations. 

The  answer  to  this  is  to  use  the  Phar  Lap  facility  for 
reserving  a  block  of  “real-mode”  memory  (memory  guaran¬ 
teed  accessible  by  a  real-mode  program).  Listing  Four  (page 
105)  shows  the  graphics  video  module  in  the  application. 
Subroutine  setvmodeC )  initializes  the  video  driver  as  well 
as  establishing  the  location  (in  both  real-  and  protected- 
address  spaces)  of  the  9-Kbyte  buffer  we  use  for  communi¬ 
cation  with  the  driver.  Subroutine  rstr_vbuf( )  restores  the 
screen  image  from  a  previously  saved  file.  (Subroutine 
save_vbuf( )  is  not  shown  but  does  exactly  the  reverse.) 

Talking  to  a  Real-Mode  Graphics  Driver  from  Protected  Mode 

The  third  challenge  arose  when  we  wanted  to  communicate 
with  our  video  drivers.  The  actual  communication  of  draw¬ 
ing  requests  seemed  easy  enough,  because  our  driver  is 
accessible  through  its  own  (software)  interrupt.  Easy  it  was, 
but  deadly  slow. 

This  wasn’t  really  a  surprise,  since  our  real-mode  product 
had  long  ago  given  up  using  software  interrupts  for  commu¬ 
nication  with  the  video  driver.  In  the  real-mode  product,  the 
video  driver  returns  at  initialization  time  the  segment  and 
offset  of  its  main  entry  point.  The  application  makes  a 
pointer  to  a  function  out  of  this,  and  calls  the  driver  directly 
just  as  if  it  was  part  of  the  application  code. 

The  problem  was  much  worse  in  the  protected-mode 
product,  however.  This  was  due  to  the  overhead  of  switch¬ 
ing  the  machine  from  protected  to  real  mode  and  back  again 


extern  char  test_string; 

/*  string  buffer  in  real  mode  module  */ 
extern  char  end_real, 

/*  end  of  real  mode  code  */ 
extern  char  QUERY_FAR; 

/*  actually  a  function,  but  we  just  want 

address  */ 


Example  1:  Three  locations  in  the  real-mode  code  are 
directly  accessed  from  protected  mode. 
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(continued  from  page  18) 

for  every  vector  sent  to  the  video  driver.  The  solution  was 
obvious  —  another  programming  challenge!  We  would  stuff 
the  driver  commands  in  a  list,  and  when  the  list  filled  up, 
throw  it  over  the  wall  to  the  real-mode  code,  which  would 
then  call  the  video  driver  for  each  item  in  the  list.  This  would 
reduce  the  overhead  of  the  real  protected-mode  change  by 
a  factor  equal  to  the  length  of  the  list. 

In  Listing  Four,  notice  the  two  lines: 

prot.vidfn.addrll]  =  r.x.si; 

prot.vidfn.addr[0]  =  r.x.di; 

These  stuff  the  address  that  the  driver  returns  (the  address 
of  its  entry  point)  into  struct  prot  for  later  use  by  the 
real-mode  list  interpreter.  Listing  Five  (page  108),  the  in¬ 
clude  file,  defines  this  structure  (see  Example  2).  This  struc¬ 
ture  actually  occurs  twice:  Once  on  the  protected  side  and 
again  on  the  real-mode  side.  Whenever  the  protected-mode 
code  runs  the  draw  list  interpreter,  it  first  copies  the  pro¬ 


struct  ( 
union  { 
int  (*  p)  ()  ; 

short  int  addr[2]; 

/*  [0] segment  and  [1] offset  of  driver  entry  point  */ 
}  vidfn  ; 
short  int  lp; 
short  int  list [LLEN] [6] ; 

1  prot  ; 


Example  2:  Protected-mode  structure 


tected  struct  over  to  the  real-mode  version,  and  then  uses 
Phar  Lap  function  0x2510  to  call  the  real  mode  draw  list 
interpreter. 

Listing  Six  (page  108)  is  the  assembly  language  module 
for  the  protected-mode  subroutine  kdidrau>( ),  which  stuffs 
draw  commands  on  the  draw  list.  If  the  draw  list  fills  up,  it 
automatically  calls  the  protected-mode  subroutine  pdin- 
terp( )  to  empty  it. 

The  assembly  language  modules  were 
generated  by  coding  the  problem  in 
C  and  then  optimizing  the  assembler 
output  of  the  compiler 


Listing  Seven  (page  109)  shows  the  C  code  of  the  protected- 
mode  side  of  the  draw  list  interpreter.  Subroutine  pdint- 
init(  )  sets  up  the  registers  structs  and  subroutine  pdinterp(  ) 
calls  the  real-mode  interpreter.  (This  is  very  similar  to  Listing 
Four,  which  calls  the  real-mode  dongle  module.) 

Finally,  Listing  Eight  (page  109)  is  the  assembly  code  of 
the  real-mode  subroutine  that  “interprets”  the  draw  list.  It 
is  just  a  tight  loop  that  pushes  six  ints  from  the  list  onto  the 
stack  and  calls  the  subroutine  pointed  to  by  the  segment 
and  offset  at  the  beginning  of  the  RAM  locations  labelled 
_real.  It  does  this  repeatedly  until  the  first  integer  in  the 
group  of  6  is  0.  This  is  the  end-of-list  marker.  The  _real 
location  is  the  real-mode  copy  of  the  prot  struct. 

The  assembly  language  modules  were  generated  by  cod¬ 
ing  the  problem  in  C  and  then  optimizing  the  assembler 
output  of  the  compiler.  The  reason  was  simply  to  maximize 
the  speed  because  the  overhead  of  the  video  calls  was 
slowing  us  down. 

Before  I  embarked  upon  the  coding  of  the  protected- 
mode  version  of  the  draw  list  interpreter,  I  built  up  a  version 
in  Borland’s  Turbo  C.  This  enabled  me  to  test  the  perfor¬ 
mance  as  well  as  debug  bits  of  it  with  a  source  debugger 
before  committing  to  the  protected  version.  The  C  code 
from  the  Turbo  C  version  was  not  in  itself  useful  for  the 
protected-mode  version,  but  the  experience  of  building  and 
debugging  it  was  worth  the  time. 

Summary 

How  did  all  this  turn  out?  Boy,  the  speed  increase  really 
surprised  us.  The  protected  ROUTER  runs  twice  as  fast  as 
the  real-mode  product  (if  the  video  is  turned  off).  The 
protected  graphics  editor,  Draftsman-EE,  also  shows  a  factor 
of  two  improvement  for  compute  bound  processes.  Video 
speed  appears  the  same  as  in  the  real-mode  product,  which 
is  probably  due  to  the  vectors  being  generated  in  real-mode 
code.  The  next  job  is  to  make  a  protected-mode  video  driver 
to  fix  that  bottleneck.  As  for  increased  capacity,  no  customer 
has  yet  tried  a  job  that  is  greater  than  65,535  elements.  (The 
real-mode  product  will  do  a  300 IC  board,  which  is  pretty  big.) 

DDJ 

(Listings  begin  on  page  104.) 
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C  Memory  Allocation 

Detect  memory  allocation  errors  automatically 


.im  Schimandle 


Originally  the  program  was 
small,  less  than  20,000  lines, 
and  command-line  driven. 
But  after  two  years,  four  dif¬ 
ferent  programmers,  and  the 
addition  of  a  lot  of  functionality  —  a 
nifty  graphical  user  interface,  multiple 
printer  support,  foreign  language  menus, 
and  a  kitchen  sink  —  the  program  grew 
to  150,000  lines.  Then  it  started  crashing. 

The  timing  of  crashes  was  erratic. 
Sometimes  the  program  would  run  for 
weeks  without  crashing,  at  other  times 
it  would  crash  in  two  days.  After  a  few 
weeks  of  debugging,  I  finally  realized 
that  the  program  was  running  out  of 
dynamic  memory.  I  had  a  classic  case 
of  memory  leakage. 

What  is  Memory  Leakage? 

When  C  programmers  allocate  mem¬ 
ory  using  malloc( ),  they  must  be  sure 
to  free( )  the  memory  when  done  using 
it.  If  the  memory  is  not  freed,  it  “leaks” 
out  of  the  usable  memory  pool.  Such 
memory  cannot  be  reused. 

Consider  the  program  in  Listing  One, 
page  110.  This  program  allocates  a  list 
of  items  until  all  memory  is  used  up. 
Then  the  list  of  items  is  freed.  If  the 
program  is  designed  properly,  it  should 
never  exit  the  while  loop  in  main( ). 


Jim  owns  Primary  Syncretics,  which 
specializes  in  the  design  of  hardware 
and  software  for  embedded,  real-time 
systems.  His  10  years  of  experience  runs 
the  gamut  from  panel  switch  bootstraps 
to  SPARC  data  acquisition  systems.  Jim 
can  be  reached  at  408-988-3818. 


When  this  program  is  compiled  and 
run,  however,  it  eventually  runs  out  of 
memory  and  exits  the  ivhile  loop. 

The  problem  is  found  in  the  junk 
_close( )  function.  The  function  cor¬ 
rectly  frees  the  JUNK  structure,  but  fails 
to  free  the  string  pointed  to  by  junk 
_name.  (See  lines  68-83  and  86-89  of 
Listing  One.) 

This  Will  Never  Happen  to  Me 

I  hear  you  cry  foul.  “This  is  nothing 
more  than  an  example  of  poor  pro¬ 
gramming,”  you’re  saying.  “This  would 
never  happen  to  a  real  programmer.” 
Besides,  if  another  programmer  looked 
at  the  code,  it  would  be  obvious  where 


the  problem  lies. 

First,  if  you  look  at  the  revision  his¬ 
tory  in  lines  2-8  of  Listing  One,  the 
genesis  of  the  error  is  more  under¬ 
standable.  The  name  tag  was  added 
by  a  different  programmer  after  the  first 
release  of  the  module.  We  can  assume 
the  second  programmer  had  a  prob¬ 
lem,  added  a  quick  fix,  and  then  forgot 
to  look  into  the  other  effects  the  change 
might  have  on  the  program. 

Secondly,  this  is  a  pared-down  ver¬ 
sion  of  the  original  150,000-line  appli¬ 
cation.  Finding  this  error  in  such  a  large 
application  is  a  daunting  task.  You  could 
look  at  this  code  for  weeks  and  prob¬ 
ably  not  notice  the  lack  of  a  single 
free( )  in  one  function. 

Finally,  in  the  original  application, 
the  calls  to  the  open  and  close  functions 
were  data  dependent.  Thus  the  program¬ 
ming  error  showed  up  only  under  cer¬ 
tain  data  conditions. 

Examining  Assumptions 

Whenever  I  am  faced  with  a  failure  in 
a  system,  I  search  for  the  basic  assump¬ 
tions  that  lead  to  the  failure.  For  the 
standard  library  memory  allocation  calls, 
the  underlying  assumption  that  leads 
to  memory  leaks  is  that  the  caller  is 
responsible  for  error  checking. 

This  assumption  is  a  direct  result  of 
the  Unix  history  of  C.  The  entire  Unix 
philosophy  assumes  that  programmers 
must  handle  all  errors,  at  all  times,  with 
no  exceptions.  There  is  no  “big  brother” 
on  Unix.  You’re  on  your  own. 

Well,  a  peon  like  myself  needs  a 
slightly  more  bullet-proof  interface. 
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What  I  really  need  is  embedded  code 
that  can  inform  me  when  a  problem 
occurs.  Then,  when  I  make  a  mistake, 
the  mistake  will  be  automatically  caught 
during  development. 

By  encapsulating  the  memory  allo¬ 
cation  functions,  I  can  provide  a  layer 
of  protection  between  my  code  and 
the  system  library.  Such  a  memory  shell 
intercepts  the  system  library  calls  and 
performs  basic  bookkeeping  and  error 
checking. 

Designing  with  a  Purpose 

Initially,  I  was  interested  only  in  detect¬ 
ing  a  memory  leak.  However,  the  ac¬ 
tual  memory  shell  realized  multiple  de¬ 
sign  goals: 

•  Memory  leaks  are  detected. 

•  Manipulation  of  an  invalid  memory 
block  is  reported. 

•  The  location  within  the  client  code 
which  generates  an  error  is  reported. 

•  There  is  minimal  execution  overhead. 

•  The  shell  does  not  require  massive 
changes  to  existing  source  code. 

Junk  Revisited 

Before  we  look  at  the  internals  of  an 
actual  memory  shell,  let’s  look  at  how 
the  shell  can  be  used.  Listing  Two, 
page  110,  contains  a  modified  version 
of  the  junk  program  in  Listing  One, 
with  only  two  changes.  The  first  is  the 
inclusion  of  the  mshell.h  interface 
header  (lines  11-13  of  Listing  Two). 


The  second  is  the  calling  of  the 
Mem_Used( /function  in  main( /,  lines 
29-44  of  Listing  Two. 

When  the  program  executes,  it  pro¬ 
duces  the  output  shown  in  Example  1 . 
Because  the  program  reaches  the 
printf( )  within  the  if  statement  (line 
38,  Listing  Two),  the  value  returned 
by  Mem_Used( )  must  have  been  non¬ 
zero.  This  indicates  that  not  all  allo¬ 
cated  memory  was  freed.  Mem  _Dis- 
play( )  produces  the  other  information 
in  the  output.  For  each  block  not  freed, 
the  amount  of  memory  and  the  file/ 
line  number  where  the  allocation  was 
made  is  displayed. 

You  can  see  that  the  most  common 
error  was  the  failure  to  free  a  26-byte 
block.  Line  83  in  Listing  Two  shows 


*  *  * 

Memory  list  not  empty  *** 

Index  Size 

File (Line)  -  total 
size  6238 

0 

6004 

junkl. c(80) 

1 

26 

junkl . c (83) 

2 

26 

junkl .c (83) 

3 

26 

junkl . c (83) 

4 

26 

junkl .c (83) 

5 

26 

junkl .c  (83) 

6 

26 

junkl .c (83) 

7 

26 

junkl .c (83) 

8 

26 

junkl .c  (83) 

9 

26 

junkl .c (83) 

Example  1:  Output  from  junkl  shows 
that  there  are  really  tuto  sources  for  the 
memory  leaks.  The  first  comes  from  the 
malloc(  )  of  the  JUNK  structure  at  line 
80.  The  second  comes  from  the  strdup(  ) 
of  the  name  at  line  83- 


that  this  is  the  string  allocated  by 
strdup( /.  The  fix  is  equally  obvious. 
Simply  add  a  free( )  of  junk_name  to 
junk_close( ).  • 

However,  another,  error  is  also  re¬ 
vealed.  Somehow,  a  JUNK  structure  al¬ 
located  on  line  80  has  not  been  freed. 
This  error  is  harder  to  determine  and 
requires  a  reexamination  of  the  logic 
in  junk_open( ).  If  the  allocation  of  the 
JUNK  structure  on  line  80  succeeds  but 
the  allocation  of  the  string  on  line  83 
fails,  junk_open(  /fails  to  free  the  JUNK 
structure  before  returning  a  NULL. 

The  second  error  would  be  hard  to 
detect  by  inspection  and  is  also  depen¬ 
dent  on  the  amount  of  memory  allo¬ 
cated  by  other  modules.  This  type  of 
error  can  be  further  masked  if  the  allo¬ 
cation  statements  in  junk_open( )  are 
written  using  a  typical  C  coding  style 
that  attempts  to  run  as  many  assign¬ 
ment  statements  as  possible  into  a  sin¬ 
gle  if  conditional,  as  in  Example  2. 
(Why  any  rational  human  being  would 
want  to  do  this  is  beyond  me.)  This 
example  demonstrates  the  utility  of  a 
memory  shell  in  tracking  down  some 
pernicious  bugs. 

Redirecting  the  Standard  Library 

How  can  I  simply  add  an  include  file 
and  suddenly  have  error  checking  of 
the  memory  interface?  The  names  of 
the  memory  routines  have  not  been 
changed.  Yet  somehow,  I  am  able  to 
get  C  to  call  my  routines  and  not  the 
standard  library. 


Pointer  Alignment 


The  standard  library  routines  malloct /, 
realloc( /,  and  calloc( /  always  return 
a  pointer  of  suitable  alignment  for  an 
object  of  any  type.  Alignment  refers 
to  a  power  of  2  address  boundary 
that  a  processor  “naturally”  operates 
on.  This  natural  boundary  is  normally 
related  to  the  bus  width  or  specific 
processor  architecture  limitations. 

A  SPARC  processor  requires  that  a 
long  be  aligned  on  a  4-byte  bound¬ 
ary.  This  means  that  the  address  for 
a  long  must  have  zeros  in  the  least 
significant  2  bits.  If  an  attempt  is  made 
to  load  a  long  from  a  misaligned  ad¬ 
dress,  an  alignment  fault  is  detected 
and  the  program  crashes. 

An  Intel  80386,  however,  has  no 
requirements  on  alignment.  You  are 
allowed  to  load  any  data  type  from 
any  address.  However,  if  you  attempt 
to  load  a  long  from  an  address  with 
ones  in  the  least  significant  2  bits,  the 
processor  must  perform  two  memory 


loads  to  get  the  data.  This  overhead 
is  unacceptable  in  most  applications. 
So,  although  the  processor  does  not 
enforce  alignment,  you  would  be  a 


Processor 

Minimum 

Size 

Suggested 

Size 

8088 

1 

1 

80286 

1 

2 

80386 

1 

4 

80386SX 

1 

2 

68000 

2 

2 

68020 

1 

4 

SPARC 

8 

16 

VAX 

1 

16 

Table  1:  The  alignment  sizes  for  vari¬ 
ous  processors  depend  upon  system 
bus  width  and  architecture  limita¬ 
tions.  Failure  to  observe  the  minimum 
size  will  cause  a  processor fault.  The 
suggested  size  is  based  on  knowledge 
of  the  bus  width  and  cache  line  sizes. 
Larger  alignment  sizes  can  cause 
larger  alignment  gaps. 


fool  not  to  take  advantage  of  the  bus 
bandwidth. 

To  meet  the  alignment  requirement, 
the  size  of  a  memory  block  header 
must  be  rounded  up  to  the  nearest 
alignment  boundary.  The  bytes  in  the 
resulting  alignment  gap  cannot  be 
used  by  either  the  memory  shell  or 
the  client  code.  The  alignment  gap 
lies  between  the  memory  block  header 
and  the  client  data  region.  (Refer  to 
Figure  1.) 

The  memory  shell  uses  ALLGN_SIZE 
to  define  the  alignment  byte  bound¬ 
ary  required  for  the  largest  object  that 
must  be  aligned.  ALIGN_SLZE  is  used 
by  the  RESERVE_SLZE  macro,  which 
rounds  up  the  size  of  the  memory 
header  to  the  next  AUGNJSLZE  bound¬ 
ary.  The  resulting  RESERVE_SLZE  is 
used  by  the  pointer  conversion  mac¬ 
ros.  Suggested  values  for  ALLGN_SIZE 
for  various  processors  can  be  found 
in  Table  1.  — J.S. 
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To  see  how  this  is  accomplished, 
you  must  understand  that  C  macros  are 
expanded  by  a  preprocessor  before  the 
compilation  phase.  If  a  macro  is  de¬ 
fined  with  the  same  name  as  a  standard 
library  function,  the  macro  definition 
is  expanded  before  compilation.  The 
compiler  actually  sees  the  macro  ex¬ 
pansions,  not  the  standard  library  calls. 
Thus,  a  malloc( )  call  in  client  code  is 
converted  to  a  mem_alloc( )  call  by  the 
macro  malloc  in  mshell.h  (see  Listing 
Three,  page  110).  To  the  client, 
mem_alloc( )  must  provide  the  same 
service  as  the  standard  library  function 
it  replaces.  This  technique  is  called  “re¬ 
direction.” 

For  example,  in  Listing  Two  the 
source  code  call  malloc(sizeof(JUNK)) 
on  line  80  is  actually  a  request  for  the 
preprocessor  to  expand  the  macro  mal¬ 
loc  defined  in  mshell.h.  This  is  expanded 
by  the  preprocessor  to  mem_alloc((size 


offJUNK)),  "junkl.c",  103).  Since  the  C 
compilation  phase  sees  only  the  token 
mem_alloc( ),  the  call  is  correctly  redi¬ 
rected  to  the  memory  shell. 

In  order  to  use  redirection,  you  must 
be  able  to  recompile  the  source  code 
that  calls  the  library.  With  this  caveat, 
redirection  can  be  implemented  for  any 
system  or  user  library.  You  can  even 
perform  redirection  without  changing 
any  source  code  by  using  compiler  com¬ 
mand-line  macro  definitions. 

I  have  used  redirection  to  debug  code 
that  interfaces  with  system  library  rou¬ 
tines  such  as  fopen( )  and  fcloseO.  I 
often  use  redirection  to  check  modules 
written  by  other  programmers. 

Other  Interface  Features 

If  MEM_  WHERE  is  defined,  the  redirec¬ 
tion  macros  expand  into  function  calls 
that  contain  filename  and  line  infor¬ 
mation.  With  this  information,  error  mes¬ 
sages  can  pinpoint  the  client  code  that 


if  ( ( ( jnew  =  (JUNK  *)  malloc (sizeof (JUNK) ) )  ==  NULL)  :: 

( ( jnew-> junk_name  =  strdup (name) )  ==  NULL)) 

{ 

return  NULL  ; 

) 

Example  2:  Obtuse  coding  for  the  allocation  of  memory  in  junk_open( )  can 
hide  the  possibility  of  a  memory  leak  when  the  first  allocation  succeeds  and 
the  second  allocation  fails. 


allocated  the  memory  block.  The 

_ FILE  and _ LINE  macros  are  not 

available  with  all  compilers,  so  turn 
on  MEM_WHERE  only  if  compiler  sup¬ 
port  is  available. 

If  MEM_LIST is  defined,  the  building 
of  an  internal  list  of  memory  blocks  is 
enabled.  This  option  is  used  internally 
in  mshell.c.  The  resulting  list  is  used 
for  dumping  the  entire  allocated  mem¬ 
ory  list  when  an  error  occurs. 

The  header  file  also  defines  two  func¬ 
tions  not  found  in  the  standard  library: 
Mem_Used(  )and  Mem_Display(  ).  These 
functions  are  used  to  check  memory 
usage  and  display  the  current  memory 
list,  respectively. 

The  redirection  of  the  standard  li¬ 
brary  occurs  only  if _ MSHELL  is  not 

defined.  The  mshell.c  module  defines 

_ MSHELL  .  which  allows  mshell.c  to 

call  the  standard  library. 

Memory  Block  Header 

In  order  to  provide  added  error  check¬ 
ing,  the  memory  shell  must  store  addi¬ 
tional  data  for  each  allocated  memory 
block.  Since  we  have  no  idea  how  many 
memory  blocks  will  be  allocated,  a  static- 
array  is  insufficient.  We  could  perform 
a  separate  malloc (  )  to  allocate  storage 
for  a  control  structure  every  time  a  new 
memory  block  is  created.  A  more  effi- 
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(continued  from  page  28) 
cient  method,  however,  is  to  allocate  a 
memory  block  large  enough  to  store 
both  the  control  structure  and  the  data 
region.  Only  the  memory  shell  func¬ 
tions  are  allowed  to  access  the  data  in 
the  control  structure.  Only  the  memory 
shell  clients  are  allowed  to  access  the 
data  region. 

In  the  memory  shell,  the  control  struc¬ 
ture  is  called  the  “memory  block 
header.”  This  header  is  placed  before 
(at  lower  addresses  in  relation  to)  the 
data  region.  See  Figure  1. 

The  standard  library  functions  use 
pointers  to  the  data  region.  Since  this 
does  not  correspond  to  the  base  of  the 
memory  block  allocated  by  the  mem¬ 
ory  shell,  we  have  to  convert  to  and 
from  memory  block  header  pointers 
and  client  data  region  pointers.  This  is 
done  by  using  pointer  arithmetic  and 
casts.  The  macros  CL1ENT_2_HDR  and 
HDR_2_CLIENT  handle  these  pointer 
conversions  (See  lines  74-75,  Listing 
Four,  page  111.) 

Header  Fields 

The  actual  fields  within  the  header  vary 
depending  on  which  compilation  op¬ 
tions  are  used  (see  lines  45-57  of  List¬ 
ing  Four).  At  a  minimum,  tag  and  size 
values  are  required. 

The  tag  is  a  unique  value  that  identi¬ 
fies  this  memory  block  as  valid.  The  tag 


field  is  set  to  the  unique  value  when 
the  header  is  first  initialized.  All  mem¬ 
ory  shell  routines  that  manipulate  the 
header  first  check  for  the  validity  of  the 
tag  before  performing  any  operations. 
While  there  is  a  finite  possibility  that 
the  tag  value  will  be  valid  for  an  invalid 
block,  the  odds  are  very  small. 

The  size  is  the  number  of  bytes  in 
the  client  data  region.  This  value  is 
needed  to  keep  track  of  the  total  num¬ 
ber  of  bytes  currently  allocated  by  the 
memory  shell. 

If  MEM_LIST  is  defined,  next  and 
previous  links  are  added  to  the  header. 
These  pointers  are  used  to  build  a  two- 
way  linked  list  of  memory  blocks.  This 
list  is  used  for  displaying  the  memory 
blocks  in  use. 

If  MEM_  WHERE  is  defined,  a  pointer 
to  a  filename  and  a  line  number  are 
added  to  the  header.  These  fields  are 
filled  in  by  the  last  memory  shell  func¬ 
tion  to  manipulate  the  block.  Note  that 
the  filename  string  is  not  copied  lo¬ 
cally.  Thus,  the  filename  must  be  either 
in  static  or  global  storage.  This  rule  is 
followed  by  all  compilers  that  I  have 
used  that  support  the _ FILE  feature. 

Shell  Implementation 

The  function  mem_alloc()  receives  calls 
intended  for  malloc( ).  First,  mem_al- 
loc( )  allocates  a  memory  block  large 
enough  for  both  the  memory  block 


by  malloc  ( ) 
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Figure  1:  A  memory  block  header  is  added  to  every  memory  block  allocated. 
This  structure  is  used  to  store  information  needed  to  implement  error  check¬ 
ing.  The  alignment  gap  is  an  artifact  of  data  type  alignment  restrictions 
enforced  by  various  processors. 
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header  and  the  client  data  region  using 
mallocO.  If  the  allocation  fails,  a  NULL 
is  returned  to  the  client.  If  the  alloca¬ 
tion  succeeds,  the  memory  header  is 
initialized.  If  MRMJ.IST'k  enabled,  the 
memory  block  is  added  to  the  memory 
block  list.  Finally,  the  HDR_2_ CLIENT 
macro  is  used  to  convert  a  memory 
block  header  pointer  to  a  client  data 
region  pointer.  The  resulting  pointer 
is  returned  to  the  client. 

Note  that  this  routine  does  not  check 
for  errors.  It  simply  stores  enough  in¬ 
formation  to  allow  for  error  checking 
in  mem_realloc(  )  and  mem_free( ). 

The  function  mem_free( )  receives 
calls  intended  for  free( ).  First,  mem 
_free( )  converts  the  client  data  region 
pointer  to  a  memory  header  pointer 
using  the  CUENT_2_HDR  macro.  If  the 
tag  in  the  header  is  invalid,  an  error  is 
reported.  The  tag  is  then  complemented 
to  force  the  tag  to  be  invalid.  This  al¬ 
lows  the  detection  of  a  duplicate  free( ) 
of  the  same  memory  block.  If  MEMJLLST 
is  enabled,  the  memory  block  is  re¬ 
moved  from  the  memory  block  list. 
Finally,  the  standard  library  free( )  func¬ 
tion  is  used  to  return  the  memory  block 
to  the  system. 

The  function  mem_realloc( )  receives 
calls  intended  for  realloc( ).  The  logic 
is  a  combination  of  that  found  in  mem 
_free(  )  and  mem_alloc( ). 

The  function  mem_strdup( )  receives 
calls  intended  for  strdup( ).  In  mem 
_strdup( ),  a  call  is  made  to  mem  allocf ) 
to  obtain  the  needed  memory.  If  the 
call  fails,  a  NULL  is  returned.  Other¬ 
wise,  the  string  is  copied  to  the  client 
data  region  and  the  string  pointer  is 
returned  to  the  client. 

Bad  memory  tags  are  reported  using 
mem_tag_err( ).  This  function  should 
be  modified  to  suit  the  needs  of  your 
particular  application.  It  currently  dis¬ 
plays  an  error  message,  dumps  the  mem¬ 
ory  list,  and  crashes  the  program.  Not 
graceful,  but  acceptable  for  development. 

The  detection  of  a  memory  leak  re¬ 
quires  a  check  immediately  before  your 
program  exits.  If  your  termination  code 
correctly  frees  all  allocated  memory, 
Mem_Used( ^should  return  zero.  If  not, 
you  can  use  Mem_Display( )  to  look 
at  the  memory  blocks  that  are  still  allo¬ 
cated.  (See  lines  36  -  41  in  Listing  Two.) 

The  functions  mem_list_add( )  and 
mem_list_delete( )  manipulate  the  two- 
way  linked  list  of  memory  blocks.  The 
list  manipulation  is  standard,  so  I  won’t 
dwell  on  it. 

I  have  not  included  calloc( )  in  the 
memory  shell  because  I  never  use  the 
function.  If  you  wish  to  use  calloc( ), 
the  implementation  is  straightforward. 
Calculate  the  size  needed,  call  mem 
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_alloc( ),  and  then  clear  the  data  region 
with  memset( ). 

Performance  and  Space  Issues 

The  memory  shell  adds  overhead  both 
in  execution  speed  and  in  the  amount 
of  memory  allocated.  In  the  wide  range 
of  applications  I  have  coded,  the  over¬ 
head  is  not  noticeable  and  has  never 
deterred  me  from  using  the  shell.  If  the 

This  shell,  in  various 
incarnations,  has 
worked  on  many 
MS-DOS  machines, 
Sun3s,  Sun4s,  and 
VAXs 


overhead  causes  problems  in  your  ap¬ 
plication,  you  can  conditionally  turn  the 
protection  features  on  for  development 
and  then  disable  the  more  time-and  space¬ 
consuming  features  for  production. 

I  tend  not  to  disable  any  error  check¬ 
ing  for  production.  Instead,  I  condi¬ 
tionally  compile  the  code  to  dump 
enough  information  to  allow  me  to  de¬ 
bug  the  problem  when  the  customer 
finds  that  inevitable  bug.  When  I  can 
debug  the  problem  quickly,  customer 
goodwill  far  outweighs  the  performance 
or  speed  penalties. 

Portability 

This  shell,  in  various  incarnations,  has 
worked  on  many  MS-DOS  machines, 
Sun3s,  Sun4s,  and  VAXs.  The  portabil¬ 
ity  problems  I’ve  encountered  are: 

•  If  your  compiler  lacks _ FILE  and 

_ LINE  support,  undefine  MEM 

_WHERE. 

•  If  your  compiler  does  not  support 
ANSI  prototypes  or  #if  defined( ),  you 
will  have  to  make  changes  to  the 
code  for  backward  compatibility. 

•  If  your  processor  enforces  alignment 
for  data  types,  the  value  of  ALIGN 
_SIZE  may  need  to  be  adjusted.  See 
the  accompanying  text  box  entitled 
“Pointer  Alignment”  for  more  infor¬ 
mation. 

•  If  you  need  to  use  system  calls  di¬ 
rectly  to  take  advantage  of  extra  func¬ 
tionality,  add  a  secondary  memory 
shell.  This  shell  provides  calls  analo¬ 
gous  to  the  standard  library  calls,  but 
will  take  advantage  of  system-spe¬ 
cific  features.  I  recently  used  such  a 
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shell  on  a  port  from  MS-DOS  to  OS/ 
286.  The  shell  allocated  each  mem¬ 
ory  block  as  a  separate  LDT  entry. 
This  allowed  hardware  checking  for 
many  pointer-related  errors.  I  was 
amazed  at  the  number  of  pointer  er¬ 
rors  that  were  detected  in  shipping 
“bug-free”  code. 

Variations  on  a  Theme 

Since  this  shell  was  implemented,  I 
have  used  it  successfully  on  several 
projects.  On  each  one,  I  have  made 
minor  modifications  to  fit  the  shell  into 
a  particular  environment.  Here  are  some 
variations  that  could  be  helpful: 
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•  A  global  out  of  memory  handler  can 
be  installed  in  malloc( )  and  real- 
loc( ).  The  handler  can  either  crash 
the  program  or  attempt  to  recover.  I 
used  this  on  one  project  and  found 
it  of  limited  utility.  Error  recovery  is 
best  handled  by  the  memory  shell 
clients,  not  a  global  error  handler. 
When  retrofitted  to  existing  code,  how¬ 
ever,  you  can  at  least  find  out  whether 
a  problem  exists. 

•  Overwrites  of  memory  can  be  de¬ 
tected  in  a  limited  way  by  adding  a 
few  extra  bytes  to  the  start  and  end 
of  each  client  data  region.  If  these 
bytes  are  filled  with  magic  values,  the 


values  can  be  checked  when  the  block 
is  freed.  If  a  client  has  written  outside 
data  region,  the  values  should  be 
trashed.  Note:  Don’t  use  either  0x00 
or  Oxff  for  your  magic  values  as  these 
are  the  most  common  values  for  “off 
by  one”  overwrite  errors. 

•  A  common  memory  allocation  prob¬ 
lem  is  the  use  of  a  pointer  to  memory 
that  has  been  freed.  The  pointer  looks 
completely  valid  for  most  purposes, 
but  the  memory  pointed  at  no  longer 
belongs  to  the  program.  The  memory 
remains  unchanged  in  most  imple¬ 
mentations,  however,  so  the  values 
stored  by  the  client  in  the  memory 
block  will  probably  be  valid  until  the 
block  is  reused  by  another  call  to 
mallocC ).  This  is  referred  to  as  using 
a  stale  pointer  and  can  cause  very 
erratic  program  behavior.  If  you  sus¬ 
pect  that  stale  pointers  are  being  used, 
the  memory  shell  can  zero  the  data 
blocks  in  mem_free( )  immediately 
before  the  free( ).  This  way,  if  a  stale 
pointer  is  used  to  access  data  in  a 
freed  block,  the  data  returned  is  zero. 
A  variation  on  this  is  to  complement 
all  bytes  in  the  block.  By  comple¬ 
menting  the  bytes,  you  can  guarantee 
that  the  data  in  the  block  is  scram¬ 
bled  when  accessed  through  a  stale 
pointer.  This  should  cause  your  pro¬ 
gram  to  blow  up  quickly. 

•  Memory  tags  are  not  guaranteed  to 
be  unique.  There  is  a  finite  prob¬ 
ability  that  an  arbitrary  memory  area 
can  contain  the  expected  memory  tag 
value.  If  you  are  worried  about  using 
memory  tags  to  check  for  a  valid  mem¬ 
ory  block,  you  can  search  the  mem¬ 
ory  block  list  at  the  places  where  I 
check  memory  tags  for  validity.  If 
you  can’t  find  the  block  pointer  in  the 
list,  the  block  is  invalid.  Such  a  list 
search  can  take  significant  execution 
time,  so  use  this  approach  only  if  all 
else  fails. 

Roll  Your  Own 

The  variations  on  a  memory  shell  are 
endless.  Every  time  I  build  a  new  appli¬ 
cation  I  find  one  or  more  improve¬ 
ments.  The  important  thing  is  to  encap¬ 
sulate  the  memory  routines.  Once  they 
are  encapsulated,  you  will  have  con¬ 
trol  over  the  memory  allocation  and 
can  add  the  features  that  your  applica¬ 
tion  needs.  You  will  come  up  with  uses 
that  I  cannot  even  imagine.  Good  luck. 

DDJ 


(Listings  begin  on  page  110.) 
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AWK 

as  a  C  Code  Generator 


The  unique  features  of  this  special-purpose  language  can 
greatly  improve  development  time 


Wahhab  Baldwin 


The  AWK  language  is  one  of  the 
gifts  that  the  Unix  environment 
has  given  to  us.  Named  for  the 
initials  of  its  developers  (Alfred 
Aho,  Peter  Weinberger,  and 
Brian  Kernighan),  AWK  was  originally 
designed  to  be  a  simple  utility  for  “quick 
and  dirty”  programming  tasks.  Since 
then,  it  gradually  evolved  into  a  pow¬ 
erful  tool  capable  of  performing  many 
time-saving  tasks  for  programmers. 

This  article  will  introduce  the  AWK 
language  and  present  an  AWK  applica¬ 
tion  that  functions  as  a  C  code  genera¬ 
tor.  While  the  specific  problem  solved 
here  may  not  be  immediately  useful  to 
you,  the  principles  applied  to  solve  the 
problem  will  give  you  ideas  about  how 
you,  too,  can  use  AWK  to  handle  your 
labor-intensive  tasks. 

The  AWK  Language 

The  AWK  language  is  an  example  of  a 
special-purpose  language.  Special-pur¬ 
pose  languages  are  not  designed  to 
solve  every  programming  problem.  In¬ 
stead  they  can  greatly  ease  the  devel¬ 
opment  effort  required  in  the  arena  for 


Wahhab  has  more  than  20 years  expe¬ 
rience  in  software  development  and  is 
currently  owner  of  Baldwin  Software 
Services,  a  small  company  specializing 
in  helping  large  companies  apply  new 
technology  and  improve  their  software 
development  process.  He  can  be  reached 
at  1011  Union  St.,  Manchester,  NH 
03104. 


which  they  are  intended  to  be  utilized. 
AWK  was  designed  to  be  a  tool  for 
writing  programs  that  first  read  one  or 
more  sequential  files  from  standard  in¬ 
put  and  then  write  a  file  to  standard 
output.  While  AWK  can  be  used  for 
developing  programs  that  handle  other 
tasks,  it  excels  at  tasks  of  this  sort. 

AWK  saves  you  time  because  it  makes 
some  assumptions  and  performs  many 
actions  without  the  need  for  you  to  ask 
that  it  do  so.  An  AWK  program  consists 
of  a  sequence  of  pattern-action  state¬ 
ments  (as  described  shortly)  and  func¬ 


tion  definitions.  Essentially,  AWK  exe¬ 
cutes  the  following  cycle: 

1.  Read  a  line  from  standard  input. 

2.  Parse  the  line  into  fields.  The  special 
variable  $0  is  assigned  to  the  whole 
line  (without  the  carriage  return).  The 
special  variable  $1  holds  the  first 
field,  and  $n  holds  the  nth  field. 

3.  Set  other  variables  as  follows:  Set 
NF  to  number  of  fields,  NR  (number 
of  record)  to  the  line  number,  FNR 
to  the  line  number  within  the  current 
input  file,  and  FILENAME  to  the  name 
of  the  current  input  file.  Thus,  $NF 
holds  the  last  field  of  the  line. 

4.  Process  the  record  according  to  each 
of  the  pattern-action  statements  in 
order. 

A  pattern-action  statement  takes  the 
form:  pattern  I action! 

The  statement  can  be  read  in  this 
way:  If  the  input  line  matches  the  pat¬ 
tern  (or  condition),  then  perform  the 
action.  Either  the  pattern  or  the  action 
can  be  omitted.  If  the  pattern  is  omit¬ 
ted,  then  by  default  the  action  is  to 
select  every  input  line.  If  the  action  is 
omitted,  then  by  default  the  action  is 
to  print  the  input  line. 

The  syntax  of  AWK  is  very  similar  to 
the  C  syntax,  except  that  in  AWK  a 
carriage  return  can  replace  C’s  ubiqui¬ 
tous  semicolon.  Also  variables  can  be 
used  in  AWK  without  being  declared, 
and  they  are  initialized  either  to  zero 
or  a  null  string,  depending  on  how 
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(continued  from  page  36) 
they  are  used. 

A  crucial  feature  of  AWK  that  is  not 
present  in  C  is  the  ability  to  perform 
regular  expression  matching.  Regular 
expression  matching  is  used  by  the 
Unix  grep  utility,  and  has  been  adopted 
by  several  text  editors,  including  Brief. 
AWK  compares  a  pattern  string  (usu¬ 
ally  enclosed  between  slashes)  against 
another  string  (which,  by  default,  is  the 
input  line),  and  then  returns  true  or 
false  depending  on  whether  the  pat¬ 
tern  is  matched.  (For  more  details,  see 
the  accompanying  text  box  entitled 
“Regular  Expressions.”) 

At  this  point,  without  explaining  the 
command  syntax  in  detail,  we  can  ex¬ 
plore  some  small  but  still  useful  AWK 
programs.  For  example,  /Fred/  prints 
all  lines  in  the  specified  input  that  con¬ 
tain  the  string  “Fred”.  The  following 
one-line  program  prints  its  input  file 
with  line  numbers:  (print  FNR,  $01 

If  alignment  of  the  input  is  neces¬ 
sary,  then  the  print f  statement  familiar 
to  all  C  programmers  can  be  used: 


I printf("%4d  %s\n",  FNR,  $0)1 
The  comma  between  the  two  pa¬ 
rameters  in  the  print  statement  causes 
an  output  field  separator  (a  space  by 

AWK  saves  you  time 
because  it  makes  some 
assumptions  and 
performs  many  actions 
without  the  need  for  you 
to  ask  that  it  do  so 


default)  to  be  placed  between  the  fields. 
If  the  space  is  not  desired,  two  strings 
can  be  concatenated  in  AWK  by  simply 
naming  them  one  after  another  (that  is, 
print  FNR  $0).  Note  that  pn'wt/'requires 


Regular  Expressions 


Regular  expressions  use  a  pattern 
string  of  characters,  enclosed  in 
slashes,  to  describe  a  pattern  that  can 
be  compared  to  a  target  string.  The 
simplest  example  of  a  pattern  string 
is  just  a  string  of  characters.  For  ex¬ 
ample,  /red/ matches  “a  red  ball”  and 
“Alfredo”,  but  not  “tuna  fish".  Differ¬ 
ent  series  of  metacharacters  have  spe¬ 
cial  meaning  in  the  pattern  string.  The 
period  refers  to  any  single  character, 
so  /r.d/ matches  “red”  and  “rod”,  but 
not  “road”  or  “rd”.  To  match  a  period 
or  any  other  metacharacter  literally, 
precede  it  with  a  backslash.  Special 
characters  can  be  matched  by  using 
C’s  escape  characters:  \t  represents  a 
tab  and  \b  represents  a  backspace, 
while  \101  represents  an  octal  value 
(65,  or  the  character  ‘a’). 

A  circumflex  matches  the  begin¬ 
ning  of  a  string  while  the  dollar  sign 
matches  the  end,  so  Z''red$/  matches 
a  line  consisting  solely  of  the  word 
“red”.  An  asterisk  matches  zero  or 
more  of  the  preceding  pattern.  For 
instance,  /l*ama/  matches  “ama”, 
“lama”,  “llama”,  “lllama”,  and  so  on. 
A  plus  matches  one  or  more,  while  a 
question  mark  matches  zero  or  one 
of  the  preceding  pattern.  Also,  char¬ 
acters  may  be  grouped  with  paren¬ 
theses.  Thus,  /M(iss)+ippi/  matches 


“Missippi”,  as  well  as“Mississippi”. 
Brackets  can  be  used  to  indicate  a 
character  that  is  one  of  the  enclosed 
characters,  so  that  [a-zA-Z]  matches 
any  letter,  while  U3 5 791  matches  an 
odd  digit.  Thus,  /(A -ZIfa-z]*/ matches 
any  word  with  an  initial  capital.  A 
circumflex  that  is  the  first  character 
after  the  open  brace  matches  any  char¬ 
acter  except  for  those  in  the  braces, 
so  /T'aeioul+  $/  matches  strings  with 
no  lower-case  vowels. 

Regular  expressions  are  a  valuable 
and  powerful  tool.  Unfortunately,  dif¬ 
ferent  implementations  of  regular  ex¬ 
pressions  occur  under  the  MS-DOS 
programs  that  use  them.  The  Micro¬ 
soft  Editor  does  not  support  paren¬ 
theses  or  the  plus  symbol;  the  Brief 
editor  uses  braces  in  lieu  of  parenthe¬ 
ses,  the  @  to  match  zero  or  more 
occurrences,  and  ?  as  a  single  charac¬ 
ter,  and  has  other  differences  as  well. 
Different  MS-DOS  implementations  of 
grep,  a  command-line  text  search  fa¬ 
cility  based  on  the  Unix  utility,  use 
slightly  differing  characters.  Nonethe¬ 
less,  regular  expressions  are  a  power¬ 
ful  tool  for  matching  text  —  once  you 
become  familiar  with  them,  you  will 
wonder  how  you  ever  lived  without 
them. 

—  W.B. 
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(continued  from  page  38) 
a  newline,  while  print,  like  its  Basic 
counterpart,  prints  a  new  line  auto¬ 
matically. 


Two  special  patterns,  BEGIN  and 
END,  refer  to  one  cycle  before  the  first 
input  record  has  been  read  and  after 
the  last  input  record  has  been  read.  For 


{total  +=  $1) 

END  {print  total)  #  Total  for  all  input 


Example  1:  A  simple  AWK  program  to  total  a  series  of  numbers. 


{gsub (/aluminium/,  "aluminum")) 
(gsub (/colour/,  "color")} 


Example  2:  A  built-in  AWK function  for  global  substitution. 


#  Program  to  count  word  usage  in  input. 

#  eliminate  all  non-letters  except  space 

{  gsub(/ [AA-Za-z  ]/,  ””)  ) 

#  add  words  to  associative  array 
{  for  (i  =  1;  i  <=  NF;  i++) 

++word[$i]  ) 

#  print  each  array  entry 
END  {  for  (j  in  word) 

print  j,  word[j]  ) 


Example  3:  Using  strings  rather  than  integers  as  array  subscripts 


instance,  Example  1  shows  how  to  to¬ 
tal  a  series  of  numbers. 

The  +=  operator,  when  used  as 
shown  in  Example  1,  is  equivalent  to 
total  =  total  +  Si.  Also  note  that  the 
pound  sign  (#)  indicates  a  comment. 

These  programs  are  typically  run  by 
first  saving  them  as  a  file  (say,  TOTAL. 
AWK)  and  then  invoking  the  file  by  the 
command  line:  AWK  -f  TOTAL.AWK 
DATA1.DATDATA2.DAT 

DATA1.DAT  and  DATA2.DAT  serve 
as  the  input  files  (DATA*.DAT  could 
also  be  used).  The  output  goes  to  STD- 
OUT  and  is  typically  redirected  into  a 
file  by  using  >.  Short  programs  can  be 
passed  directly  as  a  parameter  to  AWK: 
AWK  ’(print  FNR,  $0)’ prog.c  > progc.lst 
This  last  method  is  more  useful  un¬ 
der  Unix  than  under  MS-DOS,  because 
MS-DOS  restricts  both  the  length  of  the 
command  line  and  the  use  of  <  or  >  in 
a  parameter. 

Note  that  AWK  is  traditionally  imple¬ 
mented  as  an  interpreter,  although  an 
AWK  compiler  for  DOS  now  exists  (see 
the  text  box  entitled  “AWKlforjDOS”). 
Most  AWK  programs  are  small  and  I/O 
bound,  so  the  quick  debug  cycle  of  an 
interpreter  generally  outweighs  the 
speed  benefits  of  a  compiler. 

AWK  contains  many  useful  built-in 
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functions  for  handling  strings.  For  in¬ 
stance,  the  program  in  Example  2  per¬ 
forms  global  substitutions  on  the  input 
file,  changing  British  spelling  to  Ameri¬ 
can.  Other  string-handling  routines  in¬ 
clude  sub,  which  performs  a  single  sub¬ 
stitution;  length  and  substr,  which  re¬ 
turn  the  length  and  substrings,  respec¬ 


struct  reel  { 

long  r1_id_no; 
char  r1_name[51]; 
int  rc_value; 

}; 

struct  rec2  { 

long  r2_id_no; 
int  r2_seq; 
char  r2_code; 
struct  { 

char  r2_state_cd[3]; 
long  r2_state_eff_dt; 
}  r2_st_range[51]; 
struct  { 

int  r2_value; 
char  r2  use_cd[3); 

}  r2  not_array; 
struct  { 

char  r2  work_cd[3]; 
long  r2_work_dt; 

}  r2_work_list[6]; 
long  r2_the_end; 

}; 


Figure  1:  Sample  input  for  Listing  One 


tively;  and  index,  which  finds  the  in- 
dex|of  Ithe  first  occurrence  of 'onejstring 
as  a  substring  of  another. 

AWK  is  unusual  in  that  all  variables 
are  both  treated  either  as  strings  or  as 
numbers,  depending  on  how  they  are 
used.  Arrays  in  AWK  are  associative 
arrays  whose  subscripts  are  strings, 


rather  than  numbers.  This  powerful  fa¬ 
cility,  also  found  in  other  languages 
such  as  SNOBOL  and  REXX,  allows  the 
construction  in  memory  of  a  structure 
that  is  similar  to  a  keyed  file.  Thus,  the 
program  in  Example  3  produces  a  list 
of  each  text  word  used  in  the  input  file 
along  with  the  number  of  times  that  the 


/*  reel  7 

stlong(p.rec1->r1  _id_no  ,  inf_rec  +  0); 
stchar(p.rec1->r1_name  ,  inf_rec  +  4); 
stint(p.rec1  ->rc_value  ,  inf_rec  +  54); 

/*  rec2  7 

stlong(p.rec2->r2Jd_no  ,  inf_rec  +  0); 
stint(p.rec2->r2_seq  ,  inf_rec  +  4); 
stchar(p.rec2->r2_code  ,  inf_rec  +  6); 
for  (i  =  0;  i  <  51 ;  i++)  { 

(p.rec2->r2_st_range[i].r2_state_cd  ,  inf_rec  +  i  *  6  +  7); 
(p.rec2->r2_st_range[i].r2_state_eff_dt ,  inf  rec  +  i  *  6  +  9); 

} 

(p.rec2->r2_not_array.r2_value  ,  inf_rec  +  313); 
(p.rec2->r2_not_array.r2_use_cd  ,  inf_jec  +  315); 
for  (i  =  0;  i  <  6;  i++)  { 

(p.rec2->r2_workJist[i].r2_work_cd  ,  inf  rec  +  i  *  6  +  317); 
(p.rec2->r2  workJist[i].r2  work_dt ,  inf_rec  +  i  *  6  +  319); 

} 

stlong(p.rec2->r2_the_end  ,  inf_rec  +  353); 


Figure  2:  C  code  generated  by  the  AWK  program  in  Listing  One 


Dr.  Dobb’s Journal,  August  1990 

692 


41 


AW  K 


text  word  occurs. 

I  have  found  AWK  to  be  very  useful 
during  the  process  of  converting  a  large 
system  over  from  one  database  man¬ 
ager,  such  as  Informix’s  C-ISAM,  to  an¬ 
other.  C-ISAM  stores  data  internally  in 
an  operating  system-independent  for¬ 
mat.  This  means  that  each  field  must 
be  converted  to  and  from  this  format 
when  records  are  read  or  written.  I 
needed  to  convert  many  different  rec¬ 
ord  types,  each  with  many  fields,  and 
the  offsets  for  each  field  had  to  be 
calculated  exactly.  I  used  the  AWK  pro¬ 
gram  in  Listing  One  (see  page  116)  to 
generate  the  C  code  required. 

In  this  case,  my  input  files  were  C 
header  files  that  contained  record  struc¬ 
tures.  In  turn,  some  of  these  record 
structures  contained  other  structures  or 
arrays  of  structures.  My  output  was  C 
source  code  to  move  the  data  from 


these  records  as  pointed  to  by  a  pointer 
called  p.  A  bit  of  sample  input  and 
output  are  shown  in  Figures  1  and  2, 
respectively. 

All  of  my  header  files  had  the  same 
basic  format,  so  I  didn’t  try  to  make  the 
AWK  program  more  general.  For  ex¬ 
ample,  the  opening  struct  statement 
and  the  closing  brace  for  each  record 
must  start  in  column  1,  while  all  other 
lines  must  be  indented.  (After  all,  this 
was  a  one-shot  program,  designed  to 
be  used  once  and  then  thrown  away.) 

The  first  line  in  Listing  One  changes 
AWK’s  default  input  file  separator  from 
its  usual  value  of  white  space  to  be  any 
mix  of  spaces,  tabs,  or  open  brackets. 
A  quirk  of  AWK  is  that  when  you  mod¬ 
ify  the  input  field  separator ;  the  lead¬ 
ing  spaces  on  a  line  are  considered  to 
be  the  first  field.  If  you  use  the  default, 
the  leading  spaces  are  ignored.  The 


field  names  (which  are  indented)  show 
up  as  the  second  field,  or  as  $2,  rather 
than  $1. 

The  next  line  of  the  program  deals 
with  input  lines  such  as:  struct  sam¬ 
ple _rec  I,  and  resets  j,  which  is  the 
offset  within  the  structure.  At  the  same 
time,  the  record  name  is  saved  for  use 
in  the  emit  function  described  in  the 
next  paragraph. 

The  bulk  of  the  program  deals  with 
the  individual  fields.  If  the  field  occurs 
within  a  structure  inside  of  the  main 
record  structure,  the  information  in  the 
field  must  be  saved  until  the  structure 
name  and  the  number  of  occurrences 
are  encountered.  The  function  setup 
does  this,  using  AWK  arrays  to  hold  the 
information.  In  the  normal  case,  the 


AWK  for  DOS 

Two  commercial  versions  of  AWK  are 
available  under  MS-DOS  and  OS/2. 
Mortice  Kem  Systems,  Waterloo,  Ont., 
Canada,  includes  both  small  and  large 
model  versions  of  AWK  in  its  MKS 
Toolkit  (with  and  without  8087  sup¬ 
port),  and  also  sells  AWK  separately, 
offering  both  DOS  and  OS/2  versions. 
This  package  includes  a  tutorial  writ¬ 
ten  by  MKS,  as  well  as  a  copy  of  the 
book,  The  AWK  Programming  Lan- 
guage  by  Aho,  Kernighan,  and  Wein¬ 
berger  (Addison- Wesley,  1988).  The 
OS/2  version  opens  the  possibility  of 
holding  enormous  arrays  in  memory. 

Sage  Software  (Beaverton,  Oreg.), 
which  recently  acquired  Polytron,  pro¬ 
vides  the  same  book  in  its  versions 
of  the  PolyAwk  program  for  MS-DOS 
and  OS/2.  PolyAwk  includes  several 
useful  extensions,  such  as  the  ability 
to  hold  associative  arrays  in  sorted 
order,  the  provision  of  true  multi¬ 
dimensional  arrays,  and  the  availability 
of  new  functions  including  getkey ,  toup- 
per,  and  tolower. 

Sage  also  offers  a  developer’s  toolkit 
that  includes  both  an  interpreter  and 
a  compiler.  By  default,  the  compiler, 
AWKC,  produces  a  program  with  an 
extension  of  .AE.  This  program  must 
run  by  a  run-time  program,  called 
AWKI.  However,  by  using  a  -xe  flag 
on  the  AWKC  command  produces  a 
stand-alone  executable  program.  The 
ability  to  write  stand-alone  programs 
using  AWK  is  a  great  benefit  if  you 
wish  to  distribute  your  software  to 
others  —  they  do  not  need  a  copy  of 
the  interpreter,  and  they  cannot  read 
or  modify  your  source  code. 

—  W.B. 


if  (type  ==  "string") 
last_part  =  ",  "  1 

else 

last_part  =  " ) ; " 

print  "\t"  type  "(p."  rec  varname 

",  inf_rec  +  "  offset  last_part 


Example  4:  Alternative  to  using  the  ?  operator 
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( continued  from  page  42) 
emit  function  is  called.  This  function 
drops  any  trailing  semicolon  from  the 
variable  name  (from  a  line  such  as  int 
field;),  and  then  prints  the  line  of  C 
code  required.  The  print  statement  in 
emit  uses  the  C  operator  ?  to  print  the 
second  parameter  required  by  strings. 
A  simpler  but  longer  approach  would 
require  the  use  of  an  extra  variable  as 
shown  in  Example  4. 

AWK  does  not  have  function  point¬ 
ers.  I  wrote  the /function  to  invoke  the 
appropriate  function  and  to  pass  on 
the  remaining  parameters. 

The  last  remaining  task  occurs  when 


the  closing  brace  to  a  structure  within 
a  structure  is  found.  If  NF  >  3,  then  this 
is  an  array  of  structures,  and  a  C  lan- 

AWK  does  not  have 
function  pointers 


guage  for  loop  is  printed.  The  field 
separator  includes  the  open  bracket 
but  not  the  close  bracket,  so  in  a  line 


such  as,  :  1  inner_struct[5l;  $4  is  set  to 
57;.  The  trick  $4+0  forces  this  to  a 
numeric  value. 

The  AWK  for  loop  uses  the  tempo¬ 
rary  variable  k  and  then  calls  the  func¬ 
tion  emit2 ,  which  is  a  close  copy  of 
emit,  except  that  it  calculates  an  offset 
from  infjrec.  When  emit2  has  spit  out 
one  line  for  each  variable  in  the  inner 
structure,  it  prints  the  closing  brace  to 
the  C  for  loop,  and  calculates  an  up¬ 
dated  offset  into  the  C-ISAM  record. 

This  AWTC  program  handles  the  pro¬ 
cess  of  moving  data  from  the  C  struc¬ 
ture  to  the  C-ISAM  record.  1  wrote  an 
almost  identical  program  to  handle  the 
reverse  process  of  moving  the  data  from 
the  C-ISAM  record  to  the  C  structure. 
The  only  problem  that  had  to  be  ad¬ 
dressed  differently  in  the  second  pro¬ 
gram  was  how  to  handle  slack  bytes. 
Different  C  compilers  place  slack  bytes 
in  various  places  to  encourage  num¬ 
bers  and  structures  to  be  word-aligned. 
Based  on  the  conditions  that  your  par¬ 
ticular  compiler  and  settings  require, 
the  addition  of  a  line  such  as  this  will 
force  the  offset  to  a  word  boundary: 
offset  +=  offset  %  2 

While  this  program  has  obvious  weak¬ 
nesses  (which  I  would  remedy  if  it 
were  to  be  run  by  others),  it  still  serves 
as  a  good  example  of  how  to  use  a 
utility  language  such  as  AWK  to  per¬ 
form  time-consuming  chores  that  could 
take  days  if  done  manually,  and  that 
would  even  take  much  longer  to  pro¬ 
gram  in  a  conventional  language  such 
as  C.  In  fact,  having  a  powerful  tool 
such  as  AWK  handy  will  lead  you  to 
do  many  tasks  you  might  not  under¬ 
take  otherwise!  Now  that  an  AWK  com¬ 
piler  is  available  (see  “AWK  for  DOS”), 
you  may  even  find  yourself  using  AWK 
for  distribution  programs. 

Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
online.  To  order  the  disk,  send  $14.95 
(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  the  DDJ  listing  service  (415-364- 
8315)  and  through  the  DDJ  Forum  on 
CompuServe  (type  GO  DDJ). 

DDJ 


(Listing  begins  on  page  116.) 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  3. 


44 

694 


Dr.  Dobb’s  Journal,  August  1990 


Implementing 

Bicubic  Splines 

Drawing  objects  that  contain  curves 


Raymond  G.  Lauzzana  and  Denise  E.M.  Penrose 


Lisp  is  an  excellent  language  for 
developing  high-level  AI  pro¬ 
grams.  In  particular  Allegro  Com¬ 
mon  Lisp  (Allegro  CL)  has  made 
the  Macintosh  an  excellent  plat¬ 
form  for  developing  AI  software.  All 
implementations  of  Common  Lisp  in¬ 
cluding  Allegro  CL,  are  limited  by  some 
serious  drawbacks.  Communications  to 
graphics  and  audio  devices  are  not  speci¬ 
fied  and  Common  Lisp  does  not  even 
define  access  to  physical  devices.  (A 
trap  mechanism  in  Allegro  CL  does  per¬ 
mit  communication  to  the  Macintosh 
Toolbox,  but  this  mechanism  is  very 
limited.)  Additionally,  complex  mathe¬ 
matical  computations,  such  as  geomet¬ 
ric  transforms  or  statistical  analysis,  are 
extremely  slow  in  any  implementation 
of  Lisp. 

To  overcome  these  problems,  you 


Raymond  is  a  research  associate  at  the 
Center  for  Knowledge  Technology, 
Utrecht,  The  Netherlands.  He  is  the  devel¬ 
oper  of  various  software  for  research 
in  design  rule  systems,  color  semantics, 
and  image  analysis.  He  also  teaches 
Lisp  and  AI  at  the  Hogeschool  voor  de 
Kunsten  Utrecht.  Denise  is  a  freelance 
writer  and  editor  covering  AI  and  elec¬ 
tronic  art  in  Europe.  Previously,  she 
was  principal  editor  at  Lotus  Develop¬ 
ment  Covp.  and  senior  editor  at  Osborne/ 
McGraw-Hill.  They  can  be  reached  at 
Oudegracht  31 7,  3511 PB  Utrecht,  The 
Netherlands,  telephone:  +31  (30)  340 
866. 


can  write  C  functions  that  are  called 
from  Lisp.  Allegro  CL  provides  a  For¬ 
eign  Function  Interface  to  facilitate  inter¬ 
language  communication.  The  use  of 
this  interface  allows  C  to  access  physi¬ 
cal  devices  and  perform  complex  com¬ 
putations  on  behalf  of  higher-level  Lisp 
operations.  This  allows  the  Lisp  pro¬ 
gram  to  be  concerned  with  high-level 
problems  such  as  rule-base  manage¬ 
ment,  while  the  C  routines  handle  all 
of  the  “dirty  work”  such  as  drawing 
pictures  on  the  screen. 

In  this  article,  we  present  a  spline 
function  that  uses  the  Macintosh  Tool¬ 


box  to  draw  a  smooth  curve.  This  spline 
function  is  one  of  18  graphic  primitives 
in  Artifex,  a  design-rule  system  based 
on  shape  grammars.  (Source  code  for 
the  system  is  available  from  the  authors 
of  this  article.)  In  order  to  calculate  the 
points  along  the  curve  of  a  bicubic 
equation  must  be  solved.  Calculations 
of  this  sort  are  miserably  slow  in  Lisp. 
However,  the  solution  presented  here 
is  quick  enough  to  reasonably  support 
user  interaction,  such  as  “rubber-splin- 
ing,”  in  which  the  user  dynamically 
instances  splines. 

The  Bicubic  Spline 

“Splines”  are  graphic  elements  that  are 
used  for  drawing  objects  that  contain 
curves.  A  spline  is  composed  of  one 
or  more  “spline  segments.”  Figure  1 
illustrates  a  spline  segment  defined  by 
the  four  points  PO  though  P3-  Points 
PI  and  P2  are  the  end  points  of  the 
spline  segment  and  the  curve  is  drawn 
between  these  two  points.  Points  PO 
and  P3  are  called  the  “control  points.” 
During  the  process  of  calculating  the 
spline,  the  two  points  are  interpreted 
as  vectors. 

The  magnitude  of  the  vector  modu¬ 
lates  the  tension  of  the  curve.  In  other 
words,  the  greater  the  distance  between 
PO  and  PI,  the  more  the  curve  will 
bend.  As  Figure  2  shows,  when  PO  and 
PI  are  coincident,  the  beginning  of  the 
curve  is  parallel  to  the  line  PI  -  P2.  As 
PO  approaches  infinity,  moving  further 
away  from  PI,  the  curve  tends  toward 
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(continued  from  page  48)  coordinates  for  the  points,  ( i,  j),  along 

the  line  P0—P1.  Similarly,  the  spline  this  curve  are  found  by  solving  the 
may  be  bent  to  one  side  or  the  other  cubic  equations  shown  in  Example  1 . 
as  illustrated  in  Figure  3,  by  modulat-  To  draw  a  curve,  you  must  solve  this 
ing  the  vector  angle.  In  this  manner,  a  pair  of  equations  for  every  point  at 
user  can  interactively  describe  a  curve  some  regular  sampling  interval.  The 
by  moving  its  control  points  in  order  number  of  samples  determines  the 
to  perform  the  rubber-splining  men-  coarseness  or  the  smoothness  of  the 
tioned  earlier.  curve.  Figure  4  illustrates  a  spline  seg- 

The  spline  presented  here  uses  a  kind  ment  that  results  from  sampling  the 
of  interpolation  known  as  “bicubic”  to  equation  four  times.  If  you  sample  the 
create  a  particular  class  of  curves.  The  equation  more  frequently,  your  curve 

will  be  smoother.  The  production  of  a 
reasonably  smooth  curve  requires  a 
fairly  short  interval  with  a  width  of 
2-3  pixels  and  a  significant  amount 
Example  1:  Cubic  equations  of  computation. 


The  free  cubic  variable  t  has  a  range 
from  0  to  1  in  real  numbers.  To  find  a 
point  in  the  middle  of  the  curve,  you 
solve  the  equations  for  t=0.5.  In  this 
way,  the  degree  of  smoothness  of  a 
curve  can  be  varied,  depending  on  the 
frequency  at  which  t  is  sampled. 

The  other  free  variable,  W,  is  a  weight¬ 
ing  factor  that  controls  the  tension  of 
the  curve.  A  value  of  0.9  produces  rea¬ 
sonable  curves  on  the  Macintosh.  If  W 
is  0,  then  a  straight  line  is  drawn  be¬ 
tween  PI  and  P2.  As  W  increases,  the 
end  of  the  curve  tends  toward  tangency 
with  the  lines  P0-  PI  and  P2—  P3 .  Fig¬ 
ure  5  illustrates  the  effect  of  varying 
this  weighting  factor. 

It  is  important  to  remember  that  an 
infinite  number  of  curves  can  be  drawn 
between  any  two  points.  Bicubic  inter¬ 
polation  produces  curves  with  conti¬ 
nuities  at  the  end  points.  These  conti¬ 
nuities  facilitate  the  process  of  combin¬ 
ing  spline  segments  into  an  infinite  class 
of  curves. 

Figure  6  illustrates  two  bicubic  spline 
segments.  The  first  spline  segment  is 
defined  on  the  line  P0-P3  and  the  sec¬ 
ond  defined  on  the  line  P1-P4.  To¬ 
gether  the  two  segments  form  a  spline 


Help  Functions 

One  C  routine  (shown  in  Listing  One) 
and  four  Lisp  Help  functions  (pre¬ 
sented  in  Listing  Two)  are  required 
to  calculate  and  display  the  spline. 

The  C  routine  distance  calculates 
the  mean-squared  distance  between 
two  coordinate  pairs.  This  calculation 
is  used  in  _Spline  to  detennine  the 
distance  between  the  end  points. 

A  higher-level  Lisp  representation 
for  a  point  @@  replaces  the  intrinsic 
#@  provided  with  Allegro  CL.  This- 
representation  establishes  device-in¬ 
dependence  for  high-level  functions, 
such  as  SPLINE.  The  function  @@  de¬ 
scribes  a  screen  location  in  physical 
coordinates.  (@@  0  0)  is  the  upper- 
left  comer.  If  a  single  integer  is  re¬ 
ceived,  the  integer  is  interpreted  as  a 
packed  point,  and  it  is  unpacked  into 
a  coordinate  pair. 

The  Lisp  predicate  POINTPtests  for 
the  pointness  of  its  argument.  If  the 
argument  is  a  point  represented  in 
coordinates  (@@  00  )  the  argument 
returns  '/;  otherwise  the  argument  re¬ 
turns  NIL.  The  two  functions  I-CO- 
ORD  and  J-COORD  extract  the  verti¬ 
cal  and  horizontal  coordinates  from 
a  point. 

—  R.L..D.P. 
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that  is  continuous  in  the  second  deriva¬ 
tive  at  P2.  In  other  words,  the  two 
spline  segments  change  at  the  same 
rate  and  have  the  same  slope  at  P2 ,  so 
they  connect  smoothly.  This  special 
property  of  bicubic  splines  makes  them 
ideal  for  use  with  graphics  software 
because  a  smooth  curve  can  be  drawn 
through  any  arbitrary  set  of  points.  An¬ 
other  advantage  of  bicubic  splines  is 
that  the  points  that  define  the  curve  of 
the  splines  lie  on  the  curve.  Other  curve¬ 
defining  functions,  such  as  the  B-spline, 
are  defined  by  points  that  are  not  lo¬ 
cated  on  the  curve. 

You  could  write  a  Lisp  routine  to 
calculate  the  points  along  the  curve, 
but  such  a  routine  would  be  very  slow. 
In  any  case,  you  would  still  need  to 
access  a  physical  line-drawing  func¬ 
tion  in  order  to  connect  the  points  into 
a  curve.  The  faster  and  better  way  to 
handle  this  calculation  is  to  call  the  C 
routine,  _Spline,  which  is  found  in  List¬ 
ing  One  (page  118).  This  routine  is 


Example  2:  Calculating  coordinates 


accessed  through  three  Lisp  functions: 
Mac_Spline,  Do_Spline  and,  at  the  high¬ 
est  level,  Spline ,  found  in  Listing  Two 
(page  119). 

The  C  Routine 

The  routine  _5jt>/mecalculates  and  draws 
a  curved  line  along  the  path  of  a  bicu¬ 
bic  spline.  This  routine  must  solve  the 
equations  mentioned  earlier  for  each 
point  along  the  curve.  The  parameters 
to  _Spline  are  the  coordinates  ( if)  of 
the  four  points  PO,  PI,  P2,  and  P3  The 
routine  has  two  parts:  an  initialization 
phase  and  a  loop.  Speed  is  important, 
so  the  routine  contains  the  minimum 
number  of  repetitive  calculations. 

The  initialization  phase  sets  up  a  two- 
pixel-wide  sampling  rate,  and  a  weight¬ 
ing  factor  of  0.9.  If  you  wish  to  create 
faster  but  coarser  splines,  you  would 
increase  the  value  of  inc  to  either  5  or 
7.  After  these  values  have  been  estab¬ 
lished,  the  Macintosh  Toolbox  func¬ 
tion  MoveTo  sets  the  current  position 


while 

it  <  i) 

i  j  = 

jl*t  +  j2* (1  -  t) 

+  W* ( j2-j3) *t* (1  -  t) * (1  -  t) 

+  W* ( jl- jO) *t*t* (1  -  t); 

i 

il*t  +  12*  (1  -  t) 

+  W*(i2-i3)*t*(l  -  t) *  (1  -  t) 

+  W* (11-10) *t*t* (1  -  t); 

t  = 

t  +  dt; 

LineTo  (i, j) ; 

} 

to  PI.  The  routine  then  calculates  the 
distance  between  PI  and  P2.  If  that 
distance  is  less  than  the  sampling  inter¬ 
val,  _Spline  uses  LineTo  to  draw  a 
straight  line  from  PI  to  P2. 

To  increase  the  speed  of  the  routine, 
the  bicubic  equation  is  partially  solved 
outside  of  the  loop.  A  straightforward 
calculation  of  the  coordinates  would 
result  in  this  loop  with  18  multiplies 
and  19  additions,  (Example  2). 

A  more  efficient  partitioning  of  the 
equation  produces  this  loop  with  13 
multiplies  and  8  additions,  as  shown 
in  Example  3- 

The  reduction  in  additions  results 
from  precalculating  the  factors,  i3,  j3 , 
15,  and  j5 .  The  reduction  in  multiplica¬ 
tion  results  from  calculating  the  cubic 
factors  t2,  t3,  and  t5  only  once  for  both 
coordinates.  This  may  seem  like  a  rela¬ 
tively  minor  improvement,  but  the  cal¬ 
culation  must  be  performed  100  or  more 
times  while  the  user  is  trying  to  in¬ 
stance  a  curve.  In  this  sort  of  situation, 
every  nanosecond  counts. 

The  cubic  variable  t  has  a  range  from 
0  to  1 .  The  increment  on  this  unit  inter¬ 
val,  dt,  describes  the  rate  of  sampling 
of  points  on  the  spline,  dt  is  the  unit 
increment  (A  0  on  the  variable  t.  For 
example,  if  you  want  to  sample  a  point 
every  2.5  pixels  and  the  distance  be¬ 
tween  PI  and  P2  is  100  pixels,  the  unit 
increment  dt  would  have  the  value  of 


Figure  5:  Varying  the  weighting  factor 


Figure  6:  Two  spline  segments  forming 
a  continuous  curve 
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0.025.  The  reciprocal  of  dt,  count ,  which 
is  the  number  of  points  to  be  calcu¬ 
lated.  In  this  case,  40  points  would  be 
sampled  along  the  spline. 

In  order  to  improve  accuracy,  the 
loop  in  the  actual  code  is  incremented 
with  respect  to  count  rather  than  t.  This 
step  incurs  the  additional  cost  of  one 
multiply,  but  the  resulting  elimination 
of  round-off  errors  improves  the  ap¬ 
pearance  of  the  curve. 

Substantially  worse  algorithms  that 
do  not  factor  out  the  cubic  variable  t 
can  be  used  to  solve  this  equation. 
Better  algorithms  are  also  probably  avail¬ 
able.  When  working  on  problems  of 
this  sort,  reach  into  your  bag  of  alge¬ 
braic  tricks  before  you  start  coding. 

Loading  the  C  Routine 

Before  you  can  use  the  C  routine  from 
Lisp,  you  must  first  compile  the  routine 
and  then  load  the  Allegro  CL  Foreign 
Function  Interface  into  your  Lisp  envi¬ 
ronment.  Remember  that  you  can  only 
load  relocatable  object  files,  not  sources 
or  programs.  In  other  words,  you  may 
only  load  compiled  subroutines.  The 
Foreign  Function  Interface  will  load 
any  MPW  C  relocatable  object  files.  It 
will  not  work  with  LightSpeed  C  or 
other  third-party  compilers. 

Once  you  have  compiled  your  C  rou¬ 
tine,  start  up  Allegro  CL.  The  simplest 
way  to  load  the  Foreign  Function  Inter¬ 
face  uses  the  expression  require.  In 
order  to  use  this  expression,  you  must 
have  already  moved  FF.fasl  from  the 
Foreign  Function  folder  to  the  Library 
folder,  as  shown  in  Example  4(a). 

Another  way  to  load  the  Foreign  Func¬ 
tion  Interface  uses  load.  In  this  case, 
you’ll  need  to  specify  the  exact  <pa- 
thname>  to  the  folder  where  you  have 
stored  FF.fasl.  See  Example  4(b).  You 
will  also  need  to  specify  the  folder  that 
stores  the  C  library  functions  that  are 
provided  with  MPW  C.  To  do  so,  create 
a  logical  pathname  CLIB  using  def- 
logical-pathname,  as  demonstrated  in 
Example  4(c). 

You  are  now  ready  to  load  the  _Spline 
function  into  your  Lisp  environment. 
The  Foreign  Function  Utility  ff-load 
loads  binary  files  and  their  associated 
libraries.  See  Example  4(d). 


while 

(ti  < 

ti 

( ti 

tl  +  dt; 

t2 

=  1.0  - 

tl 

; 

t5 

=  W*tl* 

tl* 

t2; 

t3 

=  W*tl* 

t2* 

t2; 

j 

=  jl*tl 

+ 

j2*t2 

+  t3*j3  + 

j5*t5; 

i 

=  il*tl 

+ 

i2*t2 

+  t3*i3  + 

i5*t5; 

LineTo  ( j , 

} 

i) 

Example  3:  Partitioning  the  equation 
shown  in  Example  2 


Dr.  Dobb 's Journal,  August  1990 


BICUBIC  SPLINES 


( continued  from  page  53) 

In  this  case,  the  object  module  for 
the  function  _Spline  is  stored  in  the  file 
called  “spline. c.o.”  ff-load  searches  this 
file  for  the  symbolic  name  __Spline.  If  it 
finds  the  name,  it  loads  the  associated 
binary  code,  ff-load  then  searches  the 
libraries  for  any  unsatisfied  symbolic 
references,  which  may  have  occurred 
within  the  code,  and  loads  them  as 
well.  For  example,  if  you  use  the  C  sqrt 
function,  you  must  tell  Allegro  CL  which 
library  to  look  in  for  the  function.  In 


other  words,  ff-load  links  and  loads  the 
routines  identified  in  the  :entry-names 
list,  using  the  libraries  in  the  .libraries 
list.  If  you  wish  to  load  more  C  func¬ 
tions,  add  them  to  the  .-entry-names 
list,  ff-load  is  a  time-consuming  func¬ 
tion,  so  you  should  call  it  as  infre¬ 
quently  as  possible. 

Binding  the  C  to  Lisp 

Once  you’ve  loaded  JSpline  into  your 
environment,  the  function’s  code  re¬ 
sides  in  the  dynamic  memory  of  your 


machine.  To  use  the  function,  you  must 
establish  a  symbolic  reference  to  its 
code  by  binding  it.  In  this  case,  the 
symbolic  reference  Mac_Spline  is  bound 
to  the  C  symbol  __Spline. 

In  Allegro  Lisp  you  can  bind  a  C 
function  in  two  ways.  The  first  method 
uses  deffcfun.  _Spline  has  eight  pa¬ 
rameters:  iO ,  jO,  and  so  forth.  Each  of 
the  parameters  is  an  integer  and  must 
be  declared  as  such.  The  flag  : novalue 
indicates  that  the  routine  produces  only 
a  side  effect;  the  routine  does  not  re¬ 
turn  a  value.  Types  for  both  input  and 
output  variables  are  declared  in  this 
manner.  Example  5(a)  demonstrates  this 
method. 

Though  deffcfun  is  a  more  simple 
function,  the  binding  is  lost  if  you  build 
a  stand-alone  application.  Most  of  the 
C  variable  types,  such  as  long ,  char, 
integer,  and  word  are  available  using 
deffcfun,  but  if  you  want  to  pass  a  list 
from  Lisp  or  a  structure  from  C,  you  are 
on  your  own.  Good  luck! 

The  second  and  preferred  method 
of  binding  a  C  function  uses  ff-look-up- 
entry,  ff-call,  and  multiple-value-hind 
to  bind  the  physical  entry  point  to  a 
Lisp  symbol.  This  method  can  be  used 
for  any  MPW  C  relocatable  object  code, 
not  just  for  C  functions.  In  other  words, 
you  could  even  bind  assembly  language 


(a) 

(require  'FF) 

(b) 

(load  "<pathname>:FF.fasl") 

(c) 

(def-logical-pathname  "CLIB;" 

"<pathname> : MPW : CLibrary " ) 

<d) 

(ff-load  "<pathname>: spline. c.o 

" 

: entry-names 

(list  "  Spline"  ) 

: libraries 

(list  "CLIB; StdCLib .o" 

"CLIB; CRuntime .0"  "CLIB; CInterf ace .0" 

"CLIB;math.o" 

"CLIB;CSANElib.o") ) 

Example  4:  Loading  the  C  routine 
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or  Pascal  code  by  using  this  method. 
This  method  is  a  hardware-dependent 
solution,  because  you  must  represent 


the  binding  in  terms  of  the  physical 
size  and  order  of  the  machine’s  stack. 
In  the  case  of  the  Mac  II,  parameters 


(a) 

(deffcfun  (Mac_Spline  "_Spline") 

(integer  integer  integer  integer  integer  integer 

integer  integer)  : novalue) 

(b) 

(defun  Mac  Spline  (a  b  c  d  e  f  g  h) 

(multiple-value-bind  (entry  a5)  (ff-lookup-entry  "_Spline") 

(ff-call  entry 

:a5  a5  :long  h  :long  g  :long  f  :long  e  :long  d  :long  c  :long  b  :long  a  rnovalue))) 

(c) 

(Mac  Spline  3  4  120  140  300  260  490  600) 

Example  5:  Binding  C  to  Lisp 


are  stored  in  reverse  order  on  the  stack. 
The  foreign  function  call  must  push 
the  parameters  onto  the  stack  in  re¬ 
verse  order. 

The  function  ff-lookup-entry  finds  the 
physical  address  of  the  entry  point  for 
the  _Spline  routine  and  the  location  of 
the  register  to  be  used  when  the  rou¬ 
tine  runs.  Because  this  function  returns 
two  values,  you  must  use  the  some- 

These  functions  allow 
you  to  link  C  with  Lisp 
for  accessing  physical 
devices  and  improving 
the  computational 
performance  of  your 
Lisp  environment 


what  esoteric  Common  Lisp  function 
multiple-value-bind  to  assign  these  val¬ 
ues  to  the  local  variables  entry  and  a5. 
The  function  ff-call  then  executes  the 
code  stored  at  the  physical  address  speci¬ 
fied  by  entry,  using  register  a5 .  Notice 
that  the  parameters  in  ff-call  are  re¬ 
versed  from  the  declaration  of 
Mac_Spline,  as  shown  in  Example  5(b). 

At  this  point,  Lisp  can  call  your  C 
routine,  _  Spline,  through  Mac_Spline. 
If  you  typed  the  following  example 
into  the  Listener  window,  a  curve  would 
be  drawn  between  the  points  (@@  120 
140)  and  (@@  300  260).  The  control 
points  for  the  curve  are  (@@  3  4)  and 
(®@  490  350).  The  result  is  shown  in 
Example  5(c). 

Mac_Spline  might  serve  as  an  ade¬ 
quate  level  of  representation  for  some 
problems,  but  in  the  case  of  the  spline, 
a  higher  level  of  representation  is 
needed. 

The  High-Level  Lisp  Functions 

The  Mac_Spline  function  draws  a  spline 
segment  in  the  current  window.  Be¬ 
cause  the  user  probably  wants  to  com¬ 
bine  several  spline  segments  into  a  con¬ 
tinuous  curve,  a  high-level  function  Do- 
Spline  must  be  used  instead.  Do-Spline 
is  a  tail-recursive  function,  and  its  argu¬ 
ment  is  a  list  that  contains  an  arbitrary 
number  of  points.  In  other  words,  Do- 
Spline  draws  a  spline  based  on  the  first 
four  points,  then  the  next  four  points, 
and  so  on,  until  only  three  points  re¬ 
main  in  the  list. 
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(continued  from  page  56) 

In  this  example,  Do_Spline  draws 
two  spline  segments  connected  at  the 
point  ( @@  300  260).  See  Example  6. 
The  first  spline  segment  is  identical  to 
the  spline  segment  drawn  in  the  previ¬ 
ous  example.  The  second  spline  seg¬ 
ment  is  a  curve  between  the  points 
(m  300  260)  and  ( @@  490  350).  The 
two  curves  are  continuous  at  (@@  300 
260).  A  few  problems  still  remain.  First, 

“Splines”  are 
graphic  elements 
that  are  used  to 
draw  objects 
containing  curves 


Do_Spline  draws  the  curve  in  your  Lis¬ 
tener  window.  You  probably  don’t  want 
to  draw  the  curve  over  the  text  in  the 
Listener  window.  Instead,  you’d  like 
to  select  the  window  in  which  the  curve 
will  be  drawn.  It’s  also  preferable  to 
invoke  the  function  by  using  the  points 
themselves,  rather  than  by  using  a  list 
that  contains  the  points.  The  highest- 
level  Lisp  function  SPLINE  provides 
these  capabilities: 

(SPLINE  window  pO.  .  .  .  pN) 

SPLINE  uses  the  Allegro  CL  object 
function  with-port  to  select  the  graph¬ 
ics  port  in  which  the  spline  will  be 
drawn.  It  then  calls  Do-Spline  to  actu¬ 
ally  draw  the  spline.  As  a  result,  the 
SPLINE  function  can  be  called  with  any 
number  of  points  and  targeted  to  any 
window.  This  function  could  be  in¬ 
stanced  in  a  display  list,  referenced  from 
a  menu,  and  otherwise  integrated  into 
a  graphics  package. 

General  Usage 

This  spline  function  can  be  modified 
and  used  as  a  template  for  facilitating 
general  connectivity  between  Lisp  and 
C,  or  for  writing  similar  C  functions  for 
use  by  Lisp.  The  Allegro  CL  Foreign 
Function  Interface  includes  six  func¬ 
tions  to  support  this  effort:  ff-load , 
deffcfim ,  deffpfun ,  ff-call,  ff-lookup- 


(Do-Spline  (list  (@@  3  4)  ( @ @  120  140) 

(00  300  260)  (00  490  350)  (00  25  30))) 


Example  6:  Drawing  spline  segments 
with  Do_Spline 
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entry ,  and  dispose-ffenv. 

ff-load  loads  any  MPW  C  object  file 
and  can  be  used  to  load  assembly  or 
Pascal  code,  as  well  as  C  code.  It  re¬ 
turns  a  foreign  function  environment 
that  consists  of  code  segments,  a  jump 
table,  a  static  data  area,  and  a  set  of 
active  entry  point  names.  It  also  re¬ 
moves  dead  code  so  that  the  environ¬ 
ment  includes  only  the  code  and  the 
data  that  can  be  reached  from  the  ac¬ 
tive  entry  points. 

deffcfun  and  deffpfun  define  func¬ 
tions  that  coerce  and  type-check  argu¬ 
ments  before  calling  the  foreign  func¬ 
tion.  deffcfun  is  used  for  C  and  deffpfun 
for  Pascal. 

ff-call  transfers  control  to  the  loaded 
object  code  and  passes  arguments  ac¬ 
cording  to  the  type-keyword/argument 
pairs.  Possible  type-keywords  are  .■ word , 
dong,  ptr,  the  data  registers  :d0  to  :d7, 
and  the  address  registers  .aO  to  :a5.  It 
is  a  low-level  function  that  is  faster 
than  deffcfun  and  deffpfun ,  because  it 
does  not  type-check  or  coerce  argu¬ 
ments.  Its  return  values  are  indicated 


by  similar  keywords  .-word,  dong,  ptr, 
:d0  to  :d7,  :a0  to  :a4,  and  the  empty 
value  :novalue. 

ff-lookup-entry  returns  two  values  that 
describe  the  entry  point.  The  first  value 
is  a  pointer  to  the  entry  point.  The 
second  value  is  the  ,  a5  address  register 
pointer  for  the  environment  where  the 
entry  point  was  found,  ff-look-up  re¬ 
turns  NIL  if  the  specified  entry-point 
name  doesn’t  exist.  If  the  entry-point 
name  exists  in  more  than  one  environ¬ 
ment,  the  function  returns  an  unde¬ 
fined  environment. 

dispose-ffenv  unloads  the  foreign  func¬ 
tion  and  frees  up  the  memory  space 
that  was  allocated  for  your  functions. 

These  six  functions  are  the  tools  that 
allow  you  to  link  C  with  Lisp.  Together 
they  provide  a  mechanism  for  access¬ 
ing  physical  devices  and  for  improving 
the  computational  performance  of  your 
Lisp  environment. 
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Extending 

printfQ 

Taking  advantage  of  variable  argument  lists  in  C 


Jim  Mischel 


While  writing  my  first  serious 
financial  program  in  C  (I’d 
previously  used  the  lan¬ 
guage  only  for  utilities),  I 
was  distressed  by  the  lack 
of  suitable  output  formatting  —  specifi¬ 
cally,  comma-separated  numbers  with 
trailing  signs.  After  working  with  Cobol 
financial  applications  several  years,  I  ex¬ 
pected  such  niceties  from  any  language. 

Faced  with  this  shortcoming,  I  im¬ 
mediately  began  working  on  a  func¬ 
tion  that  provided  Cobol-like  output 
formatting  using  Cobol  edit  picture 
strings,  and  so  on.  The  output  function 
worked  well,  but  was  awkward  to  use. 
I  wanted  an  easy-to-use  function  such 
as  printfi  )  that  would  allow  me  to 
output  formatted  numbers  as  well  as 
all  the  other  standard  printfi  )  types.  I 
posed  this  problem  to  several  C  pro¬ 
grammers  and  got  a  variety  of  answers. 
The  most  common  answer  was,  “buy 
the  runtime  library  code  and  modify 
printfi )."  I  agreed  that  this  was  prob¬ 
ably  the  best  solution  for  my  particular 
situation;  nevertheless  it  would  have 
been  implementation-specific,  expen¬ 
sive  (Turbo  C  library  source  code  costs 
$250),  and  no  solution  at  all  for  compil¬ 
ers  for  which  the  runtime  library  source 
code  is  not  available. 

The  second  most  common  reply  was, 
“write  your  own  printfi ).”  I  under- 


Jim  is  a  former  financial  systems  pro¬ 
grammer  and  data  processing  consul¬ 
tant.  He  can  be  reached  at  13610  N. 
Scottsdale Rd.,  Suite  10-  251,  Scottsdale, 
AZ  85254  ( CompuServe:  7371 7, 1355). 


stood  that  this  is  a  common  pastime 
among  bored  computer  science  majors 
and  back  room  hackers,  but  I  had  nei¬ 
ther  the  time  nor  the  desire  to  reinvent 
the  wheel  in  order  to  make  a  minor 
engineering  change. 

Finally,  one  programmer  I  spoke  with 
suggested  that  I  write  a  front  end  to 
printfi  )  and  use  this  function  to  pre¬ 
scan  the  argument  list,  handling  the 
special  formats  before  passing  the  ar¬ 
guments  to  printfi  ). 

Variable  Arguments 

One  of  the  niceties  C  offers  is  the  ability 
to  write  functions  that  accept  a  variable 


number  of  arguments.  The  standard  func¬ 
tions  printfi  )  and  scanfi  )  are  the  pri¬ 
mary  examples.  Normally  these  func¬ 
tions  have  a  fixed  minimum  number 
of  parameters  and  a  variable  number 
of  arguments,  the  number  of  which  is 
usually  specified  either  explicitly  or  im¬ 
plicitly  by  the  fixed  arguments. 

There  are  actually  two  types  of  func¬ 
tions  that  accept  a  variable  number  of 
arguments.  The  way  these  work  is  best 
described  by  examining  the  prototypes 
for  the  two  types  of  functions.  The 
functions  printfi  )  and  vprintfi  ),  de¬ 
fined  by  the  prototypes  shown  in  Ex¬ 
ample  1,  perform  almost  the  same  func¬ 
tion.  The  only  difference  is  how  they 
access  arguments  passed  to  them: 
printfi )  expects  an  unknown  number 
of  arguments  to  follow  the  format  string, 
and  vprintfi  )  is  passed  a  pointer  to  a 
contiguous  block  of  memory  that  con¬ 
tains  the  number  of  arguments  speci¬ 
fied  in  the  format  string. 

The  arguments  to  printfi  )  are  read 
from  the  stack  after  being  pushed  in 
the  function  call,  vprintfi )  reads  the 
arguments  from  the  block  of  memory 
to  which  the  ap  variable  points.  On  the 
Intel  80x86  processors,  these  functions 
work  almost  identically  —  the  only  dif¬ 
ference  is  that  printfi  )  must  first  deter¬ 
mine  where  the  block  of  memoiy  starts, 
which  just  happens  to  be  the  address 
contained  in  the  SS.  SP  registers.  Mem¬ 
ory  maps  for  these  function  calls  are 
shown  in  Figure  1 . 

The  ANSI  standard  for  the  C  lan¬ 
guage  calls  for  a  standard  header  file, 
( continued  on  page  63) 
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( continued  from  page  60) 
stdarg.h,  that  defines  the  typedef  va_list 
and  the  functionality  of  the  macros 
va_start,  va_arg,  and  va_end.  These 
macros  are  used  in  functions  that  ac¬ 
cept  a  variable  number  of  arguments. 
In  Turbo  C,  the  content  of  this  header 
file,  shown  in  Example  2,  makes  me 
wonder  if  “  . . .  ”  is  a  valid  variable 
name. 

The  vajstart  macro  stores  initial  con¬ 
text  information  in  the  variable  desig¬ 
nated  by  the  pointer  ap.  parmN  is  the 
name  of  the  last  argument  that  you 
declare.  parmN  must  not  be  an  array 
type,  function  type,  type  float,  or  an 
integer  type  that  is  changed  when  pro¬ 
moted  (that  is,  char).  This  macro  must 
be  invoked  before  the  initial  va_arg 
macro  is  used. 

The  va_arg  macro  returns  the  value 
of  the  argument  of  type  type  that  is 
pointed  to  by  the  pointer  ap.  It  then 
increments  the  pointer  ap  to  the  next 
argument. 

The  va_end  macro  is  used  to  per¬ 
form  the  cleanup  operations  required 
before  the  function  can  return.  Although 
this  macro  does  nothing  in  Turbo  C, 
some  implementations  may  require  it, 
so  you  might  want  to  include  it  in  the 
interest  of  portability. 


comma-separated  number  with  optional 
leading  or  trailing  sign.  Field  output 
width,  precision,  and  justification  can 


also  be  specified  as  in  the  other printf( ) 
formats.  Default  width,  precision,  and 
size,  and  a  full  explanation  of  the  ef- 


int  printf  (const  char  *format,  ...); 

int  vprintf  (const  char  *format,  va_list  ap) ; 


Example  1:  The  functions  printf(  )  and  vprintf(  )  are  defined  by  these 
prototypes. 


typedef  void  *va  list; 

♦define  va  start (ap,  parmN) 

(ap  =  . . .) 

♦define  va  arg(ap,  type) 

(‘((type  *)  (ap) )  ++) 

♦define  va_end(ap) 

Example  2:  Contents  of  the  Turbo  C  header file 


The  %m  Format  Type 

The  %m  format  that  I  added  to  printfi  ) 
and  associated  functions  outputs  a 


struct  Person  { 
char  *Name; 
int  Age; 

}  Jim = {"JimMischel",  29}; 

(a)  printf  ("%s  is  %d  years  oldAn", 
Jim. Name,  Jim.Age); 


Jim. Age 


Jim. Name 


&(format  string) 
return  address 


(b)  vprintf  f%s  is  %d  years  oldAn",  &Jim) ; 


&Jim 


&(format  string) 


return  address 


Figure  1:  Stack  contents  for  printfC  ) 
and  vprintf(  )  calls  that  output  the 
information  contained  in  the  Person 
structure. 
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fects  of  flag  characters,  are  shown  in 
Table  1. 

The  first  major  stumbling  block  was 
redirecting  printf( )  and  associated  func¬ 
tion  calls  so  that  they  could  take  advan¬ 
tage  of  my  new  output  format.  Fortu¬ 
nately  the  C  preprocessor  came  to  the 
rescue  with  macros  that  did  the  redi¬ 
rection  for  me. 

These  macros  simply  change  any 
printf( )  reference  to  AltPrintfJ ),  and 
iprintfC )  to  AltVprintfC ),  and  so  forth. 
Listing  One  (page  120),  which  shows 
mfmt.h,  the  header  file  that  contains 
these  macros,  must  be  included  AFTER 
stdio.h  in  any  program  that  uses  this 
new  format. 

The  Alt ..  .  functions  simply  set  up 
the  argument  pointer,  call  the  Format- 
ter( )  function  to  handle  the  %m  for¬ 
mats,  and  then  call  the  appropriate  rou¬ 
tine  to  handle  the  rest  of  the  print  for¬ 
matting  using  the  new  format  string  and 
argument  list. 

Listing  Two  (mfmt.c,  page  120)  con¬ 
tains  the  code  that  performs  the  num¬ 
ber  formatting  and  associated  functions. 
This  code  can  be  broken  down  logi¬ 
cally  into  two  sections:  The  alternate 
entry  functions  lAltPrintf  AltFprintf 
AltSprintf  AltVprintf  AltVfprintf, 
AltVsprintJ ),  and  Formatted )  and  as¬ 
sociated  functions. 

The  alternate  entry  functions  pro¬ 
vide  a  path  between  the  application 
program  and  the  Formatted ) function. 
The  alternate  entry  functions  intercept 
the  arguments,  set  up  a  new  argument 
area  if  necessary,  and  produce  the  final 
output  after  the  Formatter f )  function 
has  handled  any  %m  formats.  These 
functions  are  never  directly  referenced 
in  the  source  code.  Instead,  they  are 
addressed  through  the  redirection  mac¬ 


ros  provided  in  mfmt.h. 

AltVprintf,  AltVfprintf,  and  AltVsprintf 
call  the  InitBlock( )  function  to  allocate 
a  temporary  memory  buffer  for  the  new 
argument  list.  This  new  argument  area 
is  necessary  because  the  calling  pro¬ 
gram’s  argument  block  cannot  be  modi¬ 
fied  without  side  effects.  The  other  three 
functions  do  not  require  this  tempo- 

I  wanted  an 
easy-to-use  function 
such  as  printf( )  that 
would  allow  me  to 
output  formatted 
numbers  as  well  as  all 
the  other  standard 
printfO  types 


rary  block  because  their  arguments  are 
passed  on  the  stack  —  changing  them 
will  not  affect  the  calling  program. 

All  of  the  alternate  functions  call  the 
FreeBlock( ^function  before  exiting.  This 
routine  frees  the  temporary  argument 
area  and  the  memory  allocated  by  the 
new  format  string  (f). 

The  heart  of  the  mfmt  module  is  the 
Formatter J )  function.  After  allocating 
the  memory  for  the  new  format  string, 
this  function  simply  copies  the  old  for¬ 
mat  string  to  the  new  format  string, 
replacing  all  %m  formats  with  the  for- 


Flag 

How  it  affects  output 

_ 

Left-justifies  the  format 

+ 

Generates  a  plus  sign  for  signed  values  that  are  positive. 

blank 

Generates  a  space  for  signed  values  that  are  positive. 

# 

Generates  a  trailing  sign  if  required  by  sign  or  one  of  the  other 

flags  (+  or  blank). 

0 

Ignored 

Width 

Same  as  for  “f”  format 

Precision 

Same  as  for  “f”  format  with  the  exception  that  default  precision  is 

2,  rather  than  6  decimal  places. 

Input-size  modifier 

;  i 

How  arg  is  interpreted 

none 

arg  is  interpreted  as  a  float 

i 

arg  is  interpreted  as  a  double 

L 

arg  is  interpreted  as  a  long  double 

Turbo  C  departs  from  the  ANSI  standard  in 

how  the  size  modifiers  are  interpreted.  The 

standard  specifies  that  "f”  is  a  double  and 

“Lf”  is  a  long  double.  There  is  no  “If”  format. 

Table  1:  The  behavior  of  the  new  “%m”  output format for  printff  )  and  related 
functions. 
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matted  number.  Any  time  a  %  symbol 
is  found  in  the  format  string,  it  calls  the 
ParseFormat( )  function  for  future  pro¬ 
cessing.  Upon  exiting  this  function,  t 
points  to  the  new  format  string  and  the 
arguments  are  correctly  placed  in  either 
NewBlock  or  on  the  stack,  depending 
on  which  alternate  entry  function  was 
called. 

When  Formatted )  finds  a  %  charac¬ 
ter  in  the  format  string,  it  calls  the 
ParseFormat( )  function  to  perform  fur¬ 
ther  processing.  This  function  picks  up 
and  saves  the  flags,  width,  precision, 
and  size  specifiers,  and  copies  the  ar¬ 
guments  to  the  modified  argument 
block. 

The  operation  of  this  function  and 
the  ParseFlags,  ParseWidth,  ParsePre- 
cision,  and  ParseSize  functions  are 
straightforward.  Only  a  couple  of  items 
warrant  mentioning. 

The  ParseFlags  function  uses  a  bit¬ 
encoding  technique  for  reporting  which 
flags  are  specified.  Each  of  the  four 
possible  flags  is  assigned  a  power  of 
2.  If  that  particular  bit  is  set,  it  indicates 
the  corresponding  flag  was  given  in 
the  format  string. 

The  ParseWidth  and  ParsePrecision 
functions  modify  two  variables  each:  a 
number  and  a  flag.  The  flags  WidthFlag 
and  PrecisionFlag  specify  which  kind 
of  width  or  precision  was  given,  and  the 
number  Width  and  Precision  specify 
the  field  width  or  precision,  respectively. 

ParseSize  modifies  the  Size  variable, 
which  reports  if  any  of  the  valid  input 
size  modifiers  were  specified. 

The  ParseType  function  determines 
which  conversion  type  is  specified  and 
acts  accordingly.  Unless  a  %m  conver¬ 
sion  is  specified,  all  flag,  width,  preci¬ 
sion,  and  size  variables  are  ignored, 
the  arguments  are  copied  directly,  and 
no  modification  is  done  to  the  format 
string.  Only  when  the  %m  conversion 
is  given  does  any  further  processing 
occur. 

Throughout  the  Parse .  .  .  functions, 

I  used  the  AddBlockArg  macro  to  copy 
arguments  from  one  parameter  block 
to  the  other,  incrementing  the  New- 
ArgPtr  variable  in  the  process.  This 
macro  references  the  va_arg  macro  to 
retrieve  the  next  argument  from  the 
list.  The  RemoveBlockArg  macro  is  used 
to  decrement  the  NewArgPtr  variable 
so  that  it  points  to  the  previous  argu¬ 
ment,  effectively  removing  that  argu¬ 
ment  from  the  argument  list. 

When  a  %m  conversion  is  identified 
by  ParseType( ),  the  mFormat( )  func¬ 
tion  is  called  to  format  the  number  into 
the  modified  format  string,  and  to  clean 
up  stray  arguments  from  the  argument 
list.  mFormatJ )  removes  any  width  or 
precision  variables  from  the  argument 
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list,  determines  the  sign  of  the  number, 
and  calls  dtoa( )  (Double  to  ASCII)  to 
format  the  number  into  the  temporary 
string  variable  Num.  When  dtoa( )  re¬ 
turns,  mFormat(  )  places  the  sign,  justi¬ 
fies  the  number,  and  adds  the  formatted 
result  to  the  modified  format  string  t. 

dtoa( )  is  a  fairly  simple  recursive 
number  formatter.  It  handles  precision 
and  comma-  separating,  but  leaves  sign 
placement  and  justification  to  the  fol¬ 
lowing  routines.  dtoa( )  will  not  cor- 

There  are  actually  two 
types  of  functions  that 
accept  a  variable 
number  of  arguments 


rectly  handle  a  negative  number;  mFor- 
mat( )  must  determine  the  proper  sign 
and  pass  the  absolute  value  of  the  num¬ 
ber  to  dtoa( ). 

Some  Notes 

The  mfmt  code  is  not  reentrant.  I  had 
originally  planned  on  making  it  reen¬ 
trant,  but  soon  found  out  why  print/ 
and  others  like  it  are  not  reentrant  in 
most  implementations:  Too  much  book¬ 
keeping  going  on!  As  a  general  rule, 
the  use  of  global  variables  is  not  good 
programming  practice.  The  code  could 
be  made  reentrant  by  using  double 
indirection  rather  than  static  variables, 
but  this  would  complicate  the  code 
and  make  it  much  slower  than  it  al¬ 
ready  is. 

These  functions  are-  slower  than  the 
standard  printf( )  functions.  In  effect, 
both  the  format  string  and  the  argu¬ 
ment  list  are  scanned  twice,  and  plenty 
of  time  is  spent  allocating  memory  and 
shuffling  things  around  so  that  the  for¬ 
matting  will  work  correctly. 

The  functions  in  the  mfmt  module 
are  a  safe  and  portable  way  of  modify¬ 
ing  the  behavior  of  the  printf( )  family 
of  functions.  However,  when  economic 
factors  and  the  need  for  speed  warrant 
it,  (and  portability  is  not  a  consideration) 
the  preferred  solution  is  to  obtain  the 
runtime  library  code  and  directly  mod¬ 
ify  the  printf( )  functions. 
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Parallel 

Extensions  to  C 

Programming  parallel  networks 


Graham  K.  Ellis 


All  extensions  to  C  compilers  for 
transputers  are  based  on  the 
Occam  concurrency  model. 
However,  there  are  two  differ¬ 
ent  approaches  for  extending 
C  for  concurrency;  one  that  adds  key¬ 
words  to  the  C  language  definition, 
and  another  that  implements  parallel¬ 
ism  using  library  routines.  Arguments 
can  be  made  for  either  case.  Bjarne 
Stroustrup,  for  example,  believes  that 
concurrency  should  be  implemented 
using  libraries  because  the  library  ap¬ 
proach  provides  the  flexibility  required 
to  implement  concurrency  at  a  lower 
level,  closer  to  the  machine  (Stevens, 
1989).  On  the  other  hand,  Narain  Ge- 
hani,  et  al.  (of  Concurrent  C  fame),  hold 
that  extending  C  (and  C++)  by  adding 
keywords  is  the  best  solution  because 
extensions  can  more  adequately  pro¬ 
vide  and  implement  the  necessary  con¬ 
currency  functions  across  a  wide  range 
of  platforms  (Gehani  and  Roome). 

My  subjective  (and  completely  un¬ 
supported)  opinion  is  a  politically  safe 
“somewhere  in  between.”  I  like  the 
use  of  C  language  extensions  for  read¬ 
ability,  but  I  think  libraries  allow  more 
flexibility  for  different  parallel  architec¬ 
tures  (important  portability  issues  not- 


Ken  is  a  graduate  student  working  on 
parallel  processing  and  controls  appli¬ 
cations  in  the  Smart  Materials  and  Struc¬ 
tures  Laboratory  at  Virginia  Tech.  He 
can  be  contacted  at  the  Mechanical 
Engineering  Department,  Randolph 
Hall,  Virginia  Tech,  Blacksburg,  VA 
24061. 


withstanding).  But  because  most  of  the 
programming  I  do  is  for  small  real-time 
control  and  signal  processing  applica¬ 
tions,  what’s  important  to  me  isn’t  nec¬ 
essarily  important  to  programmers  work¬ 
ing  on  large  programs. 

On  a  day-to-day  basis  I  use  Logical 
Systems’  C  (LSC)  compiler,  an  ANSI  C 
compiler  that  implements  the  transputer 
parallelism  using  library  calls.  The 
transputer-specific  library  functions  can 
be  grouped  into  seven  categories:  chan¬ 
nel  communication,  channel  status  test¬ 
ing,  transputer  concurrency  (CSP 
model),  transputer  concurrency  (fork/ 
join  model),  transputer  semaphore  sup¬ 
port,  transputer  timing  and  scheduling, 


and  miscellaneous  routines  (see  Table 
1).  Because  of  space  constraints,  I’ll 
discuss  only  the  channel,  channel  status, 
and  CSP  concurrency  functions. 

Library  Functions 

Channel  communication  is  implemented 
by  first  allocating  a  channel,  then  read¬ 
ing  and/or  writing  from  process  to  pro¬ 
cess.  ChanAllocC )  is  used  to  allocate 
an  internal  channel  by  returning  a 
pointer  to  the  allocated  channel.  For 
channels  assigned  to  actual  hardware 
links,  a  pointer  assignment  to  the  hard¬ 
ware  address  is  used  instead  of  Chan- 
Alloc( ).  These  and  other  transputer  spe¬ 
cifics  are  defined  in  the  conc.h  include 
file.  When  an  allocated  channel  is  no 
longer  needed,  memory  can  be  freed 
using  ChanFree( ).  Code  showing  ba¬ 
sic  channel  usage  is  listed  in  Figure  1. 

There  are  three  pairs  of  functions  for 
channel  communication.  Chanln( )/ 
ChanOut( )  transfer  an  arbitrary  num¬ 
ber  of  bytes  of  data;  Chanlnlnt(  )/Chan- 
OutInt( )  transfer  a  single  integer;  and 
ChanlnCharJ  )/  ChanOutCharp  )  trans¬ 
fer  a  character.  There  are  also  channel 
routines  for  fault-tolerant  applications 
that  abort  after  a  user-specified  time¬ 
out  period  or  by  communication  on 
another  channel. 

The  alternative  functions  operate  on 
lists  of  channels.  ProcAlt( )  and  Proc- 
AltList( )  scan  a  list  for  inputs.  The  pro¬ 
gram  blocks  (waits)  until  one  channel 
is  ready  for  an  input  and  then  selects  a 
channel.  ProcSkipAlt( )  and  ProcSkip- 
AltList( )  scan  a  list  of  channels;  how¬ 
ever,  process  blocking  is  not  performed. 


70 


Dr.  Dobb’s Journal,  August  1990 

709 


PARALLEL  EXTENSIONS 


el  Communication 


Ghannel  Status 


Concurrency  (CSP  Model) 


ProcAlt 

ProcAltList 

ProcSkipAlt 

ProcSkipAltList 

ProcTimerList 

ProcTimerAltList 


ChanAlloc 

ChanFree 

Chanin 

ChanlnChanFail 

ChanlnChar 

Ghanlnlnt 

ChanlnTimeFail 

ChanOut 

ChanOutChanFail 

ChanOutChar 

ChanOutlnt 

ChanOutTimeFail 

ChanReset 


Concurrency  (Fork/'Join)  Timing  and  Scheduling 


PFork 

PForkHigh 

PForklnit 

PForkLow 

PHalt 

PJoin 

PRun 

PSetup 

PStop 


GetHiPriQ 

GetLoPriQ 

ProcAfter 

ProcCall 

ProcGetPriority 

ProcReschedule 

SetHiPriQ 

SetLoPriQ 

SetTime 

Time 


ProcAlloc 

ProcFree 

Proclnit 

ProcPar 

ProcParam 

ProcParList 

ProcPriPar 

ProcRun 

ProcRunHigh 

ProcRunLow 

ProcStop 

ProcToHigh 

ProcToLow 

ProcWait 


Miscellaneous 

BitCnt 

BitRevNBits 

BitRevWord 

Move2D 

Move2DNonZero 
Move2DZero 
restorefp 
_boot_chan_in 
boot  chan_out 
nodenumber 


Table  1:  Partial  list  of  LSC functions 


Figure  1:  Channel  communications 


Figure  2:  Multiplexer  using  the  channel  alternative 


(continued  from  page  70) 

If  no  channels  are  ready  for  input,  the 
function  returns  immediately.  ProcTi- 
merAlt(  land  ProcTimerAltList(  ) block 
the  current  process  until  one  of  the  chan¬ 
nels  is  ready  or  until  a  user-specified 
time  elapses.  An  example  of  the  alter¬ 
native  process  is  shown  in  Figure  2. 

I  like  the  use  of 
C  language  extensions 
for  readability, 
but  I  think 
libraries  allow  more 
flexibility  for  different 
parallel  architectures 

There  are  several  methods  for  run¬ 
ning  an  arbitrary  number  of  processes 
in  parallel  on  a  single  chip.  In  any  case, 
each  process  must  be  allocated  —  a 
stack  frame  must  be  built  for  each  pro¬ 
cess  and  memory  created  for  a  process 
structure.  ProcAlloc( )  performs  these 
tasks  by  returning  a  pointer  to  an  in¬ 
itialized  process  structure.  When  the 
allocated  processes  are  no  longer 
needed,  ProcFreeO  returns  the  allo¬ 
cated  memory  to  the  heap. 

Once  all  processes  have  been  allo¬ 
cated,  one  of  the  process  creation  func¬ 
tions  —  ProcRunO ,  ProcRunHigh( ), 
ProcRunLow( ),  ProcParf  ),  ProcPar- 
List( ),  and  ProcPriParf ) —  can  be  used. 
These  functions  take  process  pointers 
and  spawn  time-sliced  processes  ac¬ 
cording  to  the  function  used.  Code  for 
two  processes  is  shown  in  Figure  3. 

Concurrent  Sorting 

To  examine  the  routines  described 
above,  I  have  developed  a  simple 
ASCII  sort  of  a  string  of  characters.  The 
sort  is  implemented  on  a  pipeline  of 
parallel  processes  and  is  a  modified  ver¬ 
sion  of  the  sorting  example  in  the  In- 
mos  Transputer  Development  System  man¬ 
ual.  Single-  and  multiprocessor  imple¬ 
mentations  of  the  sorting  algorithm  are 
shown  in  Listings  Five  and  Six,  respec¬ 
tively.  The  two  programs  utilize  the  fol¬ 
lowing  files  (only  the  formats  of  the 
main  programs  differ):  Listing  One  (page 
124)  lists  proto.h,  Listing  Two  (page 
124)  mytypes.h,  Listing  Three  (page  124) 
multisort.nif,  and  Listing  Four  (page  124) 
buffers,  c. 


72 

710 


Dr.  Dobb’s  Journal,  August  1990 


PARALLEL  EXTENSIONS 


(continued  from  page  72) 

The  single-processor  implementation 
of  the  sorting  routine  (see  sort.c,  List¬ 
ing  Five,  page  124)  performs  the  ac¬ 
tions  in  Example  1.  In  the  schematic 
representation  of  this  sort  shown  in 
Figure  4,  the  circles  represent  parallel 
processes  and  the  lines  represent  the 
communication  channels.  Note  that  the 
data  flows  through  the  pipeline  in  sorted 
order.  As  a  result,  the  further  down  the 
pipeline  a  process  (or  processor)  is, 


the  lower  its  utilization.  This  is  accept¬ 
able  for  a  single-processor  implemen¬ 
tation,  but  it  is  a  waste  of  resources  in 
a  multiprocessor  implementation  be¬ 
cause  most  of  the  processors  would 
be  idle  most  of  the  time. 

Also  note  that  the  channel  inputs 
and  outputs  match.  For  each  byte  (or 
word  or  array)  output,  data  of  the  exact 
same  length  must  be  input.  If  the  length 
of  the  data  transfers  does  not  match, 
the  data  transfer  will  deadlock.  Since 


deadlock  is  probably  the  most  com¬ 
mon  programming  bug  that  occurs 
when  using  transputers,  extra  care  must 
be  taken  to  ensure  that  channel  I/O 
matches.  In  addition,  channel  commu¬ 
nication  must  be  decoupled  sufficiently 
to  ensure  that  processes  are  not  wait¬ 
ing  for  each  other  to  communicate  first. 

The  two-processor  version  (see  multi¬ 
sort. c,  Listing  Six,  page  126)  performs 
the  exact  same  sort,  but  the  organiza¬ 
tion  is  slightly  different.  In  this  case, 


Transputer  Architecture 


A  transputer  is  a  microprocessor  de¬ 
veloped  by  Inmos  and  designed  spe¬ 
cifically  for  Multiple  Instruction  Multi¬ 
ple  Data  (MIMD)  parallel-processing 
applications.  All  transputers  have  on- 
chip  memory  and  serial  links  for  con¬ 
necting  one  transputer  to  another. 
Transputers  come  in  several  flavors: 
16-bit,  16-bit  with  disk  control  logic, 
32-bit,  and  32-bit  with  an  on-chip  float¬ 
ing-point  unit.  The  current  genera¬ 
tion  of  transputers  has  4  Kbytes  of 
on-chip  RAM  and  four  bidirectional 
serial  links  that  can  operate  at  20,  10, 
or  5  Mbits/sec. 

In  addition,  transputers  have  a  mi- 
crocoded  scheduler  with  two  priority 
levels,  which  allows  concurrent  (time- 
sliced)  processes  to  share  a  proces¬ 
sor’s  time.  There  are  also  two  sets  of 
timers,  one  for  each  priority  level.  A 
block  diagram  of  the  Inmos  T800  float¬ 
ing-point  transputer  is  shown  in  Fig¬ 
ure  7.  A  T800  transputer  offers  ap¬ 
proximately  the  same  performance  as 
the  Intel  80386/80387  chip  combina¬ 
tion  at  around  half  the  cost  because 
you  buy  one  chip  instead  of  two. 

Transputer  Concurrency  Model 

The  transputer  concurrency  model  is 
based  on  C.A.R.  Hoare’s  “Communicat¬ 
ing  Sequential  Processes”  (CSP) 
(Hoare,  1978).  The  “native”  transputer 
language  Occam  (named  after  the  14th- 
century  philosopher  William  of 
Occam)  is  based  on  the  CSP  idea  of 
concurrency  and  communication  (May 
and  Taylor,  1984).  A  process  performs 
a  sequence  of  actions  and  then  termi¬ 
nates.  Concurrent  processes  can  be 
thought  of  as  multiple  black  boxes, 
each  of  which  has  its  own  internal 


state.  Communication  between  pro¬ 
cesses  is  performed  through  point-to- 
point  channels  (CHAN).  Each  chan¬ 
nel  provides  a  one-way  connection 
between  two  processes.  It  is  not  pos¬ 
sible  to  share  a  channel  between  more 
than  two  processes,  nor  is  there  shared 
memory  between  processes.  Informa¬ 
tion  is  updated  through  channel  com¬ 
munication,  thus  alleviating  the  need 
for  memory  locks  such  as  those  used 
on  shared  memory  multiprocessors. 
Communication  between  processes  is 
synchronous  and  unbuffered.  One  pro¬ 
cess  is  blocked  (descheduled)  until 
the  other  is  ready  to  communicate. 
When  both  the  sending  and  receiving 
processes  are  ready,  they  proceed. 

The  communication  channels  can 
be  virtual  channels  maintained  inter¬ 
nally  by  a  single  transputer,  or  they 
can  be  mapped  onto  one  of  the  hard¬ 
ware  links  for  true  parallel  processing 
applications.  The  transparent  nature 
of  virtual  and  physical  channel/link 
communication  enables  the  program¬ 
mer  to  develop  many  programs  on  a 
single  transputer  and,  with  minor  modi¬ 
fication,  map  the  program  onto  a  net¬ 
work  of  processors. 

Another  channel  construct  is  the 
alternative.  The  alternative  (ALT)  con¬ 
struct  provides  a  method  of  choosing 
the  first  available  channel  from  a  set 
of  channels  and  is  implemented  on 
the  input  side  of  channel  communi¬ 
cation.  ALT  is  often  used  to  control 
the  flow  of  data  through  a  network. 

To  generate  concurrent  (or  virtual 
concurrent)  processes,  a  parallel  con¬ 
struct  (PAR)  is  used.  As  previously 
mentioned,  parallel  processes  can  only 
communicate  through  channels.  The 


transputer  supports  high  priority  (used 
for  communication  processes)  and  low 
priority  (for  computation  processes). 
While  this  may  seem  backward,  it  is 
important  in  a  multiprocessor  environ¬ 
ment  to  keep  as  many  processors  as 
busy  as  possible  by  providing  them 
data  to  process.  Low-priority  processes 
get  time-sliced  approximately  every 
I  millisecond.  High-priority  processes 
do  not  get  time-sliced.  They  will,  how¬ 
ever,  deschedule  while  waiting  for 
channel  communication . 

Transputer  Environments 

Transputer  networks  generally  con¬ 
sist  of  a  root  transputer  that  interfaces 
directly  with  a  host  such  as  a  PC, 
Macintosh,  or  Sun.  All  other  transputers 
in  the  network  are  connected  in  some 
fashion  to  the  root  transputer  using 
the  built-in  serial  links.  Even  though 
these  network  nodes  may  reside  in 
the  host,  they  rely  on  the  host  only 
for  power  and  ground.  Only  the  root 
transputer  communicates  with  the  host 
computer. 

Typically,  the  root  transputer  is  con¬ 
nected  to  an  adapter  chip  that  con¬ 
verts  a  transputer  serial  link  to  a  bus 
interface.  The  host  runs  some  sort  of 
file  server  program  to  service  the 
transputers.  In  the  case  of  the  C  com¬ 
piler,  the  server  provides  access  to 
the  keyboard,  monitor,  and  disk  stor¬ 
age  of  the  host.  The  LSC  compiler  has 
the  hooks  in  its  library  so  that  the 
standard  C  library  functions  commu¬ 
nicate  correctly  with  the  host  server. 
However,  at  this  point  in  time,  only 
the  root  transputer  can  use  stdio  rou¬ 
tines  to  the  host  without  extra  pro¬ 
gramming  effort.  —  G.K.E. 
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Figure  3:  Two  parallel  processes  code  fragment 


Root  Transputer: 

SEQUENTIAL 

-  Read  in  line  of  text  and  store  in  character  buffer. 

-  Allocate  channels  and  processes. 

PARALLEL 

-  Send  out  a  character  at  a  time  to  the  first  pipe  process. 

-  In  256  parallel  pipe  processes:  read  in  a  character  then 

read  a  new  character,  forward  the  character  with  the 
lowest  ASCII  value. 

-  Read  in  one  character  at  a  time  from  last  pipe  buffer 
and  write  it  to  the  screen. 

-  Deallocate  channels  and  processes. 


Example  1:  Actions  performed  by  the  single-processor  implementation  of  the 
sorting  routine. 


Figure  4:  Single-processor  sort 


Root  Transputer 

Transputer  1 


Figure  5:  Two-transputer  sort 


(continued  from  page  74) 
the  root  processor  merely  reads  the 
character  string,  then  forwards  it  out  a 
hardware  link  to  the  next  processor. 

At  the  same  time,  the  sorted  data  com¬ 
ing  from  the  network  is  read  in  and 
displayed  a  character  at  a  time.  The 
block  diagram  of  this  is  shown  in  Figure 
5.  In  this  case,  a  rectangle  represents  a 
transputer  and  the  circles  represent  con¬ 
current  processes  (see  Example  2).  A 

I  have  written  the 
sorting  program  in  a 
somewhat  unusual 
manner:  The  code 
for  each  processor 
of  the  multitransputer 
version  of  the  sort 
is  identical 


method  for  mapping  the  program  from 
two  processors  onto  a  larger  transputer 
network  is  illustrated  in  Figure  6.  The 
only  differences  in  the  two-processor 
version  are  that  the  pipe  processes  are 
distributed  among  more  processors,  and 
some  of  the  channels  are  mapped  onto 
hardware  links  instead  of  using  inter¬ 
nally  allocated  channels. 

I’ve  written  the  sorting  program  in  a 
somewhat  unusual  manner:  The  code 
for  each  processor  of  the  multitransputer 
version  of  the  sort  is  identical.  Nor¬ 
mally,  I  would  write  a  unique  root 
transputer  program  and  then  another 
program  to  be  used  for  all  of  the  addi¬ 
tional  network  nodes.  However,  be¬ 
cause  I  have  only  two  processors,  I’ve 
set  up  the  program  to  determine  on 
which  node  the  code  is  running  and 
then  perform  the  appropriate  actions. 
The  __node_numberv ariable  is  supplied 
to  each  node  by  the  network  loader. 

To  modify  the  code  for  more  proces¬ 
sors,  forward  the  data  to  another  pro¬ 
cessor  with  more  sorting  processes  in¬ 
stead  of  having  Processor  1  above  re¬ 
turn  the  data  to  the  host.  The  last  pro¬ 
cessor  in  the  network  can  then  be  con¬ 
nected  back  to  one  of  the  other  root 
transputer  links. 

The  sorting  algorithm  uses  the 
source( ),  output( ),  and  pipe( )  func¬ 
tions,  which  are  the  same  for  every 
version  of  the  program.  Only  the  for- 
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mat  of  the  main  program  varies  from 
the  single-  to  multitransputer  case. 

Functions  run  in  parallel  require  a 
Process  pointer  parameter  as  the  first 
function  in  the  parameter  list.  This 
pointer  is  used  by  the  LSC  process  allo¬ 
cation  function.  Aside  from  its  appear¬ 
ance  as  the  first  variable  in  the  parame¬ 
ter  list,  its  use  is  completely  transparent 
to  the  programmer. 

•  source( )  takes  as  its  parameters  a 
pointer  to  an  output  channel  and  a 
pointer  to  the  character  buffer  where 
the  text  to  be  sorted  is  stored.  A  single 
character  at  a  time  is  output  down  the 
specified  channel.  When  an  ASCII  NULL 
is  encountered,  the  function  exits. 


Figure  6:  128-transputer  sort 


•  pipe(  )  takes  pointers  to  both  an  in¬ 
put  and  an  output  channel.  Two  char¬ 
acters  are  read  in,  and  the  one  with  the 
lowest  ASCII  value  is  forwarded  to  the 
next  pipe  process.  Then  a  new  charac¬ 
ter  is  read,  a  comparison  is  performed, 
and  the  character  with  the  lowest  ASCII 
value  is  forwarded.  When  a  NULL  is 
received,  the  stored  character  is  for¬ 
warded,  the  NULL  is  forwarded,  and 
the  function  exits. 


•  output( )  reads  a  character  at  a  time 
from  an  input  channel  and  displays  it 
using  the putchari  ) function.  The  func¬ 
tion  exits  when  a  NULL  is  received. 


In  the  single-processor  case,  each  time 
a  line  of  characters  is  sorted,  the  chan¬ 
nels  and  processes  are  allocated,  used, 
and  then  deallocated.  For  multipro¬ 
cessors,  only  the  root  node  allocates 
and  deallocates  each  time  through  the 
loop.  The  network  pipe  buffer  pro¬ 
cesses  are  allocated  once,  and  termi¬ 
nate  only  as  the  root  processor  exits  to 
the  host.  Actually,  the  network  nodes 
deadlock  due  to  lack  of  data  from  the 
root  node,  but  this  is  okay  as  long  as 
the  root  node  shuts  down  gracefully. 
This  implementation  is  used  to  keep 
the  network  programs  as  simple  as  pos¬ 
sible  and  to  circumvent  the  lack  of 
support  for  multiple  processes  on  the 
root  to  being  able  to  communicate  us¬ 
ing  the  stdio  stream. 

Conclusion 

This  article  provides  a  basic  idea  of 
how  you  can  take  advantage  of  the 
features  available  on  transputers  for 
building  parallel  processing  networks. 
The  ease  with  which  parallel  networks 
of  transputers  can  be  programmed  and 
expanded,  and  the  performance  achieved 
by  using  this  method,  enable  program¬ 
mers  to  use  transputers  to  solve  prob¬ 
lems  that  were  previously  relegated  to 
large  and  expensive  computing  re¬ 
sources. 


Dr.  Dobb’s Journal,  August  1990 


77 

713 


PARALLEL  EXTENSIONS 


Acknowledgements 

I  would  like  to  thank  the  NASA  Gradu¬ 
ate  Student  Researcher’s  Program  (NGT- 

Functions  run  in 
parallel  require  a 
Process  pointer 
parameter  as  the  first 
function  in  the 
parameter  list 


50392)  for  their  support,  and  Kirk  Bailey 
at  Logical  Systems  for  answering  my 
questions  about  the  compiler. 

References 

Hoare,  C.A.R.,  “Communicating  Sequen¬ 
tial  Processes,”  Communications  of  the 
ACM,  Vol.  21f  No.  8  (August),  pp.  666  - 
677,  1978. 

May,  David  and  Taylor,  Richard, 
“Occam  —  an  Overview,”  Microproc¬ 


essors  and  Microsystems,  Vol.  8,  no.  2 
(March),  pp.  73  -  79, 1984. 

Stevens,  Al,  “From  C  to  C++:  Inter¬ 
views  with  Dennis  Ritchie  &  Bjarne 
Stroustrup,”  Dr.  Dobb’s  C  Sourcebook, 
Vol.  14,  no.  159  (Winter),  pp.  9-17, 
1989. 

Gehani,  N.  H.  and  Roome,  W.  D., 


Concurrent  C,  Computer  Technology 
Research  Laboratory  Technical  Reports, 
Concurrent  C  Project,  AT&T  Bell  Labo¬ 
ratories,  Murray  Hill,  NJ  07974. 

Henderson,  Brian,  “Par.c  System  — 
a  C  Compiler  for  Transputers,”  Mailshot 
April  1990,  SERC/D7T  Transputer  In¬ 
itiative,  Rutherford  Appleton  Labora- 


Root  Transputer: 

SEQUENTIAL 

-  Read  in  line  of  text  and  store  in  character  buffer. 

-  Allocate  channels  and  processes. 

PARALLEL 

-  Send  out  a  character  at  a  time  to  the  first  buffer. 

-  Read  in  a  character  at  a  time  and  write  it  to  the  screen. 

-  Deallocate  channels  and  processes. 

Transputer  Node  1: 

SEQUENTIAL 

-  Allocate  channels  and  processes. 

PARALLEL 

-  Read  in  data  from  link  a  character  at  a  time,  sort,  forward  to 

next  pipe  process. 

-  In  254  parallel  pipe  processes:  read  in  a  character  then 

read  a  new  character,  forward  the  character  with  the 
lowest  ASCII  value. 

-  Read  in  data  from  pipe  process  sort,  forward  data  to 

root  transputer. 


Example  2:  Actions  performed  by  the  two-processor  implementation  of  the 
sorting  routine. 


78 

714 


Dr.  Dobb’s  Journal,  August  1990 


tory,  Chilton,  DIDCOT,  Oxon,  0X11 
OQX,  pp.  45-51. 

Logical  Systems  Transputer  Toolset 
(Version  89.1),  C  Library  Description, 
Logical  Systems,  P.O.  Box  1702, 
Corvalis,  OR  91359- 

Transputer  Development  System,  IN- 
MOS,  Ltd.,  Prentice-Hall,  New  York, 
1988. 

Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
online.  To  order  the  disk,  send  $14.95 
(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  the  DDJ listing  service  (415-364- 
8315)  and  through  the  DDJ  Forum  on 
CompuServe  (type  GO  DDJ). 

DDJ 

(Listings  begin  on  page  124.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  6. 


Figure  7:  T800 Jloating-point  transputer  block  diagram 


715 


Debugging 

Memory  Allocation  Errors 

Replacing  standard  C  functions  and  checking 
the  status  of  the  heap 


Lawrence  D.  Spencer 


It’s  10  a,m.,  and  you  are  working 
on  your  new  real  estate  analysis 
program,  HIGHRISE,  that’s  sched¬ 
uled  to  be  finished  tomorrow.  The 
high-powered  analysts  will  soon 
be  sitting  in  their  high-backed,  leather 
chairs,  clicking  on  your  high-rise  icon, 
eager  to  find  out  which  property  will 
drive  profits  still  higher.  However,  you’re 
feeling  pretty  low.  HIGHRISE  works 
great,  but  once  in  a  while  it  locks  up 
the  computer.  Usually,  this  happens 
after  about  a  half  hour  of  operation. 
Also,  what  about  the  time  HIGHRISE 
forecasted  a  profit  of  $17,546,321.97 
on  a  $ 1 ,000  investment?  You  never  could 
reproduce  the  problem,  so  it  was  prob¬ 
ably  a  fluke,  right?  “Please,  let  it  have 
been  a  hardware  error!” 

Of  course,  if  you  know  enough  C  to 
be  interested  in  this  article,  you  know 
that  there  is  a  99  percent  chance  that 
the  problem  is  related  to  memory  allo¬ 
cation.  Maybe  you  freed  a  pointer  that 
you  never  allocated.  Much  like  trying 
to  walk  down  stairs  that  have  not  been 
built  yet.  Maybe  you  allocated  memory 
but  never  freed  it.  A  slower,  agonizing 
death  by  asphyxiation. 

You  are  probably  thinking,  “If  I  know 
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puter  Consultants  Assoc.  He  can  be 
reached  at  10  N.  Main  St.,  West  Hart¬ 
ford,  CT 06107;  203-236-9209. 


enough  C  to  be  interested  in  this  arti¬ 
cle,  I  just  don’t  make  that  kind  of  mis¬ 
take.”  Don’t  be  so  sure.  About  half  the 
commercial  database  and  screen-han¬ 
dling  libraries  I  have  worked  with  fail 
to  free  all  the  memory  they  allocate, 
even  after  their  shutdown  functions 
have  been  called!  If  the  pros  can  make 
this  mistake,  so  can  we  all. 

The  only  way  to  find  HIGHRISE’s 
problem  is  to  identify  each  memory 
allocation,  make  sure  there  is  a  corre¬ 
sponding  free( ),  then  find  each  free(  ) 
and  make  sure  there  is  an  allocation 
for  it.  But  HIGHRISE  has  now  grown 
to  half  a  meg  of  source.  Even  with  a 


sophisticated  debugger,  you  face  a  for¬ 
midable  task. 

I’ll  show  you  an  easier  way.  In  the 
first  part  of  this  article,  I’ll  present  some 
functions  that  can  replace  the  standard 
functions  malloc( ),  free( ),  and  so  on. 
Each  replacement  function  tracks  your 
program’s  activity  and  reports  it  in  a 
debugging  file.  If  all  is  well,  it  calls  the 
standard  library  function  to  do  the  real 
work.  Using  these  replacement  func¬ 
tions,  I’ve  tracked  down  some  very  cun¬ 
ning  bugs,  and  you  will,  too.  In  the 
second  part,  I’ll  show  how  to  obtain 
the  heap-status  of  the  heap  without 
any  special  programming.  A  few  well- 
placed  calls  to  the  functions  may  help 
you  home  in  on  the  section  of  code 
that  is  giving  you  trouble.  This  tech¬ 
nique  described  in  the  second  part 
turned  up  the  errors  in  those  commer¬ 
cial  libraries  mentioned  earlier. 

Replacement  Functions 

Look  at  the  program  in  Listing  One 
(page  178).  This  program  is  a  disaster. 
One  block  of  memory  is  allocated  but 
never  freed.  If  this  happens  enough 
times  in  a  program,  it  runs  slower  and 
slower,  until  it  finally  runs  out  of  mem¬ 
ory  and  hangs.  Another  block  in  Listing 
One  is  freed  without  ever  having  been 
allocated.  In  DOS,  that  kind  of  mistake 
can  even  clobber  your  file  allocation 
table.  (I  did  once!)  Either  type  of  error 
can  be  almost  impossible  to  track  down 
in  a  large,  complex  program. 

Now  look  at  Listing  Two  (page  178). 
I  have  replaced  the  calls  to  the  stan- 
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dard  functions  with  calls  to  the  replace¬ 
ment  functions  that  I  will  now  describe. 

First,  notice  the  calls  to  memMal- 
loc( ).  memMalloc( 7works  just  like  mal- 
loc( ),  but  there  is  a  second  argument. 
This  argument  is  a  “tag”  that  you  can 
use  to  identify  the  call  in  the  debug¬ 
ging  file.  This  is  the  pattern  for  all  the 
replacement  functions:  You  use  them 
just  like  the  standard  functions,  but 
they  take  a  tag  as  an  extra  argument. 

The  calls  to  memFree( )  replace  calls 
to  free( ).  Again,  a  tag  is  added  to  the 
argument  list.  Listing  Three  (page  178) 
shows  the  replacement  routines.  We’ll 
begin  with  memMalloc( ).  This  func¬ 
tion  begins  by  calling  malloc( ). 
memTrack_alloc( )  is  then  used  to  track 
the  allocation. 

memFree ( )  calls  memTrack_Jree( ), 
which  tracks  the  attempt  to  free,  and 
returns  TRUE  if  the  memory  may  in 
fact  be  freed  or  FALSE  if  not.  Only  after 
determining  that  the  memory  may  be 
freed  does  memFree( )  free  it.  The 
memTrack  routines  are  obviously  the 
key  to  the  whole  scheme,  so  let’s  dis¬ 
cuss  them  next. 

memTrack_alloc(  )and  memTrack_ 
free( )  keep  track  of  pointers  allocated 
and  freed.  The  implementation  shown 
here  keeps  a  journal  of  activity  in  a  file, 
but  you  could  easily  write  an  implemen¬ 
tation  that  keeps  records  in  an  array  or 
a  binary  tree.  Although  the  file  method 
is  slower,  it  has  the  advantage  of  sur¬ 
viving  the  crash  that  you  are  trying  to 
debug! 

As  you  can  see  in  memTrack_alloc( ), 
the  file  consists  of  records  of  three  fields 
each.  The  first  field  is  either  an  A  (for 
allocated)  or  F  (for  freed).  The  second 
is  the  address  of  the  allocated  item. 
The  third  is  the  tag  you  supplied  in 
your  call  to  the  routine. 

memTrack_alloc( )  simply  appends 
a  record  of  the  allocation  that  it  is  track¬ 
ing.  Part  of  this  record  is  the  allocated 
address,  in  %p  (pointer)  format.  This 
formats  the  address  as  0000:0000.  The 
%p  format  is  not  available  with  some 
compilers,  so  you  may  want  to  use  a 
long  integer,  or  whatever  is  appropri¬ 
ate  on  your  machine. 

memTrack^free( )  searches  through 
the  file,  looking  for  confirmation  that 
the  memory  you  are  about  to  free  was, 
in  fact,  allocated.  If  it  finds  an  “allo¬ 
cated”  record  with  the  same  memory 
address,  it  over-writes  the  A  (allocated) 
with  an  F  (freed).  If  it  does  not  find 
such  a  record,  it  writes  an  error  mes¬ 
sage  to  the  file. 

These  routines  call  the  function 
memTrack_fp( ),  which  returns  a  FILE 
pointer  for  the  debugging  file.  The  name 
of  this  file  must  be  in  the  environment 
variable  MEMTRACK.  In  DOS,  this  is 


accomplished  with  something  like:  SET 
MEMTRACK=C:  \  MYPROG.MEM 

You  may  want  to  use  a  RAM  drive  if 
your  program  is  at  least  giving  you  a 
normal  exit.  (If  the  program  locks  up 
your  system,  you  will  have  no  way  to 
get  to  the  RAM  drive!) 

If  MEMTRACK  is  not  set  in  the  envi¬ 
ronment,  nothing  will  hang  —  you  just 
won’t  get  a  debugging  file.  This  pro¬ 
vides  an  easy  way  to  turn  off  memory 
tracking  without  recompiling  all  your 
code. 

Finally,  memTrack_msg( )  appends 
a  message  to  the  debugging  file.  If,  for 
some  reason,  the  debugging  file  could 
not  be  opened,  the  message  goes  to 


standard  error. 

Speaking  of  the  debugging  file,  check 
Figure  1  to  see  what  it  looks  like  now. 
Recall  that  the  memory  for  “tag  1”  was 
allocated  but  never  freed.  In  the  de¬ 
bugging  file,  this  results  in  a  line  that 
starts  with  an  “A”  (for  allocated).  The 
memory  for  “tag  2”  was  allocated  and 


A  2524:000C  tag  1 
F  2524:  021Atag2 

Tried  to  free  113A:000B  (tag  4).  Not 
allocated. 


Figure  1:  The  debugging  file  after 
memTrack_msg(  ) 
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freed  properly.  memTrack _free( )  has 
over-written  an  “A”  that  used  to  be  on 
line  2  with  an  “F.”  This  is  how  you 
want  all  your  debugging  lines  to  be. 
Finally,  there  is  a  real  problem  with  the 
line  for  tag  4:  We  tried  to  free  a  pointer 
that  we  never  allocated. 

Of  course,  all  this  housekeeping  takes 
extra  processing  time  so  we  want  to 
be  able  to  use  the  standard  functions 
alone  in  final  production.  The  #include 

In  a  complicated 
program,  the  best 
approach  is  to  call 
heapPrt( )  in  places 
where  you  can  predict 
the  status  of  the  heap 


file  mem.h  (Listing  Four,  page  180)  takes 
care  of  this  for  us.  Notice  the  statement 
#ifdef  MEMTRACK. 

If  you  have  #defined  MEMTRACK, 
the  header  file  emerges  from  the  pre¬ 
processor  as  a  set  of  function  proto¬ 
types.  If  you  have  not  ( #else ),  the  calls 
to  the  replacement  routines  are  #de- 
fined  to  be  calls  to  the  functions  in  the 
standard  library.  Thus,  you  will  incur 
no  extra  overhead  in  your  tested,  pro¬ 
duction  version.  Even  the  tag  strings 
will  not  take  up  static  space  in  your 
executable  program;  they  vanish  at  pre¬ 
processing  time,  when  the  #define  is 
processed!  You  can  cause  MEMTRACK 
to  be  #defined  by  coding  #define 
MEMTRACK  in  each  of  your  C  pro¬ 
grams,  ahead  of  your  Hnclude  mem.h. 
Alternatively,  you  can  use  a  command¬ 
line  switch  on  your  compiler.  With  the 
Microsoft  compiler,  for  example,  type 
cl  /c  /DMEMTRACK  program,  c. 

I  prefer  the  command-line  method 
because  it  is  easier  to  undo.  I  just  re¬ 
compile  without  the  switch.  The  in¬ 
source  method  does,  however,  have 
one  advantage:  You  can  tell  whether  a 
given  module  was  compiled  with 
MEMTRACK  simply  by  looking  at  the 
source. 

If  you’re  careful,  you  can  even  #de- 
fine  MEMTRACK  selectively.  That  is, 
you  can  compile  one  subset  of  pro¬ 
grams  with  /DMEMTRACK  and  another 
without.  For  this  to  work,  each  subset 
must  be  self-contained  as  far  as  mem¬ 
ory  allocation  is  concerned  —  neither 
one  should  free  memory  allocated  by 
the  other. 


So  far,  we  have  replaced  only  mal- 
loc( )  and  free( ).  However,  there  are 
several  other  routines  in  the  standard 
library  that  allocate  memory.  We  must 
replace  all  of  them,  or  we  will  not  have 
a  complete  record  of  our  activity.  For 
example,  if  we  do  not  replace  real- 
loc( ),  our  debugging  file  will  have  no 
record  of  its  allocation.  memFree(  /will 
then  raise  a  spurious  objection  when 
we  try  to  free  the  memory.  The  other 
functions  in  Listing  Three  complete  the 
job  by  replacing  calloc( ),  realloc( ), 
and,  don’t  forget,  strdupC ). 

To  debug  a  program  with  the  re¬ 
placement  functions,  then,  there  are 
five  steps: 

1 .  ^include  <mem.h> 

2.  Use  the  mem  routines  instead  of  the 
standard  ones 

3-  Compile  with  MEMTRACK  #defined , 
either  in  the  source-  or  on  the  com¬ 
piler’s  command  line 

4.  Link  with  the  mem  routines 

5.  Set  the  environment  variable  MEM¬ 
TRACK  equal  to  the  name  of  your 
debugging  file. 

To  turn  off  debugging  you  have  two 
choices: 

•  Recompile  everything  without 
MEMTRACK  #t defined,  and  link  with¬ 
out  the  replacement  routines.  This 
is  the  preferred  method  for  a  com¬ 
mercial  release. 

•  Take  MEMTRACK  out  of  your  envi¬ 
ronment.  The  replacement  routines 
will  still  be  a  part  of  your  code,  but 
the  memTrack  routines  will  not  do 
anything. 

Heap  Status 

Sometimes  the  situation  is  so  awful, 
and  your  program  so  large,  that  it  is 
impractical  to  begin  with  the  approach 
presented  earlier.  Or  you  may  think  the 
situation  is  perfect,  and  you  just  want 
to  be  sure.  The  routines  that  follow 
give  you  a  summary  of  the  heap’s  status 
with  one  function  call.  These  routines 
are  built  on  some  that  Microsoft  pro¬ 
vides  with  its  C  compiler.  In  the  hope 
that  you  use  Microsoft,  or  that  your 
compiler  provides  similar  routines,  I 
now  refer  you  to  Listing  Five  (page 
180). 

You  will  see  that  I  have  made  all  the 
same  mistakes  I  made  in  Listing  One. 
But  this  time,  I  have  interspersed  calls 
to  the  heapPrt( )  function.  This  func¬ 
tion  tells  me  how  many  allocations  I 
have  made,  and  how  many  bytes  they 
total.  By  default,  heapPrt( )  writes  to 
standard  output,  with  puts( ).  Depend¬ 
ing  on  what  else  your  program  does 
to  the  screen,  this  may  not  be  what  you 
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want.  I  have,  therefore,  coded  heap- 
Prt( )  so  you  can  designate  your  own 
message  function.  In  Listing  Five,  we 
use  my_own_msg_func( ). 

The  output  at  the  end  of  the  listing 
tells  the  story:  We  have  10  bytes  yet  to 
be  freed  when  the  program  is  done. 
This  is  never  good,  if  only  from  a  stylis¬ 
tic  point  of  view.  Now,  some  program¬ 
mers  like  to  let  the  operating  system 
free  the  memory  when  the  program 
exits.  If  you  are  one  of  those  program¬ 
mers,  I  tell  you  that  this  is  like  letting 
your  wife  or  mother  pick  up  your  dirty 
laundry.  Sure  she’ll  do  it,  but  sooner 
or  later  it’s  going  to  bite  you.  Maybe 
your  program  will  become  a  subrou¬ 
tine  and  strangle  your  application  after 
enough  calls.  Or  maybe  you  will  have  a 
real  memory  problem  that  will  be  diffi¬ 
cult  to  find  amidst  all  the  sloppiness. 

Whatever  your  relationship  with  your 
mother,  I  think  you  can  appreciate  the 
usefulness  of  heapPrt( ).  It  takes  a  global 
view,  while  the  mem  .  .  .  ()  routines 
in  the  first  part  of  this  article  are  more 
focused.  heapPrt( )  is  particularly  use¬ 
ful  when  you  suspect  that  there  is  un¬ 
freed  memory  in  someone  else's  code 
and  you  can’t  replace  all  his  malloc(  Js 
with  the  routines  in  this  article. 

In  a  complicated  program,  the  best 
approach  is  to  call  heapPrt( )  in  places 
where  you  can  predict  the  status  of  the 
heap.  Often,  you  will  predict  that  two 
successive  calls  to  heapPrt( )  will  pro¬ 
duce  the  same  output,  because  the  code 
in  between  is  supposed  to  free  all  the 
memory  it  allocates.  If  your  expecta¬ 
tion  is  not  met,  you  can  zero  in  on  the 
problem  with  more  heapPrt( )  calls,  or 
use  the  mem  .  .  .  ()  routines. 

The  code  for  heapPrt( )  and  an  asso¬ 
ciated  function,  heapUsed( ),  is  in  List¬ 
ing  Six  (page  180). 

A  Freebie 

At  the  beginning  of  this  article,  I  said 
that  99  percent  of  slow  deaths  are 
caused  by  memory  allocation  mistakes. 
What  about  the  other  one  percent? 
Those  are  the  programs  that  open  files 
but  never  close  them.  Eventually,  you 
run  out  of  file  handles.  That  problem 
is  analogous  to  the  memory  allocation 
problem,  and  I  have  written  a  suite  of 
functions  to  handle  it.  They  are  in¬ 
cluded  in  the  file  you  can  download 
from  this  magazine’s  bulletin-board  ser¬ 
vice.  You  also  may  obtain  the  whole 
package  free  of  charge  by  writing  me 
at  Cornerstone  Systems  Group,  10  N. 
Main  St.,  West  Hartford,  CT  06107. 
Please  include  a  formatted,  IBM  PC- 
compatible  disk. 

Summary 

I  have  presented  two  sets  of  functions. 


The  first  can  serve  as  a  bookkeeping 
layer  between  your  programs  and  the 
standard  memory  management  func¬ 
tions.  The  bookkeeping  can  be  turned 
off  by  a  quick  change  to  your  environ¬ 
ment.  The  bookkeeping  layer  can  be 
removed  completely  by  recompiling. 
The  second  set  of  functions  will  give 
you  a  snapshot  of  the  heap  at  any 
point.  Either  set  of  functions  can  save 
hours  of  time  in  very  difficult  situations. 

Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
online.  To  order  the  disk,  send  $14.95 


(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal ,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  the  /l/l/listing  service  (415-364- 
8315)  and  through  the  DDJ  Forum  on 
CompuServe  (type  GO  DDJ). 

DDJ 

(Listings  begin  on  page  178.) 

Vote  for  your  favorite  feature/article. 
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Optimizing  with 
Microsoft  C  6.0 

Based  pointers  and  global 
optimization  highlight  features 
of  this  new  incarnation 


Scott  Robert  Ladd 


For  two  years,  Microsoft  C  5.1  has 
been  the  benchmark  by  which 
other  C  compilers  are  judged. 
Vendors  of  competing  compil¬ 
ers  always  compare  themselves 
against  Microsoft’s  product.  Some  com¬ 
petitors  have  edged  ahead  of  Microsoft 
C  5.1  —  Watcom  C  7.0  produces  faster 
programs;  Borland’s  Turbo  C  and  oth¬ 
ers  are  faster  at  producing  programs. 
While  Microsoft  C  5.1  has  remained  at 
the  top  of  the  heap,  it  is  no  longer  the 
leader  in  many  categories. 

The  upgrade  has  finally  arrived  in 
the  form  of  Microsoft  C  6.0.  Microsoft’s 
answer  to  the  competition  includes  a 
new  programming  environment,  an  im¬ 
proved  code  optimizer,  a  new  version 
of  the  venerable  CodeView  debugger, 
and  some  new  library  enhancements. 
Pulling  out  all  the  stops,  Microsoft  has 
made  clear  its  intent  to  keep  its  C  com¬ 
piler  at  the  forefront  of  the  industry. 

An  Overview 

Perhaps  the  biggest  surprise  for  many 
is  that  Microsoft  C  6.0  (MSC6)  does  not 
include  any  C++  extensions.  With  most 
other  vendors  jumping  on  the  C++  band¬ 
wagon,  it  might  seem  odd  that  Micro¬ 
soft  has  not  followed  the  same  path. 
Some  industry  watchers  have  opined 
that  Microsoft  has  made  a  mistake  by 
leaving  out  C++.  I  don’t  agree  —  C++ 
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is  a  language  that  is  still  maturing.  Most 
C  programmers  are  sticking  with  C; 
only  a  few  have  embraced  C++  as  their 
primary  programming  language.  For 
now,  C  is  the  dominant  programming 
language  for  professional  developers 
of  PC  applications,  and  Microsoft  is 
addressing  this  market. 

You  must  use  Microsoft’s  Setup  pro¬ 
gram  to  install  MSC6.  The  files  on  the 
distribution  disks  are  compressed,  and 
they  can  be  expanded  only  by  using 
the  Setup  program.  Setup  is  a  very  good 
installation  program;  it  gives  you  the 
choice  of  installing  different  sets  of  li¬ 
braries  and  tools  based  on  your  needs. 
Additional  libraries  can  be  built  later 
without  having  to  reinstall  the  entire 
package. 

MSC6  is  disk-hungry;  installing  the 
MS-DOS  version  of  the  compiler,  the 
programming  environment,  two  mem¬ 
ory  models  (small  and  large)  each  for 
the  floating-point  emulator  and  the  copro¬ 
cessor,  and  other  tools  used  over  7 
Mbytes  of  space  on  my  hard  drive.  If 
you  install  all  four  memory  models  for 
all  three  floating-point  options  along 
with  the  OS/2  version  of  the  compiler, 
you  can  easily  use  more  than  1 2  Mbytes 
of  disk  space.  Obviously,  it  is  not  pos¬ 
sible  to  use  MSC6  on  a  floppy  disk- 
based  computer! 

One  last  change  in  the  basic  package 
may  take  some  people  by  surprise:  It  is 
now  distributed  on  1.2-Mbyte  5  ’A- 
inch  disks  and  720K  3  'A-inch  disks.  If 
you  want  MSC6  on  360K  disks,  you’ll 


have  to  special  order  them  after  you’ve 
bought  the  package.  Microsoft  is  offer¬ 
ing  MSC6  on  CD-ROM,  preinstalled  and 
ready  to  run. 

Documentation? 

No,  the  question  mark  is  not  a  typo. 
Looking  at  MSC6  you  may  wonder  if 
Microsoft  forgot  to  pack  the  documen¬ 
tation.  Microsoft  has  minimized  the  pa¬ 
per  documentation  in  their  language 
products  in  recent  years.  Instead  of 
providing  thick  books,  Microsoft  puts 
the  majority  of  the  documentation  into 
on-line  databases.  MSC6  comes  with 
only  940  pages  of  documentation,  less 
than  half  the  length  of  the  manuals 
provided  with  MicrosoftC  5.1  (MSC5.1). 
Going  from  the  fat  three-ring  binders 
of  MSC5. 1  to  the  thin  paperback  manu¬ 
als  of  MSC6  gives  the  impression  that 
Microsoft  has  left  something  out. 

The  documentation  isn’t  missing;  it’s 
just  not  where  you’d  expect  it  to  be. 
The  on-line  help  system  is  where  the 
real  documentation  for  MSC6  lies.  There 
are  nearly  2  Mbytes  of  help  files  cover¬ 
ing  every  aspect  of  MSC6  in  great  de¬ 
tail.  These  help  files  are  available  either 
through  the  QuickHelp  program,  or 
from  within  the  Programmer’s  Work¬ 
bench  environment. 

In  MSC5.1,  the  command-line  com¬ 
piler  had  a  /HELP  switch  that  displayed 
a  simple  list  of  compiler  switches.  The 
same  switch  in  MSC6  is  now  available 
for  virtually  every  program  in  the  pack¬ 
age.  Instead  of  a  simple  command  list, 
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though,  /HELP  will  invoke  the  interac¬ 
tive  menu-driven  QuickHelp  system. 
This  provides  complete  information  on 
the  program  in  question.  Entering  the 
command  lib  /HELP  will  bring  up  de¬ 
tailed  information  on  the  library  man¬ 
ager  utility.  The  scope  of  the  informa¬ 
tion  runs  from  an  explanation  of  lib  to 
complete  coverage  of  lib  switches  and 
commands  (with  examples). 

The  lion’s  share  of  the  help  informa¬ 
tion  is  available  only  when  you  are 
working  within  the  Programmer’s  Work¬ 
bench.  If  you’re  working  with  OS/2, 
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the  QuickHelp  utility  can  be  used  as  a 
keyboard  monitor,  so  that  it  can  be 
popped  up  at  any  time  for  use.  Unfor¬ 
tunately,  MS-DOS  users  do  not  have 
the  luxury  of  a  TSR  version  of  Quick¬ 
Help. 

Considering  the  amount  of  on-line 
documentation,  I  was  pleased  to  find 
that  the  seemingly  small  amount  of  pa¬ 
per  documentation  was  actually  very 
useful.  There  are  two  paperback  manu¬ 
als  in  the  MSC6  box:  the  spiral-bound 
380-page  Microsoft  C  Reference  and  the 
480-page  Advanced  Programming  Tech¬ 


niques.  The  amazingly  long  title  In¬ 
stalling  and  Using  the  Professional  De¬ 
velopment  System  belongs  to  an  80- 
page  booklet  that  explains  the  installa¬ 
tion  process  and  the  fundamentals  of 
using  the  Programmer’s  Workbench  en¬ 
vironment. 

The  Microsoft  C  Reference  begins  with 
a  section  describing  each  program  pro¬ 
vided  by  Microsoft.  For  the  compiler 
and  utilities,  a  list  of  command-line 
parameters  and  switches  is  given.  For 
nmake  —  Microsoft’s  much-awaited  en¬ 
hanced  make  utility  —  a  reference  to 
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Based  Pointers  for  Optimization 

Bruce  D.  Schatzman 


Microsoft  C  6.0  provides  an  important 
new  tool  in  the  battle  to  keep  code 
small  and  fast  —  the  based  pointer. 
Virtually  all  Microsoft  C  programmers 
are  familiar  with  near  and  far  point¬ 
ers,  and  how  they  are  used  within 
standard  or  mixed  memory  models. 
The  2-byte  wearpointers  provide  both 
size  and  speed  advantages  over  the 
larger  and  slower  4-byte  far  pointers. 
As  such,  programmers  tend  to  use 
near  pointers  within  small  memory 
models  whenever  possible. 

Even  the  most  carefully  designed 
small  model  programs,  however,  some¬ 
times  hit  the  memory  wall  of 
DGROUP’s  64K  allocation.  Program¬ 
mers  are  then  faced  with  a  tough  de¬ 
cision:  Find  a  way  to  keep  the  pro¬ 
gram  within  the  confines  of  a  Small 
memory  model  to  preserve  the  speed 
advantage,  or  admit  defeat  and  move 
to  larger  and  less  efficient  models  such 
as  compact  or  large.  The  inefficiency 
of  larger  models  is  primarily  the  result 
of  the  use  of  4-byte  (fa r)  pointers. 
Each  time  a  far  data  item  is  refer¬ 
enced,  both  the  segment  and  offset 
address  must  be  loaded  into  one  of 
the  80x86’s  segment  registers.  This 
double  load  consumes  more  CPU  cy¬ 
cles  than  near  pointers  (which  load 
only  an  offset  address),  and  increases 
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both  code  and  data  sizes. 

Microsoft  C  6.0  provides  a  solution 
to  this  problem  through  the  use  of 
based  pointers.  This  new  data  type 
gives  you  the  reach  of  far  pointers 
while  retaining  the  size  and  speed 
advantages  of  near  pointers.  You  can 
now  increase  your  program’s  data 
space  without  necessarily  moving  to 
a  larger  memory  model  or  a  mixed 
(near/far)  model. 

Listing  Five  (page  131)  presents  a 
small  skeleton  program  that  sets  up 
a  linked  list  of  file  names  using  a  set 
of  structures  (  TAG),  with  a  maximum 
number  of  AL4A_7I4Gstructures.  Two 
new  keywords  are  used:  _segment 
and  _based.  The  statement  _segment 
segvar;  declares  a  variable  that  will 
hold  a  segment’s  memory  address. 
segvarwiW  become  a  segment  in  which 
a  set  of  data  is  based  —  thus  the  name 
“based  pointers.” 

This  basing  is  illustrated  in  the  state¬ 
ment  _based(segvar)  *PTAG,  TAG;, 
which  defines  a  2-byte  structure  pointer 
and  a  structure  that  are  both  based 
within  the  segment  segvar. 

The  compiler  generates  code  that 
automatically  looks  at  the  segvar  vari¬ 
able  each  time  a  reference  is  made  to 
*PTAG  and  TAG,  necessitating  only 
the  use  of  a  2-byte  offset  address. 
Technically,  *PTAG  and  TAG  are  both 
in  a  far  heap,  yet  they  act  as  if  they 
reside  in  a  near  heap. 

If  MAX_TAG were  smaller,  this  pro¬ 
gram  could  fit  comfortably  within  a 
small  memory  model.  However,  with 
MAXJTAG  =  2000,  the  tag  list  itself 
could  fill  up  a  64-Kbyte  data  segment. 
Basing  our  structures  within  segvar 
means  that  as  the  program  runs,  suc¬ 
cessive  references  to  these  structures 


involve  loading  only  the  2-byte  seg¬ 
ment  offset.  Because  the  structures 
are  all  within  one  segment,  the  seg¬ 
ment  address  is  preloaded  into  one 
of  the  segment  registers  and  does  not 
need  to  be  reloaded  every  time  a  new 
segvar  structure  is  referenced. 

However,  referencing  another 
named  segment  (or  far  pointer)  will 
requires  loading  a  new  value  within 
a  segment  register.  Therefore,  based 
pointers  are  most  effective  for  use 
with  successive  references  to  data 
items  within  the  same  segment,  and 
offer  performance  equivalent  to  that 
of  near  pointers. 

Note  the  program’s  use  of  the  new 
C  6.0  library  routines  _bheapseg  and 
_bmalloc,  which  allocate  a  based- 
heap  segment  and  memory  within  that 
segment. 

Although  I’ve  focused  here  on  keep¬ 
ing  small  programs  small,  based  point¬ 
ers  can  also  be  used  to  reduce  the 
size  (and  increase  the  speed)  of  large 
programs.  This  is  accomplished  by 
converting  some  or  all  of  a  large  pro¬ 
gram’s  far  pointers  to  based  pointers. 

Based  pointers  are  an  important 
tool,  but  they  have  their  limitations. 
Perhaps  the  most  significant  is  the 
fact  that  their  actual  addressing  capa¬ 
bility  is  16  bits  —  the  size  of  a  single 
segment.  They  do  not  have  the  un¬ 
limited  32-bit  scope  of  far  pointers, 
and  thus  cannot  be  used  for  very 
large  data  structures,  such  as  arrays 
that  exceed  64K.  far  pointers  are  the 
only  real  choice  in  these  circum¬ 
stances.  Nevertheless,  based  pointers 
are  a  tool  that  will  undoubtedly  be 
used  by  a  large  percentage  of  Micro¬ 
soft  C  programmers  to  optimize  code 
for  smaller  size  and  greater  speed. 
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makefile  statements  is  provided.  The 
section  on  CodeView  presents  a  com¬ 
plete  list  of  all  debugger  commands 
and  data  formats.  The  documentation 
for  Programmer’s  WorkBench  includes 
tables  explaining  the  environment’s  nu¬ 
merous  switches,  macros,  functions,  and 
key  assignments. 

Following  the  utilities  section,  the 
Microsoft  C  Reference  has  a  complete 
list  of  all  library  functions,  providing 
information  on  prototypes,  required 
header  files,  return  values,  and  com¬ 
patibility  between  operating  systems. 
Each  function  has  a  one-  or  two-sen¬ 
tence  description,  which  is  adequate 
for  an  experienced  C  programmer.  The 
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appendices  list  printf  and  scanf  format 
specifiers,  key  codes,  and  ASCII  val¬ 
ues.  I  think  the  Microsoft  C  Reference 
is  the  longest  quick-reference  manual 
I’ve  seen,  but  it  has  quickly  become 
indispensable. 

A  wide  variety  of  topics  are  covered 
in  Advanced  Programming  Techniques. 
It  contains  chapters  on  optimization, 
floating-point  operations,  memory  man¬ 
agement,  the  new  indine  assembler, 
project  development,  debugging,  graph¬ 
ics,  and  mixed-language  programming. 
This  how-to  book  provides  details  on 
how  the  MSC6  system  can  be  used 
most  effectively. 

My  overall  impression  of  the  docu¬ 


mentation  is  that  it  was  designed  for 
an  experienced  professional.  I  would 
not  recommend  this  product  to  some¬ 
one  just  beginning  to  work  with  C. 
Beginners  need  hand-holding  and  de¬ 
tailed  documentation,  something  that 
Microsoft  is  not  providing  with  MSC6. 

The  Compiler  and  Tools 

QuickC  is  not  included  with  MSC6.  How¬ 
ever,  the  core  compiler  for  QuickC  is 
there;  it  can  be  invoked  by  the  com¬ 
piler  control  program  with  the  /qc 
switch.  Using  /qc  doubles  the  speed 
of  compiles,  but  prevents  you  from 
using  advanced  optimizations.  The  com¬ 
piler  itself  has  actually  changed  in  a 
number  of  areas  from  MSC5.1  to  MSC6. 
The  primary  additions  are  in  improved 
ANSI  compatibility,  a  Tiny  memory 
model,  an  in-line  assembler,  optimiza¬ 
tions,  “based”  pointers  (see  sidebar), 
and  a  new  long  double  type. 

MSC5.1  stuck  closely  to  the  ANSI 
standard;  MSC6  is  just  about  on  the 
money.  New  ANSI  features  in  MSC6 
include  complete  support  for  volatile , 
long  values  in  switch  statements,  and 
support  for  “locales.”  A  locale  describes 
the  numeric,  money,  date,  and  time 
formats  for  a  given  country.  As  with 
most  MS-DOS  C  compilers,  MSC6  only 
supports  the  C  locale,  which  is  identi¬ 
cal  to  the  locale  for  the  United  States, 
and  is  the  only  locale  an  ANSI-standard 
compiler  must  support. 

Microsoft  has  finally  recognized  that 
some  programmers  want  to  produce 
programs  in  the  simple  .COM  format. 
The  new  Tiny  memory  model  is  a  modi¬ 
fied  version  of  the  Small  model;  the 
primary  difference  is  in  how  a  program 
is  linked.  Link  combines  a  special  li¬ 
brary  with  Tiny  model  programs  to  di¬ 
rectly  create  a  .COM  file  without  a  call 
to  exe2bin. 

The  in-line  assembler  was  introduced 
by  Microsoft  in  QuickC  2.01,  and  it’s 
now  available  in  MSC6.  The  _asm  key¬ 
word  can  preface  a  block  of  assembler 
instructions  in  a  C  program.  The  _emit 
function  places  a  series  of  arbitrary  byte 
values  into  program  code.  While  the 
in-line  assembler  and  _emit  are  non¬ 
portable,  they  do  provide  a  conven¬ 
ience  many  programmers  will  find  dif¬ 
ficult  to  resist  (see  “DOS  +  386  =  4 
Gigabytes,”  DDJ,  July  1990). 

As  predicted,  Microsoft  has  increased 
the  power  of  its  optimizer.  Many  new 
optimization  options  have  been  added, 
including  global  optimizations  that  look 
at  functions  as  a  whole  when  analyz¬ 
ing  a  program.  MSC6  is  now  in  the 
same  class  as  Watcom  and  Zortech 
when  it  comes  to  optimizations. 

MSC5.1  was  known  for  the  infamous 
aliasing  problem.  An  alias  occurs  in  a 
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C  program  when  two  different  names 
refer  to  the  same  memory  location.  An 
optimizer  can  produce  faster  code  if  it 
can  assume  that  no  aliases  exist.  Under 
MSC5. 1 ,  the  maximum  optimization  com¬ 
piler  switch  (/Ox)  told  the  optimizer  to 
ignore  the  existence  of  aliases.  Many 
programmers  complained  when  MSC5.1 
generated  non-functional  programs 
from  code  that  contained  aliases.  Mi¬ 
crosoft  has  changed  /Ox  in  MSC6  so 
that  it  assumes  aliases  exist.  You  can 
still  tell  the  optimizer  to  ignore  the 
possibility  of  aliasing,  but  you  must 
do  so  explicitly  with  the  /Oa  switch. 

A  new  feature  of  MSC6  is  that  optimi¬ 


zations  can  be  turned  on  and  off  within 
a  source  file  through  the  use  of  prag¬ 
mas.  This  allows  you  to  explicitly  pro¬ 
tect  a  piece  of  code  from  strong  optimi¬ 
zations,  for  example.  MSC6  can  enreg- 
ister  parameters,  an  optimization  pio¬ 
neered  by  Watcom  C.  Individual  func¬ 
tions  or  complete  source  modules  can 
be  compiled  with  enregistered  parame¬ 
ters.  Normally  the  parameters  to  a  func¬ 
tion  are  pushed  onto  the  stack  before 
the  function  call  is  made.  When  enreg¬ 
istered  parameters  are  in  effect,  pa¬ 
rameters  are  stored  in  registers  when 
the  function  call  is  made.  This  saves  a 
considerable  amount  of  pushing  and 
popping  of  parameters  on  the  stack, 


and  can  increase  the  speed  of  a  pro¬ 
gram  that  makes  numerous  calls  to  func¬ 
tions  with  small  numbers  of  arguments. 

nmake  is  Microsoft's  professional 
make  utility.  The  older  make  program 
included  with  previous  versions  of  Mi¬ 
crosoft  C  was  abysmally  weak.  Unlike 
its  predecessor,  nmake  is  compatible 
with  Unix. 

Debugging 

CodeView  3.0  has  been  awaited  with 
great  expectations.  Earlier  versions  of 
Microsoft’s  pioneering  debugger  were 
very  good  but  clumsy  to  use.  Products 
such  as  Borland’s  Turbo  Debugger  were 
easier  to  use  and  more  powerful.  While 
CodeView  3.0  goes  a  long  way  towards 
answering  its  critics,  it’s  still  a  few  steps 
short  of  what  programmers  want. 

Tiled  windows  are  passe  —  more  in¬ 
formation  can  be  easily  displayed  in 
layered  windows.  Unfortunately,  Code¬ 
View  3-0  uses  tiled  windows.  With  Pro¬ 
grammer’s  WorkBench  and  other  full¬ 
screen  applications  using  a  layered  win¬ 
dow  system,  CodeView  seems  a  bit 
out-of-step.  I  could  not  use  CodeView 
3.0  with  more  than  four  windows  open 
on  a  25-line  screen. 

I  also  found  CodeView  3  0  to  be 
frustrating.  I  want  CodeView  to  always 
come  up  in  VGA  50-line  mode  with  use 
of  the  80386  debugging  registers.  While 
commands  for  CodeView  can  be  placed 
in  the  TOOLS.INI  initialization  file,  none 
of  these  commands  change  the  default 
command-line  parameters.  There  isn’t 
even  a  CV  environment  variable  to 
which  default  switch  settings  can  be 
assigned.  The  compiler  and  linker  both 
support  environment  variables  that  con¬ 
tain  command-line  switches;  why  Code¬ 
View  doesn’t  is  a  mystery  to  me. 

CodeView  3  0  can  be  run  in  extended 
memory  (leaving  more  room  for  pro¬ 
grams  in  main  memory),  but  it  can  only 
do  so  when  the  HIMEM.SYS  driver  is 
loaded.  HIMEM.SYS  is  incompatible 
with  any  other  386  control  program, 
which  prevented  me  from  using  Quali- 
tas’  386MAX  program,  for  example,  to 
manage  high  memory  when  HI¬ 
MEM.SYS  is  loaded. 

CodeView  3  0  does  not  support  the 
Virtual  Control  Program  Interface  (VCPI) 
for  386  programs,  a  standard  devel¬ 
oped  by  Phar  Lap  that  allows  multiple 
386  virtual  memory  programs  to  oper¬ 
ate  in  concert.  Microsoft  informed  me 
that  a  VCPI  version  of  CodeView  may 
be  developed,  but  did  not  name  a  re¬ 
lease  date.  Make  no  mistake:  Code¬ 
View  3-0  is  superior  to  previous  ver¬ 
sions  of  the  debugger.  It  has  several 
new  windows,  including  a  “locals”  view, 
which  shows  all  variables  local  to  the 
currently  executing  function.  There  is 
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(continued  from  page  88) 
more  flexibility  in  how  windows  can 
be  tiled,  and  the  command-line  inter¬ 
face  has  largely  been  replaced  by  a  set 
of  keystrokes  and  mouse  selections. 
Overall,  CodeView  3.0  is  a  very  power¬ 
ful  debugger.  With  a  little  work,  it  could 
be  the  best  MS-DOS  debugger  available. 

Benchmarks 

Benchmarks  are  infamous  for  being 
both  controversial  and  subjective,  yet 
they  are  one  of  the  few  empirical  tools 
we  have  for  comparing  compilers. 

Optimization  has  become  one  of  pri¬ 
mary  ways  in  which  vendors  differenti¬ 
ate  their  products  from  the  competi¬ 


tion.  An  optimizing  compiler  performs 
an  analysis  on  a  program  being  com¬ 
piled,  generating  a  more  efficient  pro¬ 
gram.  Optimizers  can  delete  unused 
code  and  variables,  improve  register 
use,  combine  common  subexpressions, 
precalculate  loop  invariants,  and  per¬ 
form  other  tasks  that  improve  program 
performance. 

At  best,  optimizing  a  well-written  pro¬ 
gram  will  improve  its  speed  by  as  much 
as  25  percent.  An  optimizer  will  not 
replace  inefficient  algorithms  with  bet¬ 
ter  ones.  As  the  saying  goes,  “garbage 
in,  garbage  out.”  Most  of  the  responsi¬ 
bility  for  a  program’s  performance  lies 
with  the  programmer.  Improving  algo¬ 


rithms  and  manually  optimizing  a  pro¬ 
gram  will  often  increase  program  speed 
by  several  orders  of  magnitude.  The 
purpose  of  an  optimizer  is  to  make  sure 
that  the  compiler  is  producing  the  fast¬ 
est  code  possible  from  your  source  code. 

In  recent  years,  Watcom’s  C  7.0  has 
become  the  standard  by  which  opti¬ 
mizing  C  compilers  are  judged.  Wat- 
com  entered  the  market  in  1988  with  a 
compiler  that  produced  very  fast  execut¬ 
able  programs.  To  see  how  well  Micro¬ 
soft  C  6.0  stands  up  to  the  competition, 
I  have  run  the  benchmarks  for  it,  as 
well  as  the  benchmark  for  Watcom  C 
7.0.  I’ve  also  included  benchmark  re¬ 
sults  for  Microsoft  C  5.10.  These  results 
will  show  current  users  of  Microsoft  C 
how  much  improvement  they  can  ex¬ 
pect  from  the  new  version.  Table  1  shows 
the  results  of  these  benchmark  tests. 

Four  programs  make  up  the  bench¬ 
mark  suite.  Dhrystone  2  is  a  standard 
industry  benchmark  designed  to  repre¬ 
sent  the  “average”  program.  For  this 
test,  it  was  set  to  run  200,000  iterations. 

DMath  is  a  test  of  floating-point  code 
generation  of  my  own  invention.  DMath 
calculates  the  sines  of  the  angles  be¬ 
tween  0  and  360  degrees  using  a  sim¬ 
ple  series.  A  test  of  floating-point  code 
generation,  DMath  contains  only  dou¬ 
ble  data  items,  and  it  makes  no  library 
function  calls. 

XRef  is  a  test  of  dynamic  memory 
management  and  I/O  speed.  XRef  is  a 
filter  program  that  creates  a  cross-refer¬ 
ence  of  input  from  standard  input.  The 
cross-reference  is  displayed  to  standard 
output. 

The  last  benchmark  program  is  Graf- 
Test,  a  program  that  exercises  my  low- 
level  graphics  library.  GrafTest  performs 
millions  of  function  calls,  and  inter¬ 
faces  directly  with  video  hardware. 

All  tests  were  run  on  a  20-MHz  i386- 
based  computer  running  MS-DOS  3  30. 
The  computer  was  equipped  with  a 
25ms  hard  drive,  a  20-MHz  80387  copro¬ 
cessor,  and  a  16-bit  VGA  video  system. 

Two  compiles  were  done  for  the 
benchmark  chart.  One  compile  used 
the  compiler  and  linker  options  I  would 
use  when  generating  a  program  with 
debug  information  in  it.  The  other  com¬ 
pile  used  full  optimization,  inline  math 
coprocessor  instructions,  and  80286 
code  generation.  Most  compiles  done 
during  development  are  with  full  de¬ 
bugging  information  on.  For  MSC6,  I 
ran  two  sets  of  benchmarks  —  one  with 
enregistered  parameters,  and  the  other 
without.  Compile  times  are  actually  a 
combination  of  compile  and  link  times. 
Timings  are  an  average  for  five  compiles/ 
mns.  The  compiler  command  lines  used 
are  shown  in  Figure  1 . 

Table  1  shows  some  clear  trends. 
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Enregistered  parameters  in  MSC6  did 
not  provide  a  significant  increase  in 
program  speed  in  the  DMath  or  XRef 
tests.  The  biggest  gain  from  enregis¬ 
tered  parameters  is  seen  in  the  Graf- 
Test  benchmark,  which  makes  hun¬ 
dreds  of  thousands  of  calls  to  functions 
that  take  two  or  three  int  parameters. 
Because  Dhrystone  2  lacks  function 
prototypes,  MSC6  was  unable  to  em¬ 
ploy  enregistered  parameters.  While 
Microsoft  C  6.0  produced  the  fastest 
debug  compiles  and  the  best  run  times 
in  three  out  of  four  tests,  it  fell  far 
behind  in  run-time  speed  on  the  DMath 
test.  Watcom  maintains  its  position  as 
the  best  compiler  for  mathematically 
demanding  applications. 

The  OPT  benchmark  program  is 
shown  in  Listing  One  (page  128).  Each 
compiler  was  directed  to  produce  an 
assembly  language  listing  of  its  output, 
based  on  a  compile  using  the-  opti¬ 
mized  compiler  switches  just  shown. 
Listing  Two  (page  128)  shows  the  out¬ 
put  from  Watcom  C  7.0;  Listing  Three 
(page  129)  shows  the  output  from  Mi¬ 
crosoft  C  5.1;  Listing  Four  (page  129) 
shows  the  output  from  Microsoft  C  6.0 
without  enregistered  parameters;  Listing 
Five  .(see  page  131)  shows  the  output 
from  Microsoft  C  6.0  with  enregistered 
parameters.  These  listings  should  give 
you  a  feel  for  the  quality  of  code  gen¬ 
eration  supported  by  the  test  compilers. 

At  the  Workbench 

Usually,  I  don’t  care  much  for  inte¬ 
grated  programming  environments  — 
the  ones  I’ve  worked  with  have  limited 
capabilities  locked  into  a  simplistic  edi¬ 
tor.  Working  from  the  DOS  prompt  has 
always  been  faster  and  more  powerful. 
That  is,  until  now. 

The  Programmer’s  Workbench  is  ac¬ 
tually  an  enhanced  version  of  the  Mi¬ 
crosoft  Editor.  The  Microsoft  Editor  was 
easily  as  powerful  as  other  professional 
program  editors.  It  allowed  separately 
compiled  “add-ons”  to  be  linked  with 
it  at  run  time.  The  Programmer's  Work¬ 
bench  takes  the  idea  of  add-ons  a  step 
further  by  using  them  to  add  support 
for  compilers,  help  systems,  and  utili¬ 
ties  to  its  menus  and  environments. 

The  Programmer’s  Workbench  edi¬ 
tor  is  powerful  and  fast,  incorporating 
all  of  the  features  programmers  expect 
from  a  professional  editor  —  record¬ 
able  and  compilable  macros,  powerful 
block  operations,  multiple  file  editing, 
and  mouse  support.  It  also  allows  you 
to  give  editor  commands  using  menus 
or  function  keys.  I  haven’t  felt  restricted 
by  the  Programmer’s  Workbench  edi¬ 
tor,  and  that’s  something  I  cannot  say 
for  other  integrated  editors. 

You  can  do  all  of  your  program  de¬ 


velopment  work  from  within  the  Pro¬ 
grammer’s  Workbench.  The  environ¬ 
ment  integrates  the  compiler,  make  util¬ 
ity,  linker,  help  system,  and  CodeView 
relatively  seamlessly.  It’s  easy  to  “live” 
within  the  Programmer’s  WorkBench, 
leaving  it  only  when  you’re  ready  to 


finish  up  for  the  day. 

Programmer’s  WorkBench  includes 
menus  that  allow  you  to  set  options  for 
compiles.  Options  can  be  set  for  C, 
Microsoft  Macro  Assembler  (MASM), 
and  the  linker.  Every  option  available 
from  the  command  line  can  be  selected 


Watcom  C  7.0  debug 

:  -2  -7  -Os  -d2  -ms 

Watcom  C  7.0  opt. 

:  -2  -7  -Oail  -s  -ms 

Microsoft  C  5.1  debug 

:  /c  /G2  /FPi87  /qc  /Zi  /Od  /AS 

Microsoft  C  5.1  opt. 

:  /c  /G2  /FPi87  /Ox  /AS 

Microsoft  C  6.0  debug 

:/c/G2  /FPi87/qc/Zi/Od/AS 

Microsoft  C  6.0  opt. 

:  /c  /G2  /FPi87  /Oxaz  /AS 

Figure  1:  The  compiler  command  lines  used  in  the  benchmark  tests.  The 
/Gr  switch  was  added  to  the  Microsoft  C  6.0  command  lines  when  enregistered 
parameters  were  used 
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Program  &  Test 

Watcom 

7.0 

Microsoft 

C  5.1 

Microsoft 

C  6.0 
no/Gr 

Microsoft 
C  6.0 
/Gr 

Dhrystone  2 

time:  debug  compile 

24.24 

13.13 

11.65 

'  ' - .  : 

time:  opt.  compile 

25.15 

20.48 

32.26 

— 

time:  execution 

31.88 

29.42 

27.25 

— 

.EXE  file  size 

14,082 

19,078 

20,334 

— 

DMath 

time:  debug  compile 

11.04 

6.50 

5.87 

6.22 

time:  opt.  compile 

10.29 

8.46 

12.21 

12.03 

time:  execution 

30.39 

40.64 

40.48 

39.41 

.EXE  file  size 

6,534 

9.572 

12,868 

12,820 

XRef 

time:  debug  compile 

13.74 

7.98 

7.20 

7.31 

time:  opt.  compile 

13.70 

11.60 

16.83 

16.98 

time:  execution 

33.48 

32.42 

32.41 

32.37 

EXE  file  size 

7,125 

9,067 

7,639 

7,607 

GrafTest 

time:  debug  compile 

19.99 

11.03 

13.35 

12.91 

time:  opt.  compile 

26.05 

22.09 

49.05 

50.47 

time:  execution 

27.71 

28.78 

27.09 

26.85 

.EXE  file  size 

4,230 

5,603 

5,845 

5,781 

Table  1:  Benchmark  results  for  Microsoft  C  51,  6.0,  and  Watcom  C  7.0 


via  the  menus.  Two  sets  of  program 
construction  options  can  be  set,  for 
debug  and  production  compiles.  Com¬ 
bined  with  a  list  of  files  that  are  part  of 
the  same  program,  the  options  are  used 
to  construct  a  make  file  for  a  project. 
When  you  build  a  project,  the  project’s 
make  file  is  then  passed  as  a  parameter 
to  nmake.  Compilation  results  appear 
in  a  window,  and  errors  can  be  tracked 
from  the  compiler’s  output  directly  into 
your  source  code.  It’s  a  slick,  powerful, 
and  uninhibited  environment  for  con¬ 
structing  software.  Microsoft  has  told 
me  that  the  interface  to  the  Program¬ 
mer’s  WorkBench  will  be  fully  and  pub¬ 
licly  documented  so  that  third  parties 
can  integrate  their  products  into  Work- 
Bench.  With  luck,  your  favorite  editor 
or  make  utility  will  become  a  part  of 
the  environment. 

Programmers  WorkBench  has  one 
drawback  that  may  limit  its  acceptance 
by  many  programmers:  It  does  not  run 
efficiently  on  anything  less  than  a  386-or 
fast  286-based  PC.  The  environment  is 
simply  too  slow  to  be  useful  when  run 
on  a  10-MHz  or  slower  286-based  com¬ 
puter,  according  to  my  correspondents. 

Other  problems  in  the  Programmer’s 
WorkBench  have  surfaced.  It  requires 
nearly  3  Mbytes  of  disk  space,  room 
many  developers  need  for  other  soft¬ 
ware  and  data.  If  you  don’t  install  Work- 
Bench  and  its  help  files,  you  no  longer 


have  access  to  the  primary  source  of 
detailed  documentation  for  MSC6.  For 
these  reasons  many  developers  may 
opt  to  leave  Programmer’s  WorkBench 
off  their  system. 

Conclusion 

Microsoft  has  made  a  valiant  effort  at 
producing  the  definitive  C  compiler  for 
MS-DOS  and  OS/2.  For  developers  who 
have  high-end  PCs  with  available  disk 
space,  Microsoft  C  6.0  is  a  solid  profes¬ 
sional  product  that  offers  some  advan¬ 
tages  over  its  competitors.  Improve¬ 
ments  in  code  optimization,  compiler 
speed,  and  ANSI  compatibility  are  ma¬ 
jor  pluses. 

Unfortunately,  Microsoft  missed  the 
mark  in  some  areas.  CodeView  3-0  is 
not  what  programmers  were  expecting 
and  the  Programmer’s  WorkBench  is  a 
professional  environment  that  is  too 
bulky  and  too  slow  for  many  develop¬ 
ers.  Finally,  the  lack  of  complete  paper 
documentation  is  simply  inexcusable 
in  a  product  priced  at  $450.  Microsoft 
still  has  some  work  to  do  before  they 
can  accurately  claim  to  have  the  best 
C  compiler  on  the  market. 

DDJ 

(Listings  begin  on  page  128.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  8. 


92 

726 


Dr.  Dobb’s Journal,  August  1990 


PROGRAMMER'S  WORKBENCH 


Collections  in 
Turbo  C++ 

A  full  C++  2.0  implementation  makes 
writing  collection  classes  a  breeze 


Bruce  Eckel 


According  to  the  unwritten  rules 
of  implementing  C++,  compiler 
vendors  have  the  option  of  say¬ 
ing  “sorry,  not  implemented” 
when  a  language  feature  is 
either  too  difficult  to  implement  or  when 
the  implementor  feels  that  the  program¬ 
mer  really  doesn’t  need  a  particular 
feature.  Most  implementors  have  in¬ 
voked  this  rule  at  one  time  or  another, 
even  AT&T  with  its  cfront  translator. 
Furthermore,  vendors  sometimes  im¬ 
plement  features  for  which  a  compiler 
may  accept  the  syntax  but  not  enforce 
it;  const  and  volatile  member  functions 
are  good  examples  of  this.  In  such 
cases,  you  may  think  you’re  getting  the 
benefit  of  a  feature  when  in  fact  you 
aren’t. 

Borland’s  Turbo  C++  is  the  finest 
implementation  of  a  C++  compiler  I 
have  seen.  This  article  examines  how 
successful  Borland  was  in  implement¬ 
ing  C++,  using  as  example  C++  '2.0 
features  such  as  multiple  inheritance 
and  pointers  to  members  to  create  a 
“collection”  class  that  counts  keywords 
and  identifiers  in  a  C++  program. 


Bruce  is  the  author  of  Using  C++ 
(Osborne/McGraw-Hill,  1989),  a  vot¬ 
ing  member  of  the  ANSI  C++  committee 
(X3J16),  and  the  owner  of  Revolution2, 
a  firm  specializing  in  C++  training 
and  consulting.  He  is  the  C++  editor/ 
columnist  for  The  C  Gazette  and  was 
a  contributing  writer  for  MicroCornu- 
copia  magazine  for  four  years.  Por¬ 
tions  of  this  article  are  based  on  the 
as-yet-unpublishedThe  Tao  of  Objects, 
by  Bruce  Eckel  and  Gary  Entsminger. 


Surveying  the  Turbo  C++  Landscape 

Turbo  C++  provides  full  ANSI  C  com¬ 
patibility  of  Turbo  C  2.0  and  is  fully 
compliant  with  the  C++  2.0  Draft  Ref¬ 
erence  Manual  (.see  the  accompanying 
text  box  for  a  description  of  C++  2.0, 
2.1,  and  the  ANSI  C++  committee).  Of 
particular  interest  is  Turbo  C++’s  sup¬ 
port  for  multiple  inheritance,  type-safe 
linkage,  pointers  to  members,  and  built- 
in  support  for  abstract  classes.  Borland 
has  also  implemented  the  AT&T  C++ 
2.0  iostream  package,  as  well  as  the 
older  C++  1.0  streams  (for  backward 
compatibility  with  old  code)  and  the 
complex  class. 

Turbo  C++  comes  with  a  library  of 
classes  intended  to  help  you  build  pro¬ 
grams,  including  useful  classes  such 
as  Dictionary  and  HashTable.  Class  li¬ 
braries  address  the  common  complaint 
among  C++  programmers  (to  wit:  “Fine, 
C++  makes  code  reuse  easier.  Where’s 
the  code  to  reuse?”).  However,  Borland 
made  the  assumption  that  what  was 
good  design  for  Smalltalk  would  be 
good  design  for  C++.  Thus  we  have  the 
ponderous  Smalltalk-like  hierarchy, 
where  everything  is  derived  from  a  base 
class  Object  (no  use  is  made  of  multi¬ 
ple  inheritance),  the  sometimes  irritat¬ 
ing  Smalltalk  names  such  as  theQueue 
and  hash  ValueType  (they’ve  also  made 
the  assumption  that  you  should  be  able 
to  ask  any  object  what  type  it  is,  rather 
than  letting  the  object  worry  about  it’s 
own  behavior),  and  some  rather  strange- 
looking  syntax  (definitely  not  for  nov¬ 
ices).  I  would  have  liked  it  better  had 
Borland  followed  AT&T’s  lead  and  in¬ 
cluded  a  task  library  instead. 


On  the  positive  side,  there’s  source 
code  for  everything,  the  manual  is  on 
disk,  and,  of  course,  you  aren’t  forced 
to  use  the  libraries.  Simple  examples 
show  how  to  use  some  of  the  classes 
(a  sorted  directory  listing  program,  for 
instance). 

Other  Features 

You  can  easily  generate  assembly  out¬ 
put  with  Turbo  C++.  This  can  be  very 
helpful,  especially  if  you  want  to  hand- 
optimize  code  or  create  your  own  as¬ 
sembly  language  routine  to  link  into  a 
C++  program.  The  name-mangling 
scheme  used  is  very  easy  to  read  (an 
aside:  When  you  get  linker  error  mes¬ 
sages,  the  names  are  automatically  un¬ 
mangled  for  you.  Nice!). 

The  Turbo  C  library  is  available  in 
Turbo  C++.  You  can  link  with  assem¬ 
bly  language  and  other  libraries,  in¬ 
cluding  all  those  created  for  the  Borland 
environment  (that  is,  Turbo  Pascal  and 
Turbo  Assembler)  or  with  Microsoft  C. 
Paradox  Engine  code  can  be  linked  in 
with  Turbo  C++,  providing  a  frame¬ 
work  for  some  powerful  C++  database 
applications.  And  I  understand  you  can 
even  link  to  Turbo  Prolog  object  mod¬ 
ules  (even  though  Turbo  Prolog  has 
reverted  to  the  Prolog  Development 
Center,  its  original  creator).  As  usual, 
Borland  encourages  third-party  support. 

The  asm( )  directive  in  C++  is  sup¬ 
ported  in  Turbo  C++;  this  allows  inline 
assembly  code.  You  have  full  control 
of  the  expansion  of  inline  C++  func¬ 
tions;  you  can  turn  inlining  off  if  you 
want  (very  convenient  if  you  go  crazy 
with  inlines  and  later  come  to  your 
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(continued  from  page  94) 
senses).  The  compiler  merges  literal 
strings  to  generate  smaller  programs. 
You  have  full  control  of  the  way  virtual 
tables  are  generated.  Borland  has  been 


careful  not  to  do  anything  to  prohibit 
embedding  Turbo  C++  code. 

Turbo  C++  uses  the  VROOMM  over¬ 
lay  manager  for  building  big  programs 
using  EMS/disk  overlays.  Sadly,  it 


C++  Release  2.0 


In  May  1989,  Bjarne  Stroustrup  (the 
creator  of  C++ )  and  the  team  at  AT&T 
announced  C++  release  2.0  ’and  pro¬ 
vided  the  C++  2.0  Draft  Reference 
Manual  (commonly  referred  to  as  the 
DRM ).  This  was  a  significant  upgrade 
to  the  earlier  release  1.2.  The  largest 
changes  were  the  addition  of  multi¬ 
ple  inheritance  and  type-safe  linkage 
(which,  although  invisible  to  the  pro¬ 
grammer,  prevents  one  of  C’s  more 
subtle  and  obnoxious  errors),  but  a 
number  of  other  smaller  gems  added 
to  the  language  make  a  significant 
difference  in  what  we  can  do. 

Class-by-class  Overloading  of  Op¬ 
erator  new  and  delete  In  release 
1.2,  you  could  only  change  the  activ¬ 
ity  of  the  dynamic  object  creation  op¬ 
erator  new( )  (and  its  complement, 
operator  deletei  ))  on  a  global  basis. 
For  example,  overloading  new  and 
delete  allows  you  to  provide  a  more 
efficient  memory-allocation  scheme. 
This  is  generally  something  you  only 
want  to  do  for  an  individual  class  (one 
you  allocate  and  deallocate  a  lot  of 
objects  for)  so  this  is  a  significant  im¬ 
provement  (also,  you  can  forget  about 
“assignment  to  this").  You  can  also 
create  a  garbage  collector  for  an  indi¬ 
vidual  class;  calling  new  for  that  class 
can  register  the  object  with  your  gar¬ 
bage  collector.  You  can  now  specify 
the  physical  location  in  memory  where 
you  want  an  object  to  be  placed  (espe¬ 
cially  useful  in  embedded  systems  or 
other  hardware-specific  situations). 

Support  for  Abstract  Classes  An 
abstract  class  is  a  base  class  from  which 
you  inherit  a  number  of  derived 
classes.  It  establishes  the  “common 
interface”  to  a  set  of  .polymorphic 
classes.  For  instance,  you  might  cre¬ 
ate  a  class  sortable,  which  defines  a 
type  of  object  that  can  be  sorted.  You 
never  make  any  sortable  objects;  in¬ 
stead  you  make  objects  of  classes  de¬ 
rived  from  sortable  (i.e.,  record).  To 
prevent  the  user  of  a  class  from  creat¬ 
ing  a  sortable  object,  C++  2.0  allows 
you  to  create  “pure”  virtual  functions 
by  setting  the  function  body  to  zero, 
as  in  virtual  int  sort(  )  =  0;.  The  com¬ 
piler  won’t  allow  you  to  create  any 
instances  of  a  class  containing  a  pure 


virtual  function. 

Copying  and  Initialization  If  you 

forget,  or  you  don’t  want  to  define 
an  opera tor( )  or  a  copy-constructor 
X(X&)  for  your  class,  the  2.0  compiler 
now  does  it  for  you.  These  functions 
have  always  been  a  source  of  confu¬ 
sion  for  new  C++  programmers,  but 
they  are  important  when  copying  an 
object  or  passing  it  by  value  into  or 
out  of  a  function. 

More  Operator  Overloading  You 

can  now  overload  the  comma  opera¬ 
tor  and  the  ->  operator  (sometimes 
called  a  “smart  pointer”). 

Const,  Volatile,  and  Static  Mem¬ 
ber  Functions  These  modifiers  al¬ 
low  you  to  change  the  way  the  com¬ 
piler  treats  class  member  functions. 
A  const  member  function  cannot 
change  the  member  data  of  an  object, 
nor  call  another  function  that  does. 
Thus  it  can  be  called  for  a  const  ob¬ 
ject.  Similarly,  a  volatile  member  func¬ 
tion  can  be  called  for  a  volatile  object; 
the  compiler  must  assume  the  object 
may  be  changed  by  outside  forces 
and  thus  cannot  make  any  assump¬ 
tions  about  object  stability  during  op¬ 
timization  of  a  volatile  member  func¬ 
tion.  A  static  member  function  is  like 
an  ordinary  function  except  it  is  part 
of  the  class,  so  its  name  is  hidden  and 
it  can  only  be  called  for  that  class. 
However,  it  cannot  access  any  non¬ 
static  members  of  an  object  (either 
functions  or  data). 

Sophisticated  Initialization  Among 
the  forms  of  initialization  in  2.0,  you 
can  initialize  automatic  and  global 
(“static”)  objects  using  all  kinds  of 
complicated  expressions.  For  example, 
if  record  and  book  are  both  derived 
from  sortable,  you  can  write: 

sortable  *  s[]  =  1 
new  record; 
new  book; 

1; 

Pointers  to  Members  You  can 

take  the  offset  of  a  class  member  and 
pass  it  into  a  function,  which  can  then 
use  that  offset  to  call  a  member  func¬ 
tion  or  modify  member  data.  This  is 
often  used  in  a  function  which  acts 
like  “apply”  in  Lisp  —  it  will  take  the 
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doesn’t  support  the  equivalent  of 
Zortech’s _ handle  pointers  (see  “Get¬ 

ting  a  Handle  on  Virtual  Memory,”  by 
Walter  Bright,  DDJ ,  May  1990)  to  do 
the  same  thing  for  data.  I  think  the 


member  function  of  your  choice  and 
apply  it  to  each  object  in  a  list.  This 
feature  has  actually  been  part  of  the 
language  before  release  2.0,  but  has 
not  been  universally  supported  (Zor- 
tech  2.06,  for  instance,  doesn’t  sup¬ 
port  pointers  to  members;  Zortech 
2.1  does). 

C++  2.1  and  ANSI  C++ 

Release  2.0  was  to  have  been  the 
specification  for  the  language  until 
the  time  that  the  ANSI  C++  committee 
(X3J16)  came  out  with  ANSI  C++.  How¬ 
ever,  Stroustmp  found  some  small  prob¬ 
lems  with  the  language  and  changed 
them  while  in  the  process  of  writing 
the  Annotated  C++  Reference  Man¬ 
ual  (by  Bjarne  Stroustrup  and  Marga¬ 
ret  Ellis,  Addison- Wesley,  1990).  The 
ARM,  as  the  Annotated  Reference  Man¬ 
ual  is  called,  serves  as  the  primary 
base  document  for  the  ANSI  C++  com¬ 
mittee.  AT&T  has  released  version  2.1 
of  its  cfront  C-code  generator  (which 
takes  C++  and  generates  C;  these  have 
sometimes  been  called  translators,  as 
opposed  to  native-code  compilers  like 
Turbo  C++  and  Zortech  C++).  All  this 
happened  rather  suddenly,  so  the  ver¬ 
sion  of  Turbo  C++  I  had  conformed 
to  the  DRM (2.0)  rather  than  the  ARM 
(2.1).  However,  the  changes  are  small 
so  I  expect  conformance  to  2.1  fairly 
soon;  not  having  the  changes  in  re¬ 
lease  2.1  isn’t  inconvenient  and  you 
may  not  even  notice  them  unless  you 
already  know  the  language  quite  well. 

Additional  Changes  In  2.1 

Classes,  enumerations,  and  typedefs 
defined  within  a  class  are  now  local 
to  the  class.  The  conversion  from  a 
pointer  to  derived-class  object  to 
pointer  to  base-class  object  has  been 
clarified.  A  class  with  a  copy-con¬ 
structor  may  be  passed  by  value  to  a 
function  with  an  ellipses  argument 
(although  a  bitcopy  is  done,  rather 
than  a  call  to  the  copy-constructor). 
You  now  delete  arrays  with  delete 
[Ip;.  Notice  that  the  number  of  objects 
in  the  array  is  no  longer  necessary. 
An  object  which  is  created  under  a 
condition  must  be  destroyed  under 
that  condition,  and  cannot  be  accessed 


_ handle  pointer  is  one  of  Walter 

Bright's  more  terrific  ideas.  I’m  hoping 
Borland  will  add  this  in  the  future. 

The  ability  to  set  the  library,  include 
information,  and  command-line  flags 


outside  that  condition  (for  example, 
in  if(x)  fordnt  i  =  10;  i;  i —  )  foo(i); 
you  cannot  access  i  for  the  rest  of  the 
scope). 

Pure  virtual  functions  are  implic¬ 
itly  inherited  as  pure.  Calling  a  pure 
virtual  function  inside  a  constructor 
produces  undefined  behavior,  rather 
than  an  error  message.  Constructors 
with  all  default  values  are  now  con¬ 
sidered  “default”  constructors  (they 
can  be  used  in  places  where  a  con- 
stnictor  with  no  arguments  is  required, 
for  example,  arrays  definitions).  You 
can  define  built-in  types  as  if  they  had 
constructors;  for  example,  int  i(5); 
(similarly  for  destructor  calls). 

Resolution  of  function  overloading 
has  been  clarified  and  improved.  You 
can  distinguish  between  pre-  and  post¬ 
fix  operator  ++  and  — .  Unions  can 
have  private  and  protected  members. 
delete  cannot  be  used  on  a  pointer  to 
a  const,  friend  functions  are  forced  to 
be  extern  (publicly  visible).  Base  classes 
may  be  inherited  as  protected.  An  ex¬ 
plicit  destructor  call  p->X::  '  X(  )  calls 
X’s  destructor  even  if  it’s  virtual,  while 
p->  ~  X(  )  uses  the  virtual  mechanism. 

Your  Comments  and  Suggestions 

The  ANSI  C++  committee  had  its  first 
meeting  March  12  -  16  in  New  Jersey 
and  the  second  July  9  -  12  in  Seattle. 
Written  public  suggestion  and  com¬ 
ment  is  invited  (in  fact,  it’s  an  integral 
part  of  the  process).  The  committee 
expects  to  finish  its  work  in  roughly 
three  years  (since  it  has  a  running 
start  with  the  ARM  and  the  ANSI/ISO 
C  specs).  The  major  extensions  that 
will  likely  be  added  by  the  ANSI  com¬ 
mittee  include  exception  handling  and 
parameterized  types  (implementations 
of  which  you  may  see  before  the  com¬ 
mittee  is  complete).  Send  suggestions 
and  comments  to: 

Dmitry  Lenkov 

X3J16  Committee  Chair 

HP  California  Language  Lab 

19447  Pnineridge  Avenue,  MS:  47LE 

Cupertino,  CA  95014 

email:  dmitry%hpda@hplabs.hp.com 

—  B.E. 
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in  the  TURBOC.CFG  file  is  excellent! 
This  immediately  eliminates  all  the  path 
collision  and  environment-space  prob¬ 
lems  you  have  when  running  more 
than  one  C++  compiler  on  your  ma¬ 
chine  (I  do  this  when  I  want  to  test 
correctness).  Turbo  C++  will  also  swap 
the  symbol  table  to  extended  memory 
or  EMS  for  compilations. 

Although  (as  with  all  C++  implemen¬ 
tations)  there  are  limitations  on  what 

You  can’t  always 
determine  how  many 
and  what  type  of  objects 
you  need  while  you’re 
writing  a  program 


the  C++  compiler  will  actually  inline, 
there  are  far  fewer  restrictions  on  what 
the  compiler  will  accept  in  an  inline 
statement.  For  instance,  Turbo  C++ 
would  accept  static  variables  and  “em¬ 
bedded”  return  statements  (those  that 
aren’t  at  the  end  of  the  function)  in 
inline  functions,  while  Zortech  and 
cfront  wouldn’t. 

Programmer's  Platform 

A  Borland  language  product  wouldn’t 
be  complete  without  the  Integrated  De¬ 
velopment  Environment  (IDE).  The  IDE 
includes  everything  you  need  to  edit, 
compile,  link,  and  debug  programs. 
This  time,  however,  the  IDE  has  been 
completely  reworked  with  multiple  over¬ 
lapping  windows  you  can  reshape  and 
move  around  the  screen.  Other  fea¬ 
tures  include  a  hypertext-style  help  sys¬ 
tem,  the  ability  to  copy  code  fragments 
from  the  help  system  to  the  editor,  and 
more.  For  those  of  you  who  can’t  seem 
to  get  by  without  rodents,  there’s  full 
mouse  support.  And,  a  nice  interactive 
tour  teaches  you  how  to  use  the  IDE 
features. 


Example  1:  Macro  that  puts  void  at  the 
the  point  where  you  invoked  it. 


The  “Turbo  Editor  Macro  Language” 
(TEML),  a  very  readable  scripting  lan¬ 
guage  that  looks  like  a  bastardization 
of  Pascal  and  C,  lets  you  use  macro 
scripts  to  write  customizations.  For  in¬ 
stance,  you  can  rebind  all  your  keys 
when  the  editor  starts  up,  grab  class 
names  and  member  function  prototypes, 
pop  to  another  file  and  append  the 
class  name  to  a  : :  and  the  function  pro¬ 
totype  to  create  a  definition  stub,  and 
so  on.  The  macros  are  compiled  with 
the  “Turbo  Editor  Macro  Compiler” 
(TEMC),  which  avoids  many  of  the 
speed  problems  associated  with  inter¬ 
preted  macro  languages.  You  can  cre¬ 
ate  named  macros  (with  arguments) 
and  you  can  bind  those  macros  to  keys; 
you  can  also  just  tie  a  set  of  statements 
to  a  key  without  a  name.  There  are 
over  140  built-in  commands  to  work 
with.  Example  1  shows  a  simple  exam¬ 
ple  of  a  macro  which  puts  void  at  the 
beginning  of  a  line,  then  returns  to  the 
point  where  you  invoked  it.  Unfortu¬ 
nately,  it  is  difficult  to  determine  from 
the  documentation  the  limitations  of 
TEML. 

The  IDE  also  has  a  built-in,  small 
version  of  the  Turbo  Debugger,  which 
displays  C++  source  code  as  you’ve 
typed  it  in  (no  messes  from  name  man¬ 
gling)  and  allows  you  to  perform  vari¬ 
ous  debugging  feats. 

Turbo  Professional 

The  full-blown  debugger  (provided  with 
the  Turbo  Professional,  or  sold  sepa¬ 
rately  with  the  Turbo  Debugger  and 
Tools  package)  is  a  step  forward  in 
debugger  technology.  It’s  better  than 
anything  I’ve  seen  (although  I  admit  I 
never  had  the  patience  to. figure  out 
CodeView).  I  didn’t  need  to  use  the 
manual  much  at  all,  since  the  menus 
and  help  system  are  so  good.  The  de¬ 
bugger  can  use  80386  protected  mode 
by  loading  a  special  device  driver;  this 
allows  viewing  assembly  language  af¬ 
ter  a  hard  crash.  I  particularly  like  the 
traceback  feature;  you  can  use  the  ani¬ 
mation  feature  to  automatically  step 
until  the  program  crashes,  then  trace 
back  and  see  its  last  thoughts  (although 
it  would  be  nice  if  you  could  speed 


beginning  of  a  line,  then  returns  to 


macro  InsertVoid 

SetMark(O);  /*  save  our  place  */ 
LeftOfLine; 

Insert Text ( " void  " ) ; 

MoveToMark (0) ;  /+  restore  the  place  */ 

end;  /*  end  of  macro  InsertVoid  */ 

Alt-V  :  InsertVoid;  /*  bind  to  key  */ 


98 

730 


Dr.  Dobb’s Journal,  August  1990 


PROGRAMMER'S  WORKBENCH 


( continued  from  page  98) 
up  animation  in  this  process  by  elimi¬ 
nating  screen  updates).  The  display  of 
class  hierarchy  is  fine,  but  it  isn’t  much 
use  by  itself;  perhaps  the  debugger  is 
the  wrong  place  for  it  —  you  want  to 
see  hierarchies  while  you’re  writing 
code,  not  while  you’re  debugging  it. 

The  Turbo  Profiler  (also  part  of  the 
professional  package)  should  alleviate 
any  concerns  you  have  about  potential 
performance  differences  with  C.  It  seems 
to  me  the  benefit  of  optimizers  is  over¬ 
stated.  An  optimizer  doesn’t  have 
enough  information  to  make  a  large 
difference  in  execution  speed.  If  you 
can  find  the  place  where  your  program 
is  spending  all  its  time,  you  can  go  in 
and  optimize  that  section  by  hand,  rather 
than  letting  the  compiler  sprinkle  po¬ 
tentially  useless  speed  improvements 
throughout  the  program.  You  can  think 
of  the  profiler  as  attacking  the  problem 
from  the  opposite  end,  and  the  im¬ 
provements  in  speed  are  potentially  far 
more  dramatic  than  what  you  will  see 
with  an  optimizer.  Don’t  underestimate 
the  value  of  this  tool. 

Taking  Up  A  Collection 

The  code  presented  in  this  section  dem¬ 
onstrates  several  concepts  programmers 
new  to  C++  should  understand.  These 
concepts  include: 

•  Collections,  which  support  a  dynamic 
style  of  programming; 

•  Multiple  inheritance,  so  that  classes 
can  be  derived  from  more  than  one 
base; 

•  Pointers  to  members,  which  let  you 
delay  the  selection  of  a  member  (func¬ 
tion  or  data)  until  run  time. 

The  classes  created  here  are  simple  but 
powerful.  The  example  that  illustrates 
them  is  used  to  count  the  keywords 
and  identifiers  in  a  C++  source  file. 

A  collection  is  an  object  which  holds 
an  arbitrary  number  of  other  objects. 
Basically,  it’s  just  a  bag  you  can  throw 
things  into  and  fish  them  out  later.  The 
reason  collections  are  so  important  is 
that  they  support  a  dynamic  style  of 
programming.  You  can’t  always  deter¬ 
mine  how  many  and  what  type  of  ob¬ 
jects  you  need  while  you’re  writing  a 
program  (although  you  may  be  in  the 
habit  of  trying  to  figure  it  out).  In  the 
general  case,  these  things  can  only  be 
established  at  run  time.  Thus,  objects 
must  be  created  and  destroyed  on-the- 
fly,  using  dynamic  object  creation  (via 
the  operators  new  and  delete ).  While 
you’re  working  with  these  objects,  you 
need  some  place  to  stash  them  —  that’s 
where  the  collection  comes  in. 

You’re  probably  familiar  with  linked 


lists,  stacks,  queues,  and  trees;  these 
are  all  prototypical  collections  in  non¬ 
object-oriented  languages.  The  collec¬ 
tion  in  Listing  One,  page  132,  looks 
vaguely  like  a  singly-linked  list.  I  like 
it  precisely  because  it  is  so  simple,  but 
you  may  have  to  stare  at  it  a  while  to 
figure  out  exactly  how  it  works. 

The  first  definition  is  a  struct  called 
item ,  which  only  contains  a  virtual  des¬ 
tructor.  Any  object  you  want  to  put  into 
a  collection  should  be  derived  from 

A  really  good  class 
library  is  carefully 
designed  and 
redesigned  and  tested 
through  use 


item  so  that  collection  can  “own”  the 
items  it  holds:  When  it  wants  to  destroy 
the  item,  the  proper  destructor  is  called 
(note  that  ownership  isn’t  always  so 
clear  cut  —  in  some  situations  an  ob¬ 
ject  is  contained  in  more  than  one  list). 

A  collection  is  a  chain  of  holder  ob¬ 
jects.  Each  holder  is  a  link  in  the  chain; 
it  has  a  pointer  to  an  item  and  a  pointer 
to  the  next  holder.  Initializing  a  holder 
is  simply  setting  its  two  pointers.  Note 
that  although  struct  holder  is  defined 
inside  class  collection ,  holder  is  a  global 
name  in  C++  2.0  (but  hidden  in  C++ 
2.1). 

A  collection  object  just  contains  two 
holder  pointers  —  one  called  head , 
which  points  to  the  top  of  the  list,  and 
one  called  cursor ;  which  moves  through 
the  list  and  points  to  the  holder  we’re 
currently  interested  in.  Initializing  a  col¬ 
lection  means  setting  its  two  pointers 
to  NULL  (to  indicate  the  list  is  empty). 
Cleaning  up  the  list  is  more  complex; 
we  must  go  to  the  head  and  move 
through  the  list  until  it’s  empty,  delet¬ 
ing  each  item  and  holder  in  the  list. 
Here  you’ll  need  to  ponder  the  code 
and  the  comments,  imagining  what’s 
going  on.  Sometimes  it  helps  to  draw 
pictures. 


item  *  i  =  c. reset  (); 
while  (i)  { 

//do  something 
i  =  c . next ( ) ; 

} 


Example  2:  Stepping  through  a 
typical  collection. 


Adding  a  new  item  to  a  collection  is 
the  slickest  part  of  the  whole  class. 
Make  a  new  holder  using  the  current 
head  pointer  and  the  new  item  pointer 
as  arguments.  The  value  returned  by 
new  (the  address  of  the  newly  created 
holder)  becomes  the  new  value  for 
head.  In  one  statement  the  list  expands, 
just  like  yeast  budding  a  new  cell  (this 
is  the  add( )  function).  Because  add( ) 
is  inline,  adding  an  element  is  amaz¬ 
ingly  fast. 

Stepping  Through  a  Collection 

You  step  through  a  collection  using  the 
reset( )  and  next( )  commands,  each 
of  which  returns  a  pointer  to  the  cur¬ 
rent  item ,  or  NULL  if  we’re  at  the  end 
of  the  list.  For  a  collection  c,  use  the 
commands  as  shown  in  Example  2.  If 
the  list  is  empty,  resetC )  returns  NULL 
and  the  while  loop  is  never  entered. 
Note  that  in  both  resetC )  and  nextC  ), 
we  must  take  care  not  to  return  an 
item*if  cursor  is  NULL-,  this  is  taken  care 
of  by  the  ternary  if-else  statement  (? 
and  :).  In  next( ),  we  must  not  move 
forward  if  cursor  is  NULL. 

Multiple  Inheritance 

In  a  “pure”  object-oriented  language 
such  as  Smalltalk,  everything  is  an  ob¬ 
ject.  All  objects  have  as  their  base  the 
same  class  (called  “object”  or  “root” 
or  something  like  that).  Collections  in 
Smalltalk  are  usually  part  of  the  exist¬ 
ing  system;  you  don’t  have  to  make 
them  yourself.  They  are  designed  to 
hold  any  type  of  object,  thus  they  usu¬ 
ally  hold  root  objects,  or  something 
close  to  root  in  the  inheritance  tree. 

The  need  for  multiple  inheritance  is 
not  obvious  in  a  system  like  this;  multi¬ 
ple  inheritance  allows  you  to  combine 
the  characteristics  of  two  or  more 
classes,  but  in  Smalltalk  all  objects  al¬ 
ready  have  a  lot  of  things  in  common. 
Now,  consider  C++  where  classes  are 
often  made  from  scratch  instead  of  be¬ 
ing  inherited  from  some  master  root 
class.  What  happens  if  you  have  two 
predefined  classes  (which  you  can’t  or 
don’t  want  to  change)  that  must  be 
combined  into  one?  As  an  example, 
consider  a  relatively  simple  class  that 
holds  a  word  and  compares  it  to  text 
strings,  incrementing  a  counter  if  there 
is  a  match.  Since  we’re  defining  the 
word  class  right  here  we  could  have 
inherited  it  from  item ,  but  imagine  it 
has  been  created  by  someone  else  and 
is  much  more  complicated. 

Now  suppose  you  want  to  make  a 
collection  of  word  objects.  Anything 
that  goes  in  a  collection  must  be  de¬ 
rived  from  item  so  the  collection  can 
“own”  it  and  properly  destroy  it.  But 
word  has  already  been  created,  so  it 
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can’t  be  derived  from  item.  What  we 
need  is  a  way  to  derive  a  new  type 
from  word  and  item  at  the  same  time. 
That’s  where  multiple  inheritance  is  es¬ 
sential  in  C++.  You  can  see  it  used  in 
the  creation  of  class  worditem,  which 
is  a  word  that  can  also  be  stored  in  a 
collection.  The  first  main(  )  in  Listing 
One  is  a  simple  demonstration  of  a 
collection  of  worditems. 

Counting  Words 

If  we  want  to  count  instances  of  words 
instead  of  just  adding  each  word  to  the 
list,  we  need  to  modify  the  collection 
class  by  inheriting  it  into  a  new  class 
called  wordcounler.  This  class  is  first 
customized  so  that  add()  only  accepts 
worditem  pointers,  and  reset( )  and 
next( )  only  return  worditem  pointers. 
Although  this  may  look  as  if  you’re 
adding  code,  there’s  actually  no  over¬ 
head  —  the  compiler  does  all  the  work 
by  enforcing  type  checking.  We  then 
add  a  new  function,  add_or_count( ), 
to  class  wordcounter.  This  will  test  a 
string  against  each  word  in  the  list;  if  it 
finds  a  match,  that  word  gets  incre¬ 
mented;  if  not,  it  adds  the  word  to  the 
list. 

Pointers  to  Members 

Finally,  we  add  a  function  called  apply, 
which  uses  pointers  to  members.  These 
are  particularly  useful  for  collections  — 
in  apply( ),  the  function  argument  is 
applied  to  each  member  of  the  list. 
Note  that  a  pointer  to  a  member  func¬ 
tion  looks  a  lot  like  a  pointer  to  a 
function;  it  just  has  the  class  name  and 
the  scope  resolution  operator  added. 
The  apply(  )  function  is  demonstrated 
in  the  second  main( ). 

You  can  imagine  a  more  powerful 
construct:  Consider  an  array  of  point¬ 
ers  to  member  functions.  You  could 
index  into  this  array  to  select  the  de¬ 
sired  member.  Pointers  to  members  can 
also  be  used  to  change  the  behavior 
of  a  “call  back.”  For  example,  with  a 
mouse  event  that  might  cause  the  sys¬ 
tem  to  change  state,  the  next  mouse 
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event  should  cause  something  differ¬ 
ent  to  happen. 

Counting  Identifiers  and  Keywords 

Now  that  we  have  the  desired  class  and 
the  desired  collection,  let’s  use  them 
to  count  the  identifiers  and  keywords 
in  a  C++  source  code  file  (I  tested  it 
on  Listing  One).  The  trick  is  simply  to 
remove  all  the  quoted  strings,  opera¬ 
tors,  comments,  and  constants  and  put 
the  remaining  words  into  our  won icoun- 
ter  collection  by  using  add_or_count( ). 
This  is  accomplished  by  using  the  ANSI 
C  library  functions  strchfi  ),  which  finds 
the  first  instance  of  a  character  in  a 
string,  strstr( ),  which  finds  the  first  in¬ 
stance  of  a  string  within  a  string,  strtok(  ), 
which  breaks  a  string  up  into  tokens 
according  to  the  delimiters  of  your 
choice,  and  strcspnO ,  which  counts 
the  characters  in  the  initial  length  of  a 
string  that  doesn’t  consist  of  characters 
from  your  chosen  string;  this  is  used 
to  determine  if  a  string  is  a  numerical 
constant.  Look  these  up  in  your  ANSI 
C  library  reference  for  further  details. 

I’m  using  standard  I/O  here  instead 
of  bothering  to  open  and  close  files. 
You  have  to  redirect  input  and  output 
on  the  command  line,  but  it  makes  the 
example  simpler. 

In  mnning  TEST3,  notice  that  the  re¬ 
sults  of  the  analysis  are  printed  to  stan¬ 
dard  output  as  the  destructors  are  called 
for  the  worditem  objects  (the  print  state¬ 
ment  is  in  the  word  destructor). 

You  can  easily  create  a  second  type 
of  list  to  hold  keywords.  Initialize  this 
list  with  the  C++  keywords,  then  test 
each  new  word  against  this  list  before 
conditionally  adding  it  to  the  sym¬ 
bol  Jable  list.  This  way  you  can  sepa¬ 
rate  keywords  and  identifiers. 

Note  that  parts  of  Listing  One  will 
compile  with  Zortech  C++  2.06  (if  you 
remove  the  pointers  to  members,  the 
whole  thing  will  compile).  However, 
the  TEST1  code  shows  a  place  where 
Zortech  C++  2.06  has  a  bug  (it  works 
properly  with  cfront  2.0  and  Turbo  C++). 

I  believe  Borland  will  capture  the 
C++  market  in  much  the  same  way 
they  did  the  Pascal  market.  They  are 
just  out  of  the  blocks  with  Turbo  C++ 
and  already  far  ahead  of  everyone  else. 
Other  C++  vendors  will  have  to  come 
up  with  something  pretty  spectacular 
for  me  to  pry  my  clenched  fingers  from 
Turbo  C++. 

DDJ 

(Listing  begins  on  page  132.) 
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Listing  One  ( Text  begins  on  page  16.) 

;  William  F.  Dudley,  Jr. 

;  real  mode  module  callable  from  protected  mode,  passes  string  in 
;  buffer  in  code  segment. 

SEGMENT  BYTE  PUBLIC  'CODE'  usel6 
ASSUME  CS:ss_text  ,  DS: NOTHING  ,  ES: NOTHING 
is  pointed  to  by  DS:SI  with  the  length  in  CX. 
value  of  string  returned  in  AX. 
public  QUERY_FAR 

PROC  FAR 

CALL  QUERY 

RET 
ENDP 

PROC  NEAR 

the  real  mode  dongle  communications  code 
ENDP 

public  _test_string 
db  256  dup  (?) 

public  _end_real 
_end_real  label  byte 

ss_text  ENDS 

END 


End  Listing  One 


Listing  Two 

/*  William  F.  Dudley  Jr. 

*  module  to  connect  real  mode  assembly  code  to  prot  mode  C 
*/ 

♦include  <stdio.h> 

♦include  <dos.h> 

♦include  "list5.h" 

int  real_addr; 
int  real_seg,  real_off; 

♦pragma  aux  QUERY_FAR 

extern  char  test_string; 
extern  char  end_real; 
extern  char  QUERY_FAR;  /* 

short  COMPUTE (char  *str) ; 
int  pr2real (void)  ; 

void  real_setup(void)  { 

real_addr  =  pr2real(); 
real_seg  =  (real_addr  »  16)  &  Oxffff  ; 
real_off  =  real_addr  &  Oxffff  ; 

) 

int  pr2real (void)  { 
union  REGS  r; 
struct  SREGS  sr; 

r.x.ax  =  0x250f;  /*  convert  prot  addr  to  real  addr  */ 

r.d.ebx  =  0;  /*  start  of  program  */ 

r.d.ecx  =  (int) send_real;  /*  length  of  real  mode  stuff  */ 

sr.fs  =  0x3c; 

sr.es  =  Ds () ; 

sr.ds  =  sr.ss  =  sr.gs  =  0x14; 
sr.cs  =  0x0c; 

int386x (0x21,  &r,  &r,  ssr) ; 
if (r .d.cflag)  { 

fprintf (stderr,  "Error  in  PR2REAL(),  can't  map  address . \n") ; 
fflush (stderr) ; 
exit (1) ; 

) 

return (r.d.ecx) ; 

) 


/*  real  address  of  start  of  real  mode  code  */ 

/*  segment  and  offset  of  real_addr  */ 

/*  tell  Watcom  C  that  no  '_'  is  used  */ 

/*  string  buffer  in  real  mode  module  */ 

/*  end  of  real  mode  code  */ 
actually  a  function,  but  we  just  want  address  */ 

/*  this  is  the  subroutine  that  does  the  work  */ 
/*  initialize  value  of  real_addr,  etc.  */ 


ss_text 

;  The  string 
;  encryption 

QUERY_FAR 

QUERY_FAR 

QUERY 

;  here  lives 
QUERY 

_test_string 


short  COMPUTE (char  *str)  ( 
union  REGS  r; 
struct  phregs  pr; 
unsigned  short  i; 
unsigned  j; 
r.x.ax  =  0x2510; 
r.d.ebx  =  realaddr; 
r.x.bx  =  ( int ) &QUERY_FAR; 
r.d.ecx  =  0; 
r.d.edx  =  (int)Spr; 
pr.ECX  =  strlen(str); 
i  =  real_off  +  (int) &test_string; 
j  =  i  +  (real_seg«4) ;  /*  calculate  address  in  selector  0x34  */ 

blk_mv_pr (str,  0x34,  j,  pr.ECX);  /*  copy  string  to  buffer  in  real  CS  */ 
r.x.si  =  i;  /*  DS:SI  points  to  string  */ 

pr.ES  =  pr.DS  =  real_seg; 
int386(0x21,  &r,  Sr) ; 
return (r.x.ax) ; 


call  function  */ 

get  segment  of  real  mode  stuff  */ 

EBX  is  address  of  QUERY_FAR  subroutine  */ 
0  words  on  stack  */ 


/*  DS:EDX  is  address  of  register  struct  */ 
/*  CX  is  length  of  string  */ 


End  Listing  Two 
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Listing  Three 

;  William  F.  Dudley  Jr. 

;  copy  from  real  to  protected  or  vice-versa 

;  void  blk_mov_pr (char  *bufadr,  unsigned  reg_seg,  unsigned  reg_off,  unsigned 


count ) ; 

;  type  variable  is  in: 

;  char  *bufadr  EAX 

;  uint  reg_off  EBX 

;  uint  count  ECX 

;  uint  reg_seg  EDX 


;  Transfers  COUNT  bytes  from  the  buffer  (in  the  current  data  seg)  bufadr 
;  to  address  in  protected  memory  at  reg_seg:reg_off . 

NAME  blk_mov 
EXTRN  _ STK: WORD 

_TEXT  SEGMENT  PUBLIC  BYTE  USE32  'CODE' 

ASSUME  CS:_TEXT 

PUBLIC  blk_mov_pr_ 

PUBLIC  blk_mov_rp_ 

;  protected  to  real 
blk_mov_pr_  proc  near 

pushf 

push  EDI 

push  ESI 

push  ES 

jecxz  nonl 

cld 

;  count  is  in  ECX  already 
mov  ESI,  EAX  ; bufadr  is  source 

mov  ES,  DX  ;reg_seg  is  dest  (ES:EDI) 

mov  EDI,  EBX  ;reg_off  is  dest 

rep  movsb 

nonl :  pop  ES 

pop  ESI 

pop  EDI 

popf 
ret 

blk_mov_pr_  endp 

;  real  to  protected 
blk_mov_rp_  proc  near 

pushf 

push  EDI 

push  ESI 

push  ES 

push  DS 

jecxz  non2 

cld 

push  DS 

pop  ES 

; count  is  in  ECX 
mov  EDI, EAX 

mov  DS , DX 

mov  ESI, EBX 

repe  movsb 

non2 :  pop  DS 

pop  ES 

pop  ESI 

pop  EDI 

popf 
ret 

blk_mov_rp_  endp 

_TEXT  ENDS 
END 


End  Listing  Three 


Listing  Four 

/*  William  F.  Dudley  Jr.  */ 

♦include  <stdio.h> 

♦include  <dos.h> 

♦include  <process.h> 

♦include  <io.h> 

♦include  "lists. h”  /*  dud's  driver  interface  constants  */ 

/*  map  of  real  mode  link  (call  buffer)  memory: 

*  rel  address  name  comment 

*  0  rcolortable  pointer  to  128  bytes  for  color  table  storage 

*  128  qpixel  pointer  to  MAXB  (8500)  bytes  for  pixel  storage 

*/ 

♦define  MAXB  8500 

int  mblocks;  /*  no  of  save/restore  blocks  */ 

static  int  ddi_allocated  =  0;  /*  true  if  initialization  has  been  performed  */ 

static  int  rcolortable;  /*  real  mode  address  of  colortable  (intermode  buf)  */ 

static  int  qpixel;  /*  real  mode  address  of  line  storage  space  */ 

int  nsegment,  noffset;  /*  line  storage  segment  &  offset  */ 

static  short  psegment;  /*  protected  address  of  pixel  buffer  */ 

static  int  poffset;  /*  protected  address  of  pixel  buffer  */ 

extern  int  vectnum;  /*  ddi  interrupt  vector  (usually  0x7A)  */ 

extern  void  pdintinit (void) ;  /*  setup  for  pdinterpO  */ 

static  int  blocksizes [100] ;  /*  array  of  saved  blocks  for  save/rstr  scrn  */ 

/*  sets  video  mode  and  initializes  the  video  parameters  */ 
void  setvmode (void) 

{ 

union  REGS  r; 
struct  SREGS  sr; 
int  i; 

(Listing  continued  on  page  106 ) 


; bufadr  is  dest  (ES:EDI) 
;reg_seg  is  source  (DS:ESI) 
;reg_off  is  source 
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Listing  Four  (Listing  continued,  text  begins  on  page  16.) 

char  paltbl[64];  /*  driver  will  dump  palette  here.  */ 


if ( ! ddi_allocated)  { 

r.x.ax  =  0x2 5 Od;  /*  get  real  mode  link  information  */ 

/*  segment  regs  must  all  have  legal  values  in  them. 

*  These  values  are  documented  in  the  Phar-Lap  Extender  manual 
*/ 

sr.fs  =  0x3c; 

sr.ds  =  sr.ss  =  sr.es  =  sr.gs  =  0x14;  /*  the  data  "segment"  */ 
sr.cs  =  0x0c;  /*  the  code  "segment"  */ 

int386x (0x21,  Sr,  Sr,  ssr) ; 

/*  esredx  =  protected  address  of  call  buffer  */ 

rcolortable  =  r.d.ebx;  /*  ebx  =  real  address  of  call  buffer  */ 

poffset  -  r.d.edx;  /*  save  protected  offset  to  table  start  */ 

psegment  =  sr.es;  /*  psegment  =  0x60  in  Phar-World  */ 

qpixel  =  rcolortable  +  128; 

reset_lines() ; 

if (r .d.ecx  <  (MAXB  +  MAXCOLORS))  (  /*  ecx  =  size  of  buffer  */ 

fprintf (stderr, "real  mode  buffer  isn't  big  enough:  %d\n",  r.d.ecx); 
abort ( ) ; 


} 

r.h.ah  =  KINIT1; 

r.x.bx  =  (rcolortable  »  16)  S  Oxffff;  /*  segment  of  real  mode  buf  */ 

r.x.cx  =  rcolortable  S  Oxffff;  /*  offset  of  real  mode  buf  */ 

r.x.si  =  r.x.di  =  0;  /*  clear  so  we  can  tell  if  they  are  set  */ 

int86 (vectnum,  Sr,  Sr); 

/*  The  registers  have  various  video  constants  in  them.  The  code  that 
*  uses  them  is  not  shown  for  clarity. 

*/ 

if ( Ir.x.si  &&  Ir.x.di)  (  /*  if  driver  does  not  return  its  address  */ 

fprintf (stderr,  "old  driver  installed,  you  need  current  version! \n") ; 
exit  (1) ; 

prot . vidf n . addr ( 1 ]  =  r.x.si;  /*  real  mode  address  of  video  entry  */ 

prot.vidfn.addr [0]  =  r.x.di; 
pdintinit () ; 
listinit () ; 

color jnask  =  (int)r.h.al  -  1; 
if ( ! ddi_allocated)  ( 

/*  copy  from  real  to  prot  bufr  */ 
blk_mv_rp(paltbl,  psegment,  poffset,  64); 

/*  copy  array  of  chars  to  array  of  ints  */ 

for  (i=0  ;  i  <=  color_mask  ;  i++  )  colortable  [i]  =■=  (int)paltbl  [i]  ; 

} 


r.h.ah  =  KINIT2; 

r.h.al  =■  0;  /*  don't  switch  modes  */ 

int86  (vectnum,  Sr,  Sr); 

/*  The  registers  have  various  video  constants  in  them.  The  code  that 
*  uses  them  is  not  shown  for  clarity. 

*/ 

mblocks  =  r.h.dl;  /*  number  of  blocks  to  save  screen  */ 

ddi  allocated  =  TRUE; 


void  reset_lines  () 

{ 

nsegment  =  (qpixel  »  16)  S  Oxffff; 
noffset  =  qpixel  S  Oxffff; 
return; 

} 

/*  Restore  Video  Buffer,  returns  status  */ 
int  rstr_vfc>uf (void) 

{ 

union  REGS  r; 

int  i,  1; 

int  rtncode  =  0; 

char  bbuf [8200] ; 

char  *lbuf; 

lbuf  =  (char  *)bbuf; 

if  (vbfnum!=NULL)  rtncode=lseek (vbfnum, 0L, 0) ;  /*  beg  of  file  */ 

else  return (OKAY) ; 

r.h.ah  =  INITDMP;  /*  init  driver  */ 

r.h.al  =  SWRITE; 

#ifdef  _ 386 _ 

r.x.bx  =  nsegment; 
r.x.cx  =  noffset; 

#else 

r.x.bx  =  FP_SEG(lbuf) ; 
r.x.cx  =  FP_OFF (lbuf) ; 
lendif 

int86 (vectnum,  Sr,  Sr) ; 

/*  now  restore  screen  */ 

for(i  =  0  ;  i  <  mblocks  ;  i++  )  { 

rtncode=read (vbfnum,  lbuf,  blocksizes [i] ) ; 
if(rtncode<=  0)  return (ERROR) ; 
r.h.ah  =  KDUMP; 

fifdef  _ 386 _ 

1  =  (blocksizes [i]  <  8192)  ?  blocksizes [i]  :  8192  ; 

blk_mv_pr (bbuf,  psegment,  poffset+128,  1);  /*  copy  from  prot  to  real  */ 

#endif 

int86 (vectnum,  Sr,  Sr); 

} 

return (OKAY) ; 

) 

/*  clear  the  draw  list  */ 
void  listinit (void)  { 
prot.list(0] [0]  =  0; 
prot.lp  =  0; 
list_p  =  prot. list [0] ; 

} 

End  Listing  Four 

(Listings  continued  on  page  108.) 
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Listing  Five  (Listing  continued,  text  begins  on  page  16.) 

/*  William  F.  Dudley,  Jr. 

*  macros  for  getting  to  the  driver  from  an  application 
*/ 

extern  int  vectnum; 

int  Ds(void);  /*  what  is  value  of  DS  register  */ 

♦pragma  aux  Ds  =  \ 

0x8c  0xd8  /*  mov  ax,  ds  */  \ 

modify  [AH  AL] ; 

/*  register  arrangement  for  Phar-Lap  function  0x2510  */ 
struct  phregs  { 

unsigned  short  DS; 
unsigned  short  ES; 
unsigned  short  FS; 
unsigned  short  GS; 
int  EAX; 
int  EBX; 
int  ECX; 
int  EDX; 

}  ; 

♦define  LLEN  100  /*  assembly  language  module  must  agree  with  this  */ 

♦ifndef  PDINTERP 

extern 

♦endif 

struct  { 
union  { 

int  {*  p) ();  /*  this  is  for  human  info  only,  we  never  call  it  */ 
short  int  addr[2];  /*  [0]seg  and  [ 1 ] off  of  driver  entry  point  */ 
)  vidfn  ; 
short  int  lp; 
short  int  list [LLEN] [6] ; 

)  prot  ; 

♦ifndef  PDINTERP 

extern 

♦endif 

short  int  *list_p; 
void  listinit (void) ; 
void  pdinterp (void) ; 

void  kdidraw (short  int, short  int, short  int, short  int, short  int, short  int); 

/*  tell  Watcom  C  how  to  use  registers  for  arguments  */ 

♦pragma  aux  kdidraw  parm  [EAX]  [EBX]  [ECX]  [EDX]  [ESI]  [EDI]; 

/*  move  to  xl,yl,  route/line  width  will  be  w  */ 

♦define  M(xl,yl,w)  kdidraw  ( (KMOVE«8) ,  xl,  yl,  w,  0,  0) 

/*  put  dot  at  xl,  y,  color  c,  atrib  at  */ 

♦define  DOT  (xl,  yl,  c,  at)  kdidraw (at+ (KWD0T«8) ,  xl,  yl,  c,  0,  0) 

/*  draw  line  from  M  point  to  xl,yl,  color  c,  atrib  at  */ 

♦define  D(xl,yl,c,at)  kdidraw (at+ (KDRAW«8) ,  xl,  yl,  c,  0,  0) 


Listing  Six 


End  listing  Five 


;  William  F.  Dudley,  Jr. 

;  "porting  a  large  application  to  386  protected  mode" 

;  This  is  the  protected  mode  function  that  stuffs  draw  commands 
;  in  the  draw  list.  If  the  list  fills  up,  it  automatically  calls 
;  pdinterp ()  to  empty  it. 


LLEN  EQU 
DGROUP 
TEXT 


kdidraw  : 


NAME  storlist 
EXTRN  pdinterp_: WORD 
EXTRN  _p rot : WORD 

EXTRN  _list_p:WORD 

100  ;  size  of  draw  list,  must  agree  with  C  version. 

GROUP  CONST, _DATA,_BSS 
SEGMENT  PUBLIC  BYTE  USE32  'CODE' 

ASSUME  CS:_TEXT,DS: DGROUP 
PUBLIC  kdidraw_ 

;  args  in  ax,  bx,  cx,  dx,  si,  di 

;  global  list  pointer  in  _list_p  is  incremented  by  12 


push  esi 

mov  si, ax 

mov  eax,dword  ptr  _list_p 
mov  word  ptr  [eax],si 

mov  word  ptr  [eax+2],bx 

mov  word  ptr  [eax+4],cx 

mov  word  ptr'  [eax+6],dx 

pop  esi 

mov  word  ptr  [eax+8],si 


;save  si 
; save  ax 


;  get  back  si 


mov 

word  ptr  [eax+10],di 

add 

eax,  12 

mov 

dword  ptr  _list_p,eax 

inc 

word  ptr  _prot+4H 

cmp 

word  ptr  prot+4H, LLEN-3 

jle 

LI 

call 

near  ptr  pdinterp_ 

jmp 

short  L2 

LI: 

mov 

word  ptr  [eax],0000H 

L2: 

ret 

_TEXT 

ENDS 

CONST 

SEGMENT 

PUBLIC  WORD  USE32  'DATA' 

CONST 

ENDS 

DATA 

SEGMENT 

PUBLIC  WORD  USE32  'DATA' 

DATA 

ENDS 

BSS 

SEGMENT 

PUBLIC  WORD  USE32  'BSS' 

BSS 

ENDS 

END 

End  Listing  Six 


108 

736 


Dr.  Dobb’s Journal,  August  1990 


listing  Seven 


/*  pdinterp.c  —  William  F.  Dudley,  Jr. 

*  protected  dinterpO  for  Phar-Lap  environment. 

*  this  is  the  protected  half  of  the  draw  list  kdi  processor 
*/ 

♦include  <stdio.h> 

♦include  <dos.h> 

♦define  PDINTERP  1 
♦include  "list5.h" 


extern  int  real_addr;  /*  real  address  o 

extern  int  real_seg,  real_off;  /*  segmen 

extern  char  real;  /*  real  copy  of  v 

extern  char  end_real; 

extern  char  dinterp;  /*'  actually  a  function,  b 
void  pdinterp(void) ; 
int  pr2real (void) ; 

static  union  REGS  pregs; 
static  struct  phregs  pr; 
static  unsigned  short  real_o; 
static  unsigned  abs_adr; 
static  int  pdinitted=0; 

void  pdinterpO  { 
union  REGS  r; 

if(lprot.lp)  return; 

if ( ipdinitted)  pdintinitO; 

/*  copy  list  to  buffer  in  real  code  seg  */ 
blk_mov_pr (&prot,  0x34,  abs_adr,  sizeof (prot) ) ; 
int386(0x21,  Spregs,  &r); 
prot. list (prot. Ip  =  0] [0]  =  0; 
list_p  =  prot. list [0] ; 


/*  real  address  of  start  of  real  mode  code 
/*  segment  and  offset  of  real_addr 
/*  real  copy  of  vidfnp,  lp,  draw  list  */ 


/*'  actually  a  function,  but  we  just  want  address  */ 


void  pdintinit (void)  { 

pregs. x. ax  =  0x2510;  /*  call  function  */ 

pregs. d.ebx  -  real_addr;  /*  get  segment  of  real  mode  stuff  */ 

pregs. x.bx  =  (short  int) Sdinterp;  /*  EBX  is  address  of  dinterp  subroutine 
pregs. d.ecx  =0;  /*  0  words  on  stack  */ 

pregs. d.edx  =  (int)&pr;  /*  DS:EDX  is  address  of  register  struct  */ 

real  o  =  real  off  +  (short  int)&real; 


abs_adr  =  real_o  +  (real_seg«4) ; 
pregs. x. si  =  real_o+6; 
pr.ES  =  pr.DS  =  real_seg; 
pdinitted  =  1; 


/*  calculate  address  in  selector  0x34 
/*  DS:SI  points  to  list  */ 


♦if  IN_C 

/*  this  is  a  C  version  of  the  kdidraw()  function  in  list6.asm  */ 
void  kdidraw (short  int  Ax, short  int  Bx, short  int  Cx, short  int  Dx, 

short  int  Si, short  int  Di)  { 

register  short  int  *pi_; 
pi_=prot . list [prot . lp] ; 

*pi_++  =  (short) (Ax); 

*pi_++  =  (short) (Bx) ; 

*pi_++  =  (short) (Cx); 

*pi_++  =  (short) (Dx); 

*pi_++  =  (short) (Si); 

*pi_++  =  (short) (Di); 
if(++prot.lp  >  LLEN-3)  pdinterpO; 
else  *pi_  =  0; 


Listing  Eight 


End  Listing  Seven 


;  William  F.  Dudley,  Jr. 

;  "Porting  a  large  application  to  386  protected  mode" 
;  This  is  the  real  mode  draw  list  interpreter. 

d_text  SEGMENT  BYTE  PUBLIC  'CODE'  usel6 

ASSUME  CS : d_text  ,  DS: NOTHING  ,  ES: NOTHING 


;  size  of  draw  list 


public  _dinterp 
public  _real 
_real  label  word 

db  (12*LLEN+6)  dup  (?) 

_dinterp  proc  far 
call  dint 

ret 

_dinterp  endp 


;  ds:si  points 
dint  proc 
floop:  push 
push 
push 
push 
push 
push 
add 
call 
add 

iftest:  cmp 
jne 
ret 

dint  endp 

d_text  ends 
end 


to  real  array  at  entry 
near 

word  ptr  [si+10] 
word  ptr  [si+8] 
word  ptr  [si+6] 
word  ptr  [si+4] 
word  ptr  [si+2] 
word  ptr  [si+0] 
si, 12 

dword  ptr  cs: [_real] 
sp,  12 

word  ptr  [si+0]  , 0 
floop 


End  Listings 
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Listing  One  (Text  begins  on  page  24.) 

1!  /*  junk.c  —  Junk  list  build/destroy  test 
2!  *  $Log:  E:/vcs/ junk/ junk. c_v  $ 

3 !  *  Rev  1.1  20  Nov  1989  09:42:00  set 

4 !  *  Added  name  field  for  junk  node  tagging 

51  *  Rev  1.0  09  Nov  1989  18:12:30  jvs 

6!  *  Initial  revision. 

7!  */ 

8! 

9!  #include  <stdio.h> 

10!  linclude  <stdlib.h> 

11!  linclude  <string.h> 

12! 

13!  /*  Junk  item  structure  */ 

14 !  typedef  struct  jnod  { 

15!  .  struct  jnod  *junk_next  ; 

16!  char.  *junk_name  ; 

17!  int  junk_data[3000]  ; 

18!  }  JUNK  ; 

19! 

20!  /*  Function  prototypes  */ 

21!  JUNK  * junk_list_build(void)  ; 

22!  void  junk_list_destroy (JUNK  *)  ; 

23!  JUNK  * junk_open (char  *)  ; 

24!  void  junk_close (JUNK  *)  ; 

25! 

26!  /*  main{)  —  Entry  point  for  test  */ 

27 !  void  main () 

28!  { 

29!  JUNK  * jlist  ; 

30! 

31!  while  ((jlist  =  junk_list_build() )  !=  NULL) 

32!  { 

33!  junk_list_destroy( jlist)  ; 

34!  } 

35!  printf("‘*‘  Should  never  get  here!  ***\n")  ; 

36!  } 

37! 

38!  /*  junk_list_build()  —  Build  a  list  of  junk  items  */ 

39!  JUNK  * junk_list_build () 

40!  { 

41!  JUNK  * jlist  ; 

42!  JUNK  * jnew  ; 

43! 

44!  jlist  =  NULL  ; 

45!  while  ((jnew  =  junk_open ("name  to  identify  junkitem"))  !=  NULL) 

46!  ( 

47!  jnew-> junk_next  =  jlist  ; 

48!  jlist  =  jnew  ; 

49!  } 

50! 

51!  return  jlist  ; 

52!  ) 

53! 

54!  /*  junk_list_destroy ()  —  Destroy  a  list  of  junk  items  */ 

55!  void  junk_list_destroy ( JUNK  * jlist) 

56!  { 

57!  JUNK  * jtmp  ; 

58! 

59!  while  (jlist  !=  NULL) 

60!  ( 

61!  jtmp  =  jlist  ; 

62!  jlist  =  jlist->junk_next  ; 

63!  junk_close( jtmp)  ; 

64!  ) 

65!  ) 

66! 

67!  /*  junk_open()  —  Create  a  junk  item  */ 

68!  JUNK  * junk_open (char  *name) 

69!  { 

70!  JUNK  * jnew  ; 

71! 

72!  jnew  =  (JUNK  *)  malloc (sizeof (JUNK) )  ; 

73!  if  (jnew  !=  NULL) 

74!  { 

75!  jnew->junk_name  =  strdup(name)  ; 

76!  if  ( jnew->junk_name  ==  NULL) 

77!  { 

78!  return  NULL  ; 

79!  ) 

80!  ) 

81! 

82 !  return  jnew  ; 

83!  ) 

84! 

85!  /*  junk_close()  —  Close  a  junk  item  */ 

86!  void  junk_close ( JUNK  *jold) 

87!  { 

88!  free(jold)  ; 

89!  } 

End  Listing  One 


Listing  Two 

1!  /*  junk.c  —  Junk  list  build/destroy  test 
2!  *  $Log:  E:/vcs/ junk/ junk. c_v  $ 

3!  *  Rev  1.2  28  Nov  1989  10:13:07  jvs 

4 !  *  Addition  of  memory  shell 

5!  *  Rev  1.1  20  Nov  1989  09:42:00  set 

6!  *  Added  name  field  for  junk  node  tagging 

7!  *  Rev  1.0  09  Nov  1989  18:12:30  jvs 

8!  *  Initial  revision. 

9!  */ 

10! 

11!  linclude  <stdio.h> 

12!  linclude  <stdlib.h> 


13!  linclude  "mshell.h" 

14! 

15!  /*  Junk  item  structure  */ 

16!  typedef  struct  jnod  { 

17!  struct  jnod  *junk_next  ; 

18!  char  *junk_name  ; 

19!  int  junk_data [3000]  ; 

20!  )  JUNK  ; 

21! 

22!  /*  Function  prototypes  */ 

23!  JUNK  * junk_list_build (void)  ; 

24!  void  junk_list_destroy ( JUNK  *)  ; 

25!  JUNK  * junk_open (char  *)  ; 

26!  void  junk_close ( JUNK  *)  ; 

27! 

28!  /*  main()  —  Entry  point  for  test  */ 

29!  void  main () 

30!  { 

31!  JUNK  ‘jlist  ; 

32! 

33!  while  ((jlist  =  junk_list_build() )  !=  NULL) 

34!  { 

35!  junk_list_destroy (jlist)  ; 

36!  if  (Mem_Used()  !=  0) 

37!  { 

38!  printf("*“  Memory  list  not  empty  “*\n")  ; 

39!  Mem_Display (stdout)  ; 

40!  exit(l)  ; 

41!  } 

42!  ) 

43!  printf("“*  Should  never  get  here!  ***\n")  ; 

44!  } 

45! 

46!  /*  junk_list_build()  —  Build  a  list  of  junk  items  */ 

47!  JUNK  *  junk_list_build ( ) 

48!  ( 

49!  JUNK  ‘jlist  ; 

50!  JUNK  ‘jnew  ; 

51! 

52!  jlist  =  NULL  ; 

53!  while  ((jnew  =  junk_open ("name  to  identify  junkitem"))  !=  NULL) 

54!  { 

55!  jnew-> junk_next  =  jlist  ; 

56!  jlist  =  jnew  ; 

57!  ) 

58! 

59!  return  jlist  ; 

60!  ) 

61! 

62!  /*  junk_list_destroy ()  —  Destroy  a  list  of  junk  items  */ 

63!  void  junk_list_destroy ( JUNK  ‘jlist) 

64!  ( 

65!  JUNK  ‘jtmp  ; 

66! 

67!  while  (jlist  !-  NULL) 

68!  ( 

69!  jtmp  =  jlist  ; 

70!  jlist  =  jlist-> junk_next  ; 

71!  junk_close ( jtmp)  ; 

72!  ) 

73!  ) 

74! 

75!  /*  junk_open{)  —  Create  a  junk  item  */ 

76!  JUNK  * junk_open (char  ‘name) 

77!  ( 

78!  JUNK  ‘jnew  ? 

79! 

80!  jnew  =  (JUNK  ‘)  malloc (sizeof (JUNK) )  ; 

81!  if  (jnew  !=  NULL) 

82!  { 

83!  jnew-> junk_name  =  strdup(name)  ; 

84!  if  ( jnew-> junk_name  ==  NULL) 

85!  ( 

86!  return  NULL  ; 

87!  ) 

88!  } 

89! 

90!  return  jnew  ; 

91!  } 

92! 

93!  /*  junk_close()  —  Close  a  junk  item  */ 

94!  void  junk_close ( JUNK  *jold) 

95!  { 

96!  free(jold)  ; 

97!  ) 

End  Listing  Two 


Listing  Three 

i:  /. - 

2!  *++ 

3!  *  mshell.h  —  Dynamic  memory  handler  interface 

4!  *  Description:  mshell.h  provides  the  interface  definitions  for  the 

5!  *  dynamic  memory  handler. 

6!  *  See  mshell.c  for  complete  documentation. 

7!  *+- 

8 !  *  $Log$ 

9!  *— 

10!  */ 

11! 

12!  /*  Compilation  options  */ 

13!  Idefine  MEM_LIST  /*  Build  internal  list  */ 

14!  Idefine  MEM_WHERE  /*  Keep  track  of  memory  block  source  */ 

151 

16!  /*  Interface  functions  */ 

17!  unsigned  long  Mem_Used(void)  ; 

18!  void  Mem_Display (FILE  *)  ; 

19! 

20!  /*  Interface  functions  to  access  only  through  macros  */ 

21!  #if  defined (MEM_WHERE) 
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22!  void 
23!  void 
24!  void 
25!  char 
26!  #else 
27!  void 
28!  void 
29!  void 
30!  char 
31!  #endif 
32! 

33!  /*  Interface  macros  */ 

34!  #if  ! defined  (_MSHELL_) 

35!  #if  defined (MEM_WHERE) 

36!  fdefine  malloc (a)  mem_alloc ( (a) , _ FILE _ , _ LINE _ ) 

37!  fdefine  realloc(a,b)  mem_realloc ( (a) , (b) , _ FILE _ , _ LINE ) 

38!  fdefine  free (a)  mem_free ( (a) , _ FILE _ , _ LINE _ ) 

39!  fdefine  strdup(a)  mem_strdup( (a) , _ FILE _ , _ LINE  ) 

40!  felse 

41!  fdefine  malloc(a)  mem_alloc(a) 

42!  fdefine  realloc (a,  b)  mem_realloc ( (a) , (b) ) 

43!  fdefine  free (a)  mem_free(a) 

44!  fdefine  strdup(a)  mem_strdup(a) 

45!  fendif 
46!  fendif 
47! 

48;  /* - - - */ 


End  Listing  Three 


Listing  Four 

i:  /* . - - - 

2 !  *++ 

3!  *  mshell.c  —  Memory  management  utilities 

4!  *  Description:  mshell.c  contains  routines  to  protect  the  programmer 

5!  *  from  errors  in  calling  memory  allocation/f ree  routines.  The  standard 

6!  *  library  calls  supported  are:  malloc,  realloc,  strdup,  free 

7!  * 

8!  *  The  interface  header  mshell.h  redefines  these  standard  libarary 

9!  *  calls  as  macros.  When  the  client  code  is  compiled,  the  macros  expand 

10!  *  to  calls  to  this  module.  This  module  then  calls  the  system  memory 

11!  *  routines,  with  additional  error  checking. 

12!  * 

13!  *  The  allocation  routines  in  this  module  add  a  data  structure  to  the 

14!  *  top  of  allocated  memory  blocks  which  tag  them  as  legal  memory  blocks. 

15!  * 

16!  *  When  the  free  routine  is  called,  the  memory  block  to  be  freed  is 

17!  *  checked  for  legality.  If  the  block  is  not  legal,  the  memory  list 

18!  *  is  dumped  to  stderr  and  the  program  is  terminated. 


*mem_alloc (size_t,  char  *,  int)  ; 

*mem_rea Hoc  (void  *,  size_t,  char  *,  int)  ; 
mem_free (void  *,  char  *,  int)  ; 
*mem_strdup(char  *,  char  *,  int)  ; 

*mem_alloc (size_t)  ; 

*mem_realloc (void  *,  size_t)  ; 
mem_f ree (void  *)  ; 

*mem_strdup(char  *)  ; 


19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 
56! 
57! 
58! 
59! 
60! 
61! 
62! 
63! 
64! 
65! 
66! 
67! 
68! 
69! 
70! 


*  Compilation  Options 

*  MEM_LIST  Link  all  allocated  memory  blocks  onto  an  internal  list. 

*  The  list  can  be  displayed  using  Mem_Display () . 

*  MEM_WHERE  Save  the  file/line  number  of  allocated  blocks  in  header. 

*  Requires  that  compiler  supports  _ FILE _  and  _ LINE _  preprocessor 

*  directives  and  FILE string  have  static  or  global  scope. 

*  Problems:  If  you  have  any  problems  with  this  module,  please  contact: 

*  Jim  Schimandle,  Primary  Syncretics,  473  Sapena  Court,  Suite  # 6, 

*  Santa  Clara,  CA  95054,  Tel:  (408)988-3818,  Fax:  (408)727-9891 
*+- 

*  $Log$ 

*/ 

fdefine  _ MSHELL _ 

finclude  <stdio.h> 
finclude  <stdlib.h> 
finclude  <string.h> 
finclude  "mshell.h" 

/*  Constants  */ 

fdefine  MEMTAG  0xa55a  /*  Value  for  mh_tag  */ 


/*  Structures  */ 

typedef  struct  memnod  /*  Memory  block  header  info  */ 

{  /* - - -  */ 

unsigned  int  mh_tag  ;  /*  Special  ident  tag  */ 

size_t  mh_size  ;  /*  Size  of  allocation  block  */ 

fif  defined (MEM_LIST) 

struct  memnod  *mh_next  ;  /*  Next  memory  block  */ 

struct  memnod  *mh_prev  ;  /*  Previous  memory  block  */ 

fendif 

fif  defined (MEM_WHERE) 

char  *mh_file  ;  /*  File  allocation  was  from  */ 

unsigned  int  mh_line  ;  /*  Line  allocation  was  from  */ 

fendif 

)  MEMHDR  ; 


/*  Alignment  macros  —  The  macro  ALIGN_SIZE  defines  size  of  the  largest 

*  object  that  must  be  aligned  on  your  processor.  The  RESERVE_SIZE  macro 

*  calculates  the  nearest  multiple  of  ALIGN_SIZE  that  is  larger  than  the 

*  memory  block  header.  Change  ALIGN_SIZE  to  match  alignment  requirements 

*  of  your  processor 
*/ 

fdefine  ALIGN_SIZE  sizeof (double) 
fdefine  HDR_SIZE  sizeof (MEMHDR) 

fdefine  RESERVE_SIZE  ( ( (HDR_SIZE+ (ALIGN_SIZE-1) ) /ALIGN_SIZE)  \ 

*ALIGN_SIZE) 

(Listing  continued  on  page  112) 
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Listing  Four  (Listing  continued,  text  begins  on  page  24.) 

180 

181 

MEMHDR  *p  ; 

71 

/*  Conversion  macros  —  These  macros  convert  the  internal  pointer 

182 

/*  Convert  client  pointer  to  header  pointer  */ 

72 

*  to  a  memory  block  header  to/from  the  pointer  used  by  the  client  code. 

183 

p  =  CLIENT  2  HDR (ptr)  ; 

73 

*/ 

184 

74 

#define  CLIENT  2  HDR(a)  ( (MEMHDR  *)  (((char  *)  (a))  -  RESERVE  SIZE)) 

185 

/*  Check  for  valid  block  */ 

75 

♦define  HDR  2  CLIENT (a)  ((void  *)  (((char  *)  (a))  +  RESERVE  SIZE)) 

186 

if  (p->mh  tag  !=  MEMTAG) 

76 

187 

{ 

77 

/*  Local  variables  */ 

188 

Mem  Tag  Err(p)  ; 

78 

static  unsigned  long  mem  size  =  0  ;  /*  Amount  of  memory  used  */ 

189 

return  NULL  ; 

79 

♦if  defined (MEM  LIST) 

190 

) 

80 

static  MEMHDR  *memlist  =  NULL  ;  /*  List  of  memory  blocks  */ 

191 

81 

fendif 

192 

/*  Invalidate  header  */ 

82 

193 

p->mh  tag  =  ~MEMTAG  ; 

83 

/*  Local  functions  */ 

194 

mem  size  -=  p->mh  size  ; 

84 

void  mem  tag  err (void  *,  char  *,  int)  ;  /*  Tag  error  */ 

195 

85 

♦if  defined (MEM  LIST) 

196 

♦if  defined (MEM  LIST) 

86 

void  mem  list  add (MEMHDR  *)  ;  /*  Add  block  to  list  */ 

197 

mem  list  delete (p)  ;  /*  Remove  block  from  list  */ 

87 

void  mem  list  delete (MEMHDR  *)  ;  /*  Delete  block  from  list  */ 

198 

♦endif 

88 

♦define  Mem  Tag  Err (a)  mem  tag  err (a, fil, lin) 

199 

89 

♦else 

200 

/*  Reallocate  memory  block  */ 

90 

♦define  Mem  Tag  Err (a)  mem  tag  err (a,  FILE  ,  LINE  ) 

201 

p  =  (MEMHDR  *)  realloc (p,  RESERVE  SIZE  +  size)  ; 

91 

♦endif 

202 

if  (p  ==  NULL) 

92 

203 

( 

93 

/****  Functions  accessed  only  through  macros  ***************************/ 

204 

return  NULL  ; 

94 

205 

) 

95 

/* - 

206 

96 

*+ 

207 

/*  Update  header  */ 

97 

*  mem  alloc  —  Allocate  a  memory  block 

208 

p->mh  tag  =  MEMTAG  ; 

98 

*  Usage: 

209 

p->mh  size  =  size  ; 

99 

*  void  * 

210 

mem  size  +=  size  ; 

100 

*  mem  alloc ( 

211 

♦if  defined (MEM  WHERE) 

101 

*  size  t  size 

212 

p->mh  file  =  fil  ; 

102 

*  ) 

213 

p->mh  line  =  lin  ; 

103 

*  Parameters:  size  Size  of  block  in  bytes  to  allocate 

214 

♦endif 

104 

*  Return  Value:  Pointer  to  allocated  memory  block,  NULL  if  not 

215 

105 

*  enough  memory. 

216 

♦if  defined (MEM  LIST) 

106 

*  Description:  mem  alloc ()  makes  a  protected  call  to  mallocO 

217 

mem  list  add(p)  ;  /*  Add  block  to  list  */ 

107 

*  Notes:  Access  this  routine  using  the  mallocO  macro  in  mshell.h 

218 

♦endif 

108 

*_ 

219 

109 

*/ 

220 

/*  Return  pointer  to  client  data  */ 

no 

void  * 

221 

return  HDR  2  CLIENT (p)  ; 

in 

mem  alloc (  ' 

222 

}. 

112 

♦if  defined (MEM  WHERE) 

223 

113 

size  t  size, 

224 

/* - 

114 

char  *fil, 

225 

*  + 

115 

int  lin 

226 

*  mem  strdup  —  Save  a  string  in  dynamic  memory 

116 

♦else 

227 

*  Usage: 

117 

size  t  size 

228 

*  char  * 

118 

♦endif 

229 

*  mem  strdup ( 

119 

) 

230 

*  char  *str 

120 

231 

*  ) 

121 

( 

232 

*  Parameters:  str  String  to  save 

122 

MEMHDR  *p  ; 

233 

*  Return  Value:  Pointer  to  allocated  string;  NULL  if  not  enough  memory 

123 

234 

*  Description:  mem  strdup ()  saves  specified  string  in  dynamic  memory. 

124 

/*  Allocate  memory  block  */ 

235 

*  Notes:  Access  this  routine  using  the  strdup ()  macro  in  mshell.h 

125 

p  =  malloc (RESERVE  SIZE  +  size)  ; 

236 

*  - 

126 

if  (p  ==  NULL) 

{ 

237 

*/ 

127 

238 

128 

return  NULL  ; 

239 

char  * 

129 

} 

240 

mem  strdup ( 

130 

241 

♦if  defined (MEM  WHERE) 

131 

/*  Init  header  */ 

242 

char  *str, 

132 

p->mh  tag  =  MEMTAG  ; 

243 

char  *fil, 

133 

p->mh  size  =  size  ; 

244 

int  lin 

134 

mem  size  +=  size  ; 

245 

♦else 

135 

♦if  defined (MEM  WHERE) 

246 

char  *str 

136 

p->mh  file  =  fil  ; 

247 

♦endif 

137 

p->mh  line  =  lin  ; 

248 

) 

138 

♦endif 

249 

139 

250 

{ 

140 

♦if  defined (MEM  LIST) 

251 

char  *  s  ; 

141 

mem  list  add(p)  ; 

252 

142 

♦endif 

253 

♦if  defined (MEM  WHERE) 

143 

254 

s  =  mem  alloc (strlen (str) +1 ,  fil,  lin)  ; 

144 

/*  Return  pointer  to  client  data  */ 

255 

♦else 

145 

return  HDR  2  CLIENT (p)  ; 

256 

s  =  mem  alloc (strlen (str) +1 )  ;  . 

146 

1 

257 

♦endif 

147 

258 

148 

/* - 

259 

if  (s  !=  NULL) 

149 

*  + 

260 

{ 

150 

*  mem  realloc  —  Reallocate  a  memory  block 

261 

strcpy(s,  str)  ; 

} 

151 

*  Usage: 

262 

152 

*  void  * 

263 

153 

*  mem  realloc ( 

264 

return  s  ; 

154 

*  void  *ptr, 

265 

) 

155 

*  size  t  size 

266 

156 

*  ) 

267 

/* - 

157 

*  Parameters:  ptr  Pointer  to  current  block 

268 

*  + 

158 

*  size  Size  to  adjust  block  to 

269 

*  mem  free  —  Free  a  memory  block 

159 

*  Return  Value:  Pointer  to  new  memory  block;  NULL  if  memory  cannot 

270 

*  Usage: 

160 

*  be  reallocated 

271 

*  void 

161 

*  Description:  mem  realloc ()  makes  a  protected  call  to  realloc (). 

272 

*  mem  free( 

162 

*  Notes:  Access  this  routine  using  the  realloc ()  macro  in  mshell.h 

273 

*  void  *ptr 

163 

*- 

274 

*  ) 

164 

*/ 

275 

*  Parameters:  ptr  Pointer  to  memory  to  free 

165 

276 

*  Return  Value:  None 

166 

void  * 

277 

*  Description:  mem  free()  frees  specified  memory  block.  The  block  must 

167 

mem  realloc ( 

278 

*  be  allocated  using  mem  alloc (),  mem  realloc ()  or  mem  strdup () . 

168 

♦if  defined (MEM  WHERE) 

279 

*  Notes:  Access  this  routine  using  the  free()  macro  in  mshell.h 

169 

void  *ptr. 

280 

*_ 

170 

size  t  size, 

281 

*/ 

171 

char  *fil, 

282 

172 

int  lin 

283 

void 

173 

♦else 

284 

mem  f  ree ( 

174 

void  *ptr, 

285 

♦if  defined (MEM  WHERE) 

175 

size  t  size 

286 

void  *ptr, 

176 

♦endif 

287 

char  *fil, 

177 

) 

288 

int  lin 

178 

289 

♦  else 

179 

{ 

(Listing  continued  on  page  114) 
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Listing  Four  (Listing  continued,  text  begins  on  page . 


/*  Convert  client  pointer  to  header  pointer  */ 
p  =  CLIENT_2_HDR(ptr)  ; 


/*  Check  for  valid  block  */ 
if  (p->mh_tag  !=  MEMTAG) 


Mem_Tag_Err (p) 
return  ; 


/*  Invalidate  header  */ 
p->mh_tag  =  “MEMTAG  ; 
mem_size  -=  p->mh_size  ; 


#if  defined (MEM_LIST) 
mem_list_delete (p)  ; 
#endif 

/*  Free  memory  block  */ 
free(p)  ; 


Functions  accessed  directly 


/*  Remove  block  from  list  */ 


Mem_Used  —  Return  amount  of  memory  currently  allocated 

Usage: 

unsigned  long 
Mem_Used ( 

) 

Parameters:  None. 

Description:  Mem_Used()  returns  number  of  bytes  currently  allocated 
using  the  memory  management  system.  Value  returned  is  simply  the 
sum  of  the  size  requests  to  allocation  routines;  does  not  reflect 
any  overhead  required  by  the  memory  management  system. 

Notes:  None 


unsigned  long 
MemJJsed ( 
void) 


return  mem  size  ; 


Mem_Display  --  Display  memory  allocation  list 
Usage: 

void 

Mem_Display ( 

FILE  *fp 

) 

Parameters:  fp  File  to  output  data  to 

Description:  Mem_Display ()  displays  contents  of  memory  allocation 
list.  This  function  is  a  no-op  if  MEM_LIST  is  not  defined. 
Notes:  None 


void 

Mem  Display ( 
FILE 
) 


#if  defined (MEM_LIST) 

MEMHDR  *p  ; 

int  idx  ; 

#if  defined (MEM_WHERE) 

fprintf(fp,  "Index  Size  File (Line)  -  total  size  %lu\n",  mem_size) 
#else 

fprintf(fp,  "Index  Size  -  total  size  %lu\n",  mem_size)  ; 

#endif 

idx  =  0  ; 
p  =  memlist  ; 
while  (p  !=  NULL) 

{ 

fprintf(fp,  "%-5d  %6u",  idx++,  p->mh_size)  ; 

#if  defined (MEM_WHERE) 

fprintf(fp,  "  %s(%d)",  p->mh_file,  p->mh_line)  ; 

#endif 

if  (p->mh_tag  !=  MEMTAG) 

{ 

fprintf (fp,  "  INVALID")  ; 

) 

fprintf (fp,  "\n")  ; 
p  =  p->mh_next  ; 

} 

#else 

fprintf (fp,  "Memory  list  not  compiled  (MEM_LIST  not  defined) \n")  ; 
#endif 


/****  Memory  list  manipulation  functions  ****** 
/*  mem_list_add()  —  Add  block  to  list  *7 


#if  defined (MEM_LIST) 
static  void 
mem_list_add( 

MEMHDR  *p 

) 


p->mh_next  =  memlist  ; 
p->mh_prev  =  NULL  ; 
if  (memlist  !=  NULL) 

{ 

memlist->mh_prev  =  p  ; 

) 

memlist  =  p  ; 

#if  defined (DEBUG_LIST) 
printf ( "mem_list_add ( ) \n" ) 
Mem_Display (stdout)  ; 
#endif 


/*  mem  list  delete ()  --  Delete  block  from  list  */ 


#if  defined (MEM_LIST) 
static  void 
mem_list_delete ( 
MEMHDR  *p 
) 


if  (p->mh_next  !=  NULL) 

( 

p->mh_next->mh_prev  =  p->mh_prev  ; 
) 

if  (p->mh  prev  !=  NULL) 

{ 

p->mh_prev->mh_next  =  p->mh_next  ; 


memlist  =  p->mh_next 


#if  defined (DEBUG_LIST) 
printf ("mem_list_delete () \n") 
Mem_Display (stdout)  ; 

#endif 


Display  memory  tag  error 


/****  Error  display 

/*  mem_tag_err ()  —  1 
static  void 
mem_tag_err ( 
void  *p 

char  *f 

int  lii 


fprintf (stderr,  "Memory  tag  error  -  %p  -  %s(%d)\n",  p,  fil,  lin) 
#if  defined (MEM_LIST) 

Mem_Display (stderr)  ; 

#endif 
exit(l)  ; 


End  Listings 
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Listing  One  ( Text  begins  on  page  36  ) 

I  This  program  reads  a  C  structure  and  produces  C  code 

#  to  write  the  record  to  a  C-ISAM  work  area. 

#  There  are  limitations  on  the  input  format :  see  sample 


BEGIN  { 


FS  =  "[  \t[]+" 


#  Override  default 

#  field  separators 

#  Opening  record  struct 


#  Struct  within  record 


$1  -=  "struct"  &&  $3  ==  "("  { 
rec  =  $2 

print  "/*  "  $2  " 

offset  =  0 

} 

$2  ==  "struct"  &&  $3  ==  { 

type  =  "struct" 
j  =  0 


$2  ==  "long"  {  f(type  ==  "struct",  "stlong",  .$3,  4) 

$2  ==  "int"  (  f(type  ==  "struct", 

$2  ==  "float"  {  f(type  ==  "struct", 

§2  ==  "double"  {  f(type  ==  "struct", 

§2  —  "char"  &&  NF  >  3  { 

f(type  ==  "struct", 

§2  ==  "char"  &&  NF  ==  3  { 


52  ==  ")" 


f (type 
( 


==  "struct" 


"stint" 

"stfloat", 

"stdbl", 

#  String 
"stchar", 

#  Single  character 
"stchar",  $3,  1) ) 

#  Array  of  structs 


S3,  2)} 

S3,  4)} 

$3,  8)) 

S3,  $4-1)} 


&&  NF  : 
type 

print  "\tfor  (i  =  0;  i  <  "  $4  +  0  i++) 

for  (k  =  0;  k  <  j;  k++)  { 
gsub(";",  "",  name[k]) 
temp  =  $3  "  ( i ]  name[k] 
emit2("\t"  stype[k],  temp,  f len [k ] ) 


print  "\t}" 
offset  +=  ($4 
slen  =  0 


1)  *  slen 


} 


$2  ==  "}"  &&  NF  ==  3  ( 
type  =  "" 

for  (k  =  0;  k  <  j;  k++) 
emit (stype(k) ,  $3 
slen  =  0 

} 

function  f(bool,  str,  x,  y)  ( 
if  (bool) 

setup(str,  x,  y) 

else 

emit (str,  x,  y) 

} 

function  setup (type,  varname,  1)  { 
name(j]  =  varname 
stype [ j]  =  type 
flen ( j++]  =  1 
slen  +=  1 


#  Named  struct 


name[k],  flen(k)) 


#  Save  field  data  in  array 


function  emit (type,  varname,  1)  {  #  Print  C  code  for  field 

gsub(";",  varname) 
print  "\t"  type  "(p."  rec  "->"  varname, 

",  inf_rec  +  "  offset  \ 

(type  ==  "ststring"  ?  ",  "  1  ");"  :  ");") 
offset  +=  1 

} 

function  emit2(type,  varname,  1)  {  #  Print  C  code  for  field  in  struct 

gsub(";",  "",  varname) 
print  "\t"  type  "(p."  rec  varname, 

",  inf_rec  +  i  *  "  slen,  "+", 
offset  (type  “  /string/  ?  ",  "  1  ");":  ");") 
offset  +=  1 

} 


End  Listing 
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Listing  One  (Text  begins  on  page  48.) 

/*  include  all  of  the  files  that  you  might  need.  */ 

♦include  <ctype.h> 

♦include  <memory.h> 

♦include  <math.h> 

♦include  <types.h> 

♦include  <quickdraw.h> 

♦include  <palette.h> 

♦include  <toolutils.h> 

♦include  <fonts.h> 

♦include  <events.h> 

♦include  <windows.h> 

♦include  <dialogs.h> 

♦include  <stdio.h> 

♦include  <menus.h> 

♦include  <desk.h> 

♦include  <textedit.h> 

♦include  <scrap.h> 

♦include  <segload.h> 

♦include  <controls.h> 

♦include  <packages.h> 

♦include  <slots.h> 

♦include  <ShutDown.h> 

♦include  <errors.h> 

♦include  <files.h> 


/* -  */ 

/*  The  low-level  help  functions  for  graphics.  */ 

/*  Mean-squared  distance  between  to  coordinate  pairs.  */ 

int  distance (iO,  jO,  il,  jl) 
int  iO,  jO,  il,  jl; 

{  int  res; 

double  xl,  x2,  yl,  y2; 


xl  =  iO;  x2  =  il;  yl  =  jO;  y2  =  jl; 

res  =  sqrt ( (xl-x2) * (xl-x2)  +  (yl-y2) * (yl-y2) ) ; 

return (res) ; 


/* -  V 

/*  The  low-level  SPLINE  function.  This  function  calculates  and  draws  a 
curved  line  along  the  path  of  a  bi-cubic  spline  the  equation  for  a  coordinate 
of  the  points  on  the  spline  is: 

j  -  jl*t  +  j2*(l  -  t)  +  W*(j2-j3)*t*(l  -  t) * (1  -  t)  +  W* ( jl- jO) *t*t* (1  -  t); 
where:  j  :  the  coordinate  being  calculated, 

t  :  the  cubic  variable. 

W  :  a  weighting  factor. 

(jl,  j2)  :  the  end-coordinates  of  the  spline. 

(jO,  j3)  :  The  control  coordinates. 

*/ 


_Spline  (iO,  jO,  il,  jl,  i2,  j2,  i3,  j3) 
int  iO,  jO,  il,  jl,  i2,  j2,  i3,  j3; 

(  float  dt,  tO,  tl,  t2,  t3,  t5,  inc,  dist,  W; 
int  i,  j,  i5,  j5,  count; 


} 


inc  =  2.5; 

W  -  0.9; 

MoveTo(jl,  il); 

dist  *  distance (il,  jl,  i2, 

if  (inc  <  dist) 

(  j5  =  jl— jO; 


/*  Two  pixel  wide  sampling  rate  */ 

/*  Set  the  weighting  factor.  */ 

/*  Move  to  PI  */ 

j2);  /*  The  distance  between  the  two  points*/ 


i5  =  il-iO; 
j3  =  j2- j  3 ; 
i3  =  i2-i3; 

dt  =  inc/dist;  /*  Transform  the  sampling  rate  to  a  function  of  T  */ 

count  =  1.0/dt;  /*  Number  of  samples  to  be  taken  in  a  unit  interval  */ 

while  (count —  >  0) 

{  tl  =  dt*count;  /*  calculate  I  and  J  as  a  function  of  T  */ 


t2 

=  1.0  -  tl; 

/* 

(1  - 

t)  */ 

t5 

=  W*tl*tl*t2; 

/* 

w*t* 

t*(l  -  t)  */ 

t3 

=  W*tl*t2*t2; 

/* 

w*t* 

(1  -  t)*(l  -  t) 

j  = 

jl*tl  +  j2*t2 

+  t3*j3 

+  j5*t5; 

i  = 

il*tl  +  i2*t2 

+  t3*i3 

+  i5*t5; 

LineTo(j,  i) ; 

}  I 

else  LineTo(i2,  j2); 


End  Listing  One 
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Listing  Two 


;;  You  need  to  change  this  to  the  directory  where  you  have  stored  FF.fasl 
(load  "Lauzzana : Ray : Pro jects : Artif ex : LLIB : FF" ) 


; ;  You  need  to  change  this  to  the  directory  where  C  libraries  is  stored 
(def-logical-pathname  "CLIB; "  "Lauzzana:Ray:Projects:Artifex:CLIB") 


;;  The  high-level  SPLINE  function 
(defun  SPLINE  (&rest  p) 

SPLINE  (Srest  point-list) 

Sets  up  the  front  window  as  a  graphics  port  to  draw  in,  and  calls 
DO-SPLINE  to  do  the  actual  work  of  drawing  a  spline. 

(with-port  (ask  (front -window)  wptr)  (do-spline  p) ) ) 

(defun  DO-SPLINE  (p) 

DO-SPLINE  (point-list) 

A  smooth  curve  coonecting  the  points. 


(let  ((pi  (carp)) 

(p2  (cadr  p) ) 

(p3  (caddr  p) ) 

(p4  (cadr  (cddr  p) ) ) 

(p5  (cadr  (cdddr  p) ) ) ) 

(cond  ((or  (null  (pointppl))  (null  (pointpp4)))  nil) 

((and  (pointp  pi)  (pointp  p2)  (pointp  p3)  (pointp  p4 ) ) 
(_Spline  (I-coord  pi) 

(J-coord  pi) 

(I-coord  p2) 

(J-coord  p2) 

(I-coord  p3) 

(J-coord  p3) 

(I-coord  p4) 

(J-coord  p4)) 

(if  (pointp  p5) 

(append  (list  'SPLINE  pi)  (cdr  (DO-SPLINE  (cdr  p)))) 
(cons  'SPLINE  p)))))) 


;;  The  high-level  help  functions  for  graphics 
;;  @0,  representation  for  a  point. 

(defun  @0  (a  Soptional  b) 

@@  ()  or  (I-coordinate  J-coordinate)  or  (integer) 

A  single  user  point  or  a  point. 

A  screen  location,  in  physical  coordinates.  (@@  0  0)  is  the  upper-left 
corner.  If  single  integer  is  recieved  it  is  interpreted  as  a  packed  point, 
and  it  is  unpacked  into  a  coordinate  pair. 


;;  Mac  II,  parameters  are  stored  in  reverse  order  on  the  stack.  Therefore, 

;;  the  foreign  function  call  must  reverse  the  order  of  the  parameters. 

;;  MULTIPLE -VALUE-BIND  is  used  to  perform  the  mapping  of  parametes. 

;;  FF-LOOKUP-ENTRY  find  the  physical  address  of  the  entry-point  for  function. 

;;  FF-CALL  executes  the  coda  stored  at  a  physical  address. 

(defun  _Spline  (a  b  c  d  e  f  g  h) 

_Spline  (iO  jO  il  jl  i2  j2  i3  j3) 

Draws  a  spline  between  pi  and  p2  to  the  control  points  pO  and  p3. 

(multiple-value-bind  (entry  a5)  (ff-lookup-entry  "_Spline") 

(ff-call  entry 

:a5  a5  :long  h  :long  g  :long  f  :long  e  :long  d  :long  c  :long  b  :long  $ 
: novalue) ) ) 


;;  The  loading  the  low-level  SPLINE  function 

;;  FF-LOAD  is  used  to  load  binary  files  and  their  associated  libraries. 

;;  In  this  case  the  object  module  for  the  function  _Spline  is  stored  in 
;;  the  file  <spline.c.o>.  FF-LOAD  searches  this  file  for  the  symbolic  name 
;;  _Spline  and  load  the  binary  code  associated  with  it. 

;;  In  addition,  it  searches  the  libraries  for  unsatisfied  symbolic  references 
;;  which  which  may  have  occurred  within  the  code  and  loads  them  as  well. 

;;  In  otherwords,  it  links  and  loads. 

;;  You  need  to  change  this  to  the  directory  where  you  have  stored  your  C 
spline 

( f f-load  "Lauzzana : Ray : Papers : Spline : spline . c . o" 

: entry-names 
(list  "_Spline"  ) 

: libraries 

(list  "CLIB;StdCLib.o"  "CLIB;CRuntime.o"  "CLIB.'CInterface.o" 
"CLIB;math.o"  "CLIB;CSANElib.o") ) 


End  Listings 


(cond  ((and  (numberp  a)  (numberp  b) )  (list  ' @@  (round  a)  (round  b) ) ) 
((numberp  a)  (let  ((i  (floor  (/  a  65536)))) 

(list  '@@  i  (-  a  (*  65536  i) ) ) ) ) ) ) 

;;  The  type  test  for  a  POINT. 

(defun  POINTP  (p) 

POINTP  (item) 

If  the  item  is  a  point  represented  in  in  coordinates,  ie.  (00  I  J) 
then  TRUE,  else  NIL. 


(and  (listp  p) 

(or  (=  3  (length  p) )  (=2  (length  p) ) )  (equal  (car  p)  '00))) 

;;  I-COORDINATE 
(defun  I-COORD  (p) 

I-COORD  (point) 

Returns  the  vertical  screen  coordinate  of  a  point. 

(if  (pointp  p)  (cadr  p) ) ) 

;;  J-COORDINATE 
(defun  J-COORD  (p) 

J-COORD  (point) 

Returns  the  horizontal  screen  coordinate  of  a  point. 


(if  (pointp  p)  (caddr  p) ) ) 


;  The  binding  to  the  low-level  SPLINE  function 
;  There  are  two  methods  to  bind  a  C  function  to  Allegro. 

;  The  first  method  uses  DEFFCFUN.  Though  this  is  a  simpler  function, 

;  The  binding  will  be  lost  if  you  build  a  stand-alone  application. 

;  Using  DEFFCFUN  the  code  would  be: 

;  (deffcfun  (Mac_Spline  "_Spline") 

;  (integer  integer  integer  integer  integer  integer  integer  integer) 
novalue) 

;  The  second  and  preferred  method  uses  MULTIPLE-VALUE-BIND  and  FF-CALL 
;  to  bind  a  physical  entry-point  to  a  symbol.  This  is  a  hardware  dependent 
;  solution,  in  that  you  need  to  represent  the  binding  in  terms  of  the 
;  physical  size  and  ordering  of  the  machines  stack.  In  the  case  of  the 
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Listing  One  (Text  begins  on  page  60.) 

/*  mfmt.h  —  macros  and  function  prototypes  for  mfmt  routine.  */ 

♦define  printf  AltPrintf 
♦define  fprintf  AltFprintf 
♦define  sprintf  AltSprintf 
♦define  vprintf  AltVprintf 
♦define  vfprintf  AltVfprintf 
♦define  vsprintf  AltVsprintf 


int  AltPrintf 
int  AltFprintf 
int  AltSprintf 
int  AltVprintf 
int  AltVfprintf 
int  AltVsprintf 


(char  *fmt,  . . . ) ; 

(FILE  *f,  char  *fmt,  . . .) ; 

(char  *Dest,  char  *fmt,  ...); 

(char  *fmt,  va_list  Arg); 

(FILE  *f,  char  *fmt,  va_list  Arg); 
(char  *Dest,  char  *fmt,  va_list  Arg) ; 


Listing  Two 


End  Listing  One 


/*  mfmt.c  —  function  to  output  comma-separated  numbers  with  printf (). 

*  Copyright  1990,  Jim  Mischel 

*  To  compile  for  testing: 

*  tcc  -ms  -f  mfmt 

*  To  compile  for  use  as  a  called  module: 

*  tcc  -ms  -c  -f  mfmt 
*/ 

/*  ♦define  TESTING  /*  remove  comment  for  testing  */ 

♦include  "stdio.h" 

♦include  "stdlib.h" 

♦include  "ctype.h" 

♦include  "string. h" 

♦include  "math.h" 


♦define  AddBlockArg (ap,  type)  {‘((type  *) (NewArgPtr) ) ++)  =  va_arg(ap,  type) 
♦define  RemoveBlockArg (type)  ((type  *) (NewArgPtr) ) — 


static  va_list  OldArgPtr;  /* 
static  va_list  NewArgPtr;  /* 
static  va_list  NewBlock  =  NULL;  /* 
static  char  *Sptr;  /* 
static  char  *Num;  /* 
static  char  ‘NumPtr;  /* 
static  char  *t  =  NULL;  /* 
unsigned  tSize;  /* 
static  char  *Tptr;  /* 
static  char  ‘SavePtr;  /* 
static  int  Flags;  /* 
static  int  Width;  /* 
static  int  WidthFlag;  /* 
static  int  Precision;  /* 
static  int  PrecisionFlag;  /* 
static  int  Size;  /* 
static  int  Sign;  /* 


Pointer  to  passed  arguments  */ 
Pointer  to  new  argument  block  */ 

New  argument  block  */ 

Pointer  to  passed  format  string  */ 
Formatted  number  */ 

Pointer  into  formatted  number  string 
New  format  string  */ 

Length  of  new  format  string  */ 
Pointer  to  new  format  string  */ 

Saved  Tptr  used  when  %m  format  found 
Flags  identified  in  format  string  */ 
Width  from  format  string  */ 
Identifies  width  type  */ 

Width  from  format  string  */ 
Identifies  precision  type  */ 
printf ()  size  modifier  */ 

Sign  of  number  for  formatting  */ 


*/ 


*/ 


/*  Increment  the  flags  counter  for  each  occurance  of  a  flag  character. 

*  Valid  flag  characters  are  blank,  '♦',  '+'.  */ 

/*  Definitions  for  flag  characters  */ 

♦define  Blank  1 
♦define  Dash  2 
♦define  Pound  4 
♦define  Plus  8 


static  void  ParseFlags  (void)  { 

Flags  =  0; 

while  (*Sptr  ==  '  '  !!  *Sptr  ==  '-'  ::  *Sptr  ==  '♦'  II  *Sptr  ==  '+') 
switch  (*Tptr++  =  *Sptr++)  ( 

case  '  '  :  Flags  +=  Blank;  break; 
case  '-'  :  Flags  +=  Dash;  break; 
case  '♦'  :  Flags  +=  Pound;  break; 
case  '+'  :  Flags  +=  Plus;  break; 

)  /*  switch  */ 

}  /*  ParseFlags  */ 

/*  Width  specification.  Minimum  field  width  is  returned  in  the  Width  variable. 

*  WidthFlag  specifies  if  'O'  or  '*'  was  given  in  the  format  string.  */ 
static  void  ParseWidth  (void)  { 

Width  =  WidthFlag  =  0; 

if  (*Sptr  ==  '0') 

WidthFlag  =  (*Tptr++  =  *Sptr++) ; 
if  (*Sptr  =='*')  ( 

WidthFlag  !=  0x80; 

*Tptr++  =  *Sptr++; 

Width  =  (AddBlockArg (OldArgPtr,  int)); 
if  (Width  <  0)  { 

Width  =  abs  (Width) ; 

Flags  ! =  Dash; 

) 

) 

while  (isdigit  (*Sptr))  { 

Width  =  Width  *  10  +  *Sptr  -  'O'; 

*Tptr++  =  *Sptr++; 

} 

}  /*  ParseWidth  */ 

/*  Precision  specification.  Returns  precision  in  the  variables  Precision  and 

*  PrecisionFlag. 

*  PrecisionFlag  =  0,  no  precision  was  specified 

*  PrecisionFlag  =  'O',  ".0"  specified 

*  PrecisionFlag  =  'n',  ".n"  specified 

*  PrecisionFlag  =  '*',  ".*"  specified 
*/ 

static  void  ParsePrecision  (void)  ( 

Precision  =  PrecisionFlag  =  0; 

if  (*Sptr  =='.'){  /*  precision  specified  */ 
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*Tptr++  =  *Sptr++; 
if  (*Sptr  =='*')  { 

PrecisionFlag  =  (*Tptr++  =  *Sptr++) ; 
Precision  =  (AddBlockArg (OldArgPtr,  int)); 

} 

else  if  (*Sptr  ==  '0') 

PrecisionFlag  =  (*Tptr++  =  *Sptr++) ; 
else  { 

PrecisionFlag  =  'n'; 
while  (isdigit  (*Sptr))  { 

Precision  =  Precision  *  10  +  *Sptr  -  '0 
*Tptr++  =  *Sptr++; 


}  /*  ParsePrecision  */ 

/*  Input  size  modifier.  (F!N!h!l!L)  */ 
static  void  ParseSize  (void)  ( 

if  (*Sptr  ==  ' F'  II  *Sptr  ==  '1'  I!  *Sptr  ==  ' L'  !! 

*Sptr  ==  'N'  I!  *Sptr  ==  'h') 

Size  =  (*Tptr++  =  *Sptr++) ; 

else 

Size  =  0; 

)  /*  ParseSize  */ 

/*  dtoa  --  convert  a  double  to  comma-separated  ASCII  representation, 
static  void  dtoa  (double  Work,  int  P,  int  Digits)  { 
int  c; 

if  (P  >=  0  ! !  Work  !=  0)  { 
if  (P  ==  0)  { 
c  =  ' . ' ; 

Digits  *  0; 

P — — ; 


else  if  (Digits  ==  3)  ( 


else  { 

c  =  (int) (fmod  (Work,  10))+' O'; 
modf  (Work/10,  &Work) ; 
if  (P  >  0) 

P— ; 

else 

Digits++; 

} 

dtoa  (Work,  P,  Digits); 

*NumPtr++  =  c; 


/*  Right-  or  left-  justifies  the  formatted  number  in  the  string. 

*  If  the  number  is  too  large  for  the  specified  width,  the  number 

*  field  is  filled  with  the  asterisk  character  (*) .  */ 
static  void  Justify  (void)  { 

if  ( (WidthFlag  &  0x7f)  ==  '0')  /*  check  width  */ 

if  (strlen  (Num)  >  Width)  { 
memset  (Num,  '*',  Width); 

NumPtr  «  Num  +  Width; 

♦NumPtr  =  ' \0' ; 
return; 

} 

if  (strlen  (NumPtr)  <  Width)  { 

if  (Flags  &  Dash)  /*  left  justify  */ 

memset  (NumPtr,  '  ',  Width  -  strlen  (Num)); 
else  (  /*  right  justify  */ 

int  n  =  Width  -  strlen  (Num) ; 
char  *p  =  Num; 

memmove  (p  +  n,  p,  strlen  (Num) ) ; 
memset  (p,  '  ' ,  n) ; 

} 

NumPtr  =  Num  +  Width; 

*NumPtr  =  '\0'; 

} 

}  /*  Justify  */ 

/*  Reports  an  out  of  memory  error  and  aborts  the  program.  */ 
static  void  MemoryError  (char  *s)  ( 

fprintf  (stderr,  "Out  of  memory  in  function  4s\n",  s) ; 
exit  (1); 

)  /*  MemoryError  */ 

/*  Format  'm'  type  into  the  new  format  string  t.  All  parameters  (flags,  width, 

*  precision,  size,  and  type)  are  stored  in  the  respective  variables.  */ 
static  void  mFormat  (void)  { 

double  Work; 

/*  Move  the  block  pointer  back  where  it  belongs  if  there  were  width  or 

*  precision  specifications  in  the  argument  list.  */ 

*SavePtr  =  '\0'; 

if  (PrecisionFlag  ==  '*') 

RemoveBlockArg  (int); 
if  (WidthFlag  &  0x80) 

RemoveBlockArg  (int); 

if  ((Num  =  malloc  (128))  ==  NULL) 

MemoryError  ("mFormat"); 

NumPtr  =  Num; 

/*  The  next  argument  in  the  list  is  the  number  that  is  to  be  formatted. 

*  This  number  will  either  be  a  float,  a  double,  or  a  long  double.  The 

*  input  size  modifier  will  tell  us  what  type.  Whatever  type  it  is,  it  will  i 

*  be  copied  into  the  double  variable  Work  for  us  to  work  with.  */ 

if  (Size  ==  '1')  Work  =  va_arg  (OldArgPtr,  double); 

else  if  (Size  ==  'L')  Work  =  (double)  va_arg  (OldArgPtr,  long  double); 


else 

Sign  =  (Work  <  0)  ? 
if  ((PrecisionFlag) 
Precision  =  2; 


Work  =  (double)  va_arg  (OldArgPtr,  float) ; 
-1  :  1; 


(Listing  continued  on  page  122) 
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Listing  Two  (Listing  continued,  text  begins  on  page  60.) 

dtoa  (floor  (fabs  (Work)  *  powlO  (Precision)), 

(Precision  ==  0)  ?  -1  :  Precision,  0); 

*NuraPtr  =  '\0'; 

/*  The  number  is  formatted  into  Num.  Precision  was  handled  by  the  dtoa() 

*  function.  Add  the  sign  and  perform  padding/ justifying  as  necessary. 

*  Determine  the  proper  sign  */ 

if  (Sign  ==  -1)  Sign  = 

else  if  (Flags  &  Plus)  Sign  =  '+'; 

else  if  (Flags  &  Blank)  Sign  =  '  ' ; 

else  Sign  =  '\0'; 

if  (Sign  !=  '\0')  /*  Place  sign  */ 

if  (Flags  &  Pound)  1  /*  trailing  sign  */ 

*NumPtr++  =  Sign; 

*NumPtr  =  ' \0' ; 

} 

else  {  /*  leading  sign  */ 

memmove  (Num+1,  Num,  (NumPtr  -  Num)); 

*Num  =  Sign; 

NumPtr++; 

) 

Justify  (); 

/*  Now  re-allocate  the  string  to  add  more  characters  and  then  append  the 

*  newly-formatted  number  to  the  string  and  release  the  memory  taken  by 

*  the  formatted  number  string.  */ 

if  ( (t  =  realloc  (t,  (tSize  +=  strlen  (Num))))  ==  NULL) 

MemoryError  ("mFormat"); 
strcat  (t,  Num) ; 

Tptr  =  t  +  strlen  (t) ; 
free  (Num); 

)  /*  mFormat  */ 

/*  Determine  the  conversion  type.  For  any  type  but  'm',  simply  copy  the  passed 
*  argument  to  the  new  argument  list  and  return.  */ 
static  void  ParseType  (void)  { 
switch  (*Tptr++  =  *Sptr++)  { 
case  'd'  : 
case  'i'  : 
case  'o'  : 
case  'u'  : 
case  '  x'  : 
case  'X'  : 

case  ' c'  :  /*  in  Turbo  C,  char  is  treated  as  int  */ 

if  (Size  ==  '1')  AddBlockArg (OldArgPtr,  long); 
else  AddBlockArg (OldArgPtr,  int); 

break; 
case  '  f'  : 
case  'e'  : 
case  'g'  : 
case  'E'  : 
case  'G'  : 

if  (Size  ==  '1')  AddBlockArg (OldArgPtr,  double); 

else  if  (Size  ==  'L')  AddBlockArg (OldArgPtr,  long  double); 


else  AddBlockArg (OldArgPtr,  float); 

break; 

/*  In  Turbo  C,  pointers  to  all  types  are  the  same  size  */ 
case  's'  : 
case  'n'  : 
case  'p'  : 

if  (Size  ==  'F' )  AddBlockArg (OldArgPtr,  char  far  *); 

else  if  (Size  ==  'N')  AddBlockArg (OldArgPtr,  char  near  *); 
else  AddBlockArg (OldArgPtr,  char  *); 

break; 
case  'm'  : 

mFormat  ();  /*  format  'm'  type  */ 

break; 

default  :  /*  anything  else  isn't  defined  */ 

break; 

}  /*  switch  */ 

|  /*  ParseType  */ 

/*  Parse  a  standard  printfO  format.  */ 
static  void  ParseFormat  (void)  { 

SavePtr  =  Tptr  -  1; 

ParseFlags  (); 

ParseWidth  (); 

ParsePrecision  (); 

ParseSize  (); 

ParseType  (); 

)  /*  ParseFormat  */ 

/*  Copy  the  input  format  string  to  the  new  format  string  t,  replacing  all  %m 

*  formats  with  the  formatted  digit  string.  Arguments  will  be  placed  in  the 

*  ParamBlock  structure,  with  the  %m  parameters  removed.  */ 
static  void  Formatter  (char  *s,  va_list  Arg)  ( 

Sptr  =  s; 

/*  Allocate  memory  for  new  format  string.  */ 
if  ( (t  *  malloc  (tSize  =  strlen  (s)))  ==  NULL) 

MemoryError  ("Formatter"); 

Tptr  =  t; 

OldArgPtr  =  Arg; 
while  (*Sptr  !=  '\0') 

if  ((*Tptr++  =  *Sptr++)  ==  '%') 

ParseFormat  (); 
va_end  (OldArgPtr) ; 

*Tptr  =  ' \0' ; 

)  /*  Formatter  */ 

/*  Allocate  a  block  of  memory  for  the  modified  argument  list.  */ 
static  void  InitBlock  (char  *s)  ( 


int  BlockSize 

=  0; 

while  (*s  !=  ' 

\0') 

/*  count  the  '%' 

characters  */ 

if  ( *s  == 

'%') 

/*  in  the  format 

string  */ 

BlockSize++; 


/*  Multiply  the  number  of  '%'  by  the  size  of  a  long  double,  giving  some 

*  idea  of  the  maximum  required  size  of  the  new  parameter  block.  It's 

*  crude  and  implementation  dependent,  but  it  works.  */ 

BlockSize  *=  sizeof  (long  double); 

if  ( (NewBlock  =  malloc  (BlockSize))  ==  NULL) 

MemoryError  ("InitBlock") ; 

NewArgPtr  =  NewBlock; 

)  /*  InitBlock  */ 

/*  Free  the  memory  used  by  the  modified  argument  list  (if  any)  and  the 

*  modified  format  string.  */ 
static  void  FreeBlock  (void)  { 

free  (t); 
free  (NewBlock) ; 

NewBlock  =  t  =  NULL; 

}  /*  FreeBlock  */ 

/*  These  6  routines  are  the  only  functions  visible  to  the  application  program. 

*  They  are  accessed  though  the  printf,  fprintf,  sprintf,  vprintf,  vfprintf, 

*  and  vsprintf  macros,  respectively.  */ 
int  AltPrintf  (char  *fmt,  ...)  ( 

va_list  Arg; 
int  r; 

va_start  (Arg,  fmt); 

Formatter  (fmt,  NewArgPtr  =  Arg); 
r  =  vprintf  (t,  Arg); 

FreeBlock  {); 
return  r; 

)  /*  AltPrintf  */ 

int  AltFprintf  (FILE  *f,  char  *fmt,  ...)  ( 
va_list  Arg; 
int  r; 

va_start  (Arg,  fmt); 

Formatter  (fmt,  NewArgPtr  =  Arg); 
r  =  vfprintf  (f,  t,  Arg); 

FreeBlock  {); 
return  r; 

)  /*  AltFprintf  */ 

int  AltSprintf  (char  *Dest,  char  *fmt,  ...)  { 
va_list  Arg; 
int  r; 

va_start  (Arg,  fmt); 

Formatter  (fmt,  NewArgPtr  =  Arg); 
r  =  vsprintf  (Dest,  t,  Arg); 

FreeBlock  (); 
return  r; 

)  /*  AltSprintf  */ 

int  AltVprintf  (char  *fmt,  va_list  Arg)  ( 
int  r; 

InitBlock  (fmt); 

Formatter  (fmt,  Arg) ; 


r  =  vprintf  (t,  NewBlock); 

FreeBlock  (); 
return  r; 

)  /*  AltVprintf  */ 

int  AltVfprintf  (FILE  *f,  char  *fmt,  va 
int  r; 

InitBlock  (fmt); 

Formatter  (fmt,  Arg); 
r  =  vfprintf  (f,  t,  NewBlock); 
FreeBlock  (); 
return  r; 

)  /*  AltVfprintf  */ 

int  AltVsprintf  (char  *Dest,  char  *fmt, 
int  r; 

InitBlock  (fmt); 

Formatter  (fmt,  Arg); 
r  =  vsprintf  (Dest,  t,  NewBlock); 
FreeBlock  (); 
return  r; 

)  /*  AltVsprintf  */ 

lifdef  TESTING 
# include  "mfmt.h" 
void  main  (void)  { 

printf  ("The  national  debt  exceeds 
I 

tendif 


list  Arg)  { 


va_list  Arg)  ( 


$% . 01m\n",  (double) 1000000000000.0) ; 


End  listings 
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PARALLEL  EXTENSIONS 


Listing  One  (Text  begins  on  page  70.) 

} 

/****  File:  proto. h  —  Contains  the  function  protocols  ****/ 

} 

/*  include  mytypes.h  first - 1  don't  do  any  checking  */ 

/****  pipe (Process  *p,  Channel  *in,  Channel  *out) 

source (Process  *,  Channel  *,  UBYTE  *); 

**  Reads  a  single  character  on  channel  in  and  falls  into  a  loop  where  next 

output (Process  *,  Channel  *); 

**  character  is  read  and  compared  in  an  ASCII  sense  to  the  current  charater. 

pipe (Process  *,  Channel  *,  Channel  *); 

**  Character  with  the  lowest  ASCII  value  is  forwarded  on  channel  out.  Loop 

**  terminates  on  a  '\0'  character.  The  "stored"  character  is  sent  before  the 

/*  end  proto. h  */ 

**  '\0'  is  propagated.  Process  *p  is  used  by  the  ProcAllocO  routine. 

**  You  must  have  this  in  the  parameter  list  for  a  parallel  process. 

End  Listing  One 

pipe (Process  *p,  Channel  *in,  Channel  *out) 

UBYTE  highest,  next; 

Listing  Two 

BOOL  running; 

BOOL  ns  node; 

/****  mytypes.h  ****/ 

if (  node  number  ==  1)  /*  If  we  are  the  root  node  only  do  the  */ 

♦define  BUFF  SIZE  256  /*  the  max.  char  buffer  size  */ 

ns  node  =  FALSE;  /*  main  loop  once.  If  we  are  a  non-  */ 

♦define  NUM  PIPES  BUFF  SIZE  /*  the  number  of  sorting  processes  */ 

else  /*  root  node,  loop  forever.  */ 

♦define  PIPE  STACK  128  /*  stack  space  for  the  processes*/ 

ns  node  =  TRUE; 

(define  INPUT  STACK  4096 

do  { 

(define  OUTPUT  STACK  4096 

running  =  TRUE; 

highest  =  ChanlnChar (in) ; 

(define  TRUE  1  /*  some  simple  defines  */ 

while (running)  { 

(define  FALSE  0 

next  =  ChanlnChar (in) ; 

switch (next)  ( 

typedef  int  BOOL; 

case  '\0'  : 

typedef  unsigned  char  UBYTE; 

ChanOutChar (out ,  highest ) ; 

running  =  FALSE; 

End  Listing  Two 

break; 
default  : 

if  (next  >  highest)  { 

Listing  Three 

ChanOutChar (out,  highest); 
highest  =  next; 

multisort.nif  --  This  is  the  file  the  transputer  uses  to  load  the  network. 

else 

The  parameters  are: 

( 

ChanOutCha  r ( out ,  next ) ; 

node  number  !  processor  reset  (link  0  !  linkl  !  link  2!  link  3  ! 

) 

!  from  processor  ! - ! 

) 

:  number  Rxx  I  The  number  here  is  the  processor! 

} 

!  !  number  we  connect  to.  ! 

ChanOutChar (out,  '\0'); 

)  while (ns  node); 

,  multisort,  R0,  0,  ,  ,  2; 

,  multisort,  Rl,  ,  ,1,  ; 

End  Listing  Four 

End  Listing  Three 

Listing  Four 

Listing  Five 

****  File:  buffers. c  --  Contains  the  funtions: 

/*************************************************************************** 

*  source (Process  *,  Channel  *,  UBYTE  *) 

**  sort.c  —  Compiles  under  Logical  Systems  Transputer  C  compiler  Versions 

*  output (Process  *,  Channel  *) 

**  88.4,  89.1.  A  single  transputer,  multi-process  ASCII  sorting  routine.  This 

*  pipe (Process  *,  Channel  *,  Channel  *) 

**  shows  how  to  allocate  and  deallocate  parallel  (multi-tasking)  processes  on 

***/ 

**  a  single  transputer.  This  algorithm  is  modelled  after  the  sorting  example 

**  in  the  INMOS  Occam  Transputer  Development  System  (TDS) .  The  algorithm 

♦include  <stdio.h> 

**  relies  on  having  as  many  parallel  processes  as  the  maximum  character 

♦include  <conc.h> 

**  buffer  size.  Data  is  sent  to  a  FIFO-like  array  of  input-ouput  buffers.  If 

♦include  "mytypes.h"  /*  include  in  this  order...  */ 

**  the  next  letter  read  in  is  less  than  (in  an  ASCII  sense)  the  current  letter 

♦include  "proto. h" 

**  in  the  buffer,  it  is  forwarded  to  the  next  buffer,  otherwise  the  current 

**  data  is  forwarded.  The  program  will  shut  down  when  a  ~  is  the  first 

****  source (Process  *p,  Channel  *out,  UBYTE  *ch) 

**  character  in  any  input  line. 

* 

*  Output  a  single  character  at  a  time  from  the  buffer  pointed  to  by  ch 

**  Must  link  in  file  buffers. c  (after  compilation  of  course..) 

* 

*  on  the  channel  out.  Terminate  when  '\0'  or  whole  buffer  is  sent. 

**  Programed  by:  G.K. Ellis,  Smart  Materials  and  Structures  Laboratory, 

* 

*  Process  *p  is  used  by  the  ProcAllocO  routine.  You  must  have  this 

**  Mechanical  Engineering  Department,  Virginia  Tech,  Blacksburg,  VA  24061 

* 

*  in  the  parameter  list  for  a  parallel  process. 

***/ 

ource (Process  *p,  Channel  *out,  UBYTE  *ch) 

*****************************************************************************/ 

s 

♦include  <stdio.h> 

1 

♦include  <conc.h>  /*  the  LSC  defines  are  here  */ 

BOOL  inline  =  TRUE; 

♦include  "mytypes.h"  /*  include  in  this  order...  */ 

int  i; 

♦include  "proto. h" 

for (i=0;  i<BUFF  SIZE;  i++)  { 

if (inline) 

/****  MAIN  PROGRAM  ****/ 

switch ( ch [ i ) )  { 

void  main() 

case  '\0':  /*  this  is  the  EOL  for  us  */ 

{ 

ChanOutChar (out,  ch [ i ) ) ; 

UBYTE  ch [BUFF  SIZE);  /*  string  buffer  */ 

inline  =  FALSE; 

BOOL  active  =  TRUE; 

break; 

int  i; 

default : 

Channel  *thru[NUM  PIPES  +  1];  /*  internal  channels  */ 

ChanOutChar (out,  ch ( i ] ) ; 

Process  *p[NUM  PIPES  +  3];  /*  process  pointers  */ 

} 

while (active)  ( 

) 

fgets(ch,  BUFF  SIZE-1,  stdin) ;  /*  get  the  input  line  */ 

) 

/*  stop  char  is  ~  as  first  letter  */ 

if(ch[0]  ==  '“')  active  =  0; 

/ 

****  output (Process  *p,  Channel  *in) 

/*  allocate  the  channels,  NULL  is  returned  if  no  memory  */ 

* 

*  Read  a  single  character  at  at  time  on  channel  in  and  send  it  to  stdout. 

for (i  =  0;  i<  NUM  PIPES  +  1;  i++)  { 

* 

*  Terminate  when  '\0'  is  received.  Process  *p  is  used  by  the  ProcAllocO 

if ( (thru [i]  =  ChanAlloc () )  ==  NULL) 

* 

*  routine.  You  must  have  this  in  the  parameter  list  for  a  parallel  process. 

printf("No  memory  for  Channel  thru [%d] \n",  i); 

output (Process  *p,  Channel  *in) 

f 

/*  allocate  the  processes,  NULL  is  returned  if  no  memory  */ 

UBYTE  ch; 

p [ 0 ]  =  ProcAlloc (source,  INPUT  STACK,  2,  thru[0],  ch) ; 

BOOL  running  =  TRUE; 

for (i  =  1;  i  <  NUM  PIPES+1;  i++) 

p[i]  =  ProcAlloc (pipe,  PIPE  STACK,  2,  thru[i-l],  thru[i]); 

while (running)  ( 

p [NUM  PIPES+1]  =  ProcAlloc (output,  OUTPUT  STACK,  1,  thru[NUM  PIPES]); 

ch  =  ChanlnChar (in) ; 

p [NUM  PIPES+2 ]  =  NULL; 

switch (ch)  { 

/*  check  to  see  if  all  processes  were  allocated  successfully  */ 

case  ' \0' : 

for (i  =  0;  i  <  NUM  PIPES  +  2;  i++) 

putchar (' \n' ) ; 

if (!p[i]) 

running  =  FALSE; 

printf("No  memory  for  Process  p[%d]\n",  i); 

break; 
case  ' \n' : 

break; 

default: 

ProcParList (p) ;  /*  Run  a  NULL  terminated  list  of  pointers  */ 

/*  to  processes.  These  are  all  low-pri  */ 

/*  Since  we  allocate  these  each  time  through  the  loop,  we  needto 

putchar (ch) ; 

(Listing  continued  on  page  126) 

124 

Dr.  Dobb’s Journal,  August  1990 

749 

PARALLEL  EXTENSIONS 


listing  Five  ( Listing  continued,  text  begins  on  page  70.) 

“  deallocate  them  here  otherwise,  we  will  run  out  of  memory  */ 


} 


for (i  =  0;  i  <  NUM_PIPES  +  1;  i++) 
ChanFree (thru [i] ) ; 
for (i  =  0;  i  <  NUM_PIPES  +  2;  i++) 
ProcFree (p [ i ] ) ; 


printf ("done!\n") ; 


/*  all  done. . 


End  listing  Five 


Listing  Six 


“  multisort. c  —  A  two  transputer  version  of  a  simple  parallel  ASCII  sorting 
“  routine.  This  program  will  work  on  either  node.  Developed  for  Logical 
“  Systems  Transputer  C  compiler  (LSC)  versions  88.4  or  89.1.  Must  link  with 
“  buffers. c.  Programmed  by:  G.K. Ellis,  Smart  Materials  and  Structures 
**  Laboratory,  Mechanical  Engineering  Department,  Virginia  Tech, 

Blacksburg,  VA  24061 


*  ★  *  *  j 


/*  string  buffer  */ 


/*  link  channels  */ 

hi-priority  processes  */ 
internal  soft  channels  */ 
low-priority  processes  */ 
We  are  the  root  node  */ 
these  are  our  links  */ 


♦include  <stdio.h> 

♦include  <conc.h> 

♦include  "mytypes.h" 

♦include  "proto. h" 

/****  MAIN  PROGRAM  ****/ 
void  main () 

( 

UBYTE  ch [BUFF_SIZE]  , 

BOOL  active  =  TRUE; 
int  i; 

Channel  *in,  *out; 

Process  ‘feeder,  ‘sink;  /* 

Channel  ‘thru [NUM_PIPES  -  1];  /* 

Process  *p[NUM_PIPES  -  2];  /* 

if (_node_n umber  ==  1)  {  /* 

in  =  LINK3IN;  /* 

out  =  LINK30UT; 
while (active)  { 

fgets(ch,  BUFF_SIZE-1,  stdin);  /*  get  the  input  line  */ 

/*  stop  char  is  ~  as  first  letter  */ 
if (ch [ 0 ]  —  )  active  =  0; 

/*  set  up  the  processes  */ 

feeder  =  ProcAlloc (source,  INPUT_STACK,  2,  out,  ch) ; 
sink  =  ProcAlloc (output,  OUTPUT_STACK,  1,  in); 

/*  Check  that  ProcAlloc ()  doesn't  return  a  NULL,  but 
“  since  we  KNOW  from  the  example  sort.c  this  is  ok  */ 

/*  run  the  feeder  and  sink  processes  in  parallel  */ 
ProcPar (feeder,  sink,  NULL); 

/*  free  the  previously  allocated  processes  */ 

/*  note  we  do  this  each  time  through  the  loop  */ 

/*  hey,  it's  only  an  example  */ 

ProcFree (feeder) ; 

ProcFree (sink) ; 


/*  finis!  */ 

/*  if  we  are  the  non-root  */ 

/*  node,  run  this  as  main()  */ 
/*  these  are  our  links  */ 

/*  allocate  soft  channels  */ 


*/ 


printf ("done! \n") ; 
exit (0)  ; 

)  else  { 

in  =  LINK2IN; 
out  =  LINK20UT; 

for (i  =  0;  i  <  NUM_PIPES  -  1;  i  ++)  { 
thru[i]  =  ChanAlloc () ; 

} 

/*  allocate  soft  channel  pipe  processes 
for (i  -  0;  i  <  NUM_PIPES  -  2;  i++) 

p t i 1  =  ProcAlloc (pipe,  PIPE_STACK,  2,  thru[i],  thru(i+lj); 
/*  allocate  the  processes  with  the  links  */ 
feeder  =  ProcAlloc (pipe,  PIPE_STACK,  2,  in,  thru[0]); 
sink  =  ProcAlloc (pipe,  PIPE_STACK,  2,  thru[NUM_PIPES-2] ,  out) 
/*  If  we  want  to  check  the  pointer  returned  from  ProcAlloc (), 
“  that  is  extra  programming  on  a  non-root  node.  Therefore, 

“  don't  try  to  printf ()  from  a  non-root  node.  There  is  a 
“  non-server  node  _ns_printf()  that  does  simple  ASCII 
“  transfers  out  a  channel  (link),  but  this  generally  requires 
“  extra  effort  to  communicate  back  to  the  server  */ 

/*  Let's  allocate  these  asynchronously  */ 

ProcRunHigh (sink) ;  /*  run  the  hardware  links  at  high  pri  */ 

ProcRunHigh (feeder) ; 

for (i  =  0;  i  <  NUM_PIPES  -  2;  i++) 

ProcRunLow(p[i] ) ;  /*  and  soft  channels  at  low  pri  */ 
_ns_exit();  /*  we  must  exit  like  this  on  non-server*/ 

/*  node  or  we  will  exit  from  the  */ 

/*  main()  program  */ 

/*  ProcRunHigh ()  and  ProcRunLow()  spawn  new  processes  asyncronously 
“  from  main().  The  _ns_exit()  does  a  STOPP  on  the  main  process 
“  leaving  the  two  spawned  processes.  The  exit()  routine  trys 
“  to  send  a  message  back  to  the  server  running  on  the  PC.  If  it 
“  isn't  there,  i.e.  you're  not  the  root,  you've  got  problems. 

“  Note  also,  if  we  are  not  the  root  node,  we  never  terminate 
“  and  restart  the  pipe  processes...  we  just  run  the  processes  !  */ 


End  Listings 
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EXAMINING  R  0  0 


Listing  One  (Text  begins  on  page  84.) 

***  Microsoft  C  6.0  *** 

♦include  "stdio.h" 

/*  prototypes  */ 

void  doit (int  i); 

void  (*  func_ptr) (int  i)  =  doit; 

void  doit (int  i) 

{ 

— >  push  bp 
— >  mov  bp,sp 
— >  push  di 
— >  push  si 

— >  mov  di , WORD  PTR  [bp+4] 
int  loop; 

for  (;  i  >  0;  — i) 

— >  or  di,di 
— >  jle  $EX225 

{ 

for  (loop  =  0;  loop  <  26;  ++loop) 

-->  $F227: 

— >  sub  si, si 

— >  mov  WORD  PTR  [bp+4 ] , di 

{ 

print f ("loop  character  =  %c\n",  0x41  +  loop); 
— >  $F230 : 

— >  lea  ax, WORD  PTR  [si+65] 

— >  push  ax 

— >  mov  ax, OFFSET  DGROUP : $SG233 
— >  push  ax 
— >  call  _printf 
— >  add  sp, 4 
— >  inc  si 
— >  cmp  si, 26 


— > 

} 

jl  $F230 

printf  (". 

i  /  16  =  %d\n\n", i  /  16); 

— >  mov 

ax,di 

— >  cwd 

— >  xor 

ax,  dx 

— >  sub 

ax,  dx 

— >  mov 

cx,  4 

— >  sar 

ax,  cl 

— >  xor 

ax,  dx 

— >  sub 

ax,dx 

— >  push 

ax 

— >  mov 

ax, OFFSET  DGROUP : $SG234 

— >  push 

ax 

— >  call 

printf 

— >  add 

sp,  4 

— >  dec 

di 

— >  jne 

$F227 

) 

— >  5EX225: 

— >  pop  si 
— >  pop  di 
— >  mov  sp,bp 
— >  pop  bp 
— >  ret 
— >  nop 
} 

int  main (void) 

{ 

funcjptr (100) ; 

— >  mov  ax, 100 
— >  push  ax 

— >  call  WORD  PTR  _func_ptr 
— >  add  sp,2 

return  0; 

— >  sub  ax, ax 
— >  ret 
1 


Listing  Two 

************************************** 
***  Microsoft  C  6.0  (using  _fastcall) 

♦include  "stdio.h" 

/*  prototypes  */ 
void  doit (int  i); 
void  (*  func_ptr) (int  i)  =  doit; 


End  Listing  One 


128 


Dr.  Dobb’s Journal,  August  1990 

751 


E  X  A  MINING  ROOM 


Listing  Three  (Listing  continued,  text  begins  on  page  84.) 


— >  cmp  WORD  PTR  [bp+4] , 0 
— >  jle  SFB202 
— >  mov  di , WORD  PTR  [bp+4] 


for  (loop  =  0;  loop  <  26;  ++loop) 

— >  $L20002 : 

— >  sub  si, si 

printf("loop  character  =  %c\n",  0x41  +  loop); 
— >  $L20000 : 

— >  lea  ax, WORD  PTR  [si+65] 

— >  push  ax 

— >  mov  ax, OFFSET  DGROUP : $SG206 
— >  push  ax 
— >  call  _printf 
— >  add  sp, 4 

} 

— >  inc  si 
— >  cmp  si, 26 
— >  jl  $L20000 

— >  mov  WORD  PTR  [bp-2], si  /loop 

printf("i  /  16  =  %d\n\n",i  /  16); 

— >  mov  ax,di 
— >  cwd 
— >  xor  ax, dx 
— >  sub  ax, dx 
— >  mov  cx, 4 
— >  sar  ax, cl 
— >  xor  ax,  dx 
— >  sub  ax, dx 
— >  push  ax 

— >  mov  ax, OFFSET  DGROUP : $SG207 
— >  push  ax 
— >  call  _printf 
— >  add  sp, 4 

I 

— >  dec  di 
— >  jne  $1,20002 

— >  mov  WORD  PTR  [bp+4] , di 

— >  $FB202 : 

— >  pop  si 
— >  pop  di 
— >  mov  sp,bp 
— >  pop  bp 
— >  ret 
— >  nop 


int  main (void) 

{ 

func_ptr (100) ; 

— >  mov  ax, 100 
— >  push  ax 

— >  call  WORD  PTR  _func_ptr 
— >  add  sp, 2 

return  0; 

— >  sub  ax, ax 


Listing  Four 

***  Watcom  C  7.0  *** 
******************** 


End  Listing  Three 


♦include  "stdio.h" 

/*  prototypes  */ 

void  doit (int  i); 

void  (*  funcjotr) (int  i)  =  doit; 

void  doit (int  i) 

{ 

int  loop; 

— >  push  bx 

— >  push  cx 

— >  push  dx 

— >  mov  cx, ax 

— >  jmp  short  L3 

for  (;  i  >  0;  — i) 

{ 

for  (loop  =  0;  loop  <  26;  ++loop) 
{ 

— >  LI: 

— >  mov  bx,0041H 


printf("loop  character  =  %c\n",  0x41  +  loop); 
— >  L2: 

— >  push  bx 
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— >  mov  ax, offset  DGR0UP:L4 

— >  push  ax 

— >  call  near  ptr  printf_ 

— >  add  sp, 0004H 

— >  inc  bx 

— >  cmp  bx,005bH 

— >  jne  L2 

} 

printf("i  /  16  =  %d\n\n",i  /  16); 

— >  mov  bx, 0010H 

— >  mov  ax,  cx 

— >  cwd 

— >  idiv  bx 

— >  push  ax 

— >  mov  ax, offset  DGROUP:L5 

— >  push  ax 

— >  call  near  ptr  printf_ 

— >  add  sp, 0004H 

— >  dec  cx 

} 

— >  L3: 

— >  test  cx,cx 

— >  jg  LI 

— >  pop  dx 

— >  pop  cx 

— >  pop  bx 

— >  ret 

} 

int  main (void) 

{ 

func_ptr (100) ; 

— >  mov  ax, 0064H 

.  — >  call  word  ptr  _func_ptr 

return  0; 

— >  xor  ax, ax 

— >  ret 

> 

End  listing  Four 

Listing  Five 

#include  <string.h> 

I  #include  <stdlib.h> 

♦include  <stdio.h> 

♦include  <malloc.h> 

♦define  MAX_TAG  2000 
unsigned  long  get_size (void) ; 

_segment  segvar;  /*  name  a  segment  for  use  with  based  pointers  */ 

/*  set  up  structures  and  tags  within  segment  segvar  */ 

typedef  mytag  { 
char  filename [ 14 ] ; 
unsigned  long  size; 
mytag  _based (segvar)  *next; 

)  _based (segvar)  *PTAG,  TAG; 

main()  { 

PTAG  head,  curptr; 

/*  Allocate  a  based  heap  of  MAX_TAG  structs.  Put  segment  address  in  segvar.  */ 

if ((segvar  =  _bheapseg(sizeof (TAG)  *  MAX_TAG) ) )  ==  NULLSEG) { 
printf  ("error  allocating  based  heap  \n"); 
exit (-1) ; 

} 

/*  Allocate  memory  within  segvar  for  first  structure  in  linked  list  */ 

if ((head  =  _bmailoc (segvar,  sizeof(TAG))  ==  _NULLOFF)  { 
printf ("error  allocating  TAG  \n"); 
exit (-1) ; 

} 

head->size  =  get_size(); 

_fstrcpy ( (char  far  *)  head->filename,  get_name());  /*  get  a 
filename  and  copy  it  to  segvar  */ 

if ( (head->next  =  _bmalloc (segvar,  sizeof(TAG))  ==  _NULLOFF)  ( 
printf ("error  allocating  TAG  \n"); 
exit (-1) ; 

) 


} 

unsigned  long  get_size (void)  ( 
return  1; 

} 

char  *get_name (void)  { 
return ("foo") ; 

} 

End  Listings 
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PROGRAMMER'S  WORKBENCH 


Listing  One  (Text  begins  on  page  94.) 

//  COLLECT. CPP  :  collection  example,  with  multiple  inheritance  and 
//  pointers  to  members. 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  <stdlib.h> 

struct  item  { 

virtual  "item()  {}  //so  collection  can  properly  destroy  what  it  holds 

}; 

//  Suppose  we  have  a  pre-existing  class  to  hold  items: 
class  collection  { 

//  in  2.0,  "holder"  is  a  global  name.  In  2.1,  it's  hidden: 
struct  holder  { 

holder  *  next;  //  link  to  next  holder 
item  *  data;  //  pointer  to  actual  data 
holder (holder  *  nxt,  item  *  dat)  //  constructor 
:  next (nxt),  data (dat)  {} 

)  ‘head,  ‘cursor; 
public: 

//  initialize  an  empty  list: 

collection()  :  head( (holder  *)NULL),  cursor ( (holder  *)NULL)  () 

//  clean  up  the  list-  by  removing  all  the  elements: 

"collection ()  { 
cursor  =  head; 

while (cursor)  (  //  while  the  list  is  not  empty  ... 

delete  cursor->data;  //  delete  the  current  data 

head  =  cursor->next;  //  head  keeps  track  of  where  the  next  holder  is 
delete  cursor;  //  delete  the  current  holder 
cursor  =  head;  //  move  to  the  next  holder 

) 

) 

//  Paste  a  new  item  in  at  the  top  (this  is  tricky) : 
void  add(item  *  i)  (  head  -  new  holder(head,  i) ;  } 

//  reset {)  and  next()  return  the  current  item  or  null,  for  the  list's  end: 
item  *  reset ()  {  //  go  back  to  the  top  of  the  list 
cursor  =  head; 

//  the  list  may  be  empty;  only  return  data  if  cursor  isn't  null 
return  cursor  ?  cursor->data  :  (item  *)NULL; 

} 

item  *  next()  ( 

//  Only  move  forward  if  cursor  isn't  null: 
if (cursor)  cursor  =  cursor->next; 

//  only  return  data  if  cursor  isn't  null: 
return  cursor  ?  cursor->data  :  (item  *)NULL; 


//  Now  suppose  we  have  a  second  pre-exising  class  to  hold  words, 
//  keep  track  of  word  counts,  and  print  itself  in  2  ways: 
class  word  ( 
char  *  w; 
int  count; 
public: 

word (char  *  wd)  :  count (1)  { 

w  =  new  char(strlen(wd)  +1);  //  allocate  space  for  word 

strcpy (w,wd) ;  //  copy  it  in 

} 

~word()  ( 

printf("%s  :  %d  occurrences^",  w,  count); 
delete  w;  //  free  space  for  word 

) 

int  compare (char  *  testword)  { 
int  match  =  !strcmp(w,  testword); 
if  (match)  count++;  //  count  testword  if  it  matches 
return  match; 

} 

void  printK)  {  printf  ("%s\n",  w) ;  )  //  1  per  line 
void  print2 () ; 

}; 

//  Zortech  2.06  and  cfront  2.0  wouldn't  allow  the  following 
//  function  as  an  inline;  Turbo  C++  would, 
void  word: :print2 ()  {  //  print  several  words  per  line 

static  plcnt;  //  count  words  on  a  line 
const  words_per_line  =  7; 
printf ("%s  ",  w) ; 

if(++plcnt  %  words_per_line)  return; 
putchar (' \n' ) ;  //  only  when  remainder  is  0 


//  What  if  we  want  to  make  a  collection  of  words?  Multiple 

//  Inheritance  to  the  rescue: 

class  worditem  :  public  item,  public  word  { 

public: 

worditem (char  *  wrd)  :  word(wrd)  () 

); 

//  now  we  can  create  a  collection  of  worditems.  Here's  an  array 
//of  words  to  put  in  our  collection: 

char  *  words []  =  (  "this",  "is",  "a",  "test",  "of",  "worditem"  ); 

♦ifdef  TEST1 
main ( )  ( 

collection  c; 

for (int  i  =  0;  i  <  sizeof (words) /sizeof (words [0] ) ;  i++) 
c. add (new  worditem (words [i] )) ; 

//  NOTE:  Zortech  C++  2.06  doesn't  work  here. 

} 

♦endif  //  TEST1 

//  But  now  we  want  to  count  instances  of  words.  We  need  to  modify  the 
//  collection  class  so  it  conditionally  adds  a  word,  or  just  counts  it 
//  if  it  already  exists: 

class  wordcounter  :  public  collection  { 
public: 

//  Customize  for  worditems  (no  overhead): 
void  add(worditem  *  wi)  (  collection: : add (wi) ;  ) 


worditem  *  reset ()  {  return  (worditem  *) collection: : reset  () ;  } 
worditem  *  next()  {  return  (worditem  *) collection: : next () ;  ) 
void  add_or_count (char  *  newword)  { 
worditem  *  cur  =  reset (); 
while (cur)  { 

//  if  found,  increment  the  count  and  quit  the  search: 
if (cur->compare (newword) )  return; 
cur  =  next {) ; 

} 

//  at  this  point,  we  didn't  find  it,  so  add  it  to  the  list: 
add (new  worditem (newword) ) ; 

} 

//  Pointers  to  members  (Zortech  2.06  doesn't  support  this): 
void  apply (void  (word: : *pmf ) () )  ( 
worditem  *  wit  =  reset (); 
while (wit)  {  //  do  while  list  is  not  empty 

(wit->*pmf) ();  //  dereference  member  function  pointer 

wit  =  next();  //  get  next  list  element 

} 

) 

); 

char  *  words2[]  =  (  "this",  "this",  "is",  "a",  "test",  "test",  "test"  }; 

♦ifdef  TEST2 
main()  ( 

wordcounter  wc; 

for (int  i  =  0;  i  <  sizeof (words2) /sizeof (words2 [0] ) ;  i++) 
wc . add_or_count (words2 [i] ) ; 

//  Now  "apply"  two  different  functions  to  the  list: 

wc . apply (& word : :printl) ; 

wc. apply (& word: :print2) ;  putchar('\n' ) ; 

} 

♦endif  //  TEST2 

//  Now,  for  fun,  let's  use  this  class  to  count  the  keywords  and 
//  identifiers  in  a  C++  program.  Try  this  program  on  itself: 

//  collect  <  collect. cpp  >  count 

//  Look  up  strstrO,  strchr()  and  strtok()  in  your  ANSI  C 
//  library  guide. 

const  char  *  delimiters  =  "  \t^/ (){}[]<>.,;: *+-~! %A&=\\ I ?\' \""; 
const  char  *  digits  =  "0123456789."; 

♦ifdef  TEST3 

main()  (  //  use  i/o  redirection  on  the  command  line, 
wordcounter  symbol_table; 
char  buf (120) ; 

while  (gets (buf))  (  //  get  from  standard  input 

if (‘buf  ==  '#')  continue;  //  ignore  preprocessor  lines 
//  strip  all  quoted  strings  in  the  line: 

char  *  quote  =  strchr(buf,  '\"');  //  find  first  quoted  string 

while (quote)  ( 

if(quote[-l]  ==  '\\')  break;  //  for  \"  literal  quote 
*quote++  =  '  ';  //  erase  quote 

while  (‘quote  !=  'V'  &&  ‘quote  !=  0) 

*quote++  =  '  ' ;  //  erase  contents  of  string 
‘quote  =  '  ';  //  erase  ending  quote 

quote  =  strchr (quote,  '\"');  //  look  for  next  quoted  string 

} 

char  *  cmt  =  strstr(buf,  "//");  //  C++-style  comments  only 

if(cmt)  *cmt  =  0;  //  strip  comments  by  terminating  string 
puts (buf);  //  Look  at  the  modified  string 
char  *  token;  //  strtok  uses  delimiters  to  find  a  token: 
if ((token  =  strtok (buf,  delimiters))  !=  NULL) (  //  first  strtok  call 

if (strcspn (token,  digits))  //  ignore  constants 
symbol_table . add_or_count (token) ; 

//  subsequent  strtok  calls  for  the  same  input  line: 
while ((token  =  strtok (0,  delimiters))  !=  NULL) 
if (strcspn (token,  digits))  //  ignore  constants 
symbol  table. add  or  count (token) ; 

) 

)  //  print  the  list  in  2  ways,  using  pointers  to  members: 

symbol_table. apply (&word: : print 1) ; 

symbol_table. apply (Sword: :print2) ;  putchar (' \n' ) ; 

}  //  results  are  output  by  the  destructor  calls 

♦endif  //  TEST3 


End  Listing 
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Handling  OS/2 

Error  Codes 

Simplify  the  tracking  and  correcting  of  OS/2  development 
errors  with  this  utility 


Nico  Mak 


This  article  presents  OS2ERR,  a 
simple  and  effective  system  to 
handle  unexpected  OS/2  error 
codes  in  Microsoft  C  programs. 
When  an  OS/2  system  function 
reaims  an  error,  OS2ERR  displays  a  pop¬ 
up  screen  with  details  about  the  error. 
It  then  gives  you  a  choice  of  aborting 
or  continuing  the  program  that  caused 
the  error.  The  pop-up  screen  contains 
the  program  name,  process  ID,  thread 
ID,  error  code,  error  classification,  and 
the  recommended  action.  It  also  lists 
the  source  code  filename,  line  number, 
and  source  code  that  called  the  system 
function.  The  system  error  message  (if 
any)  for  the  error  code  is  displayed. 
This  information  greatly  simplifies  track¬ 
ing  and  correcting  the  problem.  Figure 
1  shows  a  typical  sample  output. 

This  detailed  error  report  saves  time 
during  application  development  and 
testing,  but  is  generally  inappropriate 
for  a  final  product.  OS2ERR  was  de¬ 
signed  to  be  used  in  conjunction  with 
typical  error  handling  routines  and  is 
easy  to  “turn  off.”  No  source  code 
changes  are  needed  to  disable  OS2ERR 
processing  —  just  recompile  and  relink 
as  described  later  in  this  article.  Or  you 
can  customize  OS2ERR  for  your  pro¬ 
duction  environment. 


Nico  Mak  is  a  software  developer  for 
Mansfield  Software  Group  in  Storrs, 
Conn.  He  can  be  reached  at  70056,241 
on  CompuServe  or  as  NicoJVlak  on 
BIX. 


Using  0S2ERR 

OS2ERR  is  easy  to  use.  First  include 
OS2ERR.FI  (see  Listing  One,  page  181) 
at  the  beginning  of  your  source  pro¬ 
gram,  after  including  the  OS/2  header 
files.  Then  use  the  os2chk(  )  macro  on 
any  OS/2  system  function  to  display 
the  pop-up  screen  if  the  function  gen¬ 
erates  an  error.  See  Example  1  for  an 
example  of  how  to  use  this  macro. 
Alternately,  you  can  use  the  os2(  /  macro 
on  system  functions  to  record  the  error 
code,  filename,  line  number,  and  source 
line  for  possible  later  use  in  an  error 
handling  routine.  The  poperrC  )  macro 
will  display  the  information  recorded 


Figure  1:  Sample  pop-up  screen 


by  the  os2( )  macro  along  with  other 
details  about  the  error.  See  Example  2 
for  an  example  of  how  to  use  these 
macros. 

Note  that  OS2ERR  waits  until  any 
existing  pop-up  screen  is  closed  before 
displaying  its  own  pop-up  screen.  The 
os2chk( )  and  poperr(  )  macros  should 
therefore  not  be  used  while  your  appli¬ 
cation  is  displaying  a  pop-up  screen. 

To  enable  OS2ERR  processing  while 
testing  your  application,  compile  your 
programs  with  the  -DOS2ERR  option, 
and  link  your  application  with  OS2- 
ERR.OBJ.  If  this  option  is  NOT  used, 
then  the  macros  do  not  generate  code, 


Error  code: 

6 

Program: 

D:\DDJ\ERRDEMO.EXE 

Command  tail: 

test 

Process  ID: 

98 

Thread  ID: 

1 

Action: 

Abort  in  an  orderly  manner 

Locus: 

Unknown 

Class: 

Application  error 

Source  name: 

D:\DDJ\ERRDEMO.C 

Source  line: 

11  (DosReadfhf,  But,  sizeof(Buf),  scbRead) ) 

Incorrect  internal  file  identifier . 

Press  Esc  to  abort  or  any  other  key  to  continue 

/*  examples  of  os2chk()  macro  * 
os2chk (DosClose (hanConf ig) ) ; 
os2chk (VioGetFont (Sviofi,  0)  ) ; 


/ 


/*  display  pop-up  screen  w/error  info 
/*  if  system  calls  return  error  codes 
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Example  1:  Examples  of  OS/ 2chk(  )  macro 
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and  OS2ERR  is  disabled.  When  OS2ERR 
is  disabled  you  do  not  need  to  link 
with  OS2ERR.OBJ. 

I’ve  tested  OS2ERR  with  Microsoft 
C,  Version  5.1,  and  IBM  OS/2,  Version 
1.10,  and  with  the  Microsoft  OS/2  Soft¬ 
ware  Development  Kit,  Version  1.06. 
Only  one  minor  change  was  needed 
when  switching  among  these  environ¬ 
ments:  The  DosGetPid  and  VioWrtTTy 
system  functions  were  renamed  to  Dos- 
GetPID  and  VioWrtTTYm  the  SDK. 

You  can  customize 
0S2ERR  for  your 
production 
environment 


OS2ERR  Components  and  Operation 

OS2ERR.H  defines  the  os2(  ),  os2chk( ), 
and  poperr( )  macros.  These  macros 
generate  calls  to  routines  in  OS2ERR.C 
(see  Listing  Two,  page  181).  The  os2( ) 
and  os2chk(  )  macros  pass  the  follow¬ 
ing  information  to  these  routines:  the 
source  code  of  the  OS/2  system  func¬ 
tion,  as  provided  by  the  ANSI  C  stringiz- 
ing  operator  (#),  the  file  name  and  line 

number,  as  provided  by  the _ FILE _ 

and _ LINE  predefined  identifiers,  and 

the  return  code  from  the  OS/2  system 
function. 

OS2ERR.C  contains  routines  to  dis¬ 
play  the  pop-up  screen,  error  messages, 
and  handle  the  abort  or  continue 
prompt.  In  addition  to  the  information 
passed  by  the  os2(  )  and  os2chk(  )  mac¬ 
ros,  these  routines  use  the  DosGetEnv 
function  to  access  the  program  name 


and  command  tail,  the  DosGetPID  func¬ 
tion  to  report  on  the  process  and  thread 
IDs,  the  DosErrClass  function  to  deter¬ 
mine  the  system  recommended  action, 
locus,  and  error  class,  and  the  DosGet- 
Message  function  to  obtain  the  system 
error  message  text.  They  use  the 
VioPopUp  and  VioEndPopUp  functions 
to  manage  the  pop-up  screen,  and  call 
KbdCharln  to  wait  for  the  user  to  press 
a  key.  If  the  user  presses  Esc  to  abort, 
the  DosExit  function  is  invoked  to  ter¬ 
minate  the  process. 

Conclusion 

OS2ERR  has  helped  me  to  quickly  iden¬ 
tify  the  source  of  a  number  of  OS/2 
development  problems.  I  hope  it  also 
saves  you  time.  If  you  make  enhance¬ 
ments  to  OS2ERR,  I  encourage  you  to 
upload  the  modified  code  to  the  Dr. 
Dobb’s  Forum  on  CompuServe.  I’ve  al¬ 
ready  uploaded  a  version  that  includes 
the  system  identifier  for  the  error  code 
(from  BSEERR.H)  if  there  is  no  system 
message  available  for  a  particular  error. 
Comments  and  suggestions  are  welcome. 

Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
online.  To  order  the  disk,  send  $14.95 
(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal ,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  the  Z/D/listing  service  (415-364- 
8315)  and  through  the  DDJ  Forum  on 
CompuServe  (type  GO  DDJ). 

DDJ 

(Listings  begin  on  page  181.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  13. 


/*  examples  of  os2  0  and  poperrO  macros  */ 

SubCommandProcess ( ) 
i 


if  ( !  set  jmp  ( jmpbuf ) )  ( 

/*  ...  processing  . . 


/*  set  up  error  handler  */ 


*./ 


err  ==  os2 (VioGetFont (Sviofi,  0));  /*  get  current  font  info  */ 

if  (err  ==  ERROR_VIO_EXTENDED_SG)  /*  if  running  in  a  VIO  window  */ 
InVioWindow  =  YES;  /*  remember  we're  in  window  */ 

else  if  (err)  /*  if  any  other  VioGetFont  error  */ 

poperrO;  /*  display  pop-up  screen  with  error  info  */ 


/*  ...  more  processing  .  . 


*/ 


if  (os2 (DosClose (hanConfig) )  /*  if  DosClose  returns  an  error  code  */ 
longjmp( jmpbuf) ;  /*  skip  to  application's  error  handler  */ 


.  .  yet  more  processing  ...  * / 


else 


poperrO;  /*  error  handler  -  display  pop-up  screen  with  error  info  */ 


Example  2:  Examples  of  OS/2(  )  and poperr(  )  macros 
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PROGRAMMING  PARADIGMS 


Windows  3.0 
Challenges  All  the 
Talent  in  the  Room 


he  title  of  this  month’s  column 
is  too  obscure  a  reference  to 
stand  unexplained. 

Thirty  years  ago  in  Advertise¬ 
ments  for  Myself,  Norman  Mailer 
established  his  reputation,  partly  for 
talent  but  mostly  for  arrogance.  In  a 
section  of  the  book  called  “Evalu¬ 
ations  —  Quick  and  Expensive  Com¬ 
ments  of  the  Talent  in  the  Room,”  he 
trashed  most  of  his  contemporary  writ¬ 
ers.  Myrick  Land  documented  the  en¬ 
suing  feuds  in  his  less  celebrated  but 
funnier  book,  The  Fine  Art  of  Literary 
Mayhem.  The  Mailer  chapter  —  Mailer 
must  have  been  miffed  to  find  that  the 
entire  book  was  not  devoted  to  him  — 
was  titled,  “Mr.  Norman  Mailer  Chal¬ 
lenges  All  the  Talent  in  the  Room.” 

Microsoft  spent  megabucks  rolling 
out  Windows  3  0  this  May  and  will  be 
spending  more  over  the  next  months 
to  encourage  Windows  2  users  to  up¬ 
grade  and  nonusers  to  take  the  plunge. 
Is  this  upgrade  such  a  big  deal? 

It’s  such  a  big  deal.  Bill  Gates  claims 
that  Windows  3.0  will  have  an  impact 
on  every  aspect  of  the  personal  com¬ 
puter  industry.  He’s  probably  right.  The 
following  are  some  thoughts  on  Win¬ 
dows  3.0  vs.  the  talent  in  the  room, 
with  the  glaring  exception  of  the  heavy- 


Michael  Swaine 


weight  contender  out  in  the  hall.  As 
Stephen  Morse  pointed  out  in  PC  Week , 
Presentation  Manager  is  quite  capable 
of  delaying  itself  with  no  help  from 
Windows  3  0 

Win  3  vs.  DOS 

Industry  watcher  Stewart  Alsop’s  view 
is  that  the  release  of  Windows  3.0  will 
increase  Apple  market  share  along  with 


the  Windows  market  share,  both  at  the 
cost  of  DOS.  PC  Week  quotes  Bill  Gates 
as  predicting  that  Windows  will  outsell 
DOS  in  a  year. 

Windows  as  a  threat  to  DOS  is,  in  a 
sense,  nonsense.  Nobody  is  going  to 
buy  Windows  rather  than  DOS.  Win¬ 
dows  is  a  DOS  extension,  more  closely 
integrated  with  DOS  than  any  shell, 
requiring  and  using  DOS,  in  particular 
the  DOS  file  system.  Furthermore,  Win¬ 
dows  3  supports  non-Windows  appli¬ 
cations,  meaning  plain  DOS  applica¬ 
tions.  Finally,  any  way  you  slice  the 
Windows/DOS  pie,  Microsoft  gets  fed. 

The  threat  that  Windows  poses  is  to 
DOS  as  a  development  platform.  It  raises 
the  question,  is  there  any  reason  to 
develop  for  plain  DOS  anymore?  The 
answer  is  surely  yes.  Here’s  a  sample 
of  some  classes  of  users  who  will  still 
need  or  want  raw  DOS. 

1 .  The  users  of  dedicated  one-applica¬ 
tion  PC-class  machines  that  do  their  re¬ 
spective  jobs  well.  If  such  a  user  sees 
no  need  to  upgrade  an  8086-class  ma¬ 
chine  running  DOS  and  such  an  appli¬ 
cation,  then  the  user  will  probably  not 
make  the  significant  investment  required. 
Some  such  applications,  despite  Win¬ 
dows  3’s  support  for  non-Windows  ap¬ 
plications,  will  need  an  upgrade,  and 
some  perfectly  functional  applications 
that  happen  to  be  no  longer  supported 
won’t  be  getting  any  upgrade. 

It’s  interesting  to  speculate  on  how 
many  of  these  machines  will  go  on 
cranking  away  in  such  environments. 
And  that’s  all  we  can  do:  speculate. 
Industry  history  is  not  long  enough  to 
base  predictions  on,  and  pre-personal 
computer  software  and  hardware  ex¬ 
perience  is  an  entirely  different  world 
of  technology  and  pricing.  But  the  mat¬ 
ter  is  unimportant  in  terms  of  develop¬ 


ing  commercial  software.  Such  machines 
and  people  effectively  become  invis¬ 
ible  to  the  market.  One  application, 
already  sold,  is  not  a  market;  people 
who  have  no  need  to  spend  money  are 
not  potential  customers.  The  veil  falls 
on  these  people. 

2.  The  impecunious.  Also  behind  the 
veil.  To  make  use  of  Windows  3  0,  in 
particular  to  be  able  to  use  multitasking, 
the  minimum  configuration  is  a  286 
with  2  Mbyte  of  memory  and  EGA.  Any 
PC  owner  who  doesn’t  have  this  hard¬ 
ware  has  the  choice  of  buying  it  or 
doing  without  Windows.  Some  will  do 
without,  and  like  homeless  people  in 
the  census,  will  drop  out  of  the 
demographics. 

3.  Users  of  embedded  systems.  Last  fall, 
Microsoft  released  ROM  Executable  MS- 
DOS  v.3.22,  a  true  DOS  in  ROM.  Da- 
talight  and  Digital  Research  both  also 
sell  ROMable  DOS  clones.  These  users 
probably  don’t  need  windows  and 
icons. 

4.  Engineers  and  scientists.  There  should 
be  no  compelling  reason  for  anyone 
in  this  market  to  buy  or  hang  on  to  a 
raw  DOS  machine  as  a  CPU;  if  there  is 
in  a  year  or  two,  it  will  mean  that  Win¬ 
dows  developers  have  not  been  seeing 
all  the  market  opportunities.  But  a  raw- 
DOS  machine  as  a  device  is  another 
thing  altogether.  One  can  easily  imag¬ 
ine  an  array  of  DOS  machines  control¬ 
ling  instruments,  with  a  Windows  box 
standing  between  all  of  them  and  the 
researcher  user. 

But  for  new  purchases  of  personal 
computers  for  business  and  other  com¬ 
mercial  uses,  raw  DOS  is  dead.  With 
upgrades  running  $50  even  for  run¬ 
time  users,  Windows  3  is  priced  well, 
and  Microsoft  is  pushing  it  hard. 
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Win  3  vs.  other  DOS  Extenders 

The  actual  competitors  to  Windows  on 
Intel  CPU-based  hardware  are  the  other 
DOS  extenders  or  Windowing  systems. 
Anyone  interested  in  the  technical  de¬ 
tails  of  how  DOS  extenders  can  live 
with  Windows  3-0  should  read  Ray  Dun¬ 
can’s  Extending  DOS  (Addison- Wesley, 
1990).  Theoretically,  the  DOS  Protected- 
Mode  Interface  (DPMI)  lets  a  DOS  ex¬ 
tender  attain  full  compatibility  with  Win¬ 
dows  3  0.  But  now  that  there  is  a  ca¬ 
nonical  windowing  extension  to  DOS 
produced  and  marketed  by  the  DOS 
folks,  it  won’t  be  fun  to  compete  in 
that  market.  And  Windows  3  is  much 
better  than  Windows  of  the  past. 

Win  3  vs.  Win  2 

Windows  3  is  a  big  improvement  over 
Windows  2.  What  strikes  one  immedi¬ 
ately  is  that  the  Romper  Room  primary 
colors  have  been  replaced  by  a  suite 
of  sophisticated  color  schemes.  This  is 
of  no  technical  significance  whatever, 
but  it  is  indicative  of  the  hand  of  de¬ 
signers  in  the  user  interface,  and  that’s 
very  important  to  the  product’s  suc¬ 
cess.  At  the  low  end,  where  a  big  battle 
will  begin  this  fall,  this  sort  of  thing 
matters  a  lot. 

Microsoft’s  Windows  3  GUI  team  in¬ 
cluded  human  factors  psychologists, 
and  visual  designers  were  involved  in 
the  development  of  the  GUI.  The  result 
is  a  product  that  should  be  significantly 
more  attractive  to  users  than  Windows 
2.  The  user  is  given  full  control  over 
color,  but  it’s  easier  to  select  a  prede¬ 
fined  suite  of  colors  that  look  good 
together  than  to  tweak  individual  col¬ 
ors.  This  is  a  good  example  of  provid¬ 
ing  the  customizability  but  guiding  the 
user  toward  reasonable  customizations. 

The  Windows  interface  now  uses  pro¬ 
portional  fonts.  Not  only  does  this  make 
the  display  more  readable,  but  it  also 
raises  the  professional  look  of  the  prod¬ 
uct.  Examining  installed  fonts  and  in¬ 
stalling  new  ones  is  simple  and  intui¬ 
tive.  The  next  release  is  expected  to 
use  TrueType  outline  fonts. 

Setup  and  configuration  for  particu¬ 
lar  hardware  is  largely  automatic.  This 
is  also  very  important  if  Microsoft  ex¬ 
pects  Windows  to  bring  new  people 
into  computing.  Apple,  which  has  an 
easier  job  of  it,  has  set  up  plug-and- 
play  expectations  that  Windows  has 
to  come  close  to  meeting,  and  does. 
Also,  user-friendly  Control  Panel  op¬ 
tions  let  the  user  select  printer  and 
network  options  from  lists;  these  selec¬ 
tions  become  effective  immediately,  with¬ 
out  reinstalling  or  restarting  Windows. 

There  are  some  holes  in  the  GUI  that 
let  DOS  show  through.  The  SysEdit 
program,  which  brings  up  all  configu¬ 


ration  files  for  editing,  is  very  handy, 
but  looking  through  a  Maclike  window 
at  DOS  batch  commands  will  be  a  dis¬ 
orienting  thing  for  a  new  computer 
user. 

All  these  user  interface  issues  are 
important  to  the  user  acceptance  and 
the  success  of  the  platform.  More  im¬ 
portant  from  a  technical  perspective 
are  the  questions  of  what  capabilities 
the  product  supports,  and  how  easy  it 
is  to  develop  for  it. 

The  big  accomplishment  is  probably 
memory  management.  Running  in  pro¬ 
tected  mode  on  the  286  and  386,  sup¬ 
porting  virtual  8086  machines  on  the 
386,  are  things  that  matter.  3-0  is  also 
more  cognizant  of  networks  than  2.x, 
but  it  doesn’t  demand  a  lot  of  network 
awareness  from  the  user.  New  APIs  let 
network  applications  mask  the  differ¬ 
ence  between  local  and  remote  re¬ 
sources.  Transparency  of  remote  ac¬ 
cess  is  going  to  become  important. 

It  will  take  time  for  the  benefits  of 
interapplication  communication  to 
emeige,  but  the  dynamic  data  exchange 
messaging  protocol  (DDE)  provides  the 
basis  for  applications  that  cooperate 
in  ways  not  seen  before. 

The  reassuring  news  is  the  ease  of 
transition  from  Version  2  to  Version  3, 
which,  Windows  developers  are  say¬ 
ing,  is  a  piece  of  cake.  The  essential 
tool,  of  course,  is  the  Windows  SDK, 
and  device  driver  developers  will  need 
the  DDK.  New  Windows  developers 
should  probably  start,  according  to  de¬ 
velopers  at  a  recent  meeting  of  the 
Software  Entrepreneurs  Forum,  with 
Charles  Petzold’s  Programming  Win¬ 
dows. 

While  the  GUI  is  not  as  unified  and 
intuitive  as  the  Mac’s,  it’s  close  enough 
to  make  a  Windows  box  look  like  a 
direct  competitor  to  a  Mac.  And  techni¬ 
cally,  Windows  has  capabilities  that  go 
well  beyond  what  the  Mac  does  at  pre¬ 
sent. 

Of  course,  Apple  has  something  up 
its  sleeve. 

System  7  vs.  System  6 

At  the  Apple  Worldwide  Developers 
Conference  in  May,  developers  got  five 
days’  intense  exposure  to  System  7,  the 
biggest  thing  in  Apple  system  software 
since  the  original  Mac  operating  sys¬ 
tem.  It’s  expected  to  be  out  by  the  end 
of  the  year. 

System  7  includes  a  new  Finder  and 
other  reworkings  of  the  user  interface. 
The  improvements  are  impressive,  de¬ 
livering  more  power  and  customizabil¬ 
ity  to  the  user  while  at  the  same  time 
making  the  interface  more  consistent, 
with  fewer  things  to  learn.  There’s  some¬ 
thing  more  than  consistency  involved; 
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(continued  from  page  138) 
it  has  to  do  with  getting  across  to  the 
user  a  big  idea,  a  general  metaphor, 
and  letting  the  user  figure  out  how 
things  ought  to  work.  Apple  does  a 
better  job  of  this  than  anybody  in  the 
industry,  and  Finder  7  is  better  at  it 
than  the  current  Finder. 

Now,  pretty  much  anything  the  user 
can  click  on  does  something  reason¬ 
able:  Applications,  utilities,  desk  acces¬ 
sories,  and  control  panels  all  launch 

Windows  as  a  threat 
to  DOS  is,  in  a  sense, 
nonsense.  Nobody  is 
going  to  buy  Windows 
rather  than  DOS 


when  clicked;  documents  open;  and 
other  things  return  useful  information 
about  themselves.  Some  formerly 
opaque  objects  now  open  to  reveal 
their  components.  This  natural  exten¬ 
sion  of  the  click-to-open  idea  elimi¬ 
nates  the  need  for  one  utility  and  one 
user  interface:  The  font/DA  mover  is 
no  longer  needed  because  fonts  and 
DAs  (desk  accessories)  are  stored  in 
openable  containers. 

Not  all  the  changes  reduce  the  set 
of  concepts  the  user  has  to  acquire. 
Apple  agonized  over  one  element  that 
it  has  finally  added  to  the  interface:  The 
movable  modal  dialog  box.  The  user 
interface  had  not  previously  distin¬ 
guished  modality  from  immovability, 
and  separating  these  aspects  visually 
caused  a  lot  of  headaches.  The  final 
design,  drawing  both  its  visual  appear¬ 
ance  and  performance  from  existing 
elements,  will  probably  pass  completely 
unnoticed  by  most  users,  which  will 
be  evidence  that  Apple  did  it  right. 

There’s  a  Find  menu  option  for  find¬ 
ing  files;  it  seems  to  be  fast,  and  allows 
a  lot  of  ways  to  direct  the  search.  There 
are  a  number  of  smaller  tweaks  to  the 
GUI.  Band  selection  and  window  and 
trash  behavior  have  been  honed.  The 
new  trash  can  is  another  example  of 
the  tighter  integration  of  the  interface: 
The  trash  can  was  formerly  a  unique 
object,  but  now  it’s  a  folder,  with  no 
peculiar  behavior  to  learn  and  adapt 
to.  There  are  new  sizes  and  colors  of 
icons.  The  outline  views  in  folders  and 
the  new  keyboard  equivalents  for 
mouse  moves  look  like  similar  features 
in  Windows. 


There’s  also  a  system-wide  help  sys¬ 
tem  called  “Balloon  Help.”  Turn  it  on 
via  an  ever  present  menu  item,  and 
anything  you  point  at  gives  some  help¬ 
ful  account  of  itself  in  a  pop-up  cartoon- 
style  word  balloon.  Apple  has  already 
documented  the  system  itself  with  Bal¬ 
loon  Help.  Developers  can  add  Bal¬ 
loon  Help  to  their  applications  without 
changing  any  code;  the  help  messages 
are  just  resources  with  pointers  to  the 
resources  (menu  items,  controls,  win¬ 
dow  parts,  and  so  on)  that  they  docu¬ 
ment.  Balloon  Help  is  one  aspect  of  the 
Toolbox  Help  Manager,  which  provides 
facilities  for  more  customized  help  sys¬ 
tems.  Balloon  Help  is  intended  to  pro¬ 
vide  a  basic  level  of  help,  letting  the 
user  ask,  “What  is  this?”  or  “What  does 
this  do?”  It’s  not  intended  to  be  the 
basis  of  a  complete  on-line  documen¬ 
tation  system,  but  Help  Manager  is  in¬ 
tended  to  provide  the  tools  for  build¬ 
ing  such  a  system. 

System  7  includes  virtual  memory, 
which  the  user  can  turn  on  or  off.  Mul- 
tiFinder  is  always  on,  so  the  System  7 
Mac  is  never  a  one-application  machine. 
Finder,  the  system-support  application, 
is  always  on,  reachable  via  an  everpre¬ 
sent  menu  at  the  right  end  of  the 
menubar,  its  capabilities  available  to 
other  applications  via  Apple’s  interap¬ 
plication  communication. 

The  interapplication  communication 
(IAC)  and  networking  features  are  nice. 
IAC  includes  several  components,  par¬ 
ticularly  AppleEvents,  Edition  Manager, 
and  the  PPC  Toolbox. 

AppleEvents  and  changes  to  the  cur¬ 
rent  Event  Manager  implement  the  frame¬ 
work  for  a  standard  language  of  mes¬ 
sages  that  applications  can  pass  to  each 
other  or  to  the  Finder.  The  set  of  stan¬ 
dard  events  is  largely  undefined;  Apple 
is  soliciting  developer  input.  A  few 
events  have  been  defined,  including 
Oapp  (open  application),  ODoc  (open 
document),  PDoc  (print  document),  and 
Quit.  All  future  applications  are  ex¬ 
pected  to  support  these,  and  others 
that  are  being  defined.  A  set  of  events 
called  “Finder  Events”  has  been  de¬ 
fined  and  implemented  in  the  Finder; 
applications  can  avail  themselves  of 
the  capabilities  of  the  Finder  by  gener¬ 
ating  Finder  Events. 

The  Edition  Manager  implements  the 
publish  and  subscribe  capability.  This 
is  live  copy  and  paste:  When  the  “pub¬ 
lished”  document  or  document  section 
is  updated,  all  subscribing  documents 
are  also  updated.  Apple  wants  all  ap¬ 
plications  to  support  publish  and  sub¬ 
scribe,  making  the  facility  as  ubiqui¬ 
tous  as  copy  and  paste.  There  currently 
are  some  user  interface  issues  to  be 
resolved;  even  Apple’s  own  HyperCard 
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(continued  from  page  140) 
team  appears  to  be  holding  off  on  sup¬ 
port  for  Edition  Manager  until  these 
issues  are  resolved. 

The  PPC  Toolbox  is  the  low-level 
facility  for  implementing  process-to- 
process  communication.  Since  there  is 
no  standard  set  of  events  at  this  level, 
it  will  require  close  cooperation  be¬ 
tween  application  developers  to  use 
this  level.  Because  it’s  low  level,  it  will 
provide  higher  performance  than  Ap- 
pleEvents.  It  will  probably  be  used  by 
large  software  vendors  to  put  high- 
performance  integration  into  suites  of 
applications.  This  superiority  of  perfor¬ 
mance  and  integration  will  probably 
be  used  to  sell  the  idea  that  users  ought 
to  buy  all  their  applications  from  one 
vendor.  Only  the  big  guys  will  be  able 
to  make  this  pitch. 

Win  3  vs.  System  7 

It  seems  likely  that  the  things  that  Win¬ 
dows  3.0  and  Mac  System  Software  Ver¬ 
sion  7  have  in  common  will  define 
personal  computer  application  devel¬ 
opment  in  the  ’90s. 

Graphical  user  interfaces  are  here  to 
stay.  A  serious  push  in  the  low  end  of 
the  market  by  clone  makers  bundling 
Windows  and  Apple  trying  to  redefine 
itself  as  a  company  will  make  it  very 
hard  to  sell  a  DOS  box.  I’ve  hinted  at 
this  low-end  war,  but  anyone  who  reads 
the  weeklies  or  heard  John  Sculley 
speak  at  the  Developer’s  Conference 
this  spring  knows  that  Apple  is  claim¬ 
ing  to  be  ready  to  accept  significantly 
lower  margins  to  compete  at  the  low 
end  with  a  line  of  high-volume,  low- 
cost  Macs.  These  machines  will  all  run 
System  7  and  will  not,  unless  Apple 
blows  it  badly,  be  feeble  machines. 
They  will  be  competitive  in  price  and 
performance  with  386  clones  running 
Windows  3.0. 

Multitasking,  interapplication  com¬ 
munication,  and  transparent  network 
accesses  will  result  in  new  kinds  of 
applications.  Large  vendors  will  develop 
interlocking  suites  of  applications  rather 
than  integrated  packages.  Smaller  ven¬ 
dors  will  develop  small,  targeted  appli¬ 
cations.  Utility  developers  will  come 
up  with  enhancement  products  that  ride 
on  other  products,  sending  messages 
to  these  products  to  get  their  work 
done.  Although  this  last  scenario  sounds 
a  little  like  spreadsheet  macros,  there 
is  a  difference  in  control.  A  spread¬ 
sheet  macro  runs  within  the  spread¬ 
sheet  application  and  is  vendor-spe¬ 
cific;  these  utility  applications  use  other 
applications  but  are  separate,  clickable 
applications,  and  they  should  work  with 
any  applications  that  support  the  Ap- 
pleEvents  they  generate. 
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Overall,  Apple  and  Microsoft  are  say¬ 
ing,  we’ll  see  more,  smaller  applica¬ 
tions. 

Applications  will,  more  and  more, 
take  on  a  tool  aspect.  What,  exactly, 
does  this  mean?  Like  all  the  preceding 
predictions,  this  is  just  what  Apple  and 
Microsoft  are  telling  developers.  It  would 
be  an  uncharitable  exaggeration  to  say 
that  the  message  Apple  and  Microsoft 
have  for  third-party  developers  is:  “We’ll 
talk  to  the  users;  you  just  talk  to  us.” 
That’s  not  what  they’re  saying.  Never¬ 
theless,  if  the  model  of  interprocess  or 

Applications  will,  more 
and  more,  take  on  a 
tool  aspect.  What, 
exactly,  does  this  mean? 


interapplication  communication  that  Ap¬ 
ple  and  Microsoft  are  pushing  comes 
fully  into  existence,  it  would  be  con¬ 
ceivable  for  a  user  to  use  a  product 
without  ever  seeing  its  user  interface. 

Nobody  is  talking  about  what  “more 
smaller  applications”  implies  in  the  bat¬ 
tle  for  computer  store  shelf  space. 

The  differences  between  Windows 
3  and  System  7  are  less  important  than 
the  similarities.  Apple  has  the  better 
user  interface,  but  it’s  not  clear  that 
that  will  make  any  difference  to  any¬ 
one  but  current  Mac  users.  I  can’t  see 
a  Mac  user  converting  happily  to  Win¬ 
dows,  but  the  superiority  of  the  Mac 
interface  may  not  be  great  enough  to 
affect  buying  decisions  by  present  PC 
users  or  new  computer  buyers. 

One  significant  difference  between 
the  two  systems  has  to  do  with  their  file 
systems.  Windows  3.0  still  uses  the  short 
DOS  file  names  and  sometimes  requires 
the  user  to  deal  with  DOS  path  names. 
More  objectlike  file  management  tools 
are  expected  in  the  future,  but  right 
now  the  file  handling  has  some  kludgy 
aspects,  and  the  DOS  file  names  are 
unfriendly. 

Mac’s  System  7  has  a  new  file  track¬ 
ing  system  called  “Alias  Manager.”  On 
the  surface,  Alias  Manager  lets  users 
create  aliases,  which  are  small  files  that 
refer  to  other  files.  Create  several  ali¬ 
ases  for  an  application  and  you  can 
store  the  aliases  in  different  folders. 
Click  on  any  of  the  aliases  and  the 
original  application  gets  launched.  The 
user  doesn't  have  to  worry  about  paths, 
because  the  Alias  Manager  keeps  track 
of  the  original  even  if  it  or  the  aliases 
are  moved  or  renamed. 


The  Alias  Manager  does  more  than 
permit  aliasing  of  files,  though.  It  is,  as 
of  System  7,  the  tool  of  choice  for  keep¬ 
ing  track  of  files  for  any  purpose.  The 
standard  file  facility  will  use  it,  so  any 
application  using  Standard  File  will  get 
the  benefits  of  Alias  Manager  from  it. 
Alias  Manager  can  be  used  for  a  wide 
variety  of  purposes.  For  one  example, 
you  put  an  alias  for  every  data  file  on 
your  hard  disk  into  a  folder  called  ar¬ 
chive,  then  archive  all  the  data  files  to 
floppy  disks.  Now  when  you  click  on 
the  alias  in  the  archive  folder,  the  Alias 
Manager  will  prompt  you  to  insert  the 
appropriate  diskette.  Since  the  alias  files 
themselves  are  very  small,  this  lets  you 
catalog  all  your  diskettes.  Aliasing  vol¬ 
umes  lets  you  kludge  a  simple  network 
manager.  The  highlight  of  the  Alias 
Manager  session  at  the  Developer’s  Con¬ 
ference  was  the  simple  Adventure  game 
created  on  the  desktop  without  any 
programming  simply  by  aliasing  files 
and  folders. 

The  alias  manager  works  by  main¬ 
taining  alias  records  in  memory,  and 
employs  a  whole  battery  of  heuristics 
for  identifying  the  target  volume  and 
the  target.  It  is  not  easily  confused  by 
mere  renaming  or  moving  of  the  target, 
and  will  search  across  network  zones 
and  request  mounting  of  volumes  if 
necessary. 

The  discussion  of  Mac  OS  and  Win¬ 
dows  similarities  and  differences  ought 
to  lead  to  a  discussion  of  porting  strate¬ 
gies,  or  to  a  discussion  of  techniques 
for  developing  one  program  for  both 
environments.  A  couple  of  years  ago, 
Michael  Brian  Bentley  wrote  an  inter¬ 
esting  but  intimidating  book  called  The 
Viewport  Technician  (Scott,  Foresman, 
1988),  about  writing  software  for  multi¬ 
ple  windowing  platforms.  If  it’s  getting 
easier  to  do  that,  and  to  end  up  with 
efficient  programs,  that  would  be  news, 
but  it’s  not  clear  that  it  is. 

ToolBook  vs.  HyperCard 

The  porting  problem  has  been  ad¬ 
dressed  for  two  applications  that  will 
be  bundled  with  Windows  3  and  Sys¬ 
tem  7:  ToolBook  and  HyperCard.  Tool¬ 
Book,  from  Microsoft  co-founder  Paul 
Allen’s  company  Asymmetrix,  is  a  Hy- 
perCard-like  software  construction  kit 
that  requires  Windows  3-0.  ToolBook 
substitutes  the  page-in-book  metaphor 
for  HyperCard’s  card-in-stack  metaphor 
and  has  some  more  concrete  differ¬ 
ences  with  HyperCard  as  well,  but  it  is 
definitely  intended  to  be  the  Hyper¬ 
Card  equivalent  for  Windows.  The  lat¬ 
est  version  of  HyperCard,  2.0,  has  some 
powerful  features,  but  it  still  lacks  some 
of  the  capabilities  of  ToolBook.  The 
products  are  enough  alike  that  Heizer 
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Software  has  already  announced  a  prod¬ 
uct  that  converts  HyperCard  stacks  into 
ToolBook  books.  I  haven’t  seen  it  yet. 

I  have  seen  ToolBook,  and  I’ve  seen 
HyperCard  2.0.  I  reviewed  ToolBook 
in  Personal  Workstation  magazine  re¬ 
cently,  and  will  be  writing  more  about 
it  and  HyperCard  2.0  here  soon.  What 
follows  here  is  a  look  at  how  “the 
hypertext  problem”  is  handled  by  Tool¬ 
Book  and  HyperCard  2.0. 

In  my  June  column  I  talked  about 
ways  in  which  some  people  have  used 
HyperCard  and  HyperTalk  to  do  re¬ 
search  into  what  could  be  called  the 
hypertext  problem.  The  problem  is  how 
to  implement  links  in  text,  and  there  is 
as  yet  no  consensus  on  the  proper  way 
to  do  it.  After  writing  that  column,  I  got 
my  hands  on  HyperCard  2.0.  Apple  did 
a  better  job  of  leaving  the  developer’s 
options  open  than  I  expected  when  I 
wrote  that  column,  but  still  didn’t  pro¬ 
vide  everything  the  hypertext  author 
might  want.  Meanwhile,  Windows  3  0 
came  out,  and  Asymmetrix  finally  got 
to  release  its  ToolBook.  ToolBook  runs 
under  Windows  3-0  and  is  very  compa¬ 
rable  to  HyperCard  2.0,  but  its  approach 
to  the  hypertext  problem  differs  funda¬ 
mentally  from  HyperCard’s. 

The  basic  problem  is  this:  Given  a 
body  of  text,  we  want  to  be  able  to 
permit  the  reader  to  click  on  part  of  the 
text  and  have  something  happen.  The 
“something”  is  usually  the  display  of 
further  information  on  the  subject  cov¬ 
ered  in  the  clicked-on  text.  This  is  in¬ 
formation  that  doesn’t  fit  into  the  linear 
structure  of  the  running  text:  a  defini¬ 
tion,  an  optional  detail,  a  digression. 
The  further  information  may  be  dis¬ 
played  in  any  of  a  variety  of  ways:  As 
a  replacement  text  that  takes  the  place 
of  the  clicked-on  text,  in  a  pop-up  field 
overlayed  on  the  clicked-on  field,  or 
in  another  body  of  text  like  the  original 
body. 

What  I  call  the  hypertext  problem 
has  two  parts.  The  first  part  of  the  prob¬ 
lem  is  how  to  indicate  to  the  user  what 
can  be  clicked  on.  In  linear,  printed 
text,  there  are  established  conventions 
(for  example,  parentheses  and  foot¬ 
notes)  for  signalling  a  departure  from 
strict  linear  structure.  The  footnote  con¬ 
vention  is  the  closest  to  what  goes  on 
in  hypertext  systems:  We  use  a  super¬ 
scripted  character  to  signal  the  exis¬ 
tence  of  a  link  to  a  block  of  text  at  the 
foot  of  the  current  page.  Among  the 
techniques  proposed  for  signalling  hy¬ 
pertext  links  are  superscripted  charac¬ 
ters,  font  changes,  and  boxes  around 
text. 

The  other  part  of  the  hypertext  prob¬ 
lem  involves  that  imprecise  phrase,  “per¬ 
mit  the  reader  to  click  on  parts  of  the 


text.”  What  could  a  hypertext  author 
mean  by  “part”?  Must  every  link  be  tied 
to  a  single  word?  Footnotes  in  linear 
printed  text  often  refer  to  entire  sen¬ 
tences  or  paragraphs,  although  there 
is  often  no  visual  cue  to  suggest  this. 
Can  the  clickable  zones  in  a  hypertext 
document  overlap;  that  is,  can  you  ar¬ 
range  that  a  sentence  and  a  word  in  the 
sentence  are  each  independently  click- 
able,  each  invoking  a  different  text  link? 
Must  clickable  text  be  contiguous? 

But  this  second  part  of  the  problem 
gets  a  little  deeper  than  this.  Does  the 
link  pertain  to  a  particular  instance  of 
the  text,  to  any  appearance  of  that  text 
fn  the  text  field,  or  to  the  nth  word  in 
the  field,  whatever  it  might  be?  For 
particular  hypertext  purposes,  any  of 
these  might  be  desirable. 

Case  1:  Linking  off  a  particular  in¬ 
stance  of  a  particular  string.  If  you  want 
the  link  object  (the  clickable  text)  to 
have  substance,  so  that  it  remains  a 
functioning  link  even  when  you  move 
it  somewhere  else,  you  probably  want 
something  like  this. 

Case  2:  Linking  off  any  instance  of  a 
particular  string.  One  excellent  use  of 
hypertext  links  is  to  provide  definitions 
for  technical  terms  in  a  document.  The 
author  does  not  want  to  force  the  reader 
to  look  at  the  definition  the  first  time  a 
particular  term  is  used,  but  wants  to 
allow  the  user  to  look  up  the  word  by 
clicking  on  any  instance  of  the  word 
in  the  document.  The  logic  is  that,  for 
any  particular  use  of  the  term,  the  user 
may  be  able  to  work  out  part  of  its 
meaning  from  context  or  outside  knowl¬ 
edge,  but  may  still  need  a  definition 
later  when  the  term  is  used  in  a  differ¬ 
ent  context.  For  this  or  a  variety  of 
other  reasons,  a  full  hypertext  author¬ 
ing  system  ought  to  allow  the  author 
to  create  a  single  link  for  all  instances 
of  a  particular  word  or  phrase. 

Case  3:  Linking  off  whatever  string 
occupies  a  particular  position.  “Posi¬ 
tion”  here  refers  to  text  position  in  a 
document,  not  pixel  location  on  a 
screen.  This  approach  allows  the  author 
to  create  links  that  depend  on  the  struc¬ 
tural  features  of  a  document.  While  this 
might  not  be  useful  for  casual  text,  it 
might  make  sense  for  highly  formal¬ 
ized  documents,  such  as  a  block  of 
assembly  language  code. 

This  is  one  way  of  slicing  up  some  of 
the  hypertext  territory;  these  cases  don’t 
cover  all  the  possibilities  or  represent 
the  only  way  to  segment  the  possibilities. 

I  present  them  only  to  give  some  frame¬ 
work  for  looking  at  what  ToolBook 
and  HyperCard  2.0  actually  do. 

ToolBook  and  the  Hypertext  Problem 

ToolBook  has  two  main  ways  to  show 


the  clickable  text  to  the  user.  First,  the 
cursor  changes  when  passing  over  this 
text.  Second,  there  is  a  facility  for  mak¬ 
ing  all  the  links  visible.  One  conven¬ 
ient  time  to  do  this  is  when  the  cursor 
passes  over  the  text  field.  This  tech¬ 
nique  puts  a  box  around  each  instance 
of  linking  text.  These  two  techniques 
are  well  thought  out.  The  cursor  change 
does  not  use  any  element  that  might 
have  another  meaning  in  the  text,  such 
as  italics,  and  is  perfectly  obvious  if 
you’re  looking  for  it  without  being  ter¬ 
ribly  intrusive  if  you’re  not.  The  boxing 
also  does  not  use  a  feature  that  you 
would  want  to  use  for  other  text  pur¬ 
poses.  The  boxes  could  clash  with  other 
framing  devices,  and  could  look  ugly, 
but  since  it  can  be  toggled  on  or  off 
easily,  this  is  not  too  serious.  It’s  chiefly 
a  peeking  device  for  the  user.  You  could 
also  use  font-style  change  to  signal  a 
link,  since  ToolBook  lets  you  mix  fonts 
and  styles  within  a  field,  something 
that  HyperCard  formerly  did  not  do. 

ToolBook  implements  links  via  hot- 
words.  A  hotword  is  an  object  with 
properties,  a  script,  and  a  place  in  the 
object  hierarchy  of  ToolBook.  You  cre¬ 
ate  a  hotword  by  selecting  text  and 
choosing  a  menu  option  that  makes 
that  text  a  hotword.  A  hotword  is  a 
Case  1  link,  a  link  off  a  specific  in¬ 
stance  of  text.  You  can  move  or  copy 
it  and  the  link  moves  with  it,  because 
the  link  is  defined  by  the  script  of  the 
object.  You  can  also  edit  the  text  of  a 
hotword,  although  if  you  delete  all  its 
text,  the  object  disappears. 

HyperCard  2.0  and 
the  Hypertext  Problem 

In  June,  I  documented  some  of  the 
contortions  that  HyperCard  stack  de¬ 
velopers  went  through  to  kludge  some 
sort  of  hypertext  facility  in  HyperCard. 
Because  HyperCard  and  ToolBook  both 
have  programming  languages,  that  sort 
of  roll-your-own  hypertext  is  always 
possible.  There’s  probably  no  approach 
to  hypertext  that  can’t  be  implemented, 
some  way  or  other,  with  each  of  these 
products.  But  hypertext  systems  have 
to  have  reasonable  performance,  and 
that  means  that  the  hypertext  abilities 
of  these  products  depend  on  the  tech¬ 
niques  built  in.  With  Version  2.0,  Hy¬ 
perCard  has  more  hypertext  capabili¬ 
ties  built  in  than  it  formerly  had. 

In  the  area  of  showing  the  clickable 
text  to  the  user,  HyperCard  puts  all  the 
decisions  in  the  hands  of  the  devel¬ 
oper.  Since  there  are  different  purposes 
for  hypertext  and  the  jury  is  still  out 
on  the  user-interface  decisions,  this  is 
generally  the  smart  approach  when  you 
want  to  provide  a  flexible  hypertext 
authoring  system.  But  the  flexibility  Ap- 
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pie  offers  is  chiefly  in  font  and  style 
change,  which  is  a  usurpation  of  the 
features  of  text  for  the  purposes  of 
hypertext.  One  option  for  marking  links 
that  would  not  be  at  all  easy  to  imple¬ 
ment  in  HyperCard  is  the  ToolBook 
box,  and  messing  with  the  cursor  in 
HyperTalk  could  be  problematic. 

HyperCard  implements  links  via  field 
handlers.  Text  can  be  grouped,  provid¬ 
ing  some  of  the  capability  of  Tool¬ 
Book’s  hotwords,  and  a  field  script  can 
examine  attributes  of  the  clicked  word, 
clicked  line,  or  arbitrary  grouping  of 
clicked-on  text.  It’s  possible  to  test  font 
or  style  and  link  off  it,  which  is  an 
interesting  reversal:  Instead  of  high¬ 
lighting  the  link,  you  link  off  the  high¬ 
light.  HyperCard’s  field  handler  ap¬ 
proach  to  hypertext  means  that  you 
can  key  off  any  instance  of  a  particular 
word  or  text  with  a  single  handler  (Case 
2).  Case  3  links  are  also  fairly  directly 
supported  by  this  scheme,  but  not  Case 
1  links. 

Here  are  my  closing  thoughts  on  Tool¬ 
Book,  HyperCard,  and  the  hypertext 
problem: 

The  indication  of  links:  This  is  hy¬ 
pertext;  i.e.,  more  than  text.  To  indicate 
the  links,  the  author  must  add  some¬ 
thing  to  the  text,  and  in  particular  to  the 
visual  appearance  of  the  text.  I’m  not 
sure  that  it  is  widely  understood  that 
the  indication  of  links  raises  spatial  de¬ 
sign  problems.  Writers  have  not  in  the 
past  had  to  deal  with  such  issues,  but 
hypertext  authors,  because  they  are  work¬ 
ing  in  more  than  one  dimension,  do 
have  to  deal  with  spatial  design  in  their 
documents.  It  is  up  to  the  hypertext 
author  to  create  and  indicate  links  with¬ 
out  making  the  document  ugly  and 
unreadable. 

What  to  link  from:  Between  the  two 
of  them,  HyperCard  and  ToolBook 
cover  the  linking  techniques  I  some¬ 
what  arbitrarily  defined  here.  In  my 
opinion,  both  of  them  ought  to  provide 
the  tools  for  creating  any  of  the  types 
of  links  I’ve  described,  or  any  reason¬ 
able  kind  of  link  anybody  might  come 
up  with,  if  they  are  to  serve  as  general 
hypertext  authoring  systems.  Neither, 
of  course,  is  being  marketed  as  a  gen¬ 
eral  hypertext  authoring  system,  but 
many  people  will  be  building  hypertext 
documents  with  them.  And  until  some¬ 
one  demonstrates  an  unequivocally 
“best”  way  to  implement  hypertext  links, 
the  hypertext  author  should  not  be  con¬ 
strained  to  one  or  a  few  techniques. 
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The  Past,  the  Future, 
and  Multi-mania 


The  annual  C  issue  is  a  special  one 
to  me.  Besides  being  devoted  to 
C,  the  issue  is  also  my  anniver¬ 
sary  with  DDJ as  the  C  columnist. 
August  1990  starts  my  third  year,  and 
marks  the  time  for  a  retrospective  view 
of  the  past  two  years.  A  lot  has  hap¬ 
pened.  In  that  time  we  watched  C 
strengthen  its  position  as  the  preeminent 
software  development  language.  The 
major  milestone  in  the  advancement 
of  C  was  the  approval  by  ANSI  of  the 
standard  definition  early  this  year.  It 
was  a  long  time  coming.  Second  place 
goes  to  the  gradual  swell  and  then 
sudden  explosion  of  interest  in  and 
use  of  C++. 

Other  milestones.  The  Integrated  De¬ 
velopment  Environment  established  it¬ 
self  as  the  preferred  way  to  write  and 
test  C  code.  Source-level  debuggers  got 
bigger  and  better.  Developers  of  oper¬ 
ating  environments  began  producing 
Applications  Program  Interface  libraries 
so  that  C  programmers  could  write  code 
into  those  environments  more  easily. 

None  of  these  developments  actu¬ 
ally  started  in  the  last  two  years.  They 
have  all  been  around  for  a  while.  But 


Al  Stevens 


each  of  them  really  took  hold  in  the 
very  recent  past. 

Several  important  new  compiler  ver¬ 
sions  came  out  in  the  first  half  of  1990. 
Borland  announced  Turbo  C++  in  May. 
Microsoft  released  Version  6.0  of  the 
Microsoft  C  compiler.  Watcom  released 
Version  7.0  with  8.0  coming  soon. 
Zortech  released  their  C++  Version  2.0. 
It  is  important  to  consider  as  well  what 


did  not  happen  in  that  period.  Neither 
Unix  nor  OS/2  took  over  the  PC  mar¬ 
ketplace.  Graphics  user  interfaces  did 
not  replace  text-based  applications.  Ev¬ 
ery  workstation  does  not  have  a  CD- 
ROM.  Programmers  have  not  been  re¬ 
placed  by  application  generators  or  so- 
called  fourth-generation  languages. 

The  Future 

You  do  not  need  tarot  cards  to  guess 
what  C  programmers  are  going  to  be 
doing  in  the  next  several  years.  A  preva¬ 
lent  platform  target  for  programmers 
will  be,  I  believe,  workstations  operat¬ 
ing  in  a  network.  For  the  foreseeable 
future,  at  least,  the  workstations  will 
be  MS-DOS  machines,  and  the  networks 
will  be  NetWare.  There  is  nothing  bold 
about  that  prediction  except  that  it  might 
raise  the  dander  of  those  who  believe  or 
who  would  prefer  that  it  is  inaccurate. 

The  position  of  the  DOS  machine  is 
secure.  The  acceptance  of  the  NetWare 
environment  is  growing.  They  are  a 
natural  fit  because  a  NetWare  system 
can  readily  accommodate  software  that 
runs  as  well  on  a  single-user  PC.  Log 
into  the  network,  and  your  DOS  appli¬ 
cation  takes  on  the  properties  of  a  mul¬ 
tiuser  system.  Usually.  Many  of  us  will 
be  writing  DOS  applications  that  can 
sense  the  presence  of  a  network  and 
deal  appropriately  with  it.  To  prepare 
we  need  to  understand  the  environ¬ 
ment  and  look  at  some  of  the  tools  that 
support  it. 

Multiuser 

Multiuser  systems  in  the  past  had  mul¬ 
tiple  terminals  connected  to  a  single 
computer  with  a  multiuser  operating 
system.  Unix  is  such  a  system.  Each 


user  had  a  terminal.  One  processor 
executed  the  programs  for  each  user. 
The  processor  jumped  from  user  to 
user  by  giving  slices  of  CPU  time  to 
each  terminal. 

Today  the  terminals  are  computers 
themselves.  They  run  their  own  pro¬ 
grams.  A  network  architecture  takes 
advantage  of  that  fact  by  off-loading 
to  the  workstations  the  work  that  is 
done  specifically  for  the  user  and  let¬ 
ting  the  host  machine,  the  “file  server,” 
perform  the  common  and  shared  tasks. 
The  multiuser  aspects  of  the  system  are 
managed  by  the  file  server. 

A  network  file  server  maintains  and 
stores  the  system’s  shared  resources, 
including  common  data  files,  software, 
and  printers.  The  file  server  can  also 
perform  services  that  are  common  to 
all  users.  One  example  of  such  com¬ 
mon  services  is  electronic  mail.  An- 
ptherTs  printer  sharing. 

An  advantage  to  the  network  archi¬ 
tecture  is  that  when  users  disconnect 
from  the  network  or  the  server  goes 
down,  the  users  are  still  in  business 
because  their  workstations  are  stand¬ 
alone  computers.  If  you  write  a  network- 
cognizant  program  that  can  run  in  the 
network  or  by  itself,  then  you  have 
made  good  use  of  that  advantage.  Be¬ 
sides  supporting  network  users,  your 
program  can  be  run  by  other  users 
who  do  not  have  networks. 

Multitasking 

Multitasking  is  when  a  user  can  run 
more  than  one  program  from  the  same 
workstation.  In  the  old  days  a  user  started 
a  program  from  the  command  line  at  the 
terminal.  The  operating  system  in  the 
distant  computer  started  it  up.  If  the 
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program  was  interactive  (communicated 
with  the  user  via  the  console),  the  user 
could  call  up  the  operating  system  com¬ 
mand  line  with  a  special  hotkey.  If  the 
program  ran  in  the  background,  the  OS 
returned  the  terminal  to  the  command¬ 
line  prompt  as  soon  as  the  program  was 
underway.  In  either  case  the  user  could 
start  a  second  program  and  the  two  ran 
together  in  tandem. 

Some  personal  computers  have  mul¬ 
titasking  operating  systems.  The  Amiga 
has  AmigaDOS.  The  Tandy  Color  Com¬ 
puter  uses  OS-9-  The  PCs  DOS  is  not 
a  multitasker,  which  is  why  TSRs  were 
invented.  But  a  DOS  user  has  a  choice. 
If  the  PC  has  enough  extended  or  ex¬ 
panded  memory,  a  DOS  user  can  add 
a  multitasking  shell  to  DOS  and  have 
all  the  benefits  of  the  multitasking  en¬ 
vironment.  DesqView  is  one  such  shell. 
I  am  writing  this  column  with  XyWrite 
and  DesqView  386.  At  the  same  time  I 
am  compiling  a  large  C  system  and 
exchanging  electronic  mail  messages 
with  kindred  souls  on  CompuServe. 
Do  not  let  anyone  tell  you  that  you 
cannot  multitask  a  DOS  PC. 

If  you  write  programs  to  run  in  a 
multitasking  environment,  you  can  take 
advantage  of  that  environment  by  writ¬ 
ing  parallel  processes  that  are  aware 
of  one  another.  For  example,  a  data¬ 


base  program  can  spawn  a  search  pro¬ 
cess  as  a  separate  task  and  return  to  the 
query  composition  program.  The  user 
can  be  writing  another  query  while  the 

The  main  purpose 
for  the  file  server 
is  to  permit  users  to 
share  the  server’s 
disk  space  and  to 
share  files 


first  one  is  being  processed.  You  can 
use  the  facilities  of  the  multitasker  to 
synchronize  processes. 

Mix  and  Match 

Assume  that  you  target  your  next  appli¬ 
cation  for  workstations  with  DesqView 
running  on  a  NetWare  network.  You 
can  ignore  those  environments  and 
write  a  DOS  application  and  it  will 
probably  run  OK.  It  will,  that  is,  unless 
you  completely  ignore  the  fact  that  more 


than  one  user  could  be  running  that 
program. 

There  are  things  to  concern  you  when 
you  run  a  program  on  a  network.  Sup¬ 
pose  the  program  has  one  configura¬ 
tion  file  with  a  fixed  name  in  a  fixed 
place.  All  your  users  are  stuck  with 
using  the  same  configuration  of  op¬ 
tions  because  each  of  them  cannot  have 
his  or  her  own  copy  of  the  file.  A 
network-aware  program  does  not  build 
in  such  restrictions. 

There  are  things  to  consider  about  a 
program  that  runs  in  a  multitasking 
environment.  The  closer  the  program 
gets  to  the  hardware,  the  less  likely  it 
is  to  peacefully  coexist  with  other  pro¬ 
grams.  Do  not  confuse  TSRs  with  mul¬ 
titasking.  A  TSR  takes  over  the  whole 
machine  by  tricking  DOS  into  thinking 
the  TSR  is  the  only  program  running. 
It  changes  the  environment  to  suit  itself 
and  puts  things  back  the  way  it  found 
them  when  it  is  done.  A  multitasked 
program  runs  in  a  virtual  DOS  machine 
within  the  context  of  the  multitasking 
shell.  Other  programs  run  in  that  con¬ 
text  concurrently.  If  your  program  re¬ 
programs  the  keyboard,  reads  and  writes 
the  mouse  ports  directly,  and  writes 
into  video  RAM  indiscriminately,  it  can 
mangle  the  environment  for  the  other 
(continued  on  page  153) 
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(continued  from  page  150) 

programs  running  in  the  same  physical 

machine. 

Writing  an  application  that  is  well- 
behaved  in  these  environments  and  that 
will  work  as  well  in  a  vanilla  DOS  PC 
is  no  easy  feat.  You’d  be  nuts  to  tackle 
it  without  help.  Quarterdeck  Office  Sys¬ 
tems,  the  vendor  of  DesqView,  and  No¬ 
vell,  the  vendor  of  NetWare,  both  pro¬ 
vide  C  programmer’s  API  packages  to 
allow  you  to  integrate  the  functions  of 
those  environments  with  those  of  your 
C  programs.  This  month  we  discuss  the 
NetWare  C  Interface-DOS  package. 

The  NetWare  Environment 

A  NetWare  network  consists  of  a  file 
server  and  a  number  of  DOS  worksta¬ 
tions.  The  file  server  is  usually  a  PC 
dedicated  to  its  server  functions,  and  it 
runs  unattended.  The  workstations  each 
have  a  network  card  that  is  cabled  to 
the  file  server.  There  are  different  elec¬ 
tronic  standards  for  the  connection  and 
different  cabling  conventions. 

The  main  purpose  for  the  file  server 
is  to  permit  users  to  share  the  server’s 
disk  space  and  to  share  files.  A  secon¬ 
dary  purpose  allows  users  to  share  print¬ 
ers.  You  can,  therefore,  build  a  net¬ 
work  where  most  of  the  disk  space  and 
all  of  the  printers  are  on  the  server.  The 
workstations  have  the  minimum  hard¬ 
ware  needed  to  run  the  programs.  All 
the  software  and  most  of  the  data  files 
are  on  the  server. 

Once  the  server  is  ainning,  each  work¬ 
station  runs  a  TSR  program  called  the 
“network  shell.”  Its  purpose  is  to  com¬ 
municate  between  the  server  and  the 
workstation.  The  shell  observes  how 
many  disk  drives  the  workstation  has 
and  maps  higher-drive  letters  to  the 
volumes  on  the  file  server.  Then  it  in¬ 
tercepts  DOS  calls.  If  a  program  is  open¬ 
ing,  closing,  reading,  or  writing  a  file 
on  one  of  the  server  drives,  the  shell 
exchanges  packets  with  the  server.  Oth¬ 
erwise  it  passes  the  calls  through  to 
DOS  on  the  workstation.  The  program 
usually  does  not  need  to  know  the 
difference.  Sounds  simple  enough.  In 
fact,  the  environment  is  much  more 
complex  than  that. 

Ideally,  a  user  would  be  unaware 
that  the  network  is  operating.  Except 
for  some  additional  commands,  the  user 
interface  is  the  same  as  DOS.  But  there 
are  some  internal  things  that  can  muddy 
up  the  process  and  that  a  programmer 
needs  to  know  about.  A  high-level  user 
called  the  “network  administrator”  as¬ 
signs  passwords  and  grants  privileges 
to  users  to  restrict  access  to  server  file 
subdirectories.  The  shell  can  intercept 
printer  output  and  redirect  it  to  a  net¬ 
work  queue  for  spooling. 


Users  log  on  with  “userids.”  Your  user 
can  “shell  out”  to  DOS  from  inside  your 
application  and  log  off  of  the  network, 
perhaps  logging  on  under  another  use¬ 
rid  with  different  access  privileges.  Files 
that  were  available  a  moment  ago,  now 
seem  —  to  your  program  —  to  not  ex¬ 
ist.  Programs  need  to  be  aware  that  such 
things  can  happen. 

The  NetWare  C  Interface 

If  you  are  going  to  write  a  program 
that  runs  in  a  network,  you  need  to 
know  how  to  make  the  extended  DOS 
calls  that  manipulate  the  network  itself. 
The  NetWare  C  Interface  is  a  library  of 
C  functions  that  provide  that  interface. 


I  am  not  going  to  try  to  discuss  the 
entire  API  here.  That  would  be  a  big 
book  all  by  itself.  Instead,  I  will  ad¬ 
dress  a  few  small  areas  to  give  you  a 
taste  of  how  the  platform  works  and 
how  well  the  API  is  implemented  and 
documented. 

Programs  that  run  in  a  NetWare  net¬ 
work  will  be  one  of  three  types.  First 
is  the  program  that  knows  nothing  about 
NetWare.  Programs  in  this  category  are 
DOS  programs  written  for  the  single- 
user  PC.  Most  of  them  run  OK  on  the 
network.  Sometimes  you  will  find  a 
program  that  opens  a  file  in  a  fixed 
place  —  usually  the  subdirectory  where 
the  EXE  exists  —  and  keeps  it  open.  A 
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second  user  on  the  network  cannot 
run  the  program  until  the  first  user’s 
copy  terminates,  because  NetWare  will 
not  allow  two  users  to  have  the  same 
file  open  at  the  same  time.  Some  instal¬ 
lations  simply  run  such  programs  from 
the  workstation’s  local  disk  and  bypass 
the  network  altogether.  Others  use  util¬ 
ity  TSR  programs  such  as  Net- Aware 
to  intercept  DOS  open  calls  and  substi¬ 
tute  user-defined  paths  and  names. 

Files  that  were 
available  a  moment 
ago,  now  seem  —  to 
your  program —  to 
not  exist 


The  second  category  of  program  is 
one  that  will  run  in  a  network  or  as  a 
DOS  program  in  a  stand-alone  PC. 
WordPerfect  is  an  example.  The  pro¬ 
gram  takes  advantage  of  the  facilities 
of  the  network  when  they  are  available 
and  gets  along  without  them  when  they 
are  not.  Printer  selection  is  one  such 
facility.  If  the  program  senses  that  no 
network  is  running,  the  program  sim¬ 
ply  uses  the  facilities  of  DOS. 

The  third  category  of  program  is  the 
one  that  runs  only  in  a  NetWare  net¬ 
work.  It  uses  network  facilities  that  DOS 
does  not  support.  A  user-to-user  mes¬ 
sage  and  chat  system  would  be  such  a 
program. 

You  don’t  need  any  help  writing  the 
first  category  of  program.  But  to  write 
one  of  the  others,  you  need  to  use  the 
NetWare  API.  Before  the  NetWare  C 
Interface  was  available,  the  API  con¬ 
sisted  of  a  document  that  explained  the 
API  calls  at  the  assembly  language  level. 
NetWare  API  calls  consist  of  an  ex¬ 
tended  set  of  INT  0x21  functions  that 
the  shell  intercepts  and  processes.  Most 
of  my  NetWare  programs  in  the  past 
used  C  language  interrupt  calls  to  in¬ 
voke  the  API  functions. 

You  can  still  take  that  approach,  but 
it  is  one  intensive  pain  in  the  nether 
quarters.  Every  call  has  its  own  unique 
format  for  request  and  response  pack¬ 
ets  and  you  will  code  a  zillion  different 
structures  to  deal  with  them.  If  you  get 
the  slightest  element  wrong,  either  in 
format  or  content,  the  API  either  re¬ 
turns  a  meaningless  error  code  or  freezes 
the  machine.  You  do  not  want  to  work 
that  way.  The  C  Interface  functions  take 
care  of  the  details  by  hiding  the  packet 


formats  and  providing  parameter  lists 
and  return  values  to  invoke  each  API 
function. 

There  are,  of  course,  some  prob¬ 
lems.  The  API  documentation  is  sprin¬ 
kled  with  errors  of  commission  and 
omission,  ones  that  will  trip  you  up 
from  time  to  time.  A  CompuServe  sub¬ 
scription  and  membership  in  the  NOVA 
forum  is  a  must.  There  are  always  knowl¬ 
edgeable  folks  there  who  can  answer 
your  questions. 

Using  the  API  requires  that  you  un¬ 
derstand  the  internal  architecture  of  the 
NetWare  operating  environment.  The 
API  libraries  are  divided  into  17  catego¬ 
ries  ranging  from  Accounting  Services 
to  Workstation  Services.  There  is  a  data 
base  called  the  “Bindery.”  There  are 
transaction  tracking  functions,  a  queue 
management  subsystem,  and  soon,  a 
print  server  API.  To  figure  out  what  all 
these  categories  are  you  need  to  read 
the  “System  Interface  Technical  Over¬ 
view”  document  and  then  experiment 
some.  It  is  not  always  clear  from  the 
descriptions  of  the  functions  what  their 
purposes  really  are.  Further,  if  you  want 
to  do  something  that  does  not  have  a 
corresponding  API  function,  you  need 
to  piece  together  the  logic  for  the  series 
of  functions  that  will  support  your  re¬ 
quirement.  There  is  not  a  lot  of  help  in 
the  API  documentation  for  these  kinds 
of  analyses. 

Suppose,  for  example,  that  your  pro¬ 
gram  wants  to  display  the  userid  of  the 
user  who  is  logged  onto  the  work  sta¬ 
tion.  (I  had  just  such  a  requirement  for 
an  e-mail  program.)  A  search  through 
the  various  API  services  reveals  no  ap¬ 
parent  function  that  returns  that  piece 
of  information.  Keep  digging.  What  you 
eventually  find  is  a  function  among  the 
Connection  Services  called  GetConnec- 
tionlnformation.  One  of  the  data  ele¬ 
ments  you  pass  it  is  a  pointer  to  a  null- 
terminated  string  to  receive  the  “name 
of  the  Bindery  object  logged  in  at  the 
connection  number.”  Bindery  object?  Con¬ 
nection  number?  A  careful  reading  of 
the  Bindery  Services  documentation  re¬ 
veals  that  the  Bindery  is  a  database  of 
objects,  one  of  which  can  be  a  User. 
What’s  the  connection  number?  That’s 
the  first  argument  to  the  GetConnection- 
Information  function.  Where  does  it  come 
from?  Nothing  says,  so  we  go  searching. 
Nearby  we  find  the  GetConnectionNum- 
ber  function,  which  returns  the  connec¬ 
tion  number  that  the  file  server  assigns 
to  a  workstation.  From  this  bit  of  secon¬ 
dary  deduction  we  conclude  that  a  func¬ 
tion  to  return  the  current  userid  would 
look  like  Listing  One  (page  168), 
getuser.c. 

As  an  experiment,  I  wrote  the  same 
(continued  on  page  157) 
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(continued  from  page  154) 
program  by  using  the  assembly  language 
API  and  the  intdosx  function  that  has 
become  a  de  facto  standard  among  PC 
C  compilers.  Listing  Two,  page  168,  is 
getuserl.c,  and  it  offers  an  interesting 
contrast  to  the  C  API.  Even  this  small 
example  shows  how  much  more  read¬ 
able  the  C  version  is.  On  the  other  hand, 
the  version  of  the  program  compiled 
with  the  C  API  takes  almost  4K  more 
than  the  one  with  its  own  interface. 
Everything  costs  something. 

Are  these  excursions  through  the 
oblique  world  of  the  NetWare  architec¬ 
ture  typical?  In  my  experience,  they 
are.  For  example,  the  documentation 
for  the  GetConnectionlnformation  func¬ 
tion  says  that  the  shell  uses  this  func¬ 
tion  to  see  if  it  is  already  loaded,  and 
that  other  programs  should,  too.  But 
the  function  needs  a  connection  num¬ 
ber,  and  no  connection  number  exists 
without  the  shell  already  being  loaded. 
Apparently  you  use  any  old  connection 
number  between  1  and  100,  and  if  the 
function  does  not  put  something  in  the 
arguments,  the  caller  can  assume  that 
the  shell  is  not  there.  The  documentation 
does  not  spell  that  out,  however. 

The  Bindery 

NetWare  programmers  should  be  fa¬ 
miliar  with  the  Bindery,  a  general-pur¬ 
pose  database  that  NetWare  uses  and 
for  which  it  provides  support  for  appli¬ 
cations  use.  The  Bindery  is  the  home 
for  definitions  of  users,  user  groups, 
queues,  servers,  gateways,  and  so  on. 
A  Bindery  entry  is  an  “object.”  Each 
object  has  an  object  “type”  and  can 
contain  one  or  more  “properties.”  A 
property  can  be  an  “item,”  which  can 
contain  one  “value”  or  it  can  be  a  “set,” 
which  contains  a  list  of  values.  Appar¬ 
ently  Novell  is  rewriting  the  database 
lexicon. 

NetWare  defines  certain  object  types 
for  the  things  it  keeps  in  the  Bindery. 
Application  programs  can  add  their  own 
object  types.  As  an  experiment,  let’s 
look  at  the  OT_USER  Bindery  object 
type.  You  can  scan  the  Bindery  for 
objects  of  a  certain  type,  all  objects, 
objects  that  match  a  specified  name, 
and  objects  with  a  given  object  identifi¬ 
cation  number.  Listing  Three,  page  168, 
is  showusrs.c,  a  program  that  scans  the 
Bindery  for  all  registered  users  and  dis¬ 
plays  their  userids  on  the  console.  To 
scan  the  Bindery,  you  pass  an  initial 
objectid  of  -1  and  a  name  with  a  wild 
card  (*)  to  the  ScanBinderyObject  func¬ 
tion.  The  function  returns  the  object’s 
name  and  objectid.  Subsequent  calls 
to  the  same  function  accept  the  object- 
id  filled  in  by  the  previous  call.  This 
scan  continues  as  long  as  the  function 


returns  the  SUCCESSFUL  return  code. 
The  documentation  is  vague  about  what 
stops  the  scan,  but  I  figured  it  out  by 
experimenting. 

Incidentally,  the  SUCCESSFUL  return 
code  is  zero,  the  same  value  that  the 
function  returns  if  the  shell  is  not  loaded. 

The  C  API 

includes  functions  that 
account  for  the 
use  of  different  services 
in  the  network 


Try  the  program  without  NetWare,  and 
you  go  into  a  loop  displaying  garbage. 
So,  you  see,  you  do  need  a  way  to  tell 
if  the  shell  is  loaded  and  the  network 
is  operating.  I  fooled  around  for  a  while 
with  the  GetConnectionlnformation  fu  no¬ 
tion  attempting  to  find  a  reliable  way 
for  it  to  tell  a  program  that  the  shell 
was  or  was  not  loaded.  No  luck.  Some 
time  ago  I  found  a  different  technique, 
which  you  can  see  in  Listing  Four,  page 


170,  nwloaded.c.  It  calls  the  shell  at  the 
lower  level  by  using  the  System  Calls 
API  to  set  the  NetWare  lock  level.  The 
effect  and  meaning  of  the  calls  are  un¬ 
clear,  particularly  when  viewed  in  the 
light  of  what  those  API  functions  are 
supposed  to  do,  but  the  function  works 
with  no  apparent  ill  effects. 

Queues 

NetWare  includes  a  queue  management 
system  (QMS).  Queues  are  lists  that  the 
queue  manager  maintains  and  they  ex¬ 
ist  as  Bindery  objects.  Users  can  be 
defined  as  being  queue  users,  queue 
operators,  and  queue  servers.  A  queue 
user  can  add  an  entry  to  a  queue  and 
observe  the  status  of  queues.  A  queue 
operator  can  modify  queue  entries.  A 
queue  server  can  retrieve  entries  from 
queues  and  service  them. 

A  queue  entry  is  a  job.  The  job  is 
whatever  you  want  it  to  be.  The  queue 
server  will  perform  the  job  based  on 
the  presence  of  the  entry  in  the  queue. 

NetWare  uses  QMS  to  manage  spool¬ 
ing  to  network  printers.  The  API  pro¬ 
vides  a  number  of  functions  that  allow 
an  application  to  control  how  that  print¬ 
ing  will  occur.  A  future  API  will  permit 
you  to  write  print  server  applications 
so  that  you  can  print  from  NetWare 
print  queues  at  workstations.  By  study- 
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ing  the  API  interface  between  print 
queues  and  QMS,  you  can  see  how  you 
might  use  QMS  in  your  own  applications. 

VAPs 

A  Value-Added  Process  is  a  program 
that  runs  in  the  file  server.  The  VAP  is 
for  use  on  NetWare  286.  This  is  a 
weighty  subject,  far  beyond  the  scope 
of  this  column,  and  it  makes  the  brave 
quiver  because  VAPs  are  difficult  to 
write  and  downright  thorny  to  test.  Net¬ 
Ware  386  has  an  improvement  on  the 
VAP  called  the  “NLM.”  The  C  API  pro¬ 
vides  functions  that  you  use  in  VAP 
development,  but  does  not  mention 
the  NLM. 


A  VAP  executes  when  the  file  server 
starts  up.  You  have  to  bring  the  server 
down  to  reload  a  new  VAP.  VAPs  run 
in  286  protected  mode,  which  means 
that  you  cannot  test  them  with  the  usual 
debugger  techniques. 

Other  API  Services 

The  C  API  includes  functions  that  ac¬ 
count  for  the  use  of  different  services 
in  the  network.  You  can  write  an  ac¬ 
counting  package  that  will  distribute 
costs  across  users.  There  are  API  func¬ 
tions  to  support  exchange  of  data  files 
between  DOS  and  Apple  workstations. 
There  are  communications  and  mes¬ 
sage  services  for  inter-user  and  inter¬ 


network  data  packets.  There  are  con¬ 
nection,  workstation,  file  and  directory 
services,  and  on  and  on. 

Summary 

I  have  barely  touched  the  surface  of 
the  NetWare  programming  environ¬ 
ment.  Of  course,  it  is  not  possible  to 
cover  all  bases  in  the  space  of  a  col¬ 
umn.  The  purpose  of  this  coverage  is 
to  expose  you  to  the  environment,  show 
you  the  tools,  and  suggest  that  this 
might  be  the  coming  thing. 

On  the  whole,  I  prefer  using  the  C 
API  to  the  alternative  method  of  coding 
the  low-level  API  calls  into  my  C  pro¬ 
grams.  The  problems  I  addressed  in 
this  column  are  not  problems  with  the 
API  software  itself,  but  with  the  level  of 
information  imparted  by  the  documen¬ 
tation.  Like  any  other  complex  software 
development  platform,  the  NetWare  en¬ 
vironment  takes  a  while  to  learn.  Pro¬ 
grammers  who  have  experience  with 
these  functions  would  intuitively  know 
the  answers  to  the  questions  I  pose. 
But  it  takes  a  while  to  reach  that  level 
of  knowledge. 

Probably  my  severest  criticism  is  of 
the  packaging.  Novell  uses  double  slip 
covers  with  two  ring  binders  in  a  cover. 
Even  my  slender  pianist’s  fingers  are 
not  deft  enough  to  easily  pull  a  manual 
out  of  its  box.  Usually  when  I  finally 
get  it  out,  the  rings  have  popped  open, 
and  the  pages  fall  on  the  floor.  Yet  the 
binders  are  that  lay-flat  kind  with  the 
rings  offset  on  one  side,  and  they  can¬ 
not  be  stored  outside  the  slip  covers. 
Doesn’t  anyone  ever  try  these  things 
out  for  a  while  before  they  commit  a 
big  budget  to  using  them? 

When  the  demand  for  better  Net¬ 
Ware  tools  reaches  a  level  that  justifies 
an  investment  in  their  development, 
software  houses  who  cater  to  program¬ 
mers  will  respond.  Then  you  will  see 
third-party  function  libraries  that  pro¬ 
vide  a  higher  level  of  access  to  the 
NetWare  innards,  providing  an  easier 
interface  for  programmers.  Perhaps  some¬ 
day  there  will  be  C++  class  libraries 
with  classes  for  objects  in  the  Bindery, 
queues,  the  communications  packets, 
and  the  rest. 

In  the  meantime,  if  you  will  be  writ¬ 
ing  NetWare-savvy  programs,  you  will 
want  to  get  the  NetWare  C  Interface- 
DOS  libraries  from  Novell.  If  you  want 
to  study  or  use  the  underlying  assem¬ 
bly  language  calls,  get  the  NetWare 
System  Calls-DOS  package. 

DDJ 

(Listings  begin  on  page  168.) 
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You  See  Toothpaste 
Pumps;  I  See 
Coil  Forms . . . 


Lord  knows,  there  shouldn’t  be 
places  named  “Drug  Emporium” 
(what  sort  of  message  does  that 
give  our  kids?)  but  I  confess  I  was 
in  there  the  other  day,  looking  for  some 
Poore’s  Potato  Chips  and  the  latest  Com¬ 
puter  Shopper.  It’s  definitely  the  category- 
killer  store  of  its  kind  in  Scottsdale, 
with  whole  aisles  devoted  to  things 
that  might  get  five  shelf-feet  in  Safeway. 
I  trucked  down  the  toothpaste  aisle, 
oblivious  until  I  hit  the  toothpaste  pump 
section.  Something  stopped  me  cold  — 
bear  with  me  on  this;  I’ll  explain  —  in 
that  all  those  toothpaste  pumps  sitting 
side-by-side  on  the  shelves  looked  just 
like  plug-in  shortwave  coil  forms. 

Sure.  Hey,  if  you’re  over  forty  you 
might  remember:  Shortwave  radios  used 
to  use  these  little  things  with  plugs  on 
the  bottom  and  wire  on  them,  that 
plugged  into  a  hole  in  the  back/front/ 
side/whatever  of  the  shortwave  radio. 
Ham  radio  operators  used  them  until 
fairly  recently,  and  some  of  us  incorri¬ 
gible  atavists  use  them  until  this  very 
day.  They  always  came  in  groups  of 
four  or  five,  one  for  each  shortwave 
band,  hence  the  feeling  of  deja  vu  in 
seeing  17  pumps  of  Ultra  Brite  side  by 
side,  standing  on  end  as  we  always 
stood  the  coils  on  end,  flared  side  down, 
ready  to  grab  if  we  got  tired  of  the  BBC 


Jeff  Duntemann,  K16RA/7 


and  wanted  to  corrupt  our  brains  with 
Radio  Moscow. 

I  haven’t  built  many  radios  lately  (stay¬ 
ing  alive  has  been  challenge  enough) 
but  I  bought  a  pump  of  Ultra  Brite 
anyway,  and  in  another  six  weeks,  once 
the  stuff  inside  is  gone,  I’m  gonna  ram 
an  old  octal  tube  base  up  its  business 
end,  wrap  some  #22  enameled  wire 
around  it,  build  a  1-FET  regen  and  go 


sniffing  for  the  “Voice  of  America.” 

It’s  a  talent  I  have.  I  see  extraordi¬ 
nary  uses  for  ordinary  things.  You  see 
scrap  plywood;  I  see  a  potential  bird- 
house.  You  see  toothpaste  pumps;  I 
see  coil  forms.  I  have  a  garage  full  of 
ordinary  things  awaiting  their  extraor¬ 
dinary  applications.  (Some  have  waited 
for  many  years.  Ask  Carol  about  it; 
she’ll  have  plenty  to  say.  .  .  .) 

Bingo! 

I’ve  used  this  talent  often  in  program¬ 
ming,  where  the  difference  between 
the  ordinary  and  the  extraordinary  is 
lots  fuzzier,  and  the  material  itself  al¬ 
most  infinitely  mutable.  I  guess  you 
could  say  that  everything  in  program¬ 
ming  is  a  potential  birdhouse;  if  you 
need  a  birdhouse  badly  enough  you’ll 
figure  out  a  way. 

Last  week  I  was  facing  a  data  entry 
problem  I  hadn’t  faced  before.  I  had 
to  design  a  means  to  enter  and  store 
magazine  bingo  cards.  You  know  what 
I  mean;  those  Free  Information!  cards 
in  the  backs  of  virtually  all  magazines 
(including  DDJ)  where  you  circle  an 
advertiser’s  number  and  they  magically 
send  you  their  full-color  brochure.  Maga¬ 
zines  get  hundreds  or  (God  help  us) 
thousands  of  these  in  the  mail  all  the 
time.  Each  card  must  be  entered  into  a 
database  somehow,  starting  with  the 
reader  name  and  address  but  ending 
by  somehow  encoding  every  number 
the  reader  has  seen  fit  to  circle. 

How  to  encode  a  circled  number 
was  an  interesting  question.  I  started 
out  by  taking  the  low  road  and  creating 
a  255-character  text  field  in  Paradox, 
into  which  each  circled  number  would 
be  typed,  separated  by  spaces.  Para¬ 
dox  has  good  pattern-matching  abili¬ 
ties  in  its  query  form,  and  it  worked 
tolerably  well  once  you  swallowed  the 
data  entry.  That  is,  it  worked  —  until 


some  joker  mailed  us  a  card  with  the 
whole  block  of  200  numbers  circled. 

That  drove  home  the  fact  that  255 
characters  would  not  contain  much 
more  than  60  or  so  numbers.  Half  a 
second’s  thought  should  have  told  me 
that  the  bingo  numbers  weren’t  num¬ 
bers  anyway.  They  were  Booleans, 
either  True  (circled)  or  False  (not  cir¬ 
cled.)  And  our  bingo  card  was  just  an 
array  of  200  Booleans.  The  birdhouse 
I  had  to  build  would  be  an  array  of  200 
Booleans  with  some  means  of  screen 
display  and  editing.  I  took  a  look  to  see 
what  I  had  lying  around  in  the  line  of 
potential  birdhouses,  and  it  hit  me:  A 
Pascal  set  is  (with  a  little  reworking) 
an  array  of  256  Boolean  values.  Packed, 
too  —  in  32  bytes,  with  not  a  bit  of 
wasted  space.  Bingo! 

Get  set 

Apart  from  SET  OF  Char  (which  I  use 
incessantly  for  text  filtering)  I  haven’t 
done  much  with  sets  of  more  than  five 
or  six  elements.  But  consider: 

TYPE 

BitSet  =  SET  OF  0..255; 

This  definition  gives  us  a  bitmapped 
data  item  containing  256  flag  bits,  with 
machinery  built  right  into  Pascal  for 
adding,  removing,  and  testing  for  pres¬ 
ence  and  absence  of  individual  bits. 
These  two  statements  amount  to  pretty 
much  the  same  thing: 

MyBooleanArray[17]  :=  True; 

MyBitSet  :=  MyBitSet  +  17; 

The  +  symbol  here  is  acting  as  set 
union,  not  addition.  (We  have  over¬ 
loaded  operators  in  Pascal  too!  Kind 
of  like  discovering  that  you’ve  been 
speaking  in  prose  all  your  life.  .  .  .)  In 
the  second  statement,  you’re  assigning 
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(continued  from  page  157) 
to  MyBitSet  the  union  of  the  earlier 
state  of  MyBitSet  and  the  value  17.  Think 
of  17  as  an  enumeration  constant  here, 
and  it  should  make  sense. 

Similarly,  you  can  remove  an  item 
from  a  set  by  using  the  set  difference 
operator,  - ,  like  this: 

MyBitSet  :=  MyBitSet  -  17; 

Again,  this  may  look  odd  unless  you 
remind  yourself  that  17  is  not  acting 
arithmetically  here.  Call  17  by  its  Mar¬ 
tian  name,  Foobity-Foo  (see  my  book, 
Assembly  Language  From  Square  One 
before  calling  out  the  guys  with  the 
butterfly  nets)  if  you  have  trouble  di¬ 
vorcing  it  from  the  realm  of  practical 
math. 

The  bottom  line:  As  the  central  data 
item  in  my  model  of  the  bingo  card,  I 
would  use  a  Pascal  set  of  the  cardinal 
numbers  from  0  to  255.  Each  number 
would  be  either  in  the  set  (circled)  or 
not  in  the  set  (left  alone.) 

Breaking  Your  Own  Rules 

As  is  my  wont  these  days,  I  immedi¬ 
ately  forged  an  object  around  the  BitSet 
data  item.  In  doing  so  I  broke  one  of 
my  own  personal  rules  that  I  shared 
with  you  in  a  previous  column:  Don’t 


make  an  object  out  of  anything  special- 
cased  by  the  compiler.  This  would  in¬ 
clude  most  primitive  data  types  includ¬ 
ing  Booleans,  characters,  strings,  and  — 
most  emphatically  —  sets. 

The  advice  I  gave  before  was  and  is 
still  sound.  Nonetheless,  I  consider  the 
exception  to  be  good  practice  because 
I’m  not  really  using  the  set  as  sets  are 
generally  used.  In  effect,  I’m  using  a 
set  as  a  packed  array  of  Booleans,  so 
just  this  once,  I’ll  build  an  object  around 
a  Pascal  primitive  data  type  and  not 
feel  guilty  about  it. 

At  the  highest  level,  designing  an 
object  consists  of  asking  the  question: 
What  must  the  object  know  how  to  do? 
For  my  application,  it  wasn’t  a  long  list. 
The  object  must  be  able  to  clear  itself 
(that  is,  set  all  bits  to  0)  display  itself, 
and  edit  itself.  That’s  all. 

The  resulting  object  is  implemented 
in  Listing  One  (page  172),  SETOBJ.PAS. 

A  Set  Object 

The  visual  expression  of  the  set  data 
consists  of  16  lines  of  sixteen  three- 
digit  numbers,  starting  with  000  and 
going  to  255.  When  a  numbered  bit  in 
the  set  is  set  (for  example,  binary  1)  the 
three  digits  are  displayed  in  reverse 
video.  For  all  bits  that  are  cleared  (bi¬ 
nary  0)  the  three-digit  numbers  are  dis¬ 


played  in  normal  white-on-black  video. 

Within  the  SetObject.Edit  method,  a 
text  cursor  is  created  by  poking  the 
two  triangle  symbols  (ASCII  16  and  17) 
to  the  screen  on  either  side  of  one  of 
the  256  numbers  indicating  bits  in  the 
set.  I  call  the  bit  so  indicated  the  “hot 
bit.”  When  you  press  Enter,  the  state 
of  the  hot  bit  is  toggled  from  cleared 
(the  default)  to  set  and  back.  By  bounc¬ 
ing  the  cursor  around  the  matrix  using 
the  arrow  keys  and  pressing  Enter  where 
appropriate,  you  can  set  or  clear  any 
bit  in  the  matrix  at  random,  with  mini¬ 
mal  keystroking  effort.  Finally,  press¬ 
ing  Esc  ends  the  edit  session,  with  any 
changes  stored  in  the  SetData  field  of 
SetObject. 

You  can  try  out  SetObjects  different 
methods  by  running  Listing  Two  (page 
177),  SETTEST.PAS. 

Pokey  Video 

Only  two  aspects  of  the  code  bear  seri¬ 
ous  explaining:  The  way  the  matrix 
pattern  is  generated  on  the  screen,  and 
the  mouse  support  for  editing. 

By  sheer  bad  luck  I  was  forced  off 
of  my  ramcharged  25-MHz  386  and 
onto  a  gen-u-wine  o-riginal  4.77-MHz 
IBM  PC  while  developing  SetObject. 
At  first  I  drew  the  matrix  on  the  screen 
using  a  pair  of  nested  loops  containing 
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(continued  from  page  163) 

GotoXY  and  Write ,  as  most  reasonable 
people  would.  This  worked  fairly  well 
on  the  386.  However,  on  the  PC  the 
results  came  close  to  making  me  scream: 
Zzzzzzzzzzzzzzzzzzzit!  I  could  watch 
the  matrix  flow  into  place  from  the  top 
of  the  screen  down.  Any  screen  that  I 
can  watch  drawing  itself  is  too  damned 
slow;  watching  mainframe  screens  slog 
their  way  to  wholeness  was  consid¬ 
ered  entertainment  rivaling  old  Andy 
Griffith  reruns  back  when  I  worked  at 
Xerox  MIS/DP. 

Sorry  Andy.  When  such  things  hap¬ 
pen,  I  go  right  to  assembler  and  a  whole 
new  approach.  Instead  of  drawing  the 
matrix  every  time  I  need  it,  I  create  the 
matrix  as  a  memory  image  on  the  heap, 
and  flash  it  in  with  the  Move  block 
move  statement  any  time  I  want  to 
display  it. 

Move  is  absurdly  simple  and  just  as 
fast;  the  trickiness  is  all  in  getting  the 
matrix  onto  the  heap  to  begin  with. 
Using  Move  to  transfer  an  easily-read- 
able  character  array  such  as  MatrixText 
in  Listing  One  won’t  work,  because  a 
screen  memory  image  must  have  an 
attribute  byte  after  each  and  every  byte 
to  be  displayed.  So  I  wrote  MatrixBlast, 
a  specialized  Move  variant  that  moves 
a  character  array  onto  the  heap  while 
inserting  an  attribute  byte  after  each 
character  byte.  It’s  an  INLINE  macro 
and  pretty  close  to  as  fast  as  such  a 
creature  can  be,  at  least  until  Michael 
Abrash  gets  hold  of  it.  The  set  matrix 
I’m  using  here  is  only  16  x  80,  but  you 
can  easily  use  MatrixBlast  to  move  en¬ 
tire  25  x  80  screens  from  a  text  array 
(perhaps  in  the  form  of  a  typed  con¬ 
stant)  to  the  heap,  and  then  flash  the 
screen  into  view  with  Move. 

Once  moved  onto  the  heap,  the  raw 
matrix  image  must  be  updated  with 
highlight  attributes  to  reflect  the  cur¬ 
rent  state  of  the  255  bits  in  SetData  field 
of  SetObject.  There’s  a  second  INLINE 
macro  that  does  that  job:  AttributeBlast, 
which  is  called  from  a  tight  loop  inside 
the  Show  method.  AttributeBlast  moves 
a  specified  attribute  byte  into  the  mem¬ 
ory  image  on  the  heap,  without  dis¬ 
turbing  the  visible  screen  data  already 
there.  In  a  sense,  AttributeBlast  ma¬ 
chine  guns  attribute  bytes  in  between 
the  ASCII  data  bytes  in  the  image  on 
the  heap,  starting  at  some  offset  from 
the  pointer  to  the  image,  and  continu¬ 
ing  for  a  specified  number  of  characters. 

With  MatrixBlast  and  AttributeBlast, 
there  were  no  longer  any  pokey  screen 
problems,  even  on  the  old  PC. 

A  note  on  a  bug  that  drove  me 
bonkers:  While  writing  MatrixBlast,  I 
inadvertently  entered  an  ordinary  right 
parenthesis  instead  of  a  right  curly 


bracket  at  the  end  of  the  first  comment 
line: 

(  Pop  attribute  character  into  AX) 

The  net  effect  was  to  comment  out  the 
$5B opcode  (POP  BX)  on  the  next  line, 
which  got  the  stack  frame  all  confused 
and  blew  my  system  away  every  time. 
It  wasn’t  until  I  started  tracing  the  pro¬ 
gram  opcode-by-opcode  with  Turbo 
Debugger  that  the  missing  $5B  became 
apparent,  and  even  then  it  took  some 
definite  right-brain  thinking.  (We’re  not 
good  at  looking  for  something  that  isn’t 
there!)  Be  careful  when  working  with 
INLINE.  The  compiler  lets  you  do  what 


you  like  —  and  one  small  twitch  in  a 
bracket  (or  lack  of  one)  can  send  your 
system  to  Bim-Bom-Bay. 

Mouse  Control 

I’m  not  fond  of  mouse  input  except 
when  it  makes  sense  —  and  mouse  in¬ 
put  for  intense  text  data  entry  and  edit¬ 
ing  rarely  makes  sense,  regardless  of 
what  the  Mac  crazies  think.  I  type  at 
about  110  words  a  minute,  and  if  I  had 
to  break  stride  to  grab  the  mouse  to 
slide  up  a  line  or  two  to  fix  a  pair  of 
transposed  letters,  I’d  never  get  any¬ 
thing  finished  on  time. 

Picking  and  toggling  bits  on  the  ma¬ 
trix,  however,  is  a  perfect  job  for  the 
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mouse,  because  everything  is  point-and- 
shoot.  There’s  no  entry  of  characters 
involved;  you  dick  on  a  number  and 
that  bit  changes  state.  For  this  reason, 
I  built  mouse  control  into  SetObject s 
Edit  method.  Furthermore,  the  user 
doesn’t  need  to  specify  mouse  control; 
if  the  mouse  driver  is  available,  SetOb¬ 
ject  will  detect  it  and  enable  the  mouse 
cursor.  If  the  mouse  driver  isn’t  found, 
the  arrow  keys  can  be  used  to  move 
the  hot  bit  and  the  Enter  key  to  change 
the  hot  bit’s  state. 

In  the  SetObj  unit’s  initialization  sec¬ 
tion,  a  call  is  made  to  a  function  that 
looks  for  either  a  null  or  an  IRET  in¬ 
struction  (opcode  $CF)  and,  finding 
neither,  assumes  that  there  is  a  mouse 
driver  at  the  other  end  of  interrupt  vec¬ 
tor  51.  I’ve  always  thought  that  a  little 
dicey,  but  no  better  way  has  been  pro¬ 
vided  by  Microsoft,  so  we’ll  run  with  it. 
A  global  Boolean  named  MouseAvail- 
able  is  set  to  True  if  the  unit  assumes  a 
mouse  driver  is  installed.  All  through 
the  unit,  MouseAvailable  is  tested  when¬ 
ever  something  associated  with  the 
mouse  needs  to  be  done.  If  no  driver 
is  installed,  the  unit  works  perfectly 
well  from  the  keyboard.  If  the  mouse 
is  there,  the  driver  is  reset  and  the 
mouse  cursor  turned  on. 

For  Want  of  a  Flag 

There  is  a  shortcoming  in  the  Microsoft 
standard  mouse  driver  that  has  infuri¬ 
ated  me  since  I  wrote  my  first  mouse- 
aware  program  back  in  1983-  (I  still  use 
that  original,  first-run  Microsoft  Mouse, 
lint-catcher  mechanical  gimcrackery  and 
all.)  Whereas  it’s  possible  to  turn  the 
mouse  cursor  on  and  off  at  will,  there’s 
no  way  to  determine  if  the  mouse  cur¬ 
sor  is  already  on.  You  have  to  keep 
your  own  flag  or  make  assumptions. 
This  is  dumb  —  there’s  a  documented 
but  unavailable  cursor-visible  flag  in¬ 
side  the  driver  somewhere,  and  all  it 
would  take  would  be  a  little  code  to 
return  it  during  the  status  function  call. 

I  do  make  certain  assumptions  here, 
in  that  if  the  mouse  driver  has  been 


found,  the  mouse  cursor  is  assumed 
to  be  visible  during  the  execution  of 
the  Edit  method.  This  is  only  signifi¬ 
cant  during  execution  of  the  Show 
method,  which  must  turn  off  the  visible 
mouse  cursor  in  order  to  blast  the  ma¬ 
trix  image  from  the  heap  into  the  video 
refresh  buffer.  (If  you  write  over  the 
mouse  cursor,  odd  things  happen.)  At 
the  end  of  Show ,  the  mouse  cursor  is 
made  visible  again  —  if  Show  was  called 
from  within  Edit.  You  don’t  want  the 
mouse  cursor  coming  on  if  you’re  just 
calling  Show  to  display  a  set  object’s 
data  with  no  intention  to  edit,  as  is 
done  in  Listing  Two.  Hence  the  other¬ 
wise  worthless  EditlnProcess  flag  that 
must  be  carted  around  by  all  instances 
of  SetObj.  If  we  could  just  test  to  see  if 
the  mouse  cursor  were  visible  at  any 
given  time,  we  could  just  not  turn  it 
back  on,  if  it  wasn’t  on  already  when 
we  entered  Show.  Grrrrr. 

Another  note  on  mouse  control: 
While  the  mouse  is  visible,  it  is  limited 
to  travelling  only  within  the  extent  of 
the  16  lines  of  the  matrix,  courtesy  of 
a  call  to  mouse  function  8  just  before 
the  cursor  is  turned  on  at  the  top  of 
SetObject. Edit.  This  is  important;  for 
simplicity  I  don’t  check  to  see  if  the 
mouse  is  outside  the  matrix,  and  if  you 
let  the  mouse  roam  the  screen  it  will 
still  toggle  the  state  of  bits  in  the  matrix 
even  when  outside  the  matrix.  (Com¬ 
ment  out  the  call  to  function  8  and 
you’ll  see  what  I  mean.) 

I  suppose  that  only  a  few  of  you 
have  magazines  and  their  attendant 
bingo  cards  to  service,  but  SetObj  may 
have  some  other  uses.  Test  scores?  Sur¬ 
vey  results?  Be  creative.  Consider  SetObj 
a  potential  birdhouse,  and  keep  your 
mind  open  to  uses  that  don’t  follow 
from  your  traditional  notions  of  what 
sets  are  for.  Hey,  do  like  I  do:  If  it  looks 
like  a  coil  form  —  go  looking  for  the 
wire! 

The  Last  Word  on  Mice 

Microsoft  has  finally  published  the  de¬ 
finitive  book  on  mouse  programming, 


Products  Mentioned 


Microsoft  Mouse  Programmer’s 

Reference 

(no  author  given) 

Microsoft  Press,  1989 
ISBN  1-55615-191-8 
Softcover,  321  pages,  $29.95 
Listings  disk  is  bound  into  all  copies 

Modula-2  A  Complete  Guide 
by  K.  N.  King 

D.C.  Heath  and  Company,  1988 
1-800-334-3284 


ISBN  0-669-11091-4 
Softcover,  656  pages,  $36 
Listings  disk  available  from  author, 
Price:  $10 

TopSpeed  Modula-2  V2.0 

Jensen  &  Partners  International 

1101  San  Antonio  Road,  Suite  301 

Mountain  View,  CA  94043 

415-967-3200 

DOS  Price:  $199 

OS/2  Price:  $495 
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six  years  after  it  should  have.  Better 
late  than  never,  I  guess  —  and  I’m  kick¬ 
ing  myself  for  not  having  written  it 
back  in  1985,  when  I  had  the  notion. 
Anyway  —  if  you  have  things  with  tails 
on  your  desktop,  pick  it  up:  Microsoft 
Mouse  Programmer’s  Reference.  (The 
book  was  written  in-house  and  carries 
no  author’s  byline.) 

The  book  is  short-ish,  but  it’s  clear, 
and  accurate,  and  tolerably  easy  to  read. 
There  are  lots  of  code  examples,  mostly 
in  C,  but  the  explanations  are  strong 
enough  to  carry  you  into  any  language 
that  has  a  software  interrupt  primitive 
or  allows  assembly  language  externals. 
The  book  is  expensive  as  thin  books 
go,  but  it  includes  a  disk  with  the  list¬ 
ings  and  some  mouse  menu  folderol 
the  usefulness  of  which  escapes  me. 

For  the  completeness  of  its  cover¬ 
age,  a  must-have. 

More  Modulo  Books 

I’ve  gotten  a  handful  of  new  books  on 
Modula-2  since  complaining  of  their 
dearth  a  few  columns  ago.  None  seem 
much  worth  mentioning  except  one: 
Modula-2  A  Complete  Guide,  by  K.N. 
King.  The  book  is  by  no  means  new 
(1988)  but  as  it’s  a  text  and  not  a  trade 
volume,  I  had  no  way  to  know  of  its 
publication  before  Dr.  King  was  kind 
enough  to  send  it  to  me. 

Modula-2  A  Complete  Guide  is  by  far 
the  best  book  on  Modula  now  on  my 
shelves.  It’s  big  (650+  pages),  clear, 
complete,  and  honest  —  it  says  what  I 
discovered  years  ago,  that  Niklaus 
Wirth’s  suggested  Processes  module  is 
next  to  worthless.  Furthermore,  King 
proposes  a  replacement  that’s  consid¬ 
erably  better,  though  I  haven’t  had  a 
chance  to  try  it  yet. 

The  writing  rises  much  above  the 
stuffy  incompetence  I  see  in  far  too 
many  CS  textbooks  these  days.  Keep 
in  mind  that  Modula-2  A  Complete 
Guide  is  not  a  DOS  book,  so  you  won’t 
get  lots  of  interesting  tidbits  on  access¬ 
ing  the  joystick  port  or  tweaking  dis¬ 
play  adapter  registers.  (Good  thing, 
too  —  perhaps  Dr.  King  has  left  enough 
for  me  to  make  a  book  of.)  You  won’t 
find  it  in  ordinary  bookstores,  although 
a  college  bookstore  where  the  book  is 
taught  would  have  it.  Fortunately,  it 
can  be  ordered  directly  from  the  pub¬ 
lisher,  through  the  800  number  given 
in  the  Products  Mentioned  box. 

Go  through  this  book  and  you’ll  have 
standard  Modula-2  in  your  hip  pocket. 
Highly  recommended. 

Closing  In  on  Modula  Objects 

By  next  column  I  hope  to  have  JPI’s 
new  2.00  Version  of  TopSpeed  Modu¬ 
la-2,  which  includes  object-oriented  ex¬ 


tensions  similar  to  those  in  Turbo  Pas¬ 
cal  5.5.  The  siren  song  of  objects  has 
taken  me  away  from  Modula  to  a  great 
extent  this  past  year,  and  now  it’s  time 
to  go  back,  I  think. 

There  may  be  some  griping,  espe¬ 
cially  from  the  portability  paranoids, 
but  hey,  guys,  consider:  Every  one  of 
the  languages  I  currently  use  is  now 
object-oriented.  Pascal,  Modula-2, 
Smalltalk,  Actor,  C  (no,  no  kidding!) 
so  .  .  .  what’s  left?  The  only  major  hold¬ 
out  is  Basic,  which  I  haven’t  touched 
for  awhile,  but  there  are  intriguing  rum¬ 
blings  from  Microsoft  that  they  may 
take  Big  Bill’s  Baby  in  an  objective 
direction  soon. 


And  then  there  are  those  ongoing 
rumors  of  object-oriented  Cobol.  .  .  . 

Stranger  things  have  happened.  The 
Berlin  Wall  is  gone.  Democrats  have 
started  voting  against  tax  hikes.  They 
still  grow  broccoli. 

In  other  words,  don’t  bet  the  rent. 

Contact Jeff Duntemann  on  MCI  Mail 
as  JDuntemann,  or  on  CompuServe 
through  ID  761 1 7, 1426. 

ddj 

(Listings  begin  on  page  172.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  14. 
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Listing  One  (Text  begins  on  page  149  ) 

)  rsbuffer  =  {  62  }; 

/*  -  Display  NetWare  USERID  -  */ 

char  *GetUserid(void) ; 

♦include  <stdio.h> 

♦include  <nit.h> 

void  main () 

char  *GetUserid (void) ; 

printf  ("\nUserid:  %s",  GetUseridO  ) ; 

void  main () 

( 

char  *GetUserid(void) 

printf ("\nUserid:  %s",  GetUserid () ) ; 

( 

1 

union  REGS  regs; 

struct  SREGS  segs; 

*  Get  the  current  logged  on  userid 

segread(Ssegs) ; 

*/ 

segs.es  =  segs.ds; 

/* - get  connection  (station)  number - */ 

char  *GetUserid(void) 

regs. h. ah  =  Oxdc; 

( 

intdosx (&regs,  &regs,  &segs); 

static  char  userid [48]; 

rqpacket. station  =  regs.h.al; 

WORD  connection  number  =  GetConnectionNumber () ; 

/* - get  connection  information - */ 

WORD  object type; 

regs. x. si  =  (unsigned)  srqpacket; 

long  objectid; 

regs.x.di  =  (unsigned)  Srsbuffer; 

BYTE  logintime [7] ; 

regs. h. ah  =  0xe3; 

intdosx (&regs,  firegs,  &segs) ; 

GetConnectionlnformation (connection  number,  userid, 

return  rsbuffer .userid; 

Sobjecttype,  &ob jectid,  logintime) ; 

) 

return  userid; 

} 

End  listing  One 

Listing  Two 

/* - getuserl.c - *  / 

End  Listing  Two 

♦include  <dos.h> 

Listing  Three 

♦include  <string.h> 

/* - showusrs.c -  */ 

/*  -  request  packet  for  get  connection  information  -  */ 

static  struct  ( 

♦include  <stdio.h> 

int  rlen;  /*  packet  length-2  */ 

♦include  <nit.h> 

char  func;  /*  NW  function  */ 

♦include  <niterror.h> 

char  station;  /*  station  number  */ 

)  rqpacket  =  {  2,  22  }; 

static  long  objid; 

/*  -  reply  buffer  for  get  connection  information  -  */ 

char  *getusers (void) ; 

static  struct  ( 

int  rlen;  /*  packet  length-2  */ 

void  main () 

long  id;  /*  object  id  */ 

{ 

int  type;  /*  type  of  object  */ 

char  ‘userid; 

char  userid[48];  /*  name  of  object  */ 

objid  =  -1; 

char  time [8];  /*  log  on  time  */ 

(Listing  continued  on  page  1 70) 
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Listing  Three  ( Listing  continued,  text  begins  on  page  149.) 

while  ((userid  =  getusersO)  !=  NULL) 
printf ("\n%s",  userid); 

} 

/* - scan  bindery  for  users - */ 

char  *getusers (void) 

{ 

static  char  name [48]; 

char  hasproperties,  flag,  security; 

WORD  type; 

if  (ScanBinderyObject ("*",  OT_USER,  fiobjid,  name,  Stype, 

&hasproperties,  Sflag,  ^security)  ==  SUCCESSFUL) 
return  name; 
return  NULL; 

} 


End  Listing  Three 


Listing  Four 

/* - nwloaded.c - */ 

♦include  <stdio.h> 

♦include  <dos.h> 

int  NetworkLoaded(void) ; 

void  main() 

{ 

printf ("\nThe  network  %s  operating", 

NetworkLoadedO  ?  "is"  :  "is  not"); 

} 

♦define  encr(lm)  (0- (~(0-lm) ) ) 

/* - test  network  operating - */ 

int  NetworkLoaded(void) 

< 

int  lockmode,  encrypted; 
union  REGS  regs; 

regs.x.ax  =  0xc600; 
intdos ( &  regs ,  &  regs ) ; 
lockmode  =  regs.h.al; 

encrypted  =  encr (lockmode) ; 

regs. h. ah  =  0xc6; 
regs.h.al  =  encrypted; 
intdos ( &  regs ,  &  regs ) ; 
lockmode  =  regs.h.al; 

return  encrypted  !=  encr (lockmode) ; 

} 


End  Listings 
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STRUCTURED  PROGRAMMING 


Listing  One  ( Text  begins  on  page  161.) 


( - ) 

(  SETOBJ  ) 

(  I 

{  Set  object  with  an  interactive  editing  method  } 

(  } 

{  by  Jeff  Duntemann  } 

{  For  DDJ  8/90  } 

{  Turbo  Pascal  5.5  } 

{  Last  modified  5/20/90  } 

{ - 1 


UNIT  SetObj; 
INTERFACE 


WITH  Regs  DO 
BEGIN 

AX  :=  Ml;  BX  :=  M2;  CX  :=  M3;  DX  :=  M4; 

END; 

INTR (51, Regs) ;  {  51  =  $33  =  Mouse  driver  interrupt  vector  } 

WITH  Regs  DO 
BEGIN 

Ml  :=  AX;  M2  :=  BX;  M3  :=  CX;  M4  :=  DX; 

END; 

END; 


PROCEDURE  ShowMouse; 
VAR 

M1,M2,M3,M4  :  Word; 


USES  DOS, Crt; 


TYPE 

BitSet 


SET  OF  0..255;  (  Maximum  size  generic  set  } 


SetObject  = 
OBJECT 
SetData 
HotBit 
ShowAtRow 
MatrixPtr 
Origin 
Attribute 
Highlight 


BitSet;  {  The  set  data  itself  } 

Integer;  {  Bit  currently  subject  to  editing  } 

Integer;  {  Matrix  may  appear  at  row  1  to  8  } 

Pointer;  (  Points  to  matrix  pattern  on  heap  ) 

Integer;  {  Display  text  starts  at  0  or  1  ) 

Integer;  {  Attribute  for  nonhighlighted  elements  ) 

Integer;  (  Attribute  for  highlighted  elements  ) 

EditlnProcess  :  Boolean;  (  True  if  inside  the  Edit  method  ) 
CONSTRUCTOR  Init (InitialOrigin, 

InitialAttribute, 

InitialHighlight, 

InitialStartRow  :  Integer); 


DESTRUCTOR 

PROCEDURE 

PROCEDURE 

PROCEDURE 

END; 


IMPLEMENTATION 


Done;  (  Removes  object  from  memory  } 

ClearSet;  {  Forces  all  set  bits  to  0  ) 

Show;  {  Displays  set  data;  doesn't  edit  ) 

Edit;  1  Displays  and  edits  set  data  } 


TYPE 

Char40  =  ARRAY[0..39]  OF  CHAR;  {  For  the  matrix;  see  below  } 


BEGIN 

Ml  :=  1;  MouseCall (Ml, M2, M3, M4) ; 
END; 


PROCEDURE  HideMouse; 

VAR 

Ml, M2, M3, M4  :  Word; 

BEGIN 

Ml  :=  2;  MouseCall (Ml, M2, M3, M4); 
END; 


(  If  called  when  left  mouse  button  is  down,  waits  for  release  } 
PROCEDURE  WaitForMouseRelease; 

VAR 

Ml, ButtonStatus,M3,M4  :  Word; 

BEGIN 
Ml  :=  3; 

REPEAT 

MouseCall (Ml, ButtonStatus,  M3,  M4) ; 

UNTIL  NOT  Odd (ButtonStatus) ;  (  Wait  until  Bit  0  goes  to  0  ) 

END; 


CONST 

LeftCursorChar  =  #16;  {  These  are  the  bracketing  characters  ) 
RightCursorChar  =  #17;  {  Indicating  which  set  element  is  being  } 

{  edited.  ) 

(  This  is  the  text  portion  of  the  16-line  number  matrix  used  to  display  ) 

{  and  edit  set  elements.  They  are  first  stored  onto  the  heap,  then  the  } 

(  object's  attribute  is  merged  with  the  text  on  the  heap.  This  way,  ) 

{  you  can  move  the  whole  image  onto  the  screen,  attributes  and  all,  } 

(  with  a  single  Move  statement.  } 


MatrixText  :  ARRAY [0 

.32) 

OF  Char40 

=  ( 

'  000 

001 

002 

003 

004 

005 

006 

007  ', 

'  008 

009 

010 

011 

012 

013 

014 

015  ', 

'  016 

017 

018 

019 

020 

021 

022 

023  ', 

'  024 

025 

026 

027 

028 

029 

030 

031  ', 

'  032 

033 

034 

035 

036 

037 

038 

039  ', 

'  040 

041 

042 

043 

044 

045 

046 

047  ', 

'  048 

049 

050 

051 

052 

053 

054 

055  ', 

'  056 

057 

058 

059 

060 

061 

062 

063  ', 

'  064 

065 

066 

067 

068 

069 

070 

071  ', 

'  072 

073 

074 

075 

076 

077 

078 

079  ', 

'  080 

081 

082 

083 

084 

085 

086 

087  ', 

'  088 

089 

090 

091 

092 

093 

094 

095  ', 

'  096 

097 

098 

099 

100 

101 

102 

103  ', 

'  104 

105 

106 

107 

108 

109 

no 

111 

'  112 

113 

114 

115 

116 

117 

118 

119  ', 

'  120 

121 

122 

123 

124 

125 

126 

127  ', 

'  128 

129 

130 

131 

132 

133 

134 

135  ', 

'  136 

137 

138 

139 

140 

141 

142 

143  ', 

'  144 

145 

146 

147 

148 

149 

150 

151  ', 

'  152 

153 

154 

155 

156 

157 

158 

159  ', 

'  160 

161 

162 

163 

164 

165 

166 

167  ', 

'  168 

169 

170 

171 

172 

173 

174 

175  ', 

'  176 

177 

178 

179 

180 

181 

182 

183  ', 

'  184 

185 

186 

187 

188 

189 

190 

191  ', 

'  192 

193 

194 

195 

196 

197 

198 

199  ', 

'  200 

201 

202 

203 

204 

205 

206 

207  ', 

'  208 

209 

210 

211 

212 

213 

214 

215  ', 

'  216 

217 

218 

219 

220 

221 

222 

223  ', 

'  224 

225 

226 

227 

228 

229 

230 

231  ', 

'  232 

233 

224 

235 

236 

237 

238 

239  ', 

'  240 

241 

242 

243 

244 

245 

246 

247  ', 

'  248 
'  256 

249 

250 

251 

252 

253 

254 

255  ', 
') 

VAR 

VidBufferPtr  :  Pointer;  {  Global,  set  in  the  init.  section  ) 
MouseAvailable  :  Boolean;  {  Global,  set  in  the  init.  section  } 

( - } 

{  Procedures  and  functions  private  to  this  unit :  ) 

f - - - 1 


{  This  is  the  general-purpose  mouse  call  primitive:  ) 
PROCEDURE  MouseCall (VAR  Ml, M2, M3, M4  :  Word); 

VAR 

Regs  :  Registers; 

BEGIN 


PROCEDURE  UhUh;  (  Says  "uh-uh"  when  you  press  the  wrong  key  ) 
VAR 

I  :  Integer; 

BEGIN 

FOR  I  :=  1  TO  2  DO 
BEGIN 

Sound (50);  Delay (100);  NoSound;  Delay (50); 

END; 

END; 


FUNCTION  Mouselslnstalled  :  Boolean; 

TYPE 

BytePtr  =  AByte; 

VAR 

TestVector  :  BytePtr; 

BEGIN 

GetlntVec (51, Pointer (TestVector) )  ; 

{  $CF  is  the  binary  opcode  for  the  IRET  instruction;  ) 
{  in  many  BIOSes,  the  startup  code  puts  IRETs  into  ) 
i  most  unused  bectors.  NIL,  of  course,  is  4  zeroes.  ) 
IF  (TestVector  =  NIL)  OR  (TestVector"  =  $CF)  THEN 
Mouselslnstalled  :=  False 
ELSE 

Mouselslnstalled  :=  True 

END; 


1  Returns  True  if  running  on  a  mono  system:  ) 
FUNCTION  IsMono  :  Boolean; 

VAR 

Regs  :  Registers; 

BEGIN 

Intr (17, Regs) ; 

IF  (Regs. AX  AND  $0030)  =  $30  THEN  IsMono  :=  True 
ELSE  IsMono  :=  False; 

END; 


, - ) 

{  Returns  True  if  left  mouse  button  was  clicked,  and  if  } 

{  the  button  *was*  clicked,  returns  the  X,Y  position  ) 

(  of  the  mouse  at  click-time  in  MouseX,MouseY.  If  ) 

{  called  when  the  mouse  was  *not*  clicked,  returns  0  ) 

{  in  MouseX  and  MouseY.  } 

{ - ) 

FUNCTION  MouseWasClicked (VAR  MouseX, MouseY  :  Word)  :  Boolean; 

VAR 

Ml, ButtonStatus  :  Word; 


(Listing  continued  on  page  1 74) 
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STRUCTURED  PROGRAMMING 


Listing  One  (Listing  continued,  text  begins  on  page  161.) 

Ml  :=  3;  MouseCall (Ml , ButtonStatus, MouseX,  MouseY) ; 

IF  Odd (ButtonStatus)  THEN  MouseWasClicked  :=  True 
ELSE 
BEGIN 

MouseWasClicked  :=  False; 

MouseX  :=  0; 

MouseY  :=  0; 

END 

END; 


PROCEDURE  MatrixBlast (TextPtr, Heapptr  :  Pointer; 

SizeOfMatrix  :  Word; 
Origin, Attribute  :  Byte); 


($58/ 

{  POP  AX  ) 

$5B/ 

(  POP  BX  ) 

$59/ 

(  POP  CX  ) 

$5F/ 

{  POP  DI  ) 

$07/ 

{  POP  ES  ) 

$5E/ 

{  POP  SI  ) 

$5A/ 

{  POP  DX  } 

$1E/ 

{  PUSH  DS  } 

$8E/$DA/ 

(  MOV  DS, DX  ) 

$86/ $C4/ 

{  XCHG  AL, AH  ) 

$03/$F3/ 

{-  ADD  SI ,  BX  ) 

$AC/ 

{  LODSB  ) 

$AB/ 

(  STOSW  } 

$E2/$FC/ 

{  LOOP  -4  } 

$1F) ; 

{  POP  DS  ) 

PROCEDURE 

AttributeBlast i 

INLINE ( 

$59/ 

{  POP  CX  } 

$58/ 

(  POP  AX  ) 

$5B/ 

{  POP  BX  ) 

$D1/$E3/ 

{  SHL  BX, 1  ) 

$5F/ 

{  POP  DI  } 

$07/ 

{  POP  ES  ) 

$03/$FB/ 

{  ADD  DI,BX  ) 

$47/ 

{  INC  DI  } 

$AA/ 

{  STOSB  } 

$47/ 

{  INC  DI  ) 

$E2/$FC) ; 

{  LOOP  -4  ) 

(  Method 

definitions  for 

{  Pop  attribute  character  into  AX) 

{  Pop  origin  digit  into  BX  } 

{  Pop  byte  count  into  CX  } 

{  Pop  heap  pointer  offset  portion  into  DI  ) 

{  Pop  heap  pointer  segment  portion  into  ES  ) 

{  Pop  matrix  pointer  offset  portion  into  SI  } 

(  Pop  matrix  pointer  segment  portion  into  DX  ) 
{  Store  Turbo's  DS  value  on  the  stack  ) 

{  Move  DX  into  DS  ) 

{  Get  attribute  into  hi  byte  of  AX  ) 

(  Add  origin  adj.  to  matrix  pointer  offset  } 

{  Load  MatrixText  character  at  DS:SI  into  AL  ) 
{  Store  matrix  char/attr  pair  in  AX  to  ES:DI  ) 
{  Loop  back  to  LOADSB  until  CX  =  0  } 

(  Pop  Turbo's  DS  value  from  stack  back  to  DS  } 


ImagePtr  :  Pointer; 

ImageOf f set , Attribute, WordCount 


Integer) ; 


{  Pop  word  count  into  CX  } 

{  Pop  attribute  value  into  AX  ) 

{  Pop  image  offset  value  into  BX  } 

{  Multiply  image  offset  by  2,  for  words  not  bytes  } 
(  Pop  offset  portion  of  image  pointer  into  DI  ) 

(  Pop  segment  portion  of  image  pointer  into  ES  ) 

{  Add  image  offset  value  to  pointer  offset  ) 

{  Add  1  to  DI  to  point  to  attribute  of  1st  char  ) 

{  Store  AL  to  ES:DI;  INC  DI  by  1  } 

(  Increment  DI  past  character  byte  ) 

{  Loop  back  to  STOSB  until  CX  =  0  } 


CONSTRUCTOR  SetOb ject . Init ( InitialOrigin, 

InitialAttribute, 
InitialHighlight, 
InitialStartRow  :  Integer); 


BEGIN 

{  Set  initial  values  for  state  variables:  } 

Origin  InitialOrigin; 

Attribute  :  =  InitialAttribute; 

Highlight  :=  InitialHighlight; 

ShowAtRow  :=  InitialStartRow; 

SetData  :=  (];  (  Set  initial  set  value  to  empty  ) 

HotBit  :=  0;  {  Set  initial  hot  bit  to  0  ) 

EditlnProcess  :=  False;  (  Not  in  Edit  method  right  now!  } 

{  Allocate  space  on  the  heap  for  the  matrix:  ) 
GetMem(MatrixPtr,SizeOf (MatrixText) *2) ; 

{  Blast  the  matrix  pattern,  with  attributes,  onto  the  heap:  ) 
MatrixBlast ( @Mat  rixText , Mat rixPt r , 

SizeOf (MatrixText) , (Origin*5) , Attribute) ; 

END; 


DESTRUCTOR  SetObject .Done; 

BEGIN 

(  Free  the  memory  occupied  by  the  matrix  image:  ) 
FreeMem(MatrixPtr, SizeOf (MatrixText) *2) ; 

END; 


PROCEDURE  SetObject .ClearSet; 

BEGIN 

FillChar (SetData, Sizeof (SetData) , Chr (0) ) ; 
END; 


PROCEDURE  SetObject . Show; 

VAR 

I, Offset  :  Integer; 

ShowPtr  :  Pointer; 

BEGIN 

(  It's  important  not  to  clobber  the  visible  mouse  cursor  in  the  } 
{  video  refresh  buffer.  This  is  why  we  turn  it  off  for  the  } 
(  duration  of  this  procedure:  ) 

IF  MouseAvailable  THEN  IF  EditlnProcess  THEN  HideMouse; 

FOR  I  :=  0  TO  255  DO 
IF  I  IN  SetData  THEN 

AttributeBlast (MatrixPtr, (1*5) +1, Highlight,  3) 

ELSE 
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AttributeBlast (MatrixPtr, (1*5) +1, Attribute, 3) ; 

Offset  :=  (ShowAtRow-1)  *  160;  {  Offset  in  bytes  into  the  vid.  buffer  } 

(  Create  a  pointer  to  the  matrix  location  in  the  video  buffer:  } 

ShowPtr  :=  Pointer (Longlnt (VidBufferPtr)  +  Offset); 

{  Move  the  matrix  image  from  the  heap  into  the  video  buffer:  ) 

Move (MatrixPtrA, ShowPtrA, (Sizeof (MatrixText)  SHL  1 ) —79) ; 

(  If  the  mouse  is  available  we  assume  we're  using  it:  ) 

IF  MouseAvailable  THEN  IF  EditlnProcess  THEN  ShowMouse; 

END; 


{ - - - } 

(  This  is  the  beef  of  the  SetOb ject  concept :  A  method  that  brings  up  } 
{  a  16  X  16  matrix  of  bit  numbers,  each  of  which  corrresponds  to  one  } 
{  bit  in  the  set.  The  method  allows  the  user  to  zero  in  on  a  single  } 
(  bit  through  the  keyboard  or  through  the  mouse  if  the  driver  is  } 
(  loaded.  Click  on  the  number  (or  press  Enter)  and  the  bit  changes  } 
(  state,  as  indicated  by  screen  highlighting.  This  is  useful  for  } 
(  debugging  or  even  data  entry  to  a  set  object.  } 


PROCEDURE  SetOb ject . Edit ; 
VAR 

I  :  Integer; 

Ml, M2, M3, M4  :  Word; 

MouseX,MouseY  :  Word; 

Quit  :  Boolean; 

InCh  :  Char; 


PROCEDURE  PokeToCursor (Left, Right  :  Char); 

BEGIN 

Char (Pointer (Longlnt (MatrixPtr) + (HotBit*10) ) A)  :=  Left; 
Char (Pointer (Longlnt (MatrixPtr) + (HotBit*10) +8) A)  :=  Right; 
END; 


PROCEDURE  MoveHotBitTo (NewHotBit  :  Integer); 
BEGIN 

PokeToCursor { '  ' , '  ' ) ; 

HotBit  :=  NewHotBit; 

PokeToCursor (LeftCursorChar, RightCursorChar) ; 
Show; 

END; 


{  Converts  a  mouse  screen  X,Y  to  a  bit  position  in  the  matrix  ) 

(  from  0-255:  ) 

FUNCTION  MouseBitPosition(MouseX,MouseY  :  Integer)  :  Integer; 

VAR 

ScreenX, ScreenY  :  Word; 

BEGIN 

ScreenX  :=  (MouseX  DIV  8)  +  1;  ScreenY  :=  (MouseY  DIV  8)  +  1; 
ScreenY  :=  ScreenY  -  ShowAtRow;  {  Adjust  Y  for  screen  position  } 
MouseBitPosition  :=  (ScreenY  *  16)  +  (ScreenX  DIV  5); 

END; 


(  Simply  toggles  the  set  bit  specified  in  FlipBitNumber :  } 
PROCEDURE  ToggleBit (FlipBitNumber  :  Integer) ; 

BEGIN 

IF  FlipBitNumber  IN  SetData  THEN  {  If  it's  a  1-bit  } 

BEGIN 

SetData  :=  SetData  -  [FlipBitNumber]; 

AttributeBlast (MatrixPtr, (FlipBitNumber*5) +1, Attribute,  3) ; 
END 

ELSE  {  If  it's  a  0-bit  ) 

SetData  :=  SetData  +  [FlipBitNumber]; 

END; 


BEGIN  (  Body  of  Edit  } 

EditlnProcess  :=  True; 

(  Make  keyboard  cursor  visible  at  HotBit:  } 

PokeToCursor (LeftCursorChar, RightCursorChar) ; 

Show; 

[  Turn  on  mouse  cursor  if  mouse  is  available:  ) 

IF  MouseAvailable  THEN 
BEGIN 

Ml  :=  0;  MouseCall (Ml, M2, M3, M4) ;  (  Reset  mouse  } 

Ml  :=  8;  M3  :=  {(ShowAtRow-1)  SHL  3) ; 

M4  :=  ( (ShowAtRow-1)  SHL  3)  +  120; 

MouseCall (Ml, M2, M3, M4) ;  {  Limit  mouse  movement  vertically  } 

Ml  :=  1;  MouseCall (Ml, M2, M3, M4) ;  {  Show  mouse  cursor  } 

END; 

Quit  :=  False; 

REPEAT 

IF  MouseAvailable  THEN  {  Test  global  Boolean  variable  } 

IF  MouseWasClicked (MouseX, MouseY)  THEN 
BEGIN  {  Mouse  was  clicked...  } 

I  :=  MouseBitPosition (MouseX, MouseY) ;  (..on  what  bit?  ) 

MoveHotBitTo (I) ;  (  Move  hot  bit  to  that  bit  ) 

ToggleBit (I) ;  (  Toggle  the  selected  bit's  state  } 

WaitForMouseRelease;  (  Wait  for  button  release  } 

Show;  {  Redisplay  the  matrix  ) 

END; 

IF  KeyPressed  THEN  (  If  the  user  pressed  any  key...  } 

(Listing  continued  on  page  1 77) 
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STRUCTURED  PROGRAM  MIN  6 


Listing  One  (Listing  continued,  text  begins  on  page  161.) 


Listing  Two 


BEGIN 

InCh  :=  ReadKey; 

IF  InCh  =  Chr (0)  THEN 
BEGIN 

InCh  :=  ReadKey; 

CASE  Ord(InCh)  OF 
{  Up  >  72  :  IF  HotBit  > 

(  Left  }  75  :  IF  HotBit  > 

{  Right  }  77  :  IF  HotBit  < 

(  Down  }  80  :  IF  HotBit  < 

{  Home  }  71  :  I  :=  0; 

(  PgUp  }  73  :  I  :=  15; 

{  End  }  79  :  I  :=  240; 

f  PgDn  }  81  :  I  :=  255; 

ELSE  Uhuh; 

END;  {  CASE  } 
MoveHotBitTo { I ) ; 

END; 

CASE  Ord(InCh)  OF 

13  :  ToggleBit (HotBit) ; 
27  :  Quit  :=  True; 

ELSE  (Uhuh;) 

END;  (  CASE  ) 


{  Get  the  key  ) 

{  If  it  was  null ...  } 

{  Get  the  second  half  } 

{  and  parse  it:  } 

15  THEN  I  :=  HotBit-16  ELSE  Uhuh; 

0  THEN  I  :=  Hotbit-1  ELSE  Uhuh; 
255  THEN  I  :=  HotBit+1  ELSE  Uhuh; 
239  THEN  I  :=  HotBit+16  ELSE  Uhuh; 


{  Enter  } 
{  ESC  } 


Show; 

END; 

UNTIL  Quit; 

IF  MouseAvailable  THEN  HideMouse;  (  Hide  mouse  cursor  } 
PokeToCursor ('  {  Erase  cursor  framing  characters  ) 

EditlnProcess  :=  False; 

END; 


PROGRAM  SetTest; 

USES  Crt,SetObj;  {  SetObj  presented  in 
VAR 

My  Set  :  SetObject; 

BEGIN 

TextBackground (Black) ; 

ClrScr; 

MySet . Init (0, $07, $70, 1) ; 

MySet.SetData  :=  [0,17,42,121,93,250]; 
MySet . Edit ; 

ClrScr; 

Readln; 

MySet. Show ; 

MySet. ClearSet; 

Readln; 

My  Set. Show; 

Readln;  {  And 

END. 


{  Initialization  section:  } 

BEGIN 

IF  IsMono  THEN  VidBufferPtr  :=  Ptr($BO00,O) 

ELSE  VidBufferPtr  :=  Ptr ($B800, 0) ; 

(  Here  we  look  for  the  presence  of  the  mouse  driver:  } 
MouseAvailable  :=  Mouselslnstalled; 

END. 


End  Listing  One 


DDJ  8/90  } 


{  Create  the  object  ) 

;  {  Give  set  a  value  ) 

(  Edit  the  set  } 

{  Clear  screen  } 

(  Wait  for  keypress  } 

{  Show  the  set  ) 

{  Zero  the  set  ) 

(  Wait  for  keypress  ) 

1  Show  the  cleared  set  } 

wait  for  final  keypress  } 


End  Listings 
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ALLOCATION  ERRORS 


Listing  One  (Text  begins  on  page  80.) 

/*  bad.c  —  Mistakes  in  memory  allocation  */ 

# include  <stdio.h> 

♦include  <stdlib.h> 

♦ include  <malloc.h> 

main  () 

{ 

char  *  a 1 locat ed_but_ne ve  r_f  reed ; 

char  *this_one_is_ok; 

char  *freed_but_never_al located; 

allocated_but_never_f reed  =  malloc(lO); 
this_one_is_ok  =malloc(20); 

free (this_one_is_ok) ; 
f ree (f reed_but_never_allocated) ; 

return (0) ; 

} 


End  Listing  One 


Listing  Two 

/*  bad.c  —  Mistakes  in  memory  allocation  */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <malloc.h> 

♦include  <mem.h> 

main  () 

{ 

char  *allocated_but_never_freed; 

char  *this_one_is_ok; 

char  *freed_but_never_allocated; 

aliocated_but_never_freed  =  memMalloc (10, "tag  1"); 
this_one_is_ok  =  memMalloc (20, "tag  2"); 

memFree (this_one_is_ok,  "tag  3"); 

memFree (freed_but_never_allocated, "tag  4") ; 

return (0) ; 

} 


End  Listing  Two 


Listing  Three 

/*  memMallocO  —  Same  as  mallocO,  but  registers  activity  using  memTrackO. 

*  Copyright  (c)  1990,  Cornerstone  Systems  Group,  Inc. 

*/ 

♦include  <stdlib.h> 

♦include  <stdio.h> 

♦include  <malloc.h> 

♦include  <mem.h> 

void  ‘memMalloc (si ze_t  bytes,  char  *tag) 

{ 

void  ‘allocated; 
allocated  =  malloc (bytes) ; 
memTrack_alloc (allocated,  tag); 
return (allocated) ; 

} 

/*  memFree  ()  --  Same  as  free(),  but  registers  activity  using  memTrackO. 

*  Copyright  (c)  1990,  Cornerstone  Systems  Group,  Inc. 

*/ 

♦include  <stdlib.h> 

♦include  <stdio.h> 

♦include  <malloc.h> 

♦include  <mem.h> 

void  memFree (void  *to_free,  char  ‘tag) 

{ 

if  (memTrack_free (to_free,  tag)) 

{ 

free (to_f ree) ; 

} 

} 

/*  MEMTRACK . C  —  Module  to  track  memory  allocations  and  frees  that  occur 

*  in  the  other  mem...()  routines.  Global  routines: 

*  memTrack_alloc ()  —  Records  allocations. 

*  mem.Track_free ()  —  Records  attempts  to  free. 

*  Copyright  (c)  1990,  Cornerstone  Systems  Group,  Inc. 

*/ 

♦include  <stdlib.h> 

♦include  <stdio.h> 

♦include  <malloc.h> 

♦include  <mem.h> 

static  FILE  *memTrack_fp (void) ; 

static  void  memTrack_msg (char  *msg) ; 
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#define  ALLOC  'A' 

♦define  FREE  'F' 

/*  Track  an  allocation.  Write  it  in  the  debugging  file  in  the  format 
*  A  0000:0000  tag  */ 

void  memTrack_alloc (void  ‘allocated,  char  *tag) 

( 

FILE  *fp; 

if  (fp  =  memTrack_f p ( ) ) 

{ 

fseek (fp, 0L,  SEEK_END) ; 

fprintf (fp, "%c  %p  %s\n", ALLOC,  allocated,  tag); 
fclose (fp) ; 

) 

} 

/*  Track  freeing  of  pointer.  Return  FALSE  if  was  not  allocated,  but  tracking 
*  file  exists.  Return  TRUE  otherwise.  */ 
int  memTrack_free (void  *to_free,  char  *tag) 

{ 

int  rc  =  1; 

FILE  *fp; 

void  *addr_in_file  =  0; 

♦define  MAX_LTH  200 
char  line [MAX_LTH] ; 
char  found  =  0; 
char  dummy; 
int  ii; 
long  loc; 

if  (fp  =  memTrack_fp () ) 

{ 

rewind (fp) ; 

for  (  loc=0L;  fgets (line,MAX_LTH, fp) ;  loc  =  ftell(fp)  ) 

{ 

if  (line[0]  !=  ALLOC)  /*  Is  the  line  an  'Allocated'  line?  */ 

continue;  /*  If  not,  back  to  top  of  loop.  */ 

ii  -  sscanf (line, "%c  %p",&dummy,  &addr_in_file) ; 
if  (ii==0  ! I  ii==EOF) 
continue; 

/*  Is  addr  in  file  the  one  we  want?  */ 
if  (  (char  *) addr_in_file  -  (char  *)to_free  »■  0  ) 

{ 

found  =  1; 

fseek (fp, loc, SEEK_SET) ;  /*  Back  to  start  of  line  */ 
fputc (FREE, fp) ;  /*  Over-write  the  ALLOC  tag  */ 

break; 

) 

) 

fclose (fp) ; 
if  (! found) 

{ 

char  msg [80]; 

sprintf (msg, "Tried  to  free  %p  (%s)  .  Not  allocated. ",to_free, tag); 


memTrack_msg (msg) ; 

} 

} 

return (rc) ; 


/*  Return  FILE  pointer  for  tracking  file.  */ 
static  FILE  *memTrack_fp () 

{ 

static  char  *ep  =  NULL;  /*  Points  to  environment  var  that  names  file  */ 

FILE  *fp  =  NULL;  /*  File  pointer  to  return  */ 

if  (ep  ==  NULL  /*  First  time  through,  just  create  blank  file  */ 

&&  (ep  =  getenv ( "MEMTRACK" ) ) 

&&  (fp  =  fopen(ep, "w") )  ) 

{ 

fclose (fp) ; 
fp  =  0; 

} 

if  (ep)  /*  If  we  have  a  file  name,  proceed.  */ 

(  /*  Otherwise,  do  nothing.  */ 

fp  =  fopen (ep, "r+") ;  /*  Open  debugging  file  for  append  access.  */ 

if  ( ! fp) 

I 

fprintf (stderr, "\a\nCannot  open  %s\n\a",ep) ; 


return (fp) ; 


/*  Write  a  message  to  the  debugging  file.  */ 
static  void  memTrack_msg(char  *msg) 

{ 

FILE  *fp; 

if  (fp  =  memTrack_fp() ) 

( 

fseek (fp,0L, SEEK  END) ; 
fprintf (fp, "\n%sYn",msg) ; 
fclose (fp) ; 

I 

else 

{ 

fprintf (stderr, "%s\n",msg) ; 

) 


/*  memCallocO  —  Same  as  callocO,  but  registers  activity  using  memTrack(). 

*  Copyright  (c)  1990,  Cornerstone  Systems  Group,  Inc. 

♦include  <stdlib.h> 

♦include  <stdio.h> 

(Listing  continued  on  page  180) 
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Listing  Three  (Listing  continued,  text  begins  on  page  80.) 

free (this  one  is  ok); 
heapPrt ("after  first  free()"); 

f include  <malloc.h> 

free (freed  but  never  allocated); 

♦include  <mem.h> 

heapPrt ("after  second  free()"); 

return (0) ; 

void  *memCalloc (size_t  num_elems,  size  t  bytes  per  elem,  char  *tag) 

} 

void  ‘allocated; 

/*  heapPrt ()  makes  its  report  with  puts()  by  default.  This  will  not  be 

allocated  =  calloc(num  elems,  bytes  per  elem); 

*  appropriate  for  some  applications,  so  we  will  demonstrate  the  use  of  an 

memTrack  alloc (allocated,  tag); 

*  alternative  message  function.  This  one  writes  to  stderr. 

return (allocated)  ; 

} 

*  The  alternative  function  should  take  one  argument  (a  char  *) .  Its 

*  return  value  is  ignored,  so  it  might  as  well  be  void. 

/*  memReallocO  -  Same  as  reallocO,  but  registers  activity  with  memTrack(). 

static  void  my  own  msg  func (char  *msg) 

*  Copyright  (c)  1990,  Cornerstone  Systems  Group,  Inc. 

*/ 

♦include  <stdlib.h> 

1 

fprintf (stderr, "My  own  message  function:  %s\n",msg); 

} 

♦include  <stdio.h> 

OUTPUT : 

♦include  <malloc.h> 

My  own  message  function:  1  allocations,  10  bytes,  after  first  malloc () 

♦include  <mem.h> 

My  own  message  function:  2  allocations,  30  bytes,  after  second  malloc () 

My  own  message  function:  1  allocations,  10  bytes,  after  first  free() 

void  ‘memRealloc (void  ‘allocated,  size  t  bytes,  char  ‘tag) 

My  own  message  function:  1  allocations,  10  bytes,  after  second  free() 

memTrack_free (allocated,  tag); 
allocated  =  realloc (allocated,  bytes); 

End  Listing  Five 

if  (allocated) 

memTrack  alloc (allocated,  tag); 

} 

return (allocated) ; 

Listing  Six 

) 

/*  memStrdupO  —  Same  as  strdupO,  but  registers  activity  using  memTrackO. 

/*  heap.h  -  Header  file  for  use  with  heap...()  functions. 

*  Copyright  (c)  1990  -  Cornerstone  Systems  Group,  Inc. 

*/ 

*  Copyright  (c)  1990,  Cornerstone  Systems  Group,  Inc. 

*/ 

♦include  <stdlib.h> 

♦include  <stdio.h> 

void  heapPrt (char  ‘tag); 

void  heapPrt_set_msg_func (void  (*new_msg_func) ()  ) ; 
void  heapUsed (unsigned  int  ‘numused,  long  ‘totbytes); 

♦include  <malloc.h> 

♦include  <string.h> 

/*  HEAPUSED. C  —  Tell  how  much  of  heap  has  been  used.  For  use  with  MS  C  5.x 

♦include  <mem.h> 

*  Copyright  (c)  1990,  Cornerstone  Systems  Group,  Inc. 

void  *memStrdup(void  ‘string,  char  ‘tag) 

{ 

♦include  <malloc.h> 

♦include  cheap. h> 

void  ‘allocated; 

allocated  =  strdup (string) ; 

void  heapUsed ( 

memTrack_alloc (allocated,  tag); 

unsigned  int  ‘numused, 

return (allocated) ; 

) 

long  ‘totbytes) 

struct  _heapinfo  hinfo; 
int  status; 

‘numused  =  0; 

‘totbytes  =  0L; 

hinfo.  pentry  =  (char  *)0; 

End  Listing  Three 

while  (  (status=  heapwalk (Shinfo) )  ==  HEAPOK) 

{ 

if  (hinfo. _useflag  ==  _USEDENTRY) 

++  (‘numused); 

Listing  Four 

/*  MEM.H  --  “  Copyright  (c)  1990,  Cornerstone  Systems  Group,  Inc.  */ 

‘totbytes  +=  hinfo.  size; 

) 

} 

♦ifdef  MEMTRACK 

/*  HEAPPRT. C  —  Print  summary  information  about  heap.  For  use  with  MS  C  5.x 

void  ‘memCalloc (size  t  num  elems,  size  t  bytes  per  elem,  char  ‘tag); 

*  This  module  contains  two  functions: 

void  memFree(void  *vp,  char  ‘tag); 

*  heapPrt ()  prints  the  summary  information. 

void  ‘memMalloc (size  t  bytes,  char  ‘tag); 

*  heapPrt  set  msg  func()  allows  you  to  specify  a  function  for  heapPrt () 

void  ‘memRea Hoc (void  ‘oldloc,  size  t  newbytes,  char  ‘tag); 

*  to  use,  other  than  printf(). 

void  *memStrdup(void  ‘string,  char  ‘tag); 

*  Copyright  (c)  1990,  Cornerstone  Systems  Group,  Inc. 

/*  The  next  two  functions  are  only  called  by  the  other  mem  functions  */ 

*/ 

void  memTrack  alloc (void  *vp,  char  ‘tag); 

♦include  <stdio.h> 

int  memTrack  free (void  *vp,  char  ‘tag); 

♦include  <malloc.h> 

♦else 

♦include  cheap. h> 

♦define  memCalloc (NUM, BYTES  EACH, TAG)  calloc (NUM, BYTES  EACH) 

♦define  memFree (POINTER, TAG)  free (POINTER) 

static  void  (‘heapPrt  msg  func) ()  =  0; 

♦define  memMalloc (BYTES, TAG)  malloc (BYTES) 

♦define  memRea lloc (OLD  POINTER, BYTES, TAG)  realloc (OLD  POINTER, BYTES) 

void  heapPrt ( 

♦define  memStrdup (STRING,  TAG)  strdup (STRING) 

char  ‘tag)  /*  Description  of  where  you  are  in  processing  */ 

♦endif 

1 

unsigned  int  numused;  /*  Number  of  allocations  used  */ 

End  Listing  Four 

long  totbytes;  /*  Total  bytes  allocated  */ 

char  msg[80];  /*  Message  to  display  */ 

heapUsed (&numused,  stotbytes); 
if  (! heapPrt  msg  func) 

heapPrt_msg  func  =  puts; 

sprintffmsg,  "%5u  allocations,  %61d  bytes,  %s", numused, totbytes, tag) ; 
heapPrt  msg  func (msg) ; 

Listing  Five 

/* - */ 

void  heapPrt  set  msg  func( 

/*  DEMOHEAP.C  -  Demonstrate  use  of  heap...()  functions. 

void  (*new_msg_func) () ) 

*  Copyright  (c)  1990  -  Cornerstone  Systems  Group,  Inc. 

( 

heapPrt_msg_func  =  new  msg  func; 

♦include  <stdio.h> 

♦include  <malloc.h> 

♦include  cheap. h> 

- - ./ 

static  void  my_own_msg_func (char  *msg) ; 

End  Listings 

main () 

char  ‘allocated  but  never  freed; 
char  ‘this  one  is  ok; 

char  ‘freed  but  never  allocated; 

heapPrt_set_msg_func (my  own  msg  func); 
allocated_but_never  freed  =  malloc(lO); 
heapPrt  ("after  first  malloc  O’1); 

this_one_is_ok  =  malloc (20); 

heapPrt ("after  second  malloc ()"); 
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Listing  One  (Text  begins  on  page  134.) 

/*  0S2ERR.H  version  1.0,  March,  1989  */ 

/*  Include  this  file  after  including  OS2.H  or  OS2DEF.H  */ 

#ifdef  OS2ERR 

USHORT  API ENTRY  xos2chk(PSZ,  USHORT,  PSZ,  USHORT); 

USHORT  APIENTRY  xos2(PSZ,  USHORT,  PSZ,  USHORT); 

VOID  APIENTRY  xpoperr (VOID) ; 

♦define  os2chk(ErrCode)  (xos2chk (_FILE_,  _LINE_,  ♦ErrCode,  ErrCode) ) 

♦define  os2  (ErrCode)  (xos2  ( _ FILE _ ,  _ LINE _ ,  ♦ErrCode*  ErrCode) ) 

♦define  poperr()  (xpoperrO) 

♦else 

♦define  os2chk (ErrCode)  (ErrCode) 

♦define  os2 (ErrCode)  (ErrCode) 

♦define  poperr() 

,endl(  End  Listing  One 

Listing  Two 

/*  OS2ERR.C  version  1.1,  April  1989  by  Nico  Mak  */ 

/*  These  functions  are  called  by  the  macros  in  OS2ERR.H  */ 

/*  Compile  this  program  with  the  options  you  use  for  the  rest  of  */ 

/*  your  application,  and  link  your  application  with  OS2ERR.OBJ  */ 

♦define  MAX_S AVE_ENTRI ES  7  /*  maximum  number  of  threads  that  will  use  OS 2 ERR  */ 

/*  definitions/declarations  for  standard  I/O  routines  */ 
/*  to  include  all  of  OS/2  base  */ 

/*  include  OS/2  common  definitions  */ 

/*  include  OS/2  base  definitions  */ 

/*  to  include  OS2ERR  declarations  and  macros  */ 

/*  include  OS 2 ERR  declarations  */ 

/*  save  */ 


♦include  <stdio.h> 
♦define  INCL_BASE 
♦include  "os2def.h" 
♦include  "bse.h" 
♦define  OS2ERR 
♦include  "os2err.h" 


typedef  struct  _SAVEINFO  { 

TID  tid; 

PSZ  pszFileName; 

USHORT  usLineNumber; 

PSZ  pszLineSource; 

USHORT  usErrCode; 

}  SAVEINFO,  FAR  ‘PSAVEINFO; 

SAVEINFO  save [MAX_SAVE_ENTRIES] ; 

USHORT  cSavedEntries  =0;  /*  number  of  threads  that  have  used  OS2ERR  */ 

BOOL  fOverFlow  =  0;  /*  1  when  all  entries  in  "save"  table  are  full  */ 

/*  DosErrClass  error  classifications  */ 

PSZ  pszClassU  =  { 

"Out  of  Resource", 

"Temporary  Situation", 

"Permission  problem", 

"Internal  System  Error", 

"Hardware  Failure", 

"System  Failure", 

"Application  Error", 

"Not  Found", 

"Bad  Format", 

"Locked", 

"Media  Failure", 

"Collision  with  Existing  Item", 

"Unknown/other", 

"Can't  perform  requested  action", 

"Time-out", 

}; 

/*  DosErrClass  recommended  actions  */ 

PSZ  pszAction[]  =  { 

Retry  immediately", 

Delay  and  retry", 

User  error,  get  new  values". 

Abort  in  orderly  manner", 

Abort  immediately", 

Ignore  this  error", 

Retry  after  user  intervention", 

}; 

/*  DosErrClass  locus  */ 

PSZ  pszLocus[]  =  ( 

"Unknown", 

"Disk", 

"Network", 

"Serial  device", 

"Memory  parameter", 

}; 

CHAR  szWaitMsg []  =  "\nPress  Esc  to  abort  process  or  any  other  key  to  continue" 
CHAR  szErrTID [ ]  =  "\npoperr()  error:  no  information  saved  for  this  thread\n\r" 
CHAR  szErrOverFlow[]  =  "\npoperr{)  error:  thread  storage  area  overflowed\n\r"; 
CHAR  szBuffer [400] ; 

USHORT  PASCAL  PszLen(PSZ  psz) ;  /*  function  returns  length  of  a  far  string  */ 
PSAVEINFO  PASCAL  FindSaveEntry (TID) ;  /*  function  returns  PSAVEINFO  for  TID  */ 

/*  xos2chk  -  handle  error  (if  any)  and  return  error  code  */ 

USHORT  APIENTRY  xos2chk(PSZ  pszFileName,  USHORT  usLineNumber, 

PSZ  pszLineSource,  USHORT  usErrCode) 

{ 

if  (xos2 (pszFileName,  usLineNumber,  pszLineSource,  usErrCode)) 
xpoperr () ; 
return  usErrCode; 

} 

/*  xos2  -  save  error  information  and  return  error  code  */ 

USHORT  APIENTRY  xos2 (PSZ  pszFileName,  USHORT  usLineNumber, 

PSZ  pszLineSource,  USHORT  usErrCode) 

{ 

PSAVEINFO  psave; 

P ID INFO  pidi; 


if  (usErrCode) 

( 

DosGetPID(Spidi)  ; 

if  ((psave  =  FindSaveEntry (pidi .tid) )  ==  N 
{ 

DosEnterCritSec ( ) ; 

if  (cSavedEntries  <  MAX_SAVE_ENTRIES ) 
psave  =  save  +  cSavedEntries++; 

else 

fOverFlow  =  1; 

DosExitCritSec () ; 

} 

if  (psave) 

( 

psave->tid  =  pidi. tid; 
psave->pszFileName  =  pszFileName; 
psave->usLineNumber  =  usLineNumber; 
psave->pszLineSource  =  pszLineSource; 
psave->usErrCode  =  usErrCode; 

} 


i 

return  usErrCode; 


) 

/*  xpoperr  -  display  pop-up  screen  with  error  information,  return  error  code  */ 
VOID  APIENTRY  xpoperr (VOID) 

( 

KBDKEYINFO  kbci; 

PIDINFO  pidi; 

PSZ  psz; 

USHORT  usClass,  usAction,  usLocus,  usWait,  usEnviron,  usOffsetCmd,  cbMsg; 
PSAVEINFO  psave; 

/*  open  a  pop-up  screen  */ 
usWait  =  VP_WAIT  I  VP_OP AQUE ; 

VioPopUp (SusWait,  0); 

DosGetPID(&pidi) ; 

if  ((psave  =  FindSaveEntry (pidi. tid) )  ==  NULL) 

{ 

VioWrtTTY (szErrTID,  sizeof (szErrTID) ,  0) ; 
if  (fOverFlow) 

VioWrtTTY (szErrOverFlow,  sizeof (szErrOverFlow) ,  0) ; 


/*  display  error  code,  command  name,  and  command  tail  */ 
sprintf (szBuffer,  "Error  Code:  %u\n\r",  psave->usErrCode) ; 

VioWrtTTY (szBuffer,  PszLen (szBuffer) ,  0); 

DosGetEnv (&usEnviron,  SusOf f setCmd) ; 

for  (psz  =  MAKEP (usEnviron,  0);  *psz;  psz  +=  PszLen (psz)  +  1) 
psz  +=  1; 

sprintf (szBuffer,  "Command:  %Fs\n\r",  psz); 

VioWrtTTY (szBuffer,  PszLen (szBuffer) ,  0); 
psz  +=  PszLen (psz)  +  1; 
psz  +=  PszLen (psz)  +  1; 

sprintf (szBuffer,  "Command  tail:  %Fs\n\r",  psz); 

VioWrtTTY (szBuffer,  PszLen (szBuffer) ,  0) ; 

/*  display  process  id,  thread  id,  and  DosErrClass  information  */ 
sprintf (szBuffer,  "Process  ID:  %u\n\rThread  ID:  %u\n\r", 

pidi . pid,  pidi . tid) ; 

VioWrtTTY (szBuffer,  PszLen (szBuffer) ,  0); 

DosErrClass (psave->usErrCode,  SusClass,  SusAction,  SusLocus) ; 
sprintf (szBuffer, 

"Action:  %Fs\n\rLocus:  %Fs\n\rClass :  %Fs\n\r", 

pszAction [usAction] ,  pszLocus [usLocus] ,  pszClass [usClass] ) ; 

VioWrtTTY (szBuffer,  PszLen (szBuffer) ,  0); 

/*  display  source  filename,  line  number,  and  source  code  */ 
sprintf (szBuffer,  "Source  name:  %Fs\n\rSource  line:  %d  (%Fs) \n\r\n\r", 
psave->pszF.ileName,  psave->usLineNumber,  psave->pszLineSource)  ; 
VioWrtTTY (szBuffer,  PszLen (szBuffer) ,  0); 

/*  display  system  message  (if  any)  */ 

if  ( !DosGetMessage(0,  0,  szBuffer,  sizeof (szBuffer) ,  psave->usErrCode, 
"OSOOOl.MSG",  & cbMsg)) 

VioWrtTTY (szBuffer,  cbMsg,  0); 

) 

/*  wait  for  a  keypress  */ 

VioWrtTTY (szWaitMsg,  sizeof (szWaitMsg) ,  0) ; 
do  { 

KbdCharln (Skbci,  IO_WAIT,  0); 

}  while  ( ! (kbci.fbStatus  &  0x40)); 

/*  close  the  pop-up  screen  and  abort  if  requested  */ 

VioEndPopUp (0) ; 

if  (kbci.chChar  ==  27  &&  kbci.chScan  ==  1) 

DosExit (EXIT_PROCESS,  1); 

} 

/*  PszLen  -  return  length  of  a  far  string  */ 

USHORT  PASCAL  PszLen (PSZ  psz) 

{ 

PSZ  pszSearch  =  psz; 

while  (*pszSearch) 
pszSearch++; 
return  pszSearch  -  psz; 

} 

/*  FindSaveEntry  -  return  pointer  to  SAVEINFO  for  a  thread  ID  */ 

PSAVEINFO  PASCAL  FindSaveEntry (TID  tid) 

{ 

PSAVEINFO  psave; 

for  (psave  =  save;  psave  <  save  +  cSavedEntries;  ++psave) 
if  (psave->tid  ==  tid) 
return  psave; 
return  NULL; 


End  Listings 
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Version  5.0  of  DR  DOS  is  available 
from  Digital  Research.  The  DR  DOS 

operating  system  provides  Memory- 
MAX,  a  memory  management  facility 
which  moves  the  operating  system, 
TSRs,  buffers,  and  drivers  (including 
network  drivers)  into  high  memory. 
MemoryMAX  automatically  configures 
itself  for  the  system  in  use  (286,  386, 
or  486);  users  no  longer  have  to  unload 
networking  software  in  order  to  run 
large  applications. 

ViewMAX  is  a  Common  User  Access 
(CUA)  keystroke-compatible  GUI  that 
is  designed  for  use  with  a  keyboard  or 
a  mouse.  Users  can  view  their  disk 
layout  as  icons,  text,  or  in  a  tree  format. 
ViewMAX  also  supports  password-pro¬ 
tected  files  and  subdirectories. 

FileLINK  is  a  file  transfer  utility  that 
installs  itself  from  one  machine  to  the 
other  via  the  serial  link,  which  enables 
DR  DOS  5.0-based  systems  to  commu¬ 
nicate  with  machines  running  regular 
DOS. 

Other  features  include  disk-caching 
for  improving  application  throughput 
and  BatteryMAX  for  battery  longevity 
on  portable  systems.  The  company  be¬ 
lieves  DR  DOS  will  continue  to  extend 
the  viability  of  DOS  well  into  the  1990s. 
DR  DOS  retails  for  $199.  Reader  service 
no.  22. 

Digital  Research  Inc. 

Box  DRI 
70  Garden  Ct. 

Monterey,  CA  93942 

800-443-4200 

408-649-3896 

An  industry-wide  committee,  includ¬ 
ing  Borland,  Eclipse,  IGC,  Intel,  Locus, 
Lotus  Development,  Microsoft,  PharLap, 
Phoenix  Technologies,  Quarterdeck, 
and  Rational  Systems,  has  defined  a 
standard  interface  that  allows  extended 
DOS  applications  to  take  advantage  of 
the  capabilities  of  protected-mode,  mul¬ 
titasking  operating  environments  for  PCs 
equipped  with  Intel’s  286,  386,  and 
i486  microprocessors.  The  DOS  Pro¬ 
tected  Mode  Interface  (DPMI)  goes 
beyond  the  Virtual  Control  Program 
Interface  (VCPI)  developed  in  1987  by 
Phar  Lap  and  Quarterdeck,  which  al¬ 
lowed  expanded  memory  managers  and 
DOS  extenders  to  coexist,  but  did  not 
address  multitasking. 


The  DPMI  provides  reliable  multi¬ 
tasking  under  a  variety  of  environments, 
including  those  supporting  system-wide 
virtual  memory,  as  well  as  binary  port¬ 
ability  for  extended  DOS  applications 
across  multiple  operating  environments 
able  to  run  DOS.  The  API  calls  defined 
in  the  DPMI  spec  allow  DOS  extenders 
to  run  on  any  operating  system  or  con¬ 
trol  program  on  386  and  i486  systems. 
Existing  DOS  extenders  can  add  DPMI 
services  to  their  applications  in  addi¬ 
tion  to  existing  stand-alone  DOS  and 
VCPI  support,  permitting  maximum  in¬ 
teroperability  of  extended  DOS  appli¬ 
cations  among  systems  based  on  the 
Intel386  Architecture.  A  386  control  pro¬ 
gram  or  operating  system  that  supports 
the  DPMI  spec  can  also  support  DOS 
extender  applications  that  follow  the  stan¬ 
dard.  DPMI  will  be  implemented  by 
DESQview,  Microsoft  Windows,  OS/2, 
Unix  386,  and  VM/386. 

Software  developers  who  support 
DPMI  can  sell  a  single,  shrink-wrapped 
extended  DOS  application  that  can  run 
on  multiple  DOS  operating  environ¬ 
ments.  And  users  will  not  be  required 
to  upgrade  their  extended  DOS  appli¬ 
cations  when  they  switch  to  newer, 
more  powerful  operating  environments. 

The  first  version  is  0.9;  an  expanded 
version,  1.0,  should  be  available  by  the 
end  of  1990  and  will  be  a  compatible 
superset  of  version  0.9.  Products  that 
support  DPMI  version  0.9  will  be  fully 
compatible  with  version  1.0.  Reader 
service  no.  20. 

For  a  copy  of  the  specification,  call 
Intel  at  800-548-4725,  or  write 
Intel  Literature  Dept.  JP26 
3065  Bowers  Ave.,  P.O.  Box  58065 
Santa  Clara,  CA  95051-8065 

Quarterdeck  announced  that  it  is  bring¬ 
ing  its  DESQview  environment  and  API 
developer  tools  to  the  X  Window  Sys¬ 
tem.  DESQview/X  will  run  X  server 
and  clients  locally  and  simultaneously 
with  DOS  programs,  as  well  as  on  a 
Novell  or  TCP/IP  network.  The  com¬ 
pany  plans  to  ship  the  product  in  the 
fourth  quarter  of  this  year.  Because  the 
theme  of  Quarterdeck’s  third  annual  API 
developers  conference  in  August  is  X 
Windows  and  DOS,  X  Window  toolkits 
for  DESQview  will  be  available  at  that 
time  to  DESQview  API  developers. 

DDJ  spoke  with  Mitchell  Vaughn  of 
U.S.DATA  Corporation  in  Richardson, 
Texas,  who  is  enthusiastic  about  this 
development.  His  company  produces 
software  products  for  factory  automa¬ 
tion.  Eighty  percent  of  the  computers 
that  control  the  equipment  and  con¬ 
nect  the  factory  floor  with  the  MIS  de¬ 
partment  are  DOS  machines,  but  more 
and  more  companies  are  investing  in 


large  systems  such  as  Unix  and  VMS 
to  run  their  entire  systems.  They  there¬ 
fore  need  a  way  to  connect  with  the 
PCs  in  real  time  and  to  do  it  graphi¬ 
cally.  Because  DEC  and  HP  are  going 
with  the  Unix  strategy  and  are  adopt¬ 
ing  X  Windows  and  Motif  as  graphics 
standards,  Vaughn  “can  now  interop¬ 
erate  with  DOS  on  DESQview  and  make 
applications  that  are  portable.  Users 
can  view  graphic  displays  of  real-time 
events  on  DOS  machines.  DESQview 
is  the  ideal  product.  It  is  a  true,  multi¬ 
tasking  DOS  environment  -  a  multiven¬ 
dor  standard,  unlike  OS/2  and  MS  Win¬ 
dows.  HP,  DEC,  and  IBM  Rise  are  all  X 
Windows;  with  DESQview/X,  I  don’t 
need  OS/2  or  MS  Windows.” 

This  technology  brings  a  3-D  look 
and  feel  and  iconic  desktop  to  DESQ¬ 
view.  DESQview/X  will  multitask  DOS 
and  286  and  386  DOS  extended  appli¬ 
cations,  as  well  as  local  16-bit  and  32- 
bit  X  Window  applications.  OSF  Motif 
and  Open  Look  window  managers  for 
DESQview/X  will  be  available  for  us¬ 
ers  running  X-based  workstations. 
DESQview/X  will  be  compatible  with 
EGA,  VGA,  EVGA,  IBM  8514,  and  DGIS 
graphic  display  standards.  This  will  pro¬ 
vide  users  and  developers  with  an  open, 
vendor-  and  hardware-independent  plat¬ 
form  that  can  connect  and  communi¬ 
cate  with  disparate  hardware  from  mul¬ 
tiple  vendors.  Reader  service  no.  21. 
Quarterdeck  Office  Systems 
150  Pico  Blvd. 

Santa  Monica,  CA  90405 
213-392-9851 

Raima  has  announced  the  PowerCell 
Spreadsheet  Library  for  professional  C 
developers.  It  contains  linkable  func¬ 
tions  that  allow  developers  to  add  spread¬ 
sheet  functionality  to  applications.  Pow¬ 
erCell  source  code  availability  makes 
it  customizable  —  an  application  can 
appear  as  an  enhanced  spreadsheet  or 
as  a  menu-driven  application  with  a 
spreadsheet  component.  Other  C-com- 
patible  libraries  can  be  linked  with  Pow¬ 
erCell. 

Hal  Kenyon  of  Artex  Tool  Corpora¬ 
tion  told  DDJ  of  the  benefits  of  Power- 
Cell.  “We  have  an  interactive  system 
that  receives  information  through  a  va¬ 
riety  of  means,  including  bar  coding. 
Anytime  we  query  the  database  to  get 
information  we  get  an  immediate  feed¬ 
back  of  the  current  condition  —  and 
can  dump  it  after  use  because  the  next 
time  the  information  will  be  updated 
automatically.”  Kenyon  said  that  Pow¬ 
erCell  allows  his  workers  to  import  data 
from  a  database  and  load  it  into  a  spread¬ 
sheet,  which  avoids  keying  the  infor¬ 
mation  in.  He  also  emphasized  that 
(continued  on  page  190) 
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(continued  from  page  185) 
you  have  to  be  a  programmer  to  use 
PowerCell  —  it  is  written  almost  en¬ 
tirely  in  C. 

C  programmers  can  write  custom 
©functions,  menu  items,  macro  com¬ 
mands,  and  keystroke  processing  rou¬ 
tines  all  in  C.  The  WKS  library  is  also 
included,  with  full  source  code.  Sup¬ 
ports  Microsoft  C  5.1  or  6.0  (required 
for  installation)  and  MASM  5.0  or  later 
for  source  code  recompiles.  PowerCell 
object  code  sells  for  $695,  source  code 
for  $1495.  Reader  service  no.  23. 

Raima  Corporation 
3245  146th  Place  SE 
Bellevue,  WA  98007 
206-747-5570 

A  linkable  library  of  routines  that  im¬ 
plement  interprogram  multitasking,  with 
no  changes  to  DOS  or  to  the  compiler 
being  used,  will  be  available  this  month 
from  Tosh  Systems  of  Minneapolis. 
The  Multi-Threading  Program  Toolkit 
will  enable  programmers  to  create  self- 
contained  DOS-based  programs  that  mul¬ 
titask.  Tasks  can  be  suspended  and 
resumed  at  any  time  or  put  to  sleep 
until  an  event  such  as  a  keystroke  or 
until  the  receipt  of  an  intertask  mes¬ 
sage  or  system  semaphore. 

Routines  accompany  a  preemptive, 
time-slicing  scheduler  to  create  and  re¬ 
move  tasks,  change  priorities  and  run- 
bursts,  send  and  receive  intertask  mes¬ 
sages,  and  acquire  and  release  system 
semaphores.  The  toolkit  was  hand¬ 
crafted  and  optimized  in  assembly  lan¬ 
guage,  so  it’s  small  and  fast.  The  sys¬ 
tem  supports  Turbo  C,  Microsoft  C, 
and  most  other  popular  C  compilers, 
with  support  for  Turbo  Pascal  and  MS 
QuickPascal  and  Basic  scheduled  for 
later  release.  The  toolkit  retails  for 
$  1 19-95  and  comes  with  a  30-day  money- 
back  guarantee.  Reader  service  no.  24. 
Tosh  Systems,  Inc. 

2627  Taylor  St.  NE 
Minneapolis,  MN  55418-2941 
800-422-8674 
612-788-9433 

For  those  looking  for  a  new  approach 
to  learning  (or  teaching)  the  C  lan¬ 
guage,  The  Waite  Group  Press  has 
recently  released  Master  C,  an  on-line 
teaching  system  based  on  The  Waite 
Group ’s  Neu>  C  Primer  Plus  (Howard 
W.  Sams  and  Company,  Indianapolis, 
Indiana,  1990).  Master  C  presents  a  les¬ 
son  and  asks  questions  to  assess  the 
reader’s  understanding  of  the  material. 
A  given  question  may  be  posed  as  either 
multiple  choice,  true/false,  or  require 
text  input,  so  that  the  question  is  never 
asked  in  the  same  manner  more  than 
once.  A  “Recall”  mode  directs  the  reader 


to  problem  areas.  Additionally,  a  C  glos¬ 
sary  can  be  queried  making  the  prod¬ 
uct  a  valuable  reference  for  novice  and 
experienced  programmers  alike. 

Master  C  focuses  on  ANSI  C  and 
covers  the  history  of  the  C  language  as 
well  as  elements  of  the  language.  Other 
features  include  the  ability  to  monitor 
and  retain  student  progress,  set  book¬ 
marks  within  lessons,  provide  feedback 
on  wrong  answers,  and  a  “slick”  user 
interface.  Master  C  requires  384K  RAM, 
DOS  3.0  or  later,  2.2  Mbytes  of  hard 
disk  space,  and  a  monochrome  or  color 
adapter,  and  can  be  purchased  for 
$44.95.  Reader  Service  no.  26. 

Waite  Group  Press 
100  Shoreline  Hwy.,  Ste.  A-285 
Mill  Valley,  CA  94941 
415-331-0575 

Free  EMS  Toolkits  are  available  for  C 
developers  from  Intel’s  Personal  Com¬ 
puter  Enhancement  Operation 

(PCEO).  Designed  to  make  it  easier  to 
create  expanded  memory  applications 
in  C,  Intel  hopes  these  kits  make  the 
developer’s  job  easier  and  the  develop¬ 
ment  process  faster.  The  EMS  Toolkit 
for  C  Developers  consists  of  a  set  of 
functions  for  managing  expanded  mem¬ 
ory  in  the  same  manner  that  conven¬ 
tional  memory  is  managed  in  C.  It  prom¬ 
ises  to  alleviate  problems  with  page 
frames,  16-Kbyte  boundaries,  and  in¬ 
terfacing  to  an  assembly  language  driver. 
Call  800-538-3373  for  your  free  copy. 
Reader  service  no.  25. 

Intel  PCEO 
C03-7 

5200  NE  Elam, Young  Pkwy. 

Hillsboro,  OR  97124-6497 
503-629-7354 

A  user-interface  class  library  that  sup¬ 
ports  Borland’s  Turbo  C++  has  been 
announced  by  Zinc  Software.  The  Zinc 
Interface  Library  (ZIL)  also  supports 
AT&T’s  C++  Version  2.0.  ZIL  allows 
developers  to  create  applications  that 
run  in  both  graphics  and  text  modes 
from  one  set  of  source  code.  C++  fea¬ 
tures  include  virtual  functions,  class  in¬ 
heritance,  operator  overloading,  and 
multiple  inheritance. 

ZIL’s  event  manager  and  window  man¬ 
ager  classes  let  you  create  flexible  pro¬ 
grams.  Because  the  library  was  designed 
specifically  for  C++,  you  won’t  inherit 
problems  associated  with  a  “layered” 
implementation  of  older  C  libraries. 

The  event  manager  class  is  the  con¬ 
trol  point  for  input  information  and 
message  passing  within  a  program;  its 
two  major  components  are  an  event 
queue  and  a  list  of  devices.  The  event 
queue  is  a  block  of  input  elements  in 
a  linked  list,  and  the  device  list  con¬ 


tains  devices  polled  by  the  event  man¬ 
ager  or  interrupt  devices  that  feed  di¬ 
rectly  into  the  event  queue. 

The  ZIL  window  manager  class  con¬ 
tains  17  robust  window  objects.  You 
can  build  applications  that  allow  users 
to  mark,  copy,  cut,  and  paste  between 
window  objects,  and  each  window  ob¬ 
ject  editor  has  an  undo/redo  capability 
and  is  fully  customizable. 

ZIL  includes  complete  help  and  er¬ 
ror  systems  for  enhancing  user  interac¬ 
tion  with  a  system.  ZIL  requires  640K 
of  RAM,  a  hard  disk,  and  MS-DOS  2.1 
or  later,  but  the  company  recommends 
MS-DOS  3-1  and  a  Microsoft  mouse. 
List  price  is  $199.95;  no  royalty  fees  are 
required.  Reader  service  no.  27. 

Zinc  Software  Inc. 

405  South  100  East,  Ste.  201 
Pleasant  Grove,  UT  84062 
801-785-8900 

ObjectVision  Inc.  has  come  up  with 
a  way  to  develop  object-oriented  pro¬ 
grams  visually.  With  ObjectVision  Re¬ 
lease  1.0,  you  can  “draw”  a  program’s 
objects,  interface,  and  database  con¬ 
nections  and  then  run  the  application 
in  ObjectVision  or  convert  it  to  C++  or 
Turbo  Pascal  5  5.  You  can  create  new 
objects  with  a  click  of  the  mouse  and 
then  graphically  add  attributes  and  pro¬ 
cedures  to  them. 

Draw  a  line  between  objects  to  es¬ 
tablish  a  relationship;  create  working 
buttons  and  switches  with  the  built-in 
bitmap  editor;  and  visualize  and  edit 
object  hierarchies  with  “3-D  View.”  A 
built-in  browser  tracks  down  objects 
hidden  in  parts  of  the  diagram  you 
cannot  see.  A  language  for  writing  meth¬ 
ods  is  converted  automatically  to  code 
in  the  target  language. 

DDJ spoke  with  Andre  Maziarzewski, 
an  engineer  with  ABB  Lummus  Crest 
Inc.  He  said  that  “ObjectVision’s  pow¬ 
erful,  practical,  and  flexible  graphical 
development  enviroment  gives  me  an 
entirely  new  way  of  making  software 
development  faster  and  more  produc¬ 
tive.  And  because  ObjectVision  also 
reduces  the  effort  required  to  learn  and 
implement  OOP,  I  find  it  an  excellent 
tool  for  training  in  object-oriented  meth¬ 
odologies.” 

Interface  functions  include  a  pixel 
editor,  drawing  functions,  four  font 
sizes,  16  drawing  colors,  and  send  to 
back,  move  to  front,  and  align  to  grid 
functions.  You  can  purchase  a  demo 
disk  for  $30  and  ObjectVision  1.0  for 
$399.  Reader  service  no.  28. 
ObjectVision,  Inc. 

2124  Kittredge  St.,  Ste.  118 
Berkeley,  CA  94704 
415-540-4889 

DDJ 
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The  Integrity  of  the  Product 


When  I  was  12  years  old,  I  spent  my  free  time  over  the  course  of  several  weeks  creating,  with 
pencil  and  paper,  parodies  of  Life,  Look ,  and  the  Saturday  Evening  Post.  I  drew  the  pictures, 
wrote  the  copy,  and  invented  pseudonyms  for  myself  to  put  in  the  masthead.  After  30  years 
these  early  examples  of  my  writing  no  longer  exist,  but  they  were,  to  the  best  of  my  recollection, 
hilarious. 

This  anecdote  illustrates  three  points. 

1.  My  writing  improves  with  age  and  forgetfulness. 

2. 1  had  a  thing  for  magazines  at  an  early  age. 

3.  Life ,  Look ,  and  the  Saturday  Evening  Post ,  three  magazines  that  served  basically  the  same  market, 
were  sufficiently  distinctive  that  they  could  be  parodied  by  a  12-year  old.  This  point  is  important, 
I  think. 

What  makes  something  parodiable?  Many  attributes  can  be  parodied:  style,  voice,  appearance, 
attitude.  Perhaps  the  one  requirement  is  the  recurrence  of  some  constellation  of  attributes 
sufficiently  cohesive  as  to  be  recognized.  It’s  not  possible,  to  parody  something  that  only  happens 
once,  but  it’s  also  not  possible  to  parody  something  that  merely  recurs  without  generating  a  sense 
of  recognition.  A  magazine  is  a  package  of  published  material  that  comes  in  the  mail  regularly;  so 
are  the  offerings  of  a  book  club.  But  a  magazine  can  be  parodied  and  the  offerings  of  a  book  club 
can’t,  because  this  stream  of  books  by  different  authors  doesn’t  have  any  recurrent  aspect  worthy 
of  parody.  (Some  book  clubs  tell  you  about  upcoming  selections  in  a  publication  that  has  some 
features  of  a  magazine;  I’m  not  talking  about  that,  or  about  a  distinctive  style  in  the  company’s 
promotional  materials.) 

This  parodiable  quality  is  also  what  made  a  12-year  old  so  fascinated  by  magazines.  As  a  child, 

I  accounted  for  my  fascination  by  saying  that  magazines  had  personalities.  This  is  an  anthropomorphism 
that  I  haven’t  grown  out  of  in  30  years,  but  while  I  still  think  that  at  least  some  magazines  do  have 
something  that  is  well  described  as  a  personality,  I  no  longer  think  that  personality  is  the  trait  that 
makes  a  magazine  parodiable  or  worthy  of  a  12-year  old’s  fascination.  That  trait,  I  believe,  is 
integrity. 

The  sense  in  which  I’m  using  the  word  integrity  has  to  do  with  parts  fitting  into  a  meaningful 
whole,  systems  following  internal  logic  the  premises  of  which  are  graspable  from  the  outside, 
people  and  companies  and  products  being  true  to  their  natures.  Integrity  is  what  makes  people  and 
magazines  parodiable,  it’s  what  makes  magazines  work,  and  it’s  one  of  the  things  that  distinguishes 
successful  products,  product  lines,  and  companies. 

The  Macintosh  is  a  product  with  integrity.  Once  you  understand  the  desktop  metaphor,  you 
don’t  need  any  help  in  using  the  Mac.  When  you  come  up  against  something  you  haven’t  seen 
before,  you  feel  confident  that  your  intuition,  based  on  your  understanding  of  the  metaphor,  will 
tell  you  what  to  do,  and  the  Mac  usually  doesn’t  disappoint  that  expectation. 

Apple  is  not  an  example  of  a  company  with  integrity;  the  continual  reorganizations  and  the 
current  push  to  produce  low-margin,  high-volume  machines  make  it  hard  to  know  the  company.  I 
am  certainly  not  suggesting  that  low-cost  Macs  are  a  bad  idea,  but  I  wouldn’t  want  to  be  working 
at  Apple  these  days. 

Integrity  is  not  just  name  recognition,  although  it  encompasses  that  (Exxon  has  name 
recognition). 

Integrity  is  not  just  consistency.  Any  system  can  be  described  consistently.  London  drivers  drive 
on  the  left  side  of  the  street  and  San  Franciscans  on  the  right,  but  one  consistent  rule  applies  to 
driving  in  both  cities:  Drive  on  the  legal  side  of  the  street.  This  even  covers  the  tricky  one-way  street 
situations  in  one  consistent  rule  that  always  keeps  you  on  the  right  side  of  the  street  and  the  law. 
“Legal,”  however,  is  a  reference  to  a  technical  manual  that  none  carries  with  them  while  driving, 
while  “right”  and  “left”  are  references  to  the  driver’s  own  body. 

Integrity  in  a  product  lets  the  designer  just  throw  out  a  few  points  with  the  assurance  that  the 
user  will  connect  the  dots.  If  you  do  it  right,  you  don’t  have  to  do  as  much,  because  the  user  will 
bring  a  lot  to  the  meeting.  Interapplication  communication  is  very  nice,  but  it’s  worth  remembering 
that  the  most  powerful  piece  of  software  in  existence  lies  on  the  other  side  of  the  screen,  waiting 
to  work  with  your  application. 


Michael  Swaine 
editor-at-large 
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EDITORIAL . 6 

by  Jonathan  Erickson 

LETTERS . 8 

by  you 

SWAINE’S  FLAMES . 168 

by  Michael  Swaine 


EXAMINING  ROOM _ 

INSIDE  OBJECT  PROFESSIONAL  62 

by  Gary  Entsminger 

Gary  takes  an  inside  look  at  Turbo  Power’s  Object  Professional,  an  object-oriented  library 
for  Turbo  Pascal. 

PROGRAMMER'S  WORKBENCH _ 

KERMIT  FOR  OS/2:  PART  I  70 

by  Brian  R.  Anderson 

In  last  year’s  “Structured  Languages”  issue,  Brian  presented  an  implementation  of  the 
Kermit  communications  protocol  for  DOS.  In  this  two-part  article,  he  moves  the  protocol 
from  DOS  to  OS/2  and  from  Logitech  to  Stony  Brook  Modula-2. 

COLUMNS _ 

PROGRAMMING  PARADIGMS  1 1 9 

by  Michael  Swaine 

Looking  for  a  new  product  niche?  Is  gardening  your  favorite  pastime  (outside  of  program¬ 
ming,  of  course)?  If  “yes,  yes”  is  your  answer,  Michael  may  have  the  idea  you’ve  been 
waiting  for. 

C  PROGRAMMING  127 

by  Al  Stevens 

Al  comes  in  from  the  cold  to  discuss  hacks,  spooks,  and  data  encryption  techniques. 

STRUCTURED  PROGRAMMING  1 37 

by  Jeff  Duntemann 

Jeff  discovers  that  multi-language  development  can  be  done  in  bits  and  pieces. 

PROGRAMMER’S  BOOKSHELF  145 

by  Andrew  Schulman 

In  launching  this  new  column,  Andrew  takes  a  look  at  Microprocessors:  A  Programmer's 
View  from  a  programmer’s  perspective. 


PROGRAMMER'S 

SERVICES 


ADVERTISER  INDEX . 160 

where  to  go  for  more  information 
on  products 

OF  INTEREST . 161 

compiled  by Janna  Custer 

PROGRAMMER’S 
MARKETPLACE . 162 

classified  ads 


SOURCE  CODE  AVAILABILITY 

As  a  service  to  our  readers,  all  source  code 
is  available  on  a  single  disk  and  online.  To 
order  the  disk,  send  $14.95  (Calif,  residents 
add  sales  tax)  to  Dr.  Dobb's Journal,  501 
Galveston  Dr.,  Redwood  City,  CA  94063, 
or  call  800-356-2002  (inside  Calif.)  or  800- 
533-4372  (outside  Calif.).  Specify  issue  num¬ 
ber  and  disk  format.  Code  is  also  available 
through  the  DDJ  Forum  on  CompuServe 
(type  GO  DDJ)  and  through  M&T’s  Telepath 
online  service. 


NEXT  ISSUE _ 

The  emergence  of  DOS  extenders  has 
pumped  new  life  into  DOS,  and  in  October 
we’ll  give  you  the  tools  for  rolling  your 
own  80386  protected-mode  DOS  Extender. 
We’ll  also  look  at  other  operating  system 
programming  issues,  including  DOS,  Unix, 
and  OS/2. 
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Taking  Care  of 
Business 


It’s  always  fun  to  bring  something  new  to  DDJ.  That’s  why  this  month  I’m  particularly  happy 
about  launching  the  “Programmer’s  Bookshelf,”  a  new  monthly  column  devoted  to  books  that 
are  important  for  programmers.  The  column,  which  you’ll  find  on  page  145  of  this  issue,  is 
co-written  on  alternate  months  by  Andrew  Schulman  and  Ray  Duncan.  Andrew  kicks  off  with  a 
look  at  a  recently  published  book  on  the  new  generation  of  microprocessors.  Unlike  most 
CPU-oriented  books  that  are  aimed  at  hardware  design  engineers,  this  one  is  written  from  the 
programmer’s  perspective.  As  Andrew  points  out,  you  get  source  code  instead  of  pin-outs. 

Over  the  coming  months,  Andrew  and  Ray  will  examine  books  they  think  should  be  on  every 
programmer’s  bookshelf.  The  ground  rules  are  that  books  are  as  important  to  every  programmer’s 
toolkit  as  software  and  that  a  book  should  be  used  as  a  tool.  They’re  reserving  the  right,  however, 
to  break  the  rules  at  any  time. 

If  you’ve  run  across  a  book  (new  or  old)  you  think  they  should  take  a  look  at,  drop  us  a  note  in 
care  of  DDJ  and  we’ll  see  if  they  agree. 

Summer  Visitors,  Neural  Nets,  and  Biocomputing 

We  look  forward  to  seeing  out-of-town  visitors  when  they  get  a  chance  to  drop  by  the  office.  One 
recent  caller  was  Stephan  Lugert  of  Open  Network  (developers  of,  among  other  tools,  a  nifty  file 
comparison  program  called  “Delta”  —  there’s  the  plug  Stephan)  who  was  on  his  way  to  Seattle, 
taking  the  train  up  from  San  Diego  where  he’d  just  attended  the  International  Joint  Conference  on 
Neural  Networks. 

One  conference  presentation  that  really  impressed  Stephan  was  a  videotape  of  a  research  project 
whereby  neurons  were  being  grown  on  silicon  plates.  Nothing  really  new  there.  What  was  new, 
however,  was  that  electrical  signals  generated  by  neural  network  circuits  were  stimulating  the  cells 
to  grow  in  certain  directions.  As  the  dendrites  grew,  the  cells  generated  growth  energy  and  seemed 
to  make  decisions  about  which  specific  way  to  grow.  Eventually  one  cell  would  take  off  while 
others  were  absorbed  back  into  the  dendrites.  Intracell  competition  was  genuinely  occurring  even 
though  the  growth  of  the  dendrites  appeared  to  be  random. 

There  were  a  couple  of  things  about  the  presentation  that  really  knocked  his  socks  off,  Stephan 
said.  One  thing  was  the  non-verbal  nature  of  the  presentation  —  seeing  it  actually  happen  instead 
of  simply  having  it  described.  The  other  was  that  the  neurons  weren’t  static;  the  growth  was  much 
more  dynamic  and  much  more  sensitive  to  the  environment  than  researchers  previously  thought. 
And  they  were  keeping  the  nerves  alive  for  up  to  three  months. 

I’m  not  sure  what  the  long  range  potential  of  research  like  this  is,  and  I’d  like  someone  to  explain 
it  to  me  in  more  depth.  If  you’ve  heard  about  this  or  similar  projects,  I’d  like  to  hear  from  you. 

I  don’t  know  if  we’ll  get  a  chance  to  look  at  projects  like  this  in  next  April’s  “Biocomputing”  issue 
(where  we’ll  be  examining  neural  networks,  genetic  algorithms,  and  the  like),  but  if  you  have 
something  in  mind,  that’s  the  perfect  forum  to  present  what  you’ve  learned. 

Inquiring  Minds  Want  to  Know 

We’ve  had  a  few  calls  asking  about  the  art  in  the  our  July  “Graphics  Programming”  issue.  Yes,  Doc 
Livingston  of  Rix  Softworks  created  both  the  Dr.  Dobb's  blimp  scene  on  the  cover  and  the  VGA 
street  sign  that  accompanied  Chris  Howard’s  article.  And  yes,  Doc  did  use  his  own  software  to 
generate  the  screens. 

DDJ  Online 

Telepath,  M&T’s  online  service,  was  officially  up  and  running  as  of  our  August  issue.  Not  only 
does  the  service  give  you  access  to  DDJ ,  but  it  also  provides  you  an  electronic  doorway  to  our  sister 
publications:  DBMS,  LAN  Technology,  and  Personal  Workstation. 

In  addition  to  furnishing  you  with  yet  another  way  to  get  DDJ’ s(and  the  other  magazine’s)  source  code 
listings,  you’ll  find  a  variety  of  active  online  technical  conferences  already  underway:  32-bit  program¬ 
ming,  C,  graphics,  OOPS,  and  discussions  about  dBase,  Oracle,  servers,  Netware,  and  so  on. 

You  can  get  to  Telepath  via  the  Tymnet  network;  dial  800-336-0149  to  find  out  your  local  Tymnet 
access  phone  number.  The  communications  parameters  are  7  data  bits,  even  parity,  and  1  stop  bit. 
When  Tymnet  answers,  press  a  and,  when  prompted  to  log  in,  type  telepath.  You’ll  then  be  led 
through  the  sign-on  process  and  you  can  go  on-line  immediately. 


Jonathan  Erickson 
editor-in-chief 
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Rhealstone  Recommendations 

Dear  DDJ , 

This  letter  is  in  response  to  the  article 
“Implementing  the  Rhealstone  Real- 
Time  Benchmark,”  by  Rabindra  P.  Kar, 
which  appeared  in  the  April  1990  issue 
of  Dr.  Dobb’s  Journal.  There  are  sev¬ 
eral  areas  of  the  benchmark  that  could 
be  improved,  which  we  discuss  below: 

1 .  Synthetic  benchmarks  and  kernels 
are  generally  held  in  less  regard  now 
than  in  the  past  by  experts  in  the  field 
of  performance  evaluation.  The  detailed 
reasons  are  too  long  to  include  here. 
However,  for  an  excellent  explanation 
please  read  Chapter  2,  “Performance 
and  Cost,”  of  the  book  Computer  Ar¬ 
chitecture-  A  Quantitative  Approach , 
by  Hennessey  and  Patterson  (published 
by  Morgan  Kaufmann,  1990).  Their  rec¬ 
ommendation  for  evaluating  perfor¬ 
mance  is  to  use  a  workload  consisting 
of  a  mixture  of  real  programs.  Hen¬ 
nessey  and  Patterson  say  that  synthetic 
benchmarks,  such  as  Whetstone  and 
Dhrystone,  are  the  least  accurate  of  all 
predictors  of  performance.  We  would 
hope  that  Rhealstone  can  avoid  some 
of  the  limitations  of  such  benchmarks. 

2.  Rhealstone  uses  average  times 
rather  than  worst-case  times.  In  many 
real-time  applications,  worst-case  time 
is  more  important  than  average-case. 
In  fact,  a  prime  characteristic  that  dis¬ 
tinguishes  real-time  systems  from  data 
processing  systems  is  that  a  real-time 
system  has  deadlines  that  must  be  met 
in  order  for  the  system  to  work  prop¬ 
erly.  Average  throughput  is  of  some 
interest  but  not  the  critical  factor.  In 
order  to  determine  whether  the  dead¬ 
lines  will  be  met,  the  worst-case  re¬ 
sponse  times  must  be  measured. 

3.  The  article  states  that  the  set  of  six 
time  values  will  typically  be  in  the  tens 
of  microseconds  to  milliseconds  range. 
Note  that  this  is  a  range  of  two  orders 
of  magnitude.  However,  to  compute 
the  “real-time  figure  of  merit”  the  equa¬ 


tion  takes  all  six  values  and  finds  the 
arithmetic  mean  of  them.  The  result  is 
that  those  components  whose  values 
are  small,  such  as  interrupt  latency, 
will  contribute  negligibly  to  the  total. 
Similarly,  large  values  (such  as  infinity 
for  deadlock-break  time  on  many  ker¬ 
nels)  will  contribute  enormously,  to 
the  point  that  the  number  of  Rhealst- 
ones  per  second  is  zero.  The  article 
does  allow  an  application-specific  meas¬ 
urement  to  assign  unequal  weights  to 
the  components,  but  for  the  standard 
measurement,  the  weights  are  all  equal. 
Hennessey  and  Patterson  present  argu¬ 
ments  for  using  geometric  means,  rather 
than  arithmetic  means,  to  avoid  some 
of  these  problems. 

4.  Regarding  the  definition  and  bench¬ 
mark  for  measure  interrupt  latency,  there 
are  really  three  aspects  of  kernels  that 
affect  interrupt  response:  the  interrupt 
disable  time,  interrupt  latency,  and  in¬ 
terrupt  servicing. 

The  interrupt  disable  time  is  the  worst- 
case  time  in  the  kernel  that  interrupts 
are  disabled  (at  task  level),  in  order  for 
the  kernel  to  manipulate  critical  data 
structures.  The  processor  cannot  re¬ 
spond  to  interrupts  at  all  during  this 
time.  Unfortunately,  it  is  extremely  dif¬ 
ficult  to  measure  this  value,  since  there 
is  little  or  no  external  indication  from 
the  processor  that  interrupts  are  dis¬ 
abled.  You  can  measure  it  statistically 
using  sophisticated  hardware  (emula¬ 
tors,  oscilloscopes,  and  so  on),  but  this 
measurement  may  not  yield  the  true 
worst-case  time.  The  only  real  way  to 
determine  it  is  by  identifying  the  in¬ 
struction  stream  in  the  kernel  that  dis¬ 
ables  interrupts  for  the  longest  period, 
and  then  calculating  the  timings  of  those 
instructions  using  worst-case  timing  fig¬ 
ures  for  the  processor.  This  may  in¬ 
clude  cache  misses,  pre-fetch  queue 
fills,  memory  wait  states,  etc. 

Interrupt  latency  is  the  time  it  takes 
from  the  point  an  interrupt  is  acknowl¬ 
edged  by  the  processor,  up  to  the  first 
application  instruction  in  the  interrupt 
service  routine.  The  article  describes 
one  way  to  measure  this  value.  For 
some  kernels,  this  value  is  simply  the 
time  taken  by  the  processor  to  respond 
to  the  interrupt,  since  they  require  no 
preamble  or  vectoring  code  through 
the  kernel,  but  instead  let  the  interrupt 
vector  point  directly  to  the  interrupt 
service  routine. 

Interrupt  service  time  is  the  time  it 
takes,  at  interrupt  level,  to  do  whatever 
work  is  required  by  the  kernel  and 
application  before  returning  to  task 
level.  Since  nested  interrupts  at  the  same 
priority  generally  are  not  allowed  dur¬ 
ing  this  period  (although  in  some  sys¬ 
tems  they  can  be),  this  timing  can  sig¬ 


nificantly  affect  interrupt  response  to 
bursts.  This  timing  can  be  measured, 
given  the  appropriate  test  case.  It  should 
be  recognized  that  different  kernels  have 
different  mechanisms  for  servicing  in¬ 
terrupts,  and  some  have  more  alterna¬ 
tives  than  others.  We  suppose  a  par¬ 
ticular  kernel  should  be  able  to  put  for¬ 
ward  its  best  case  for  this  measurement. 

Any  benchmark  attempting  to  define 
interrupt  response  characteristics  should 
address  all  three  of  these  factors.  Rheal¬ 
stone  currently  measures  only  inter¬ 
rupt  latency. 

5.  The  Rhealstone  benchmark  as  de¬ 
scribed  measures  a  small  set  of  cases 
that  actually  measure  more  or  less  the 
same  thing:  The  time  it  takes  to  switch 
from  one  task  to  the  other  in  a  system 
with  2  or  3  tasks.  This  approach  fails 
to  address  an  important  aspect  of  ker¬ 
nel  performance  which  relates  to  the 
behavior  (of  the  kernel)  when  large 
numbers  of  tasks  are  present.  Some 
kernel  designs  use  linear  linked-lists 
for  handling  ready  tasks.  This  approach 
can  be  fast  in  the  case  of  small  num¬ 
bers  of  tasks,  but  degrades  when  large 
numbers  of  tasks  are  present  and  are 
made  ready  in  a  particular  order.  Other 
designs  have  flat  response  time  relative 
to  the  total  number  of  tasks.  Any  bench¬ 
mark  should  address  this  issue,  for  ex¬ 
ample  by  measuring  task  switch  time 
in  a  system  with  a  hundred  tasks. 

6.  The  standard  definition  of  dead¬ 
lock  is  a  situation  in  which  each  mem¬ 
ber  of  a  set  of  tasks  is  waiting  for  a 
resource  that  is  owned  by  another  task 
in  the  set,  in  such  a  way  that  none  of 
the  tasks  (regardless  of  priority)  are 
able  to  proceed.  What  the  article  refers 
to  as  a  “deadlock”  is  called  priority 
inversion  in  standard  terminology. 

7.  Since  many  real-time  operating  sys¬ 
tems  do  not  implement  priority-inheri¬ 
tance  or  priority-ceiling  protocols,  which 
automatically  solve  the  priority  inver¬ 
sion  problem,  the  “deadlock-break  time” 
will  be  infinity  for  such  systems.  Al¬ 
though  it  is  legitimate  to  ask  whether 
or  not  a  kernel  has  a  particular  feature, 
it  should  be  expressed  as  such,  rather 
than  masking  it  as  a  “performance 
measurement." 

There  are  other  techniques  available 
for  avoiding  priority  inversion  in  these 
systems  through  explicit  control  of  the 
application.  The  simplest  way,  if  the 
application  allows  for  it,  is  to  avoid 
having  unequal  priority  tasks  compete 
for  the  same  resources.  If  this  is  not 
possible,  the  following  method  can  be 
used:  Let’s  assume  the  classic  example 
of  three  tasks  H,  M,  and  L,  with  respec¬ 
tive  priorities  high,  medium,  and  low. 
Tasks  H  and  L  share  a  common  re- 
(continued  on  page  12) 
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(continued  from  page  8) 
source.  Task  M  is  unrelated  to  H  or  L 
and  does  not  compete  for  the  resource. 
When  L  wants  to  acquire  a  resource,  it 
should  explicitly  raise  its  priority  to 
that  of  the  highest-priority  task  that  also 
uses  that  resource  (H),  before  taking 
the  resource.  This  requires  a  few  extra 
system  calls,  but  achieves  the  purpose. 
It  behaves  a  little  differently  than  the 
iRMX/iRMK  style,  which  lets  M  run 
briefly  until  H  waits  on  the  resource. 
However,  the  former  behavior  may  be 
more  efficient  in  that  respect,  as  it  avoids 
two  context  switches  into  and  out  of 
M.  It  does  block  M  temporarily,  even 
if  H  doesn’t  really  want  the  resource  at 
all  during  the  time  L  has  it. 

8.  Rhealstone  does  not  include  a 
benchmark  which  measures  “broadcast” 
wake-up  of  several  tasks,  using  event 
flags.  Since  this  feature  is  commonly 
used  in  real-time  systems,  we  suggest 
that  this  be  added. 

9-  Since  Rhealstone  is  described  in 
English,  each  implementation  of  it  may 
be  written  in  a  different  programming 
language,  make  different  operating  sys¬ 
tem  calls,  and  make  various  assump¬ 
tions  about  what  the  English  text  really 
means.  This  will  make  it  impossible  to 
interpret  the  benchmarks  on  different 
systems.  To  have  validity,  the  bench¬ 
mark  must  be  written  in  one  program¬ 
ming  language,  call  one  set  of  operat¬ 
ing  system  services,  and  there  must  be 
one  master  implementation  of  it  which 
everyone  uses. 

To  summarize,  we  feel  that  these 
issues  should  be  addressed  to  improve 
the  validity  of  the  proposed  Rhealstone 
benchmark.  However,  even  with  these 
corrections,  the  accuracy  in  performance 
prediction  of  a  synthetic  benchmark, 
such  as  Rhealstone,  can  never  come 
close  to  that  of  an  actual  real-time  pro¬ 
gram.  We  feel  that  benchmarks  for  real¬ 
time  should  describe  or  incorporate  ac¬ 
tual  real-time  programs.  These  programs 
will  presumably  call  some  pro  prietary 
real-time  operating  system  services,  so 
the  operating  system  calls  should  be 
converted  to  a  standard,  portable,  op¬ 
erating  system  interface  such  as  POSIX, 
with  its  Real-Time  Extensions.  Only  then 
can  meaningful  performance  measure¬ 
ments  be  obtained. 

Glenn  Kasten,  Ready  Systems 

David  Howard,  Ready  Systems 

Bob  Walsh,  Ready  Systems 

Robin  responds:  The  authors  of  this 
letter  raise  some  interesting  and  valid 
issues  about  the  Rhealstone  benchmark. 
Responding  to  each  issue  in-depth 
would  make  this  almost  a  full-length 
article,  so  I  will  address  some  of  the 


more  important  objections  that  they 
have  raised. 

One  major  criticism  of  Rhealstones 
is  that  it  specifies  the  measurement  of 
average  times  rather  than  worst-case 
time.  This  criticism  stems  from  the  no¬ 
tion  that  real-time  systems  (hardware 
+  real-time  OS  or  kernel)  are  bench- 
marked  primarily  to  validate  their  criti¬ 
cal  response-time  capability.  The  ex¬ 
pectation  here  is  that  the  Rhealstone 
number  achieved  by  the  system  should 
indicate  if  it  will  meet  interrupt  re¬ 
sponse  or  other  deadlines  with  100  per¬ 
cent  certainty.  The  reality  is  that  bench¬ 
marks  are  used,  by  the  computer  in¬ 
dustry,  to  evaluate  and  compare  aver¬ 
age,  long-run  performance  of  “ typical 
system  operations,  ”  after  determining 
that  the  system  can  meet  the  job’s  mini¬ 
mum  requirements .  There  is  little  doubt 
that  any  widely  used  real-time  bench¬ 
mark  will  be  put  to  similar  use.  Conse¬ 
quently,  Rhealstones  measure  average 
performance  of  “typical  real-time  op¬ 
erations.  ”  Running  Rhealstones  will  not 
lift  the  burden  of  determining  worst- 
case  response  times  from  the  applica¬ 
tion  designer’s  shoulders;  it  was  never 
intended  for  that  purpose. 

Section  4  in  the  letter  states  that  in¬ 
terrupt  disable  time,  interrupt  latency, 
and  interrupt  servicing  together  affect 
interrupt  response;  and  further  claims 
that  Rhealstones  only  measures  latency. 
My  article  defines  interrupt  latency  as 
the  delay  between  the  CPU’s  receipt  of 
an  interrupt  request  and  the  execution 
of  the  first  application-specific  instruc¬ 
tion.  Their  letter  defines  latency  from 
the  point  that  an  interrupt  is  acknowl¬ 
edged  by  the  CPU.  In  effect,  Rheal¬ 
stones  measure  both  interrupt  disable 
time  as  well  as  “latency,  ”  as  defined 
in  the  letter.  It  does  not  measure  inter¬ 
rupt  service  time,  because  that  is  en¬ 
tirely  a  function  of  the  application, 
NOT  the  system. 

Section  5  points  out  that  real-time 
system  performance  may  be  impacted 
if  the  system  is  running  a  large  num¬ 
ber  of  concurrent  tasks.  It  suggests  that 
the  benchmark  should  measure  task- 
switch  time,  for  example,  with  a  hun¬ 
dred  active  tasks.  Their  point  is  well 
taken  but,  I  believe,  it  is  inappropriate 
for  the  benchmark  to  specify  what  the 
“background  load’’  should  be.  Why  a 
hundred  tasks?  Why  not  five  tasks  or 
five  hundred?  And  what  should  each 
task  be  doing?  Background  loading  is 
a  very  application-specific  issue.  The 
only  way  to  obtain  a  generic  bench¬ 
mark  number  is  to  use  an  unloaded 
system  (no  background  application 
tasks). 

The  most  important  objection  raised 
in  this  letter  is  that  we  should  not  be 


trying  to  devise  or  use  synthetic  bench¬ 
marks  like  Rhealstones  (or  Whetstones 
or  Dhrystones)  at  all.  A  book  on  com¬ 
puter  architectures  is  cited  to  support 
the  assertion  that  “a  mixture  of  real 
programs”  can  be  a  better  vehicle  for 
performance  evaluation  than  a  syn¬ 
thetic  benchmark.  We  could  have  a 
long  and  vigorous  debate  on  that  point. 
But  even  if  it  were  true,  Kasten,  How¬ 
ard,  and  Walsh  seem  to  have  over¬ 
looked  some  major  drawbacks  of  using 
a  suite  of  actual  real-time  programs 
as  a  benchmark. 

•  For  a  benchmark  to  gain  wide  ac¬ 
ceptance  in  an  industry,  it  must  be 
compact  and  easy  to  recompile  and 
run  in  a  variety  of  software/hardware 
environments.  This  is  much  more  true 
of  a  synthetic  benchmark  than  an  ac¬ 
tual  program  suite.  It  is  probably  the 
major  reason  why  Dhrystones  and  Whet¬ 
stones  are  so  commonly  used,  whatever 
their  theoretical  shortcomings. 

•  Since  synthetic  benchmarks  are  short 
and  relatively  simple,  the  application 
engineer  can  easily  understand  them, 
modify  them  and/or  decide  if  they  are 
appropriate  for  the  task  at  hand.  In  the 
real  world,  few  engineers  have  the  time 
to  even  understand  what  exactly  is  be¬ 
ing  measured  by  some  humongous pro¬ 
gram  suite.  If  you  were  evaluating  a 
real-time  kernel  for  use  in  an  automo¬ 
bile  microcontroller,  how  much  confi¬ 
dence  would  you  have  in  a  mixture  of 
benchmark  programs  from  the  oil-drill¬ 
ing  industry,  satellite  manufacturers, 
nuclear  reactor  designers,  and  a  dozen 
other  industries  (especially  if  you  did 
not  know  what  any  program  actually 
did)? 

•  The  program  suite  would  not  reveal 
what  the  system ’s  worst-case  response 
times  are.  This  was  one  of  their  major 
criticisms  of  Rhealstones,  but  their  sug¬ 
gested  solution  comes  no  closer  to  ad¬ 
dressing  it. 

Finally  I’d  like  to  thank  Kasten,  How¬ 
ard,  and  Walsh  for  their  thoughtful 
response  to  my  benchmarking  proposal. 
The  absence  of  a  widely  used  real-time 
benchmark  standard  often  leads  to  the 
use  of  inappropriate  general-purpose 
benchmarks  (Whetstone,  Dhrystone)  by 
real-time  application  designers.  The 
Rhealstone  benchmark  was  proposed 
to  help  fill  this  void,  though  neither 
Rhealstones  nor  any  other  benchmark 
will  do  justice  to  every  real-time  situ¬ 
ation.  If  it  seeds  and  motivates  further 
creative  effort  and  discussion  in  the 
real-time  software  community,  the 
Rhealstone  proposal  will  have  more  than 
served  its  purpose. 

(continued  on  page  14) 
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LETTERS 


(continued  from  page  12) 

SEGTABLE  and  Windows  3-0 

Dear  DDf 

Facing  the  start  of  a  Windows  develop¬ 
ment,  I  recently  reread  the  article  which 
Tim  Paterson  and  Steve  Flenniken  con¬ 
tributed  to  the  March  1990  issue  of 
DDf  “Managing  Multiple  Data  Segments 
Under  Microsoft  Windows.”  It  was  a 
good  article.  But  I  have  a  few  questions 
about  its  applicability  to  Windows  3-0. 

The  obvious  first  question  is  does 
Windows  3-0  support  the  undocu¬ 
mented  call  they  use  to  register  the 
local  segment  table?  Since  recent  Mi¬ 
crosoft  apps  that  ran  under  Win  2.0 
and  that  they  say  use  these  techniques 
run  unchanged  under  Win  3.0, 1  would 
guess  that  the  answer  is  “Yes,  the  world 
does  look  a  bit  different,  though,  in 
Win  3.0  since  the  segment  table  is  no 
longer  handling  segment  numbers  but 
rather  protected-mode  segment  descrip¬ 
tors.”  Again,  I  would  guess  that  this 
shouldn’t  make  too  much  difference. 

In  the  second  article  in  the  series, 
Paterson  and  Flenniken  spend  time  dis¬ 
cussing  how  the  segment  table  tech¬ 
nique  fits  in  the  EMS.  Since  Win  3-0 
manages  all  memory  on  a  machine,  I 
would  think  that  one  need  no  longer 
worry  about  EMS  but  should  write  an 
application  as  if  one  had  much  more 
global  memory  available  for  allocation. 
One  might  still  be  memory  constrained 
on  a  machine  with  1  Meg  of  RAM  run¬ 
ning  in  Win  3.0  real  mode,  but  now  it 
seems  that  the  solutions  are  to  write  to 
use  less  RAM  (which  might  include 
roll-your-own  virtual  memory)  or  to 
require  more  RAM  installed  as  extended 
memory  and  use  Win  3.0’s  protected 
memory  mode. 

I  actually  find  it  a  bit  disturbing  that 
Microsoft  uses  these  techniques  in  their 
products  but  does  not  document  them. 
It  seems  to  give  the  lie  to  their  assertion 
that  Microsoft  apps  writers  have  no 
secret  information  about  Windows  that 
gives  them  a  competitive  advantage. 

In  addition  to  commenting  on  the 
above,  I  would  appreciate  any  other 
comments  Tim  Paterson  might  have  with 
regard  to  using  memory  in  Win  3-0. 
Steve  Williams 
3Com  Corporation 
Santa  Clara,  California 

Tim  responds:  Steve  asked  some  very 
good  questions  about  the  relationship 
between  Windows  3  0  and  the  segment 
table  I  described  in  my  February/March 
article.  Fortunately,  the  answers  are 
surprisingly  simple,  once  you  know  a 
little  bit  about  the  new  Windows. 

Windows  3-0  has  three  operating 
modes,  selected  when  it  starts  up.  Real 
mode  is  identical  to  Windows  2.x,  so 


it  can  run  all  Windows  2.x  applica¬ 
tions  unchanged.  Real  mode  even  works 
on  8088/8086 processors,  just  as  Win¬ 
dows  2.x  did.  Real  mode  also  supports 
the  segment  table  exactly  as  I  described 
in  my  article.  In  fact,  the  new  Windows 
Software  Development  Kit  (SDK)  includes 
a  description  q/t(?<?DefineHandleTable() 
function  that  kicks  in  the  segment  ta¬ 
ble,  although  the  one-paragraph  de¬ 
scription  is  a  little  thin  to  relate  a  full 
understanding  of  its  application. 

The  other  modes  for  Windows  3-0 
are  Standard  mode  ( or 286  mode)  and 
386  Enhanced  mode.  From  the  stand¬ 
point  of  a  Windows  application,  these 
modes  are  the  same;  their  main  differ¬ 
ence  is  in  how  they  handle  non-Win¬ 
dows  programs.  'These  modes  run  the 
processor  in  protected  mode,  where  the 
values  loaded  into  the  segment  registers 
are  “selectors,  ”  not  paragraph  addresses. 
Even  when  the  Windows  memory  man¬ 
ager  moves  or  discards  a  segment  in 
protected  mode,  the  selector  never 
changes;  as  far  as  the  application  is 
concerned,  there  is  no  memory  move¬ 
ment.  The  concept  of  the  segment  table 
is  meaningless,  and  the  DefineHan- 
dleTableO  function  is  ignored. 

In  other  words,  if  you  ’re  willing  to 
limit  your  applications  to  286  or  better 
processors  running  Windows  3-0,  ig¬ 
nore  my  article.  Not  only  will  you  get 
to  pass  far  pointers  around  willy-nilly 
with  no  concern  for  memory  move¬ 
ment,  you  will  also  get  transparent  ac¬ 
cess  to  extended  memory.  But  if  you 
want  to  run  on  the  older  machines 
( 8088/8086)  or  with  Windows  2.x,  Win¬ 
dows  3-0  Real  mode  changes  nothing. 
It  appears  that  most  companies,  in¬ 
cluding  Microsoft,  will  be  taking  the 
first  approach. 

I,  too,  found  it  disturbing  that  Micro¬ 
soft  applications  were  using  a  tech¬ 
nique  that  was  not  documented  — 
that’s  why  Steve  Flenniken  and  I  wrote 
the  article.  However,  people  at  Micro¬ 
soft  left  the  impression  that  this  was 
more  of  an  oversight  (or  maybe  just  too 
much  trouble  to  document)  than  in¬ 
tentionally  holding  back.  I  find  myself 
working  for  Microsoft  once  again,  and 
no  one  has  complained  to  me  that  I 
told  a  secret. 

Hypertext  Caveats 

Dear  DDJ, 

Regarding  your  June  1990  hypertext 
issue:  How  do  I  usually  read  DDf  I 
usually  read  it  on  the  train  or  as  bed¬ 
side  reading.  I  also  usually  mark  up  the 
listings.  Hypertext  has  its  place,  but 
not  in  the  quiet  contemplation  that  must 
accompany  learning. 

John  O.  Goyo 

Port  Credit,  Ontario,  Canada 


Patents  Cont. 

Dear  DDf, 

Lacking  Barr  Bauer’s  special  qualifica¬ 
tions  and  insights  into  the  patent  ethos, 
I  would  nonetheless  like  to  reply  to  his 
letter  which  appeared  in  the  July  1990 
edition  of  DDf.  Mr.  Bauer  makes  a  con¬ 
vincing  case  that  an  inventor  or  inves¬ 
tor  should  be  encouraged  to  advance 
the  cause  of  technological  innovation. 
Whether  patent  laws  do  this  or  not  is 
not  clear. 

It  appears  that  patent  laws  can  bene¬ 
fit  large,  well-financed  organizations, 
but  this  benefit  comes  more  from  the 
ability  to  defend  themselves  in  court 
than  from  any  innate  protection  afforded 
by  the  laws  themselves.  Many  innova¬ 
tions  of  the  twentieth  century  (button- 
release  socket  wrenches,  intermittent- 
control  windshield  wipers,  FM  radio, 
television,  to  name  only  a  few)  have 
been  appropriated  from  their  original 
inventors  and  exploited  by  large  or¬ 
ganizations.  And,  ironically,  a  signifi¬ 
cant  part  of  the  success  story  of  Ameri¬ 
can  industry  in  the  late  1800s-early- 
1900s  and  beyond  is  the  story  of  indus¬ 
trial  espionage  and  the  infringement 
of  some  key  European  patents. 

Whether  or  not  investors  and  inven¬ 
tors  benefit  in  the  long  run  from  patent 
laws,  it  seems  to  me  that  a  larger  ques¬ 
tion  when  the  laws  are  applied  to  soft¬ 
ware  is  whether  the  craft  or  society 
itself  benefits.  As  Mr.  Bauer  points  out, 
changes  in  software  come  so  rapidly 
that  patents  may  outlive  their  useful¬ 
ness  well  before  they  expire.  If  this  is 
so,  how  can  developers  ever  hope  to 
build  on  existing  software  to  further 
the  state  of  the  art? 

I  think  patenting  will  tend  to  further 
fragment  the  development  of  software, 
adding  unnecessary  costs  and  delaying 
true  innovation.  Isaac  Newton  said  “I 
have  stood  on  the  shoulders  of  giants,” 
and  by  this  he  meant:  No  programmer 
is  ever  going  to  get  anywhere  if  he  has 
to  go  back  to  square  one  every  time 
he  boots  his  system. 

Phil  Wettersten 

Chillicothe,  Ohio 

We  welcome  your  comments  (and  sug¬ 
gestions).  Mail  your  letters  (include  disk 
if  your  letter  is  lengthy  or  contains  code) 
to  DDJ,  501  Galveston  Dr.,  Redwood 
City,  CA  94063,  or  send  them  electroni¬ 
cally  to  CompuServe  76704,50  or  via 
MCI  Mail,  c/o  DDJ.  Please  include  your 
name,  city,  and  state.  We  reserve  the 
right  to  edit  letters. 


DDJ 


14 

794 


Dr.  Dobb’s fournal,  September  1990 


Making  the  Move  to 

Modula-2 


Modular  structure  is  important  for  multiprogrammer  projects 


J.V.  Auping  and  J.C.  Johnston 


Three  years  ago,  we  had  occasion  to  upgrade  a  group 
of  small  scientific  computers  used  for  laboratory 
data  acquisition.  We  chose  to  standardize  all  of  our 
new  software  efforts  and  use  Modula-2.  In  this  arti¬ 
cle,  we’ll  talk  about  why  we  chose  Modula-2  and 
about  the  benefits  and  drawbacks  of  the  language. 

As  support  programmers  for  a  materials  research  labora¬ 
tory,  we  are  involved  in  writing  application  programs  that 
perform  control  functions  and  acquire  data  from  special- 
purpose  experimental  furnaces.  There  are  about  a  dozen  such 
furnaces  for  controlled  heating  and  cooling  of  metals  and 
alloys  and  for  crystal  growth  activities.  Each  furnace  had  been 
initially  equipped  with  a  data  acquisition  and  control  system 
made  up  of  a  small  desktop  computer  that  was  programma¬ 
ble  in  Basic  and  an  IEEE-488-based  data  acquisition  unit. 
As  our  researchers  came  up  with  more  complex  experi¬ 
ments,  we  were  limited  by  the  speed  and  memory  capacity 
(32K  words  of  user  space)  of  the  desktop  computers. 

In  addition,  as  the  researchers  became  familiar  with  the 
capabilities  of  the  PC  systems  appearing  in  their  offices,  they 
grew  dissatisfied  with  the  small  display  and  slow  tape  drives 
of  the  data  acquisition  computers.  The  decision  was  made 
to  replace  the  old  computers  with  faster,  larger,  PC-type 
systems.  We  had  been  quite  satisfied  with  the  capabilities 
of  the  data  acquisition  units,  and  also  had  invested  sig¬ 
nificant  amounts  of  time  in  the  wiring  of  thermocouples  and 
other  transducers.  We  were  determined  to  keep  them  with 
whatever  new  systems  we  developed.  This  put  some  con¬ 
straints  on  our  choice  of  hardware. 


Judy  Auping  and  Chris  Johnston  work  in  the  Microgravity 
Materials  Science  Laboratory  at  NASA ’s  Lewis  Research  Cen¬ 
ter  in  Cleveland.  They  both  hold  Ph.D.s  in  chemistry  from 
Cleveland  State  University.  Chris  Johnston’s  book,  The  Mi¬ 
crocomputer  Builder’s  Bible,  was  published  by  Tab  Books 
in  1983 .  They  can  be  reached  at  2 1 6-433-50 16  and  216-433- 
5029,  respectively. 


After  a  survey  of  the  available  computers,  we  settled  on 
an  80286-based  AT-compatible  system  with  a  40-Mbyte  hard 
disk  and  EGA  display.  We  also  chose  an  IEEE-488  interface 
card  that  promised  code  to  support  most  of  the  popular 
programming  languages.  Since  we  had  been  dissatisfied 
with  the  cryptic  nature  of  even  our  own  most  carefully 
written  Basic  code,  we  were  pleased  to  have  the  chance  to 
move  to  a  more  satisfactory  programming  language.  This 
was  an  important  decision  for  us,  because  we  wanted  to 
standardize  on  one  language  throughout  the  lab.  As  the 
different  furnaces  have  many  functions  in  common,  we 
wanted  to  be  able  to  share  code. 

Looking  at  Languages 

The  first  language  we  considered  was  Pascal,  as  one  of  us 
had  had  considerable  experience  with  it  prior  to  this  project. 
After  trying  to  apply  Pascal  to  our  experiments,  we  decided 
we  liked  the  strong  typing  and  structured  design  of  the 
language,  but  were  concerned  that  it  would  be  unable  to 
support  a  joint  programming  effort.  We  had  been  intrigued 
by  literature1'2  that  described  Modula-2  as  a  language  de¬ 
signed  for  team  programming.  Its  similarity  to  Pascal  was 
convenient,  and  it  seemed  well-suited  to  joint  projects  that 
required  low-level  access  to  the  computer  hardware.  So, 
we  decided  to  test  a  Modula-2  development  system. 

We  were  particularly  interested  in  and  wanted  to  evaluate 
a  number  of  features  described  in  the  articles  on  Modula-2: 

•  The  modular  structure,  which  would  allow  two  or  more 
programmers  to  work  in  a  controlled  manner  and  permit 
code  interaction  without  unforeseen  side  effects. 

•  Transparent  access  to  the  low-level  facilities  of  the  ma¬ 
chine  without  disturbing  the  rest  of  the  program. 

•  Increase  in  program  reliability  because  of  built-in  type 
checking. 

•  The  idea  of  creating  independent  modules  that  can  be 
used  in  other  programs. 
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A  number  of  things  looked  as  if  they  would  be  real  (if  minor) 
annoyances: 

•  The  issue  of  case  sensitivity.  All  of  Modula-2’s  identifiers 
are  case  sensitive,  and  reserved  words  are  required  to  be 
uppercase. 

•  Modula-2's  inability  to  do  I/O  on  complex  types  (records 
and  arrays,  for  instance)  directly,  without  byte  counting. 

•  The  relative  scarcity  of  commercial  software  libraries  avail¬ 
able  for  Modula-2. 

After  installing  the  Modula-2  development  system  and 
writing  a  few  short  test  programs,  we  were  sufficiently 
encouraged  to  embark  on  a  fairly  major  “learning  project.” 
We  looked  around  for  something  that  would  be  a  good 
multiprogrammer  test  project  and  that  would  be  useful  to 
us  later  if  we  decided  to  standardize  on  Modula-2.  At  that 
time,  nearly  all  of  our  experiments  were  already  running 
on  the  smaller  computers,  generating  data  that  required 
plotting.  Our  researchers  had  also  begun  clamoring  for  the 
ability  to  view  their  data  graphically  while  an  experiment 
was  in  progress.  To  evaluate  Modula-2’s  ability  to  solve  our 
problems  we  decided  to  implement  a  library  of  screen  and 
plotter  graphing  routines  for  our  data  acquisition  and  con¬ 
trol  programs. 

Developing  Modula-2  Libraries 

The  first  step  in  developing  our  library  was  to  determine 
exactly  what  capabilities  it  would  provide.  We  were  pleased 
with  the  plotting  functions  available  in  the  Basic  ROMs  in 
our  small  computers,  and  we  decided  to  include  many  of 
these  functions  but  improve  on  the  calling  syntax.  This  gave 
us  a  base  set  of  “high-level”  procedures  that  would  have  to 
be  implemented.  These  would  be  the  only  procedures  in¬ 
voked  directly  by  an  applications  programmer  using  the 
library.  We  defined  a  number  of  other  functions  that  would 
be  needed  either  as  additions  to  the  base  set  or  as  lower- 
level  functions  required  to  implement  the  base  calls. 

Once  we  had  an  idea  of  what  we  had  to  write,  we  needed 
to  break  the  project  into  two  more  or  less’  equal  pieces. 
Based  on  our  examination  of  the  procedures  we  had  already 
identified,  the  project  seemed  to  divide  naturally  between 
the  low-level  hardware  manipulation  functions  and  the  higher- 
level  graphing  calls.  The  procedure  for  drawing  an  axis 
doesn’t  need  to  know  about  how  the  lines  are  drawn  or  that 
drawing  lines  on  the  display  and  the  plotter  are  handled 
differently.  On  the  other  hand,  the  line  drawing  procedure 
doesn’t  need  to  know  what  is  being  drawn.  Table  1  lists  the 
low-level  hardware  manipulation  and  high-level  plotting 
functions.  Although  it  may  look  like  an  unequal  division  of 
labor,  most  of  the  low-level  function  calls  contain  separate 
code  for  each  plotting  device  included  in  the  system;  so  the 
low-level  section  required  more  lines  of  code. 

In  Modula-2,  all  modules  except  for  the  main  program 
module  have  two  parts:  A  definition  module  that  formally 
defines  what  procedures  and  variables  are  available,  and 
an  implementation  module  where  the  executable  code  to 
perform  those  functions  resides.  The  definition  module  for 
the  high-level  plotting  functions,  ModPlot ,  is  shown  in  List¬ 
ing  One,  page  76,  and  the  module  for  the  low-level  func¬ 
tions  GDriver  is  shown  in  Listing  Two,  page  76.  We  also 
created  the  module  DataDefs  (Listing  Three,  page  76)  to 
hold  all  of  the  global  types.  By  defining  color  types,  device 
types,  and  so  forth,  we  are  able  to  use  statements  such  as 
SetBackgroundColorJBlue)  or  SetPlotDemce  (EGA)  rather  than 
a  cryptic  numerical  code.  The  price  we  pay  for  this  in¬ 
creased  program  readability  is  that  the  relevant  types  must 
be  explicitly  imported  from  DataDefs  into  every  other  mod- 
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ule  using  those  types.  Note  that  DataDefs  is  an  example  of  a 
Modula-2  definition  module  with  an  empty  implementation 
module.  It  allots  us  to  define  a  number  of  types  and  variables 
to  be  imported  whenever  necessary  but  contains  no  execut¬ 
able  code;  its  only  function  is  to  define  the  variables. 

In  our  case,  determining  which  of  us  would  do  what  part 
of  the  project  was  easy.  The  division  into  high-level  (user- 
related)  and  low-level  (hardware-related)  functions  matched 
our  interests  fairly  well.  But  we  still  had  to  decide  how  to 
pass  information  from  one  part  to  the  other  and  how  to 
handle  range  checking  and  error  reporting.  Since  we  al¬ 
ready  had  the  DataDefs  module  for  defining  global  types, 
we  decided  to  use  it  to  also  hold  a  set  of  global  variables 
that  would  contain  the  current  settings  for  the  graphics 
parameters.  This  would  reduce  the  number  of  formal  argu¬ 
ments  needed  to  pass  information.  We  decided  to  do  all  of 
the  checking  for  the  validity  of  data  in  the  high-level  proce¬ 
dures.  The  procedures  in  GDriver  trust  that  they  are  being 
passed  legal  pixel  coordinates  by  the  code  that  calls  them. 

Part  of  the  idea  behind  Modula-2  is  that  it  allows  program- 


Low-level  Hardware  Manipulation  Functions 

Determine  what  graphics  devices  are  available 
Move  the  active  position  to  the  specified  device  coordinates 
Draw  from  the  active  position  to  the  specified  device  coordinates 
Draw  a  label  string 

Clear  the  video  screen  and  set  to  text,  graphics,  or  menu  (no 
cursor)  mode 


High-level  Plotting  Functions 

Initialize  the  graphics  functions 

Choose  a  plotting  device  for  subsequent  output 

Set  plotting  boundaries 

Set  boundaries  for  a  scaled  area 

Set  the  scale  for  the  scaled  area 

Set  the  type  of  plotting  units 

Set  the  size  of  characters  for  subsequent  labels 

Set  the  angle  for  subsequent  labels 

Set  the  line  type  for  subsequent  draw  commands 

Set  the  pen  color 

Set  the  background  color 

Set  the  label  orientation  relative  to  the  active  position 
Set  the  number  of  digits  to  the  right  of  the  decimal  point 
Return  the  ratio  of  the  physical  dimensions  of  the  plotting  area 
of  the  current  device 

Set  the  character  font  to  be  used  in  subsequent  labels 

Draw  a  line  from  the  active  position  to  the  specified  coordinates 

Move  to  the  specified  coordinates 

Do  an  incremental  draw  from  the  active  position 

Do  an  incremental  move  from  the  active  position 

Draw  an  X-axis  with  tic  marks 

Draw  a  Y-axis  with  tic  marks 

Draw  a  set  of  X-Y  axes  with  tic  marks 

Draw  an  X-Y  grid 

Draw  a  label  at  the  active  position  according  to  the  current 
character  size,  label  orientation,  and  label  angle  settings 
Draw  a  set  of  X-Y  axes  with  tic  marks,  labelled  according  to  the 
current  character  size  and  fixed  decimal  settings 
Draw  an  X-Y  grid,  labelled  according  to  the  current  character 
size  and  fixed  decimal  settings 
Draw  a  box  around  the  current  plotting  area 
Draw  a  symbol  of  specified  size  and  type  at  the  active  position 
Return  the  coordinates  of  the  active  position 
Clear  the  screen  and  set  the  mode 


Table  1:  Library  functions 


mers  to  define  an  interface  between  modules  that  is  stable 
and  isolates  one  module  from  another.  In  theory  you  should 
think  deep  thoughts  about  the  interface  (the  definition 
module),  define  it,  and  never  change  it  again.  In  our  experi¬ 
ence,  reality  was  only  a  little  different.  Both  the  high-level 
ModPlot  definition  module  and  the  low-level  GDriver  defi¬ 
nition  module  were  remarkably  stable  once  we  had  thought 
about  them  for  a  while.  GDriver  did  require  one  addition, 
the  Cleanup  procedure,  unforeseen  in  the  original  design. 

Modula-2  has  delivered 
on  its  promise 
to  he  very  suitable 
for  multiprogrammer  projects 

(The  cleanup  procedure  was  needed  because  of  the  way 
one  of  the  compiler-supplied  library  modules  managed  the 
interrupt  system.  Another  compiler  might  handle  things 
differently,  making  the  additional  procedure  unnecessary.) 
We  made  a  few  minor  changes  to  the  types  of  the  arguments 
in  some  of  the  ModPlot  procedure  calls.  The  DataDefs 
module,  however,  an  important  behind-the-scenes  part  of 
the  interface,  was  a  lot  more  fluid. 

The  actual  process  of  implementing  our  library  was  straight¬ 
forward.  We  spent  two  weeks  defining  and  partitioning  the 
functions.  We  then  went  our  separate  ways  to  do  the  coding 
and  some  independent  testing  of  the  sections.  Obviously, 
as  in  any  hierarchically  divided  project,  it  was  more  satis¬ 
fying  to  test  the  low-level  modules.  Testing  of  the  high-level 
ModPlot  functions  was  limited  to  producing  textual  output 
such  as  “Call  to  DrawAbs  made  with  the  following  argu¬ 
ments  ...  ”,  whereas  the  testing  of  the  low-level  procedures 
generated  pretty  pictures  right  from  the  start.  On  the  other 
hand,  when  the  low-level  modules  malfunctioned  they  were 
harder  to  debug,  as  the  errors  usually  were  not  obvious  and 
sometimes  were  catastrophic.  After  about  a  month  of  sepa¬ 
rate  coding  and  testing,  we  were  able  to  link  the  two 
sections  together  in  a  test  program.  We  spent  a  relatively 
short  time  using  test  programs  to  debug  the  library.  The 
whole  project  took  about  two  months  (four  man  months) 
from  start  to  finish. 

Listing  Four,  page  77,  and  Figure  1  show  the  source  code 
and  output  of  a  program,  Example ,  which  demonstrates  the 
use  of  the  ModPlot  library.  Note  that  Example  imports  types 
from  DataDefs  that  do  not  explicitly  appear  in  variable 
declarations,  but  do  have  instances  appearing  in  the  code. 
For  example,  SizeType  must  be  imported  because  Small  is 
used  in  the  statement  SetCharSize(Small). 

Team  Programming  and  Modula-2 

Of  course,  the  big  question  is,  how  did  the  use  of  Modula-2 
affect  the  process  of  writing  a  team-programming  project? 
Our  feeling  is  that  the  modular  nature  of  the  language 
streamlined  the  process  of  writing  and  testing  each  function. 
Granted,  this  could  be  done  with  any  “good”  structured 
language,  but  the  formal,  definition  module/implementation 
module  structure  made  it  particularly  easy  to  isolate  and 
group  similar  procedures. 

Comparison  with  our  past  experience  shows  that  the  strict 
typing  of  Pascal  or  Modula-2  eliminates  the  source  of  a  lot 
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of  errors  that  creep  into  Basic  or  Fortran  programs.  In 
comparing  Pascal  to  Modula-2,  it  is  more  difficult  to  see  a 
great  difference.  The  tendency  (in  well-written  programs, 
at  least)  for  Modula-2  programs  to  be  broken  into  many 
small  parts  makes  the  isolation  and  elimination  of  errors 
easier  than  in  Pascal  and  makes  Modula-2  code  more  reli¬ 
able  from  the  outset  than  Pascal  or  C  code.  We  have,  of 
course,  found  occasional  bugs  in  our  library  during  the  past 
year  and  a  half.  Almost  all  of  these,  however,  have  been  due 
either  to  errors  in  logic  or  to  timing  problems  caused  by 
moving  to  machines  with  different  clock  speeds. 

The  reusability  of  modules  is  an  important  part  of  the 
rationale  behind  Modula-2.  Once  you  write  and  debug  a 
module  you  can  put  it  in  your  library  and  use  it  whenever 
you  need  that  function  again.  A  problem  arises  in  modules 
that  import  information  from  other  modules.  GDriver  im¬ 
ports  a  module  called  HdwDefs.  That  means  that  GDriver 
can’t  be  used  in  another  program  unless  HdwDefs  is  avail¬ 
able  too.  We  have  found  that  the  most  easily  reusable 
modules  are  often  the  lowest-level  ones  that  perform  one 
simple,  clearly  focused  function.  Reusability  of  more  com¬ 
plicated  modules  must  be  planned  for  in  the  original  design 
of  the  code  because  you  need  to  minimize  the  number  of 
dependencies. 

On  the  other  hand,  GDriver  is  a  general-purpose  drawing 
and  labeling  module  available  for  any  program  needing  it. 
This  approach  is  preferable  to  writing  the  same  functions 


Figure  1:  Sample  output  from  our  data-plotting  program 


again  the  n<  ct  time  they  are  needed.  In  a  broader  sense,  this 
was  the  pu  >ose  of  the  entire  plotting  package.  It  provides 
a  simple  int  .rface  for  a  programmer  who  needs  to  add  some 
simple  graphing  functions  to  a  program.  As  a  byproduct  of 
its  creation  we  now  have  a  number  of  modules  that  we  can 
use  anytime. 

The  issue  of  transparent  access  to  low-level  facilities  was 
also  important  to  us.  Some  of  the  functions  that  we  require 
in  our  experiments  involve  the  use  of  boards  that  plug  into 
the  AT  bus.  Many  of  these  require  special  software  to  access 
their  registers  and  onboard  memory.  Modula-2  has  enabled 
us  to  do  that  quite  successfully.  Some  of  these  devices  use 
interface  code  that  is  wholly  or  partially  written  in  assembly 
language  but  is  called  from  a  Modula  program  as  if  it  were 
any  other  module.  Modula-2  can  access  individual  memory 
locations  and  I/O  ports,  allowing  the  programmer  to  do 
much  of  this  manipulation  without  resorting  to  assembler. 
It  is,  however,  a  good  idea  to  isolate  any  such  extremely 
machine-dependent  code  in  its  own  module. 

Error  handling  has  been  and  continues  to  be  more  of  a 
problem.  If  an  external  error  occurs  deep  in  a  nested  set  of 
procedures,  there  is  no  easy  way  of  invoking  some  error¬ 
handling  procedure  unless  an  error  flag  is  tested  each  step 
of  the  way  back.  For  example,  if  the  plotter  goes  offline 
during  a  plot  (someone  inadvertently  turns  it  off  or  the 
paper-load  lever  is  moved),  the  transmission  code  deep  in 
the  low-level  routines  will  eventually  time  out,  generating  a 
serial  error.  The  error  is  posted  in  a  variable  in  DataDefs 


FOURIER  SERIES  APPROXIMATION  TO  A  SAWTOOTH  WAVE 
Y  =  2  (sin(x)  -  sin  (2x)/2  +  sin  (3x)/3  -  sin  (4x)/4  +  ...} 
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along  with  a  string  explaining  the  problem.  There  is  no  way 
to  guarantee  that  the  calling  program  will  notice  this  condi¬ 
tion  unless  the  error  flag  is  checked  after  every  call  to 
GDriver.  This  means  that  every  call  to  DrawAbs,  MoveAbs, 
or  DrawString  in  GDriver  has  to  be  checked,  and  the  rest 
of  the  calling  routine  short-circuited,  returning  an  error 
indication  to  the  external  calling  program.  This  issue  has 
not  been  resolved  to  our  satisfaction.  Our  working  solution 
has  been  to  have  the  low-level  code  that  discovers  the  error 
post  a  message  to  a  reserved  area  on  the  display  screen 
explaining  the  problem  and  giving  the  user  a  chance  to  fix  it. 

The  Upside  and  Downside  of  Modula-2 

One  unanticipated  benefit  of  Modula-2  has  been  that  it 
allows  us  to  maintain  our  own  coding  styles  and  habits  and 
a  sense  of  ownership  of  our  own  code  without  impeding 
the  collaboration  necessary  to  make  a  project  like  this  work. 
(As  you  may  have  gathered,  we  have  not  progressed  to  the 
point  of  “egoless”  programming.  We  are,  at  best,  pursuing 
“ego-reduced”  programming.)  For  example,  one  of  us  likes 
the  indented  structure: 

IF  SomeCondition  THEN 

DoThis; 

ThenThat; 

ELSE 

DoSomethingElse ; 

END  (*  if*); 

while  the  other  prefers: 

IF  SomeCondition 

THEN 

DoThis; 

ThenThat; 

ELSE  DoSomethingElse; 

END  (*  if*); 

The  fact  that  we  can  each  write  and  maintain  our  own  code 
in  separate  modules  means  that  neither  has  to  put  up  with 
the  other’s  unspeakably  ugly  IF-THEN  style. 

We  expected  that  the  language’s  case  sensitivity  would 
turn  out  to  be  an  annoyance.  Instead,  we  have  found  that 
once  you  are  used  to  the  rules  it  isn’t  a  burden  at  all, 
especially  if  you  use  a  syntax-assisted  editor.  In  fact,  we 
have  both  grown  to  like  the  fact  that  reserved  words  are  all 
in  caps.  Using  normal  capitalization  for  variable  and  proce¬ 
dure  names  allows  you  to  quickly  pick  them  out  from  the 
reserved  words  in  the  code.  Case  sensitivity  forces  you  to 
clean  up  the  variable  names  so  they  all  match  exactly.  In 
Pascal,  case  insensitivity  allows  you  to  put  off  cleaning  up 
the  code  to  make  it  prettier.  Modula-2’s  case  sensitivity  does 
have  a  drawback  in  that  it  makes  some  new  errors  possible. 
It  is  legal  to  declare  a  local  variable  with  the  same  name  as 
a  global  variable.  No  changes  can  be  made  to  the  global 
variable  inside  the  procedure  where  the  local  variable  is 
declared,  protecting  the  global  from  unforeseen  side  effects. 
However,  if  you  miscapitalize  the  declaration  of  the  local 
you  can  inadvertently  change  the  global.  This  situation 
actually  occurred  in  some  code  a  student  wrote  for  us,  and 
it  took  quite  a  while  for  us  to  help  him  locate  the  problem. 

A  real  annoyance  with  Modula-2  is  that  it  has  no  equiva¬ 
lent  for  Pascal’s  get  and  put  statements,  which  allow  a 
program  to  automatically  handle  I/O  on  complex  data  struc¬ 
tures  such  as  records.  In  order  to  write  a  record  variable  in 
Modula-2,  a  program  has  to  calculate  the  size  of  the  record 
and  then  write  that  number  of  bytes.  Presumably,  this  is  in 
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keeping  with  the  philosophy  that  all  I/O  in  Modula-2  would 
be  through  a  procedure  specific  to  the  data  type  involved. 
It  would  be  nice  if  there  were  a  more  automatic  way  to  do 
this.  The  random  access  I/O  of  data  to/from  disk  files  has 
the  same  kind  of  limitation,  also  probably  for  the  same 
reason.  It  seems  that  the  compiler  could  do  this  for  you. 

Another  drawback  of  using  Modula-2  becomes  evident  if 
you  are  writing  a  short  program  from  which  you  want  quick 
results.  There  is  some  significant  overhead  in  typing  in  the 
numerous  FROM  SomeLibrary  IMPORT SomeProcedure;  state¬ 
ments  necessary  to  do  any  useful  task.  For  a  while,  we  both 
returned  to  Turbo  Pascal  when  we  had  to  do  something 
quickly.  Eventually,  as  we  became  more  involved  with 
Modula-2,  we  evolved  template  main  program  modules  that 
contain  the  imports  (such  as  WriteLn,  WriteString,  Assign, 
Concat,  and  so  forth)  that  we  typically  use  in  our  work. 
However,  there  are  still  the  frustrating  times  when  you 
discover  at  compile  time  that  you’ve  forgotten  to  import  one 
or  more  of  the  procedures  you  need. 

The  scarcity  of  commercially  available  software  libraries 
for  Modula-2  was  not  an  insurmountable  problem  for  us. 
We  invested  about  six  months  in  writing  our  own  utility 
routines,  including  both  a  program  to  produce  straightfor¬ 
ward  scientific  plots  and  a  useful  set  of  generic  field  editing 
routines.  We  have  also  successfully  used  packages  designed 
to  be  called  from  other  languages,  with  more  or  less  trouble 
depending  on  what  memory  model  the  library  uses.  One 
image-processing  library  written  to  be  called  from  Microsoft 
Pascal  required  an  assembly  language  interface  module  to 
rearrange  the  stack  so  that  the  arguments  were  passed 
correctly.3 

Conclusions 

After  extensive  use,  we  have  both  become  rather  fanatical 
about  Modula-2  and  have  standardized  on  it  for  all  new 
development  in  the  lab.  We  have  hired  undergraduate  and 
graduate  students  for  summer  jobs  who  were  able  to  learn 
the  language  quickly  and  produce  modules  for  us  in  reason¬ 
ably  short  periods  of  time.  We  have  certainly  met  resistance 
from  programmers  unfamiliar  with  Modula-2,  but  we  have 
adhered  to  our  decision  to  maintain  a  single  language. 

In  short,  we  feel  that  Modula-2  has  delivered  on  its 
promise  to  be  very  suitable  for  multiprogrammer  projects. 
Its  modular  structure  has  allowed  us  to  write  efficient, 
reusable  code  that  can  be  used  in  a  variety  of  applications. 
At  this  point,  we’re  looking  forward  to  more  support,  both 
commercial  and  user  group. 
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Porting  Fortran 

Programs  from  Minis  to  PCs 

A  method  to  prevent  software  madness 


John  L.  Bradberry 


Improvements  in  personal  computer 
hardware,  operating  systems,  and 
compilers  have  placed  PCs  in  a 
competitive  role  in  applications  tra¬ 
ditionally  dominated  by  mainframe 
computers.  Developers  of  scientific  ap¬ 
plications  such  as  radar  and  antenna 
software  have  traditionally  defined  “state 
of  the  art”  in  the  digital  world  at  all 
levels  of  electronic  instrumentation.  His¬ 
torically,  PCs  were  limited  in  clock 
speed,  extended  precision  computing 
power,  and  compiler  sophistication.  As 
a  result,  the  scientific  community  re¬ 
stricted  PC  uses  to  intelligent  terminals, 
word  processors,  and  spreadsheets.  In 
only  the  past  few  years,  these  limita¬ 
tions  have  almost  been  completely  re¬ 
solved  and  PCs  are  rapidly  becoming 
viable  options  in  all  levels  of  problem 
solving. 

This  article  addresses  issues  related 
to  porting  large-scale  software  from  main¬ 
frames  to  the  PC.  Issues  related  to  com¬ 
pilers,  programming  techniques,  ANSI 
standards,  and  some  PC  software  re¬ 
sources  will  also  be  examined.  For  the 
purposes  of  example,  the  structure  of 
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can  be  reached  at  2359  Windy  Hill 
Road,  Suite  201-J,  Marietta,  Georgia 
30067. 


Microplots,  a  Fortran-based  graphics 
system,  is  used  to  illustrate  a  structured 
programming  design  approach.  Micro¬ 
plots  was  ported  successfully  from  a 
minicomputer  to  the  PC  using  Micro¬ 
soft  Fortran  5.0. 

Minicomputer  Operating  Systems  Versus 
PC  Development  Environments 

For  many  years,  the  most  popular  mini¬ 
computer  operating  systems  and  com¬ 
pilers  were  products  offered  by  the 
hardware  vendors.  VMS  from  Digital 
Equipment  Corp.  is  a  good  example. 


VMS  maintains  widespread  support  as 
a  good  solution  to  problems  involving 
huge  arrays  for  32-  to  64-bit  number 
crunching  problems.  Although  the  real¬ 
time  responsiveness  of  VMS  has  often 
been  questioned,  DEC  made  many  im¬ 
provements  to  Fortran  77,  and  its  cus¬ 
tomers  responded  with  millions  of  lines 
of  code  dedicated  to  VAX  Extended 
Fortran.  Much  of  this  resulted  in  code 
with  virtually  no  chance  of  portability. 

Another  example  is  RTUX  from  Hew¬ 
lett  Packard.  Over  the  last  two  years, 
HP  has  adopted  a  modified  version  of 
real-time  Unix  (RTUX).  As  a  Unix-based 
operating  system,  RTUX  offers  virtual 
memory  management  and  additional 
connectivity  options.  However,  Fortran 
development  is  at  best  secondary  in 
most  Unix  environments. 

With  DOS-based  PC  architectures, 
third-party  clone  vendors  created  a  pot¬ 
pourri  of  hardware  and  software  to 
steadily  increase  the  PC’s  feasibility  as 
a  scientific  problem  solver.  The  single¬ 
task  nature  of  DOS  not  withstanding, 
the  increase  in  clock  speed  and  devel¬ 
opment  support  software  proved  to  be 
irresistible  to  the  scientific  community. 
However,  full-featured  minicomputer 
development  environments  still  offer 
features  not  easily  addressed  under  PC 
DOS.  Some  of  these  features  include: 

•  Virtual  memory  access  (>640K)  trans¬ 
parent  to  the  process. 

•  Full  featured  system  services  librar- 
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(continued  from  page  26) 
ies  such  as  spawning  child  processes 
from  within  a  program  shell,  direct 
keyboard/memory  operations  with 
or  without  wait,  and  I/O  such  as 
IEEE  and  8-  to  1 6-bit  Digital  Control 
and  DMA  (Direct  Memory  Access) 
Channels. 

•  Symbolic  debuggers  extended  to 
source  level  with  access  to  user  and 
system  library  modules. 

•  User-controlled  global  variable  space 
with  inter-process  communication  ca¬ 
pability  (memory  based!). 

It  should  be  noted  that  some  of  these 
issues  have  been  addressed  in  OS/2 
and  to  a  limited  extent  with  386/486 
development  utilities  (DesqView  for  ex¬ 
ample).  However,  the  vast  majority  of 
DOS  applications  and  the  scope  of  this 
article  is  limited  to  DOS  3  x  and  4.x 
versions. 

Converting  Software  from  Minicomputers 
to  PC  Platforms 

In  an  ideal  world,  application  portabil¬ 
ity  from  one  machine  to  another  would 
simply  involve  moving  the  source  code 
from  machine  to  machine,  then  recom¬ 
piling  and  linking  all  program  mod¬ 
ules.  Unfortunately,  only  a  small  num¬ 
ber  of  relatively  simple  programs  ever 


top-down  programming  approach  is  usu¬ 
ally  complimented  with  a  “bottom  up” 
implementation.  The  resultant  layering 
of  software  will  ultimately  result  in  the 
form  of  an  inverted  pyramid,  as  illus¬ 
trated  in  the  Figure  1 . 

Lower  layers  represent  the  device 
and  CPU-specific  implementations  of 
key  functions.  At  the  device  driver  level 
(layer  2  in  the  figure)  other  third-party 
vendor  software  can  be  merged  for 
completeness.  The  following  features 
of  this  structure  readily  support  efforts 
in  the  port  process: 


Figure  1:  Topdown  software  design 
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make  this  a  reality.  The  main  reasons 
for  this  phenomenon  are  readily  appar¬ 
ent:  CPU  and  compiler-dependent  code 
grows  in  direct  proportion  to  the  size 
and  complexity  of  an  application.  In¬ 
experienced  programmers  and  program 
managers  are  often  unaware  or  uncon¬ 
cerned  about  portability.  In  addition, 

A  structured  design 
approach  can  he 
essential  as  preventative 
maintenance  for 
software  support 

issues  of  portability  sometimes  surface 
after  hardware  or  software  obsolescence 
becomes  imminent.  (See  the  accompa¬ 
nying  text  box  for  some  Do ’s  and  Don  ’ts 
of  developing  portable  software.) 

In  the  rest  of  this  article,  I’ll  discuss 
porting  a  large  graphics  application  from 
a  mainframe  computer  architecture  to 
a  PC.  The  application,  called  “Micro¬ 
plots,”  is  a  collection  of  scientific  plot¬ 
ting  routines  for  two-dimensional  and 


•  As  the  tree  is  implemented,  the  top 
two  levels  maintain  a  fairly  generic 
Fortran  77  form.  All  code  at  these 
levels  exists  in  a  form  virtually  appli¬ 
cation  and  CPU  independent. 

•  Each  layer  provides  virtually  unlim¬ 
ited  expansion  of  capability  by  the 
easy  addition  of  plot  algorithms  or 
graphics  devices  with  little  impact 
on  existing  code. 

•  As  suggested  by  the  pyramid  struc¬ 
ture,  the  software  most  affected  by 
changes  in  CPU  or  graphics  devices 
represents  the  smallest  amounts  of 


Top  Level:  Microplots  Graphics  Application  Software 

Contour  Plot  -  Polar  Plot  -  Linear  Plot ...  Other  Plots 

Layer  4:  Graphics  Macros 

Rect  Grid  -  Circle  -  Arc  -  Frame  -  Box  -  Label  ...  Other  Macros 

Layer  3:  Graphics  Primitives 

Move  -  Draw  -  Ginit  -  Scale  -  Pen  ...  Other  Primitives 
Layer  2:  Graphics  Device  Drivers 
HPGL  -  IBM  PC  -  TEKTRONIX  -  DEC  VTxx  ...  Other  Devices 
Layer  1:  Graphics  Device  Interface 

CRT  -  Disk  -  Digital  Plotter ...  Other  Devices 


three-dimensional  data  files.  The  Mi¬ 
croplots  routines  contain  over  11  algo¬ 
rithms  originally  designed  for  VAX  and 
other  minicomputers.  (For  a  demo  disk 
of  the  Microplots  system,  contact  the 
author  at  the  address  at  the  beginning 
of  this  article.) 

The  compiler  chosen  for  porting  Mi¬ 
croplots  to  the  PC  was  Microsoft’s  Ver¬ 
sion  5.0  of  Fortran  77.  It  was  chosen 
primarily  because: 

•  System  service  features  such  as  com¬ 
mand  line  access,  child  process  spawn¬ 
ing,  and  programmable  operating  sys¬ 
tem  functions  were  desired. 

•  Mixed  language  calls  were  necessary 
for  unsupported  system  services  utili¬ 
ties  such  as  keyboard  peeks  (read_with- 
out_wait).  Microsoft  supplies  a  full 
compliment  of  mixed  language  sup¬ 
port  for  C,  Assembler,  and  Basic. 

•  Fortran  calls  to  lower-level  graphics 
primitives  were  essential  for  this  ap¬ 
plication. 

•  ANSI  Fortran  77  extension  support. 

Designing  for  Portability 

A  structured  design  approach  can  be 
essential  as  preventative  maintenance 
for  software  support.  The  term  “top- 
down”  software  design  has  become  a 
cliche  over  the  years.  In  reality,  the 


code  in  the  entire  system.  Of  the 
approximately  100K  lines  of  source 
code  in  Microplots,  less  than  three 
percent  (the  bottom  of  the  pyramid) 
is  device  or  CPU  dependent. 

Source  Code  Port  Example 

The  plot  program  that  generates  the 
globe  shown  in  Figure  2  is  shown  in 
Listing  One  (page  80).  Prior  to  the  port, 
the  globe  program  contained  many  poor 
programming  practices  that  made  the 
port  process  cumbersome.  For  exam¬ 
ple,  most  variables  were  not  typed  (IM- 


Figure  2:  Sample  output  from  the 
globe  program 
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PLICIT  NONE  eliminates  guessing  and 
mistakes  automatically  when  porting 
code).  Also,  program  loops  and  struc¬ 
tures  were  not  indented  (non-indented 
loops  and  logic  clauses  make  code  more 
difficult  to  interpret).  Added  to  this, 
extended  use  was  made  of  non-de- 
scriptive  variable  names.  (Be  sure  to 
spell  out  variable  names  when  practi¬ 
cal  to  clarify  usage  and  meaning.) 

Hard  coded  logical  unit  specifics  were 


implemented  using  WRITE(6,*)  .  .  . 
which  makes  pointing  to  other  devices 
or  terminals  difficult  without  modify¬ 
ing  all  occurrences  of  output  and  enter 
statements.  (Global  device  specifics  sim¬ 
plified  this  process.)  Furthermore,  the 
program  used  improper  program  con¬ 
text  definition.  (You  should  use  consis¬ 
tent  program  and  subroutine  headers 
throughout  the  code  so  that  you  can 
tell  at  a  glance  where  one  module  ends 


The  DO’s  and  DON’Ts  of 
Writing  Portable  Fortran  Code 


When  faced  with  the  task  of  writing  portable  software,  you  may  wonder 
how  to  assess  the  quality  of  your  code  and  a  plan  of  attack.  Here  are  some 
Do’s  and  Don’ts  for  system  design  that  may  make  this  task  easier.  Although 
these  issues  are  concentrated  on  Fortran,  some  of  them  apply  to  any 
programming  language  or  operating  system. 

The  Do’s  The  Don’ts 


Define  every  variable  explicitly  in  each 
module.  Use  Integer*2  or  Real*4  for 
example.  Default  word  sizes  vary  from 
machine  to  machine. 

The  ANSI  extension  of  IMPLICIT 
NONE  should  be  universally  adopted. 
An  amazingly  large  number  of  debug 
nightmares  and  spelling  errors  can 
be  avoided  by  this  simple  statement 
included  at  the  beginning  of  each 
subroutine  and  function. 

Indent  all  loop  bodies  and  IF  clauses. 

Use  one  variable  per  line  and  a  trail¬ 
ing  descriptive  clause  if  possible.  The 
ANSI  comment  extension  allowing  the 
!  trailer  is  useful  for  this  purpose. 

Use  the  ANSI  extended  DO-END  DO 
and  DO  WHILE-END  DO  to  avoid 
line  numbers  and  continue  statements 
for  better  code  readability. 

Use  a  compiler  that  allows  the  MIL- 
standard  ANSI  extensions  to  Fortran 
77  if  possible. 

Use  batch  or  command  files  for  all 
phases  of  program  compiling  and  link¬ 
ing.  Command-line  parameters  are  usu¬ 
ally  only  remembered  by  the  person 
writing  the  module.  In  time,  even  the 
original  author  may  forget  which 
switches  to  use! 


Do  not  use  computed  GOTOs. 

Do  not  use  the  DIMENSION  state¬ 
ment  (explicit  typing  of  variables 
should  be  used). 

Do  not  use  non-integer  parameters 
in  do  loops  or  shared  tennination  state¬ 
ments. 

Do  not  use  alternate  RETURN  state¬ 
ments. 

Do  not  use  non-descriptive  variable 
names  such  as  XXX  and  YYY. 

Do  not  use  long  subprograms  per¬ 
forming  many  tasks  with  multiple  ex¬ 
its. 

Do  not  pass  constants  as  formal  pa¬ 
rameters  to  subroutines. 

Do  not  embed  compiler  or  machine- 
dependent  directives  in  source  code. 

—  J.L.B. 


and  the  next  one  begins.) 

Because  different  machines  use  dif¬ 
ferent  default  storage  functions,  you 
should  pass  constants  as  formal  pa¬ 
rameters  to  subroutines  or  functions. 
Integer  constants  passed  as  formal  pa¬ 
rameters  may  default  to  16  or  32  bits 
of  storage  depending  on  the  compiler 
or  machine. 

The  minicomputer  versions  of  the 
program  also  made  excessive  use  of 


Porting  to  another 
language  is  often  much 
easier  without  line 
numbers 


line  numbers.  When  designing  a  pro¬ 
gram  that  might  be  ported,  you  should 
eliminate  line  numbers  when  possible. 
Not  only  does  the  code  look  less  clut¬ 
tered,  but  porting  to  another  language 
is  often  much  easier  without  line  num¬ 
bers.  Finally,  DO  loops  that  shared  the 
same  CONTINUE  termination  statement 
and  multiple  entry  and  exit  points  made 
the  program  confusing. 

In  Listing  One,  most  of  the  problems 
have  been  removed  while  still  keeping 
the  code  100  percent  compatible  with 
Microsoft  Fortran.  Note,  however,  that 
almost  all  of  the  device-  and  compiler- 
specific  issues  are  more  isolated. 

While  this  program  is  complete,  it 
does  not  make  allowances  for  other 
graphics  devices.  Therefore,  the  last 
changes  made  before  adding  the  globe 
program  to  the  Microplots  system  re¬ 
quired  expanding  the  graphics  devices 
supported  to  include  devices  in  the 
structure  pyramid  of  Figure  1.  To  ac¬ 
complish  this  goal,  the  program  frag¬ 
ments  in  Listing  Two  (page  82)  illus¬ 
trate  the  further  layering  of  the  device 
initialization  process  to  include  other 
drivers. 

The  top  level  of  the  globe  program 
makes  a  call  to  initialize  the  current 
graphics  device.  As  in  the  case  of  all 
of  the  top-level  routines,  the  device 
specific  details  are  left  to  lower-level 
macros,  in  this  case  GINIT. 

In  the  fragment  of  level  3,  the  sub¬ 
routine  GINIT  makes  the  appropriate 
call  to  a  device  driver  pointed  to  by  the 
symbol  DEVICETYPE.  The  symbol  DE¬ 
VICETYPE  is  an  integer  constant  set  to 
a  number  representing  one  of  the  many 
devices  defined  by  the  system.  A  match 
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(continued  from  page  30) 
is  searched  for  in  the  body  of  the  IF- 
THEN  structure  and  the  specific  lower- 
level  driver  is  called. 

In  level  2,  the  CPU  and  compiler- 
specific  code  for  the  various  devices  is 
selected.  If  and  only  if  the  current  de¬ 
vice  happens  to  be  of  the  IBM  PC  vari¬ 
ety,  the  IBMPCINIT  driver  is  called. 
IBMPCINIT  contains  specific  references 
to  the  graphics  library  routines  sup¬ 
plied  with  Microsoft  5.0  Fortran.  If  and 
only  if  the  current  device  is  of  the  VAXsta- 
tion  variety,  the  VAXSTAINIT  driver  is 
called.  This  driver  contains  symbols  and 
library  references  known  only  to  the 
VAX  compiler  and  CPU. 

As  illustrated  by  this  test  case,  the 
code  least  portable  is  isolated  to  “well- 
defined”  driver  modules  at  the  lowest 
levels  of  the  graphics  library.  As  a  re¬ 
sult,  the  graphics  routines  can  be  ported 
to  virtually  any  CPU  with  minimal  ef¬ 
fort.  In  addition,  an  unlimited  number 
of  additional  graphics  devices  and  plot¬ 
ting  algorithms  can  be  added  to  the 
Microplots  system. 

This  approach  is  not  without  some 
minor  compromise  in  performance  and 
flexibility  in  a  few  areas.  However,  when 
faced  with  the  options  of  porting  code 
riddled  with  CPU  and  compiler-spe¬ 
cific  options  or  changing  a  few  low- 
level  drivers,  the  compromises  can  save 
many  man  months  of  coding  and  de¬ 
bug  efforts. 

It  is  interesting  to  note  here  that  the 
top-down  approach  used  for  the  graph¬ 
ics  design  can  also  be  used  in  other 
scientific  application  areas  such  as  file, 
signal  processing,  and  I/O  libraries. 

Future  Considerations  for  PC  Fortran  77 
Development 

Efforts  of  most  Fortran  suppliers  have 
made  porting  large-scale  programs  to 
the  PC  quite  practical.  However,  For¬ 
tran’s  use  on  PCs  for  development  of 
new  software  may  continue  to  be 
phased  out  in  the  future.  Until  more 
system  services  and  features  are  added 
to  the  language  and  supported  (will 
Fortran  8x  ever  be  released?),  mixed- 
language  calls  to  Assembler  or  C  will 
continue  to  be  a  necessary  evil.  As  C 
becomes  more  object  oriented  and  For¬ 
tran  standards  continue  to  stagnate,  the 
notion  of  using  Fortran  for  reasons  other 
than  performing  complex  math  func¬ 
tions  may  prove  impossible  to  defend 
in  the  future. 

DDJ 
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Persistent  Objects  in 

Turbo  Pascal 

Create  a  storable  object  type  to  share  objects 
between  applications 


Scott  Robert  Ladd 


There  are  four  fundamental  fea¬ 
tures  of  any  true  object-oriented 
programming  language:  data  ab¬ 
straction,  encapsulation,  inheri¬ 
tance,  and  polymorphism.  These 
are  the  core  concepts  necessary  for  object- 
oriented  programming.  However,  they 
aren’t  the  only  concepts  that  are  useful 
to  the  object-oriented  programmer. 

With  most  programming  languages, 
objects  are  created,  manipulated,  and 
destroyed  within  the  context  of  a  sin¬ 
gle  program.  Each  program  is  a  com¬ 
munity  of  objects  that  do  not  commu¬ 
nicate  with  other  communities  of  ob¬ 
jects.  Put  yourself  in  the  place  of  an 
object.  Think  of  inter-object  communi¬ 
cation  as  a  network  of  roads  and  each 
program  as  a  city.  You  can  go  any¬ 
where  inside  your  own  city,  but  there 
are  no  roads  leading  to  other  cities. 
This  is  frustrating,  because  it  limits  the 
ability  of  different  programs  within  a 
system  to  share  objects. 

Supporting  Persistence 

Turbo  Pascal,  C++,  and  Smalltalk  do 
not  directly  support  the  saving  of  ob¬ 
jects  from  one  invocation  of  a  program 
to  another.  This  is  like  building  a  car 
every  morning,  driving  it  to  work,  and 
then  having  it  disintegrate  when  you 
get  back  home  at  night.  Every  time  you 
commute  to  work,  you  need  to  build  a 


Scott  is  a  free-lance  ivriter;  he  has  more 
than  15  years  of  experience  in  a  vari¬ 
ety  of  programming  languages.  Scott 
can  be  reached  at  705  W.  Virginia, 
Gunnison,  CO  81230. 


new  car.  Similarly,  whenever  you  cre¬ 
ate  an  object  in  a  program,  it  exists 
only  until  the  program’s  work  is  done. 
Every  time  the  program  starts,  it  has  to 
begin  by  building  new  objects. 

Bertrand  Meyer  incorporated  the  con¬ 
cept  of  “persistent  objects”  into  his  Eif¬ 
fel  programming  language.  A  persis¬ 
tent  object  can  be  stored  external  to  a 
program,  usually  in  a  file.  More  than 
one  program  can  share  the  same  per¬ 
sistent  object,  and  a  program  can  save 
its  objects  for  future  executions. 

Eiffel  implements  persistent  objects 
via  a  special  base  class  called  STOR¬ 
ABLE.  Objects  of  a  class  derived  from 


STORABLE  have  store  and  retrieve  meth¬ 
ods.  When  an  object  is  stored,  its  entire 
data  structure  is  written  to  a  specified 
file.  Later,  that  entire  structure  can  be 
loaded  into  an  object  of  the  same  class. 

Does  having  built-in  support  for  per¬ 
sistent  objects  make  Eiffel  a  superior 
object-oriented  programming  language? 
In  one  sense,  the  answer  is  yes:  Any¬ 
thing  a  programming  language  can  pro¬ 
vide  for  you  is  a  definite  advantage  over 
having  to  develop  a  facility  on  your 
own.  However,  persistence  can  be  ac¬ 
complished  in  other  programming  lan¬ 
guages  with  a  minimal  amount  of  work 
and  the  knowledge  of  object  formats. 

Persistence  with  Turbo  Pascal 

The  Turbo  Pascal  object  implementa¬ 
tion  is  relatively  simple  when  compared 
to  Smalltalk  and  C++.  Listing  One  (page 
84)  shows  an  example  of  a  simple  Turbo 
Pascal  class  hierarchy.  Shape  is  an  ab¬ 
stract  base  class,  which  defines  the  com¬ 
mon  characteristics  of  all  Shape  classes. 
Derived  from  Shape  are  two  classes, 
Box  and  Ring.  Box  defines  a  rectan¬ 
gular  shape,  and  Ring  defines  a  circle. 
The  Draw  method  is  polymorphic,  by 
virtue  of  the  VIRTUAL  keyword. 

Listing  Two  (page  84)  is  a  short  pro¬ 
gram  which  uses  the  polymorphic  na¬ 
ture  of  Draw  to  implement  a  generic 
procedure  called  DrawShape.  The  ar¬ 
gument  to  DrawShape  is  a  pointer  to 
the  common  base  class  {Shape)  of  Box 
and  Ring.  The  call  to  the  Draw  method 
in  DrawShape  invokes  the  implemen¬ 
tation  of  Draw  for  the  specific  class  of 
the  object  whose  pointer  was  used  as  an 
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(continued  from  page  36) 
argument.  In  other  words,  passing  a 
pointer  to  a  Box  to  DrawShape  will 
cause  the  Box. Draw  method  to  be  called. 

Making  Turbo  Pascal  objects  persis¬ 
tent  requires  that  we  understand  how 
objects  are  stored  in  memory.  A  Turbo 
Pascal  object  is  basically  the  same  thing 
as  a  record:  The  instance  variables  of 

Persistence  can  be 
accomplished  in  other 
programming 
languages  with  a 
minimal  amount  of 
work  and  knowledge  of 
object  formats 


an  object  are  stored  contiguously  in 
memory,  aligned  on  16-bit  word  bounda¬ 
ries.  A  derived  object  class  will  contain 
all  of  the  members  defined  for  its  base 
class,  plus  all  of  the  members  unique 
to  itself.  Shape  defines  a  single  instance 
variable,  Color.  Because  Sox  is  derived 
from  Shape ,  it  inherits  Color.  You  can 
think  of  Box,  for  persistence  purposes, 
as  the  Pascal  RECORD  structure  shown 
in  Example  1. 

The  obvious  approach  to  writing  an 
object  to  disk  is  to  use  the  same  method 
used  for  writing  a  record.  Were  Box  a 
record  as  shown  in  Example  1,  a  FILE 
OF  Box  could  be  declared  to  hold  Box 
objects.  Alas,  a  file  component  type  in 
Turbo  Pascal  cannot  be  an  object  type; 
FILE  OF  Box  generates  an  error  to  this 
effect. 

An  untyped  file  allows  us  to  solve 
our  problem.  Listing  Three  (page  84) 
employs  an  untyped  file  and  the 
Block  Write  and  BlockRead  functions  to 
store  and  retrieve  Ring  and  Box  ob¬ 
jects.  The  Reset  and  Rewrite  functions 
declare  the  file  record  length  to  be 
one,  letting  us  write  any  number  of 
bytes  to  the  untyped  file.  When  we 
read  and  write  an  object,  the  SizeOf 
function  is  used  to  get  the  size  of  the 
object. 


BoxRec  =  RECORD 

BEGIN 

Color  :  INTEGER; 

UpperLeftX,  UpperLeftY  : 

INTEGER; 

LowerRightX,  LowerRightY 

:  INTEGER; 

END; 

Example  1:  Representing  the  Box  ob¬ 
ject  as  a  Turbo  Pascal  record. 
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An  object  that  has  virtual  methods 
must  be  initialized  with  a  CONSTRUC¬ 
TOR  call  before  it  can  be  loaded  with 
an  object  value  from  disk.  The  CON¬ 
STRUCTOR  assigns  the  address  to  vir¬ 
tual  function  pointers  for  the  object.  The 
values  of  the  instance  variables  can  then 
be  updated  via  a  call  to  BlockRead. 

Using  individual  calls  to  BlockWrite 
and  BlockRead  will  store  the  instance 
variables  of  an  object  in  a  disk  file.  This 
isn’t  the  best  method,  though.  For  ex¬ 
ample,  let’s  say  that  we  wanted  to  cre¬ 
ate  a  function  which  writes  any  type 
of  Shape  to  a  file.  An  obvious  first 
attempt  at  such  a  function  might  look 
like  that  shown  in  Example  2. 

It  looks  good,  but  it  won’t  do  what 
you  might  expect.  A  Shape  is  defined 
with  only  one  integer  instance  vari¬ 
able,  so  SizeOf(Shape)  is  only  two.  A 
Box  has  10  bytes  of  instance  variables, 
and  a  Ring  has  8  bytes.  So,  passing  the 
address  of  a  Box( for  example)  to  Write- 
Shape  will  result  in  having  only  the  first 
2  bytes  of  the  Box  stored.  Obviously, 
this  is  not  going  to  work.  A  better  sys¬ 
tem  is  to  use  methods  to  store  and 
retrieve  objects  in  files.  By  making  these 
methods  polymorphic  across  a  class 
hierarchy,  generic  functions  such  as 
WriteShape  can  be  created. 

Listing  Four  (page  84)  shows  new 
versions  of  the  Shape ,  Ring,  and  Box 
classes.  The  Shape  object  type  defines 
a  pair  of  virtual  methods  called  FWrite 
and  FRead.  The  Box  and  Ring  classes 
define  specific  versions  of  these  meth¬ 
ods,  which  write  and  read  the  corre¬ 
sponding  object  type  into  the  specified 
file.  Listing  Five  (page  86)  shows  how 
these  functions  can  be  used  in  place 
of  the  BlockRead  and  BlockWrite  calls 
used  in  Listing  Three.  Using  these  new 
methods,  a  generic  WriteShape  proce¬ 
dure  would  look  like  that  shown  in 
Example  3- 

What  about  building  a  Turbo  Pascal 
class  (object  type)  that  emulates  the 
function  of  the  STORABLE  class  included 
with  Eiffel?  Because  Turbo  Pascal  sup¬ 
ports  only  single-inheritance  —  where 
a  class  may  have  only  one  base  class 
—  STORABLE  would  have  to  be  the 


PROCEDURE  WriteShape (f  :  FILE;  s 
BEGIN 

BlockWrite {f , s, SizeOf (sA) ) ; 

END; 

''Shape); 

Example  2:  A  first  attempt  at  writing 
a  procedure  to  store  a  persistent  object 

PROCEDURE  WriteShape ( f  :  FILE;  s 
BEGIN 

s->F Write (f ) ; 

END; 

A Shape) ; 

Example  3:  A  generic  WriteShape  pro¬ 
cedure  to  store  persistent  objects. 
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only  base  class.  Using  a  STORABLEbase 
class  with  the  Shape  classes  would 
change  their  definitions  only  slightly. 

Consider  the  Storable  object  type  de¬ 
fined  in  Example  4.  The  Shape  object 
type  and  the  object  types  derived  from 
it  inherit  the  basic  I/O  functions  from 
Storable.  Every  object  type  for  whom 
Storable  is  an  ancestor  defines  its  own 
implementation  of  the  FWrite  and  FRead 
methods. 

Another  advantage  of  read/write  meth¬ 
ods  customized  to  an  object  type  can  be 
seen  with  objects  that  represent  dynamic 
data  structures.  Let’s  say  that  you’ve  cre¬ 
ated  a  linked-list  object  type:  Each  linked- 
list  object  will  have  a  pointer  to  the  first 
node  in  the  list;  the  other  pointers  and 
the  actual  data  will  be  stored  in  dy- 


Storable  =  OBJECT 
BEGIN 

PROCEDURE  FWrite (f  :  FILE) ; 
PROCEDURE  FRead (f  :  FILE); 

.END,;. 

Shape  -  OBJECT  (Storable) 

BEGIN 

Color  :  INTEGER; 

PROCEDURE  Draw;  VIRTUAL; 
END; 


Example  4:  A  storable  base  class  (ob¬ 
ject  type)  that  emulates  the  features  of 
the  Eiffel  storable  class. 


PERSISTENT  OBJECTS 


namic  memory.  Simply  writing  a  linked- 
list  object  directly  with  a  BlockWrite 
statement  will  store  the  pointer  only  to 
the  first  element  in  the  list. 

Obviously,  this  pointer  will  be  mean¬ 
ingless  in  another  execution  of  the  pro¬ 
gram  (because  addresses  will  change). 
Even  worse,  the  other  nodes  in  the  list 
will  be  lost  when  the  program  termi¬ 
nates.  Class-specific  read/write  meth¬ 
ods  can  solve  this  problem  by  writing 
the  data  in  the  nodes  of  the  linked  list 
to  the  disk  file  in  the  same  order  as  they 
appear  in  the  list.  Then  a  linked  list  is 
read  from  disk,  and  the  dynamic  tree 
can  be  recreated  from  the  node  data. 

Conclusion 

Persistent  objects  are  useful  in  restor¬ 
ing  the  state  of  objects  within  a  pro¬ 
gram  from  one  run  to  the  next.  This  is 
particularly  important  for  objects  that 
are  created  on-the-fly.  In  addition,  per¬ 
sistent  objects  allow  different  programs 
to  share  common  objects. 

As  object-oriented  technology  un¬ 
folds,  persistent  objects  will  play  an 
increasingly  important  role.  The  bene¬ 
fits  will  be  seen  not  only  in  program¬ 
ming,  but  in  applications  such  as  object- 
oriented  databases  and,  ultimately,  in 
operating  systems. 

The  greatest  benefits  to  programmers 


will  come  when  persistent  objects  can 
be  shared  between  programs  written 
in  different  languages.  Wouldn’t  it  be 
nice  to  grab  a  Pascal  object  from  C++? 

A  common  specification  for  the  crea¬ 
tion  and  management  of  persistent  ob¬ 
jects,  such  as  that  being  proposed  by 
Microsoft,  will  be  needed.  As  you  have 
seen  in  this  article,  it  is  relatively  easy 
to  implement  persistent  objects  in  Turbo 
Pascal.  With  slight  modifications,  the 
ideas  presented  here  can  be  applied 
to  both  Smalltalk  and  C++. 

Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
on  line.  To  order  the  disk,  send  $14.95 
(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  M&T’s  Telepath  on-line  ser¬ 
vice  (via  TYMNET)  and  through  the  DDJ 
Forum  on  CompuServe  (type  GO  DDJ). 

DDJ 

(Listings  begin  on  page  84.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  3. 
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Fast  Search 


File  access  in  the  fast  lane 


Leon  Campise 


This  article  presents  FASTSRCH, 
a  Basic  function  that  scans  a 
data  file  and  returns  an  array 
containing  the  record  numbers 
of  all  records  that  match  a  speci¬ 
fied  key.  FASTSRCH  applies  a  couple 
of  basic  concepts  to  attain  very  fast 
sequential  access  to  data  files:  First,  it 
reads  and  processes  many  records  at  a 
time  using  Basic’s  binary  file  I/O,  yield¬ 
ing  fewer  Disk  Read  Requests  to  DOS. 
Secondly,  it  uses  Basic’s  INSTR  func¬ 
tion  to  “instantly”  scan  for  records  meet¬ 
ing  the  desired  criteria. 

The  idea  is  to  scan  the  data  file  as 
fast  as  the  disk  drive  can  access  it.  This 
is  not  attained  in  the  traditional  record 
processing  as  there  is  a  great  deal  of 
overhead  that  goes  along  with  retriev¬ 
ing  each  record,  comparing  the  key 
against  a  specific  value,  and  iterating  a 
loop  counter. 

We  use  FASTSRCH  in  almost  every 
case  where  we  used  to  scan  files  se¬ 
quentially.  The  areas  where  you  see 
the  most  dramatic  gains  are  with  smaller 
records.  However,  speed  increases  with 
almost  any  record  length.  This  is  espe¬ 
cially  true  when  incorporating  Instr- 
ASM  in  lieu  of  Basic’s  INSTR.  (See  the 
accompanying  text  box,  “Beyond  FAST¬ 
SRCH.”) 


Leon  is  the  senior  managing  engineer 
for  a  software  developing  firm  special¬ 
izing  in  medical  practice  management 
systems.  Leon  can  be  reached  at  Dental 
Plan  Inc.,  3633  Broadway,  Garland, 
TX  75043. 


On  transactional  files  having  record 
lengths  less  than  about  100  bytes,  the 
speed  increase  is  amazing.  For  exam¬ 
ple,  one  application,  which  finds  and 
displays  all  transactions  for  a  certain 
customer,  searches  a  summary  transac¬ 
tion  file  that  has  a  record  length  of  32 
bytes.  I  benchmarked  the  old  code  on 
a  large  data  set  which  took  almost  1 
minute,  20  seconds.  Using  FASTSRCH, 
the  file  was  processed  in  6  seconds! 

Calling  FASTSRCH 

FASTSRCH  is  easy  to  call  in  a  program. 
First,  you  dimension  an  array  that  will 
hold  the  found  record  numbers,  then 


open  the  file  to  be  searched,  and  then 
execute  the  call.  When  FASTSRCH  re¬ 
turns  control,  the  array  has  all  match¬ 
ing  record  numbers  loaded  and  is  ready 
to  go! 

Figure  1  could  be  from  a  program 
that  scans  a  transaction  file  and  dis¬ 
plays  all  records  that  belong  to  a  par¬ 
ticular  customer.  This  example  shows 
how  it  might  be  done  in  a  traditional 
manner.  In  Figure  2,  FASTSRCH  is  used 
for  the  scan.  The  first  difference  when 
using  FASTSRCH  is  that  we  must  set 
the  maximum  number  of  records  we 
can  retrieve  in  order  to  dimension  the 
array  that  will  receive  the  selected  re¬ 
cords’  record  numbers.  The  next  dif¬ 
ference  is  we  open  the  file  in  binary 
access  mode  instead  of  random  access 
mode.  This  allows  FASTSRCH  to  pro¬ 
cess  many  records  at  once.  But  the 
greatest  difference  in  the  calling  pro¬ 
gram’s  logic  comes  after  the  call  to 
FASTSRCH.  Here,  we  close  and  reopen 
the  file  in  random  access  mode.  Then, 
instead  of  looping  through  all  records 
in  the  file,  searching  for  matching  ones, 
FASTSRCH  has  already  identified  the 
records  we  need,  and  hence,  we  can 
access  the  data  directly.  The  seven  pa¬ 
rameters  to  pass  to  FASTSRCH  are  listed 
in  Table  1;  Table  2  lists  the  returned 
values. 

Examining  FASTSRCH 

FASTSRCH  (Listing  One,  page  90), 
which  was  compiled  with  Microsoft  Ba¬ 
sic  7.1,  calculates  and  loads  as  many 
records  as  it  can  into  a  large  file  buffer. 
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OPEN  "TRANSACT. DAT”  FOR  RANDOM  AS  #1  LEN  =  LEN (T) 

FOR  T1  =  1  TO  NumRecs% 

GET  #1,  1%,  T 

IF  KeyVal$  =  T.CustNum  THEN  CALL  PrintlRec(T) 

NEXT 


Figure  1:  Scanning  a  file  without  FASTSRCH 


DIM  FoundRecs% (MaxToFind%) 

OPEN  "TRANSACT.DAT"  FOR  BINARY  AS  #1 

NumFound%  =  FASTSRCH (1,  LEN(T),  7,'KeyVal$,  1,  LastRec%,  FoundRecs% () ) 
CLOSE  #1 

OPEN  "TRANSACT.DAT"  FOR  RANDOM  AS  #1  LEN  =  LEN (T) 

FOR  1%  =  1  TO  NumFound% 

GET  #1,  FoundRecs% (1%) ,  T 
CALL  PrintlRec(T) 

NEXT 


Figure  2:  Scanning  a  file  using  FASTSRCH 


(continued  from  page  42) 

Then  it  searches  each  byte  in  the  buffer 
for  a  match  on  the  key.  When  it  finds 
a  match,  it  uses  modular  arithmetic  (re¬ 
mainder  after  division)  to  find  out  if  the 
matched  data  is  in  the  key’s  location. 


Parameter 

Function 

BuffFile% 

The  file  handle  used 
in  the  OPEN  state¬ 
ment. 

RecLen% 

The  fixed  length  of 
the  data  record. 

KeyLocX, 

The  starting  byte  of 
the  field  being 
matched  on. 

KeyVal$ 

The  value  that  the 
key  needs  to  have 
to  be  a  "match”. 

StartRecX 

The  first  record  to 
begin  searching  on. 

LastRecX 

The  record  number 
of  the  last  number 
to  search. 

FoundRecsXQ 

The  array  that  will 
hold  the  record  num¬ 
bers  of  matching  re¬ 
cords. 

Table  1:  Parameters  passed  to 
FASTSRCH 


Parameter 

Function 

FoundRecs%(  ) 

When  this  array 
is  passed  back,  it 
will  contain  the 

matching  record 
numbers. 

FASTSRCH 

Returns  the 
number  of 
matches  found. 

If  it  is,  it  calculates  the  physical  record 
number  of  the  matched  key’s  record 
and  adds  it  to  the  array  of  matching 
records;  otherwise,  it  continues  to  search 
the  rest  of  the  buffer.  When  the  entire 
buffer  is  searched,  it  loads  the  next 
group  of  records  into  the  buffer  and 
starts  over. 

In  detail,  FASTSRCH  starts  out  by 
creating  a  10,000-byte  file  buffer  in  the 
far  heap.  My  consultant,  Bill  McGill 
and  I  have  found  that  a  buffer  larger 
than  this  doesn’t  seem  to  speed  things 
up  much.  Next  we  perform  some  in¬ 
itialization. 

Note  that  we  check  to  see  if  the  key 
that  we  will  be  matching  on  starts  on 
the  last  byte  of  the  logical  record  length 
(even  though  this  would  rarely  be  the 
case).  If  it  does,  we  set  the  key  location 
compare  variable  to  zero  instead  of  the 
key  location.  (Because  we  will  later  be 
using  modulo  arithmetic  to  verify  that 
a  match  is  at  the  key  location.)  If  the 
key  location  is  the  last  byte  of  the  rec¬ 
ord,  the  remainder  will  be  zero  instead 
of  the  record  length.  We  use  integer 
division  to  calculate  the  number  of 
whole  records  that  can  fit  into  our  file 
buffer:  This  is  the  maximum  amount 
of  buffer  that  we  will  use. 

The  outer  loop  executes  once  for 
each  buffer  full  of  records  we  search. 
The  first  thing  we  do  is  calculate  the 
byte  in  the  file  that  is  the  first  byte  we 
will  load  into  the  buffer.  Then,  starting 
at  that  byte,  we  retrieve  the  data  into 
the  buffer.  Next,  if  this  is  the  last  buffer 
and  it  is  not  full,  we  restrict  the  number 
of  bytes  to  search. 

The  middle  loop  executes  each  time 
we  find  a  matching  record  in  this  buffer. 
The  innermost  loop  exists  because  Ba¬ 
sic’s  INSTR  will  return  a  “false  match” 
if  there  is  a  match  not  in  the  key’s 
location.  This  loop,  therefore,  is  needed 
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(continued  from  page  44) 
to  weed  out  the  false  matches.  When 
INSTR  finds  a  match,  we  check  to  make 
sure  it  isn’t  past  our  logical  buffer  length. 
If  it  is,  or  there  just  weren’t  any  matches 
at  all,  we  exit  the  loop.  If  there  was  a 
match  then,  the  LOOP  UNTIL  makes 
sure  that  we  are  on  the  key  position 
before  exiting  the  loop  and  adding  this 
record  to  our  other  found  records.  Oth¬ 
erwise,  we  loop  again,  continuing  from 
the  byte  where  we  left  off. 

When  we  fall  out  of  this  inner  loop, 
we  check  to  see  if  there  was  a  match, 
and  if  there  is  room  for  it  in  our  array. 


If  so,  we  calculate  the  physical  record 
number  and  add  it  to  the  array. 

This  middle  loop  will  continue  until 
there  are  no  more  matches  in  this  buffer. 
The  next  logical  record  number  is  cal¬ 
culated  and  we  loop  again  if  we  are 
not  past  the  end  of  the  file.  Finally,  we 
set  the  number  of  records  found  to 
FASTSRCH%. 

Modifying  FASTSRCH 

The  FASTSRCH  function  listed  with 
this  article  is  a  bare-bone  version  to  use 
for  discussion.  Once  you  understand 
(continued  on  page  49) 
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FASTSRCH  has  a  few  limitations  that 
can  be  overcome  by  using  customized, 
low-level  searching  routines  in  place 
of  INSTR.  Performance  gain  can  be  less¬ 
ened  when  searching  long  records. 
Because  FASTSRCH  uses  Basic’s  IN¬ 
STR  to  find  a  match,  every  byte  in  the 
buffer  must  be  searched  sequentially. 
When  the  records  are  short,  there  are 
not  many  extraneous  comparisons. 
But  when  records  are  long,  say  256 
bytes,  up  to  255  extraneous  compares 
are  being  made  for  each  record.  This 
problem  becomes  compounded  when 
the  value  of  the  key  being  compared 
matches  in  other  places  in  the  re¬ 
cords.  These  “false”  matches  can  fur¬ 
ther  degrade  performance. 

A  solution  to  the  problem  is  to  cre¬ 
ate  a  smarter  INSTR  function  that 
knows  at  which  position  in  the  re¬ 
cords  the  key  is  located,  and  checks 
only  this  key  data.  For  this  to  execute 
as  quickly  as  possible,  the  core  of  the 
search  must  be  written  in  assembler. 
We  have  written  two  routines:  InstrR 
(see  Listing  Two,  page  90)  written  in 
Basic  and  compiled  with  Microsoft 
Basic  7.1,  is  called  by  FASTSRCH,  and 
InstrASM  (Listing  Three,  page  90),  writ¬ 
ten  in  assembler  and  assembled  with 
MASM  5.1,  is  called  by  InstrR.  InstrR 


Figure  3:  Implementing  InstrR 


basically  does  the  setup  for  InstrASM, 
which  actually  performs  the  search. 

In  order  to  implement  InstrR, 
FASTSRCH  needs  to  be  simplified 
slightly.  Because  InstrR  only  returns 
matches  on  the  key  (no  false  matches) 
then  the  entire  inner  loop  of 
FASTSRCH  can  be  replaced  with  the 
lines  in  Figure  3(a).  Also,  the  formula 
for  calculating  the  matching  record’s 
actual  record  number  must  be  simpli¬ 
fied  as  shown  in  Figure  3(b). 

Using  Conditionals  Other 
than  "Equal  to" 

Another  limitation  of  the  FASTSRCH 
when  using  INSTR  is  its  ability  to  se¬ 
lect  records  based  only  on  matching 
a  key  value  exactly.  However,  when 
using  InstrASM,  we  have  control  over 
which  conditional  we  use  to  make 
selections.  Instead  of  using  JE  (jump 
if  equal),  we  can  use  JA  (jump  if 
above),  or  JB  (jump  if  below)  any 
other  conditional.  Changing  the  one 
jump  statement  is  all  it  takes  to  make 
this  modification,  which  adds  a  tre¬ 
mendous  amount  of  flexibility  to  our 
searching  capabilities. 

—  L.C. 


(a) 

Match%  =  InstrR(Match%  +  1,  FarBufff),  KeyVal$,  RecLen%,  KeyPos%) 
IF  Match%  >  BuffLen%  then  Match%  =  0 

(b) 

FoundRecs% (NumMatches%)  =  Match%  +  CurRec%  -  1 
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(continued  from  page  46) 
the  concept  behind  it,  you  can  custom¬ 
ize  and  enhance  FASTSRCH  to  improve 
performance,  flexibility,  and  presenta¬ 
tion.  Here  are  a  few  considerations: 

•  If  the  file  being  searched  can  grow 
to  have  more  than  about  32,000  re¬ 
cords,  then  a  long  integer  array  should 
be  used,  and  FASTSRCH  itself  may  need 
to  return  a  long  integer. 

•  If  records  longer  than  about  100  bytes 
are  to  be  searched,  or  if  there  will  be 
many  false  matches  (matches  not  in  the 
key’s  location)  then  a  smarter,  more 
sophisticated  version  of  INSTR  can  be 
used  to  enhance  performance.  We  have 
written  such  a  routine  in  assembler 
called  InstrASM. 

•  If  you  need  more  flexible  searching 
capabilities,  such  as  greater  than  or  less 
than  a  specified  value,  you  can  use  a 
slightly  modified  InstrASM. 

•  FASTSRCH  is  very  conducive  to  hav¬ 
ing  a  “percent  finished”  indicator  dis¬ 
played  on  the  screen  without  slowing 
things  down.  Simply  set  up  the  win¬ 
dow  before  calling  FASTSRCH  and  add 
the  following  line  as  the  first  statement 
inside  the  outer  DO  loop:  LOCATE 
Rou>%,  Col%,  0:  PRINT  USING 
“###”;(CurRec% / LastRec%)  *  100; 

•  If  it  is  likely  that  the  number  of  matches 
is  not  predictable  then  you  can  have 
FASTSRCH  return  “-1”  to  indicate  the 
capacity  of  the  dimensioned  array  was 
exceeded.  Then  the  data  can  be  pro¬ 
cessed  and  control  could  be  passed 
back  to  FASTSRCH  to  process  the  rest 
of  the  file. 

When  it  comes  to  accessing  data  files 
quickly  without  the  hassle  of  maintain¬ 
ing  sophisticated  linked  lists,  or  using 
database  engines,  FASTSRCH  can  be 
the  answer  to  the  “Searching,  Please 
wait ...”  blues. 

Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
online.  To  order  the  disk,  send  $14.95 
(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal ,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  M&T’s  Telepath  on-line  ser¬ 
vice  (via  TYMNET)  and  through  the  DDJ 
Forum  on  CompuServe  (type  GO  DDJ). 
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A  Generic  One-Pass 

Assembler 


Symbol  management  is  the  key  to  one-pass  assembly 


William  E.  Ives 


The  one  thing  most  programmers 
are  interested  in  when  develop¬ 
ing  code  in  assembly  language 
is  fast  assembly  turnaround  time. 
A  one-pass  assembler  facilitates 
this  by  avoiding  the  delays  associated 
with  multipass  assemblers,  and  thus  is 
able  to  out-perform  them.  This  per¬ 
formance  increase  has  some  cost,  the 
foremost  being  optimization.  But  even 
this  can  be  minimized  by  proper  sym¬ 
bol  management. 

This  article  describes  one  approach 
to  a  generic  one-pass  assembly.  The 
ideas  presented  can  be  applied  to  most 
of  the  current  assembly  languages. 

Symbols 

A  symbol  is  an  alphanumeric  short¬ 
hand  used  by  programmers  to  refer¬ 
ence  a  value  that  the  symbol  is  tied  to 
at  some  time  during  assembly.  As  an 
example,  consider  the  symbol  THERE 
in  the  following  code  fragment: 

JMP  THERE 

THERE  ADD  #1,D0 

The  assembler  must  interpret  the  value 
of  THERE  as  being  the  address  of  the 
ADD  instruction.  It  must  then  generate 


William  is  a  software  design  engineer 
in  the  Colorado  Telecommunications 
division  of  Hewlett  Packard,  5070  Cen¬ 
tennial  Blvd.,  Colorado  Springs,  CO 
80919 ■  William's  Internet  address  is 
u  <ei@hpctdlh.  hp.com. 


the  machine  code  for  the  JMP  instruc¬ 
tion  with  the  resolved  address.  Notice 
that  #1  and  DO  are  not  considered  sym¬ 
bols  because  their  values  or  meanings 
are  implied  within  the  assembly  lan¬ 
guage.  In  this  case  #1  means  the  imme¬ 
diate  value  of  one,  and  DO  means  data 
register  zero. 

As  shown  above,  a  symbol  can  be 
tied  to  an  address  by  a  line  label.  Most 
assemblers  also  provide  a  method  of 
defining  symbols  through  an  assem¬ 
bler  EQUATE  pseudocommand. 

ONE  EQUATE  1 

Here,  the  EQUATE  does  not  assemble 
to  any  machine  code,  but  rather  in¬ 


structs  the  assembler  to  tie  the  value  1 
to  the  symbol  ONE. 

Once  the  symbols  are  either  tied  to 
values  or  resolved,  the  job  of  the  as¬ 
sembler  is  to  use  these  values  to  gener¬ 
ate  machine  code  for  those  instructions 
whose  operands  reference  symbols.  For 
example,  the  JMP  instruction  shown 
earlier  would  normally  have  a  base 
opcode  followed  by  a  target  address 
within  its  machine  code.  The  assem¬ 
bler  fills  in  the  target  address  portion 
of  the  machine  code  once  the  symbol 
THERE  is  resolved. 

Forward  References 

Assemblers  traditionally  pass  through 
code  using  a  location  counter  to  keep 


0000 

A6  8D  0003 

LDA  FORWARD, PCR  ;  16-bit  offset 

SHORT 

0004 

A6  8C  00 

LDA  FORWARD, PCR  ;  8-bit  offset 

0007 

01  FORWARD 

FCB  1  ;  Force  constant  byte 

Figure  1:  Example  of  the  SHORT  directive  to  generate  an  8-bit  offset 


ABS  SHORT 

;  set  default  to  absolute  word 

0000 

2038  000A 

MOVE.B  DO, LABEL 

ABS  LONG 

;  set  default  to  absolute  long 

0004 

2039  0000 
OOOA 

MOVE.B  DO, LABEL 

000A 

01  LABEL  DC. B  1  ;  define  constant  byte 

Figure  2:  Changing  the  default  addressing  mode  on  the  68000 


0000 

6004 

BRA.B 

TARGET  ;  8  bit  offset  of  4 

0002 

6000  0002 

BRA 

TARGET  ;  1 6  bit  offset  of  2 

0006 

6000  FFFE  TARGET 

BRA 

TARGET  ;  16  bit  offset  Of -2 

Figure  3:  Making  a  branch  command  deterministic  using  the  .B  size  specifier 
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(continued  from  page  50) 
track  of  the  address  of  each  instruction. 
As  each  instruction  is  processed,  the 
location  counter  is  incremented  based 
upon  the  number  of  bytes  required  to 
hold  the  machine  code  of  the  instruc¬ 
tion.  This  forces  the  sequential  location 
of  machine  code  for  each  instruction 
with  no  “undefined”  bytes  between  in¬ 
structions.  In  addition,  it  leaves  space 
in  the  final  machine  code  to  go  back 
and  fill  in  resolved  symbols  such  as 
THERE. 

This  is  a  problem,  however,  when 
the  amount  of  space  to  be  reserved  for 
forward  referenced  symbols  is  un¬ 
known.  This  is  especially  apparent  on 


ASSEMB L E  R 


processors  that  offer  multiple  forms  of 
the  same  instruction.  For  example,  the 
JMP  instruction  might  come  in  either 
form:  16-bit  or  32-bit  target  address. 
The  question  is  how  much  space  is  left 
in  the  machine  code  if  the  assembler 
does  not  yet  know  the  value  of  the 
target  address  (THERE). 

Multipass  assemblers  address  this  di¬ 
lemma  by  resolving  symbols  on  the 
first  pass  through,  adjusting  instruction 
addresses  appropriately,  then  generat¬ 
ing  machine  code  on  additional  passes. 
With  this  approach,  most  multipass  as¬ 
semblers  handle  both  the  forward  ref¬ 
erences  and  machine  code  optimization. 
Although  this  method  generates  opti¬ 


mal  machine  code,  it  is  often  time- 
consuming  and  thus  tedious  for  the 
programmer  who  is  looking  for  a  fast 
turnaround  time. 

A  one-pass  assembler  addresses  this 
same  problem  by  passing  through  the 
code  only  once,  leaving  space  for  the 
forward  referenced  symbols,  then  fill¬ 
ing  in  these  spaces  as  the  symbols  are 
resolved.  This  process  is  called  “back- 
patching.”  By  making  the  assembly  lan¬ 
guage  deterministic  with  assembler  de¬ 
faults  or  directives,  the  one-pass  as¬ 
sembler  knows  how  much  space  to  leave 
for  forward  referenced  symbols.  This 

As  with  any  multiple 
module  assembly,  a 
linker  must  be  used  to 
create  the  final 
assembly  program 


may  not  result  in  optimal  code,  but 
does  result  in  improved  assembly  time. 

The  directives  or  defaults  needed  to 
make  this  possible  depend  heavily  on 
the  actual  processor  and  its  addressing 
modes.  For  example,  the  6809  constant 
offset  program  counter  for  the  relative 
mode  has  an  8-bit  and  a  16-bit  form. 
This  can  be  made  deterministic  by  de¬ 
faulting  to  the  larger  size  (16-bit)  and 
allowing  the  user  to  force  the  8-bit 
offset  by  using  an  assembler  directive 
(SHORT).  The  code  in  Figure  1  demon¬ 
strates  this. 

An  example  for  the  68000  involves 
the  absolute  addressing  mode,  which 
can  be  either  a  16-bit  or  32-bit  address. 
Whenever  a  forward  referenced  sym¬ 
bol  is  used  for  these  modes,  the  current 
assembler  default  is  used.  This  default 
size  can  be  changed  from  word  to  long 
by  the  directives  shown  in  Figure  2. 

The  68000  branch  commands  must 
also  be  deterministic  because  they  come 
in  byte  and  word  forms.  This  is  done 
by  defaulting  to  the  word  offset  unless 
the  instruction  is  qualified  by  a  size 
specifier  of  B,  as  shown  in  Figure  3- 

These  limitations  might  seem  unrea¬ 
sonable  at  first,  but  the  default  assem¬ 
bler  settings  can  be  used  so  that  mini¬ 
mal  effort  is  required  on  the  part  of  the 
programmer.  The  programmer  can  use 
the  directives  to  override  the  defaults 
for  optimization;  this  need  be  done 
only  for  forward  references  because 
backward  references  can  automatically 
be  optimized.  This  approach  is  not  at 
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( continued  from  page  52) 
all  uncommon  in  many  of  today’s  com¬ 
mercial  assemblers.  For  example,  those 
familiar  with  Microsoft’s  Macro  Assem¬ 
bler  will  recognize  the  directive,  jmp 
short  there,  which  tells  the  assembler 
that  the  jump  reference  is  within  the 
current  code  segment. 

Symbol  Management 

Once  an  assembly  language  is  made 
deterministic,  symbol  management  be¬ 
comes  the  key  to  the  assembly  process. 
First,  each  line  is  parsed,  and  any  sym¬ 
bols  are  extracted  from  it.  Then  a  ma¬ 
chine  code  size  determination  is  made 
based  on  assembler  defaults  and  direc- 


ASSEMBLER 


tives.  If  all  of  an  instruction’s  operand 
symbols  are  resolved,  the  machine  code 
can  be  immediately  generated.  Other¬ 
wise,  all  information  associated  with 
the  instruction  and  its  unresolved  sym¬ 
bols  is  saved  (in  an  operand  reference 
list)  for  later  assembly  through  back- 
patching.  In  either  case,  the  location 
counter  is  incremented  by  the  size  of 
the  machine  code,  and  the  next  source 
line  is  similarly  processed. 

The  symbols  for  each  line  are  pro¬ 
cessed  immediately  after  they  are  parsed 
from  the  line.  The  two  types  of  sym¬ 
bols  are  the  line  label  and  any  operand 
symbols.  Each  type  of  symbol  is  associ¬ 
ated  with  a  list:  A  label  with  the  re¬ 


solved  value  list  and  an  operand  sym¬ 
bol  with  the  reference  list.  The  line 
label  is  resolved  to  the  current  value 
of  the  location  counter.  The  label  and 
its  value  are  added  to  the  label  list  so 
that  future  references  to  the  label  can 
be  resolved.  Then,  any  previous  refer¬ 
ences  to  the  line  label  are  taken  from 
the  operand  reference  list.  These  are 
resolved,  and  machine  code  genera¬ 
tion  is  done  for  each  of  their  instruc¬ 
tions  through  backpatching.  A  flow¬ 
chart  of  this  is  shown  in  Figure  4. 

The  operand  symbol  management 
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(continued  from  page  54) 
was  described  earlier.  A  flowchart  for 
this  is  shown  in  Figure  5.  An  example 
of  assembling  a  generic  piece  of  as¬ 
sembly  code  using  these  two  flowcharts 
is  shown  in  Figure  6. 

By  making  the  assembly 
language  deterministic 
with  assembler  defaults 
or  directives,  the  one- 
pass  assembler  knows 
how  much  space  to 
leave  for  forward- 
referenced  symbols 


Note  that  at  any  given  time  the  oper¬ 
and  reference  lists  contain  only  those 
forward  references  not  yet  resolved. 
In  this  respect,  it  does  rely  on  memory 
being  available  for  expansion,  but  the 
list  size  is  always  at  a  minimum  for  the 
code  being  assembled.  Again,  this  is 
the  trade-off  of  space  versus  time. 


Multiple  Modules 

The  above  management  model  can  eas¬ 
ily  be  expanded  to  support  multiple 
module  assembly.  This  is  done  by  intro¬ 
ducing  a  global  directive  to  export  sym¬ 
bols  from  a  module  and  an  external 
directive  to  import  symbols.  In  addi¬ 
tion,  two  new  lists  are  added:  A  global 
label  list  and  an  external  reference  list. 
These  are  similar  to  the  label  list  and 
operand  reference  list,  respectively. 

The  new  flowcharts  are  shown  in  Fig¬ 
ures  7  and  8.  The  major  difference  to 
note  in  the  label  symbol  management 
flowchart  (Figure  8)  is  the  order  in  which 
the  various  label  lists  are  searched.  By 
searching  the  external  and  global  lists 
first,  this  flowchart  precludes  the  possi¬ 
bility  of  mistakenly  placing  a  global  la¬ 
bel  in  the  local  label  list.  This  order  of 
searching  also  provides  the  scoping  rules 
between  local  and  global  symbols. 

The  operand  symbol  management  flow¬ 
chart  (Figure  7)  shows  another  point  of 
interest.  If  a  global  label  has  not  been 
resolved  before  it  is  referenced  as  an 
operand  symbol,  the  reference  is  added 
to  the  local  operand  reference  list.  This 
is  done  because  a  global  symbol  must 
be  resolved  before  the  end  of  a  mod¬ 
ule.  Thus,  any  references  to  it  can  be 
treated  just  like  local  references. 

Linking 

As  with  any  multiple  module  assembly, 
a  linker  must  be  used  to  create  the  final 


Address 

Label 

Command 

Operand 

LI 

Top 

Jmp 

Forward 

L2 

Move 

00.  Data 

L3 

Lea 

AO.  Top 

L4 

Forward 

Clr 

Data 

L5 

Data 

Dc.b 

1 

Line  processed 


Label  list 


Operand  reference  list 


L2 


L3 


L4 


Symbol  Value 


Top 


LI 


No  change 


No  change 


Top 

LI 

Forward 

L4 

Symbol 


Ref. 


Forward 


LI 


Forward 

LI 

Data 

L2 

No  change 


Backpatched  LI 
Forward  resolved 


Data 


L2  L4 


Top 

LI 

Forward 

L4 

Data 

L5 

Backpatched  L2  &  L4 
Data  resolved 


Figure  6:  Assembly  example  using  flowcharts  from  Figures  4  and  5 
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( continued  from  page  56) 
assembly  program.  Here,  again,  the  one- 
pass  symbol  management  approach  is 
used  because  linking  is  just  a  matter  of 
resolving  external  references  across  mod¬ 
ules  and  generating  machine  code 
through  backpatching.  Of  course,  link¬ 
ing  involves  much  more,  but  a  detailed 
discussion  is  beyond  the  scope  of  this 
article. 

One  feature  of  linking  is  relocation, 
which  is  not  too  difficult  to  add  to  the 
current  model  because  it  merely  in¬ 
volves  treating  all  symbols  as  relative 
to  the  base  of  the  module.  Once  the 
module  base  address  is  known,  all  sym¬ 
bols  for  the  module  are  resolved.  An¬ 
other  advanced  feature  is  arithmetic 
expression  support.  This  can  be  added 
by  using  expression  trees  in  place  of 
the  symbols.  Resolution  then  becomes 
the  resolution  of  the  entire  tree  for 
each  instruction’s  operand.  Unfortu¬ 
nately,  each  of  these  adds  overhead 
and  slows  down  the  assembler.  If  these 
advanced  features  are  used  extensively, 
the  trade-off  may  be  worthwhile. 

A  One-Pass  Assembler 

Listings  One  through  Nine  provide  a 
simple  one-pass  assembler  for  a  ge¬ 
neric  assembly  language.  Listing  One 
(page  92)  provides  the  main  driver; 
Listing  Two  (page  92)  contains  the  pro¬ 
cedures  to  handle  assembly;  Listing 
Three  (page  96)  is  the  error  handler 
module;  Listing  Four  (page  97)  con¬ 
tains  the  procedures  to  handle  the  in¬ 
struction  set;  Listing  Five  (page  98)  is 
the  listing  module;  Listing  Six  (page 
100)  is  the  math  module;  Listing  Seven 
(page  100)  is  the  parser  module;  Listing 
Eight  (page  102)  provides  the  proce¬ 
dures  for  pseudocommand  assembly; 
and  Listing  Nine  (page  103)  is  the  sym¬ 
bol  table  module. 

Because  of  space  considerations,  all 
comments  have  been  removed  from 
the  code.  Fully  commented  code,  fur¬ 
ther  test  cases,  and  an  executable  ver¬ 
sion  of  the  assembler  are  available  from 
DDJ.  (For  more  information  see  page  3.) 

This  code  can  easily  be  modified  to 
build  a  full-featured  assembler  by  add¬ 
ing  an  advanced  parser,  instruction  op¬ 
code  lookup  facility,  and  error  trap¬ 
ping.  In  all,  symbol  management  is  the 
key  to  one-pass  assembly.  And,  al¬ 
though  such  an  assembler  may  not  cre¬ 
ate  optimal  code,  it  does  have  the  fast¬ 
est  development  turnaround  time. 

DDJ 

(Listings  begin  on  page  92.) 
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E  X  A  M  I  N  I  N  G  ROOM 


Inside  Object 
Professional 


A  rich  set  of  objects  is  the  key  to  object- 
oriented  development  in  Turbo  Pascal 


Gary  Entsminger 


Object  Professional,  from  Turbo 
Power  Software,  is  a  splen¬ 
did  library  of  object-oriented 
classes  for  Turbo  Pascal  5.5 
programmers.  It’s  extensive  — 
consisting  of  over  50  units,  130  object 
types,  2100  documented  procedures, 
functions,  and  methods,  1200  additional 
internal  routines,  and  1600  pages  of 
text  and  examples  neatly  divided  into 
3  manuals. 

Object  Professional  includes  com¬ 
plete  Turbo  Pascal  and  assembly  lan¬ 
guage  source  code  so  you  can  modify, 
append,  and  derive  to  your  heart’s  de¬ 
light.  If  you’re  a  Turbo  Pascal  5  5  pro¬ 
grammer  developing  applications  that 
need  sophisticated  screen  management, 
data  input/output,  or  TSR  routines, 
check  out  this  package.  It  could  save 
you  months  of  development  time. 

Pick  an  Object 

Object  Professional  includes  objects  for 
screen,  keyboard,  and  mouse  handling; 
windows,  menus,  pick  lists,  and  direc¬ 
tories;  text  editing  and  viewing;  data 
entry  and  code  generation  for  data  en¬ 
try  screens;  printing  typefaces,  control 
sequences,  and  forms;  data  objects  (“con¬ 
tainer  classes”),  lists,  sets,  and  so  on; 


Gary  is  a  writer,  programmer,  and  a 
consultant.  He  is  the  co-author  (with 
Bruce  Eckel)  of  Tao  of  Objects  to  be 
published  later  this  year.  Gary  can  be 
reached  at  Rocky  Mountain  Biological 
Lab.,  Crested  Butte,  CO  81224,  or 
through  CompuServe:  71141,3006. 


handling  longer  than  255  character 
strings;  interfacing  to  DOS;  creating  TSRs 
that  automatically  swap  to  EMS  or  disk; 
memory  allocation  and  deallocation; 
keyboard  macros;  BCD  arithmetic;  and 
more.  The  list  of  objects  really  goes  on 
and  on. 

Much  of  Object  Professional  is  a  trans¬ 
lation  of  Turbo  Professional,  Turbo 
Power’s  state-of-the-art  library  of  non¬ 
object-oriented  subroutines  for  Turbo 
Pascal  4.0  and  5.0,  and  much  of  Object 
Professional  is  new.  Container  classes, 
a  swapping  EXEC  function,  improved 
windows  and  mouse  support,  large  ar¬ 
rays  that  can  use  RAM,  disk,  or  EMS, 
text  and  binary  file  viewing,  complete 
window-oriented  text  editing,  and  sev¬ 
eral  utilities  for  making  data  entry 
screens  and  menus  have  been  added. 
It  would  (literally)  take  a  dozen  pages 
just  to  list  the  new  procedures  and 
functions.  Instead  of  doing  that,  let’s 
take  another  approach  toward  examin¬ 
ing  Object  Professional.  One  that  fo¬ 
cuses  on  the  object-oriented  structure 
of  the  library. 

Figure  1  shows  a  portion  of  Object 
Professional’s  object  hierarchy.  The  hierar¬ 
chy  is  well-thought  out  and  is  thorough. 
Abstract  objects  (such  as  AbstractField, 
AbstractFrame,  AbstractWindow,  Ab- 
stractSelector,  AbstractHelpWindow,  and 
AbstractArray)  are  built  into  the  library 
making  it  easy  to  derive  new  objects 
from  Toolbox  objects  and  to  implement 
polymorphism. 

Root  is  the  ancestor  of  all  the  objects 
in  the  library  except  ColorSet.  The  high¬ 


est  level  objects  (and  the  most  com¬ 
plex)  are  the  most  indented  in  the  hier¬ 
archy.  Note  well  that  Object  Profes¬ 
sional  is  primarily  built  up  from  data 
structures.  Various  lists  (single,  dou¬ 
ble,  and  so  on),  arrays,  and  windows, 
for  example,  are  ancestors  for  many  of 
the  objects  in  the  toolbox  (see  Figure 
2).  A  TextEditor,  for  example,  is  a  com¬ 
plex  object  that  rivals  the  Turbo  Pascal 
editor  in  power  and  flexibility.  It’s  very 
complete  —  with  word  wrapping,  cur¬ 
sor  positioning,  extensive  file  I/O,  block 
reads,  writes,  copies,  moves,  and  its 
own  editing  and  command  windows. 
A  text  editor  can  be  incorporated  into 
an  application  very  easily.  Listing  One 
(page  108)  shows  how  little  code  is 
needed  to  create  an  editor  window, 
read  a  file,  edit  the  file,  and  save  it. 

In  addition,  the  TextEditor  offers  two 
sets  of  programming  hooks  that  allow 
you  to  completely  customizes  TextEdi¬ 
tor  objects  for  specific  applications.One 
set  takes  procedure  pointers  as  parame¬ 
ters,  thus  allowing  you  to  specify  which 
procedures  will  be  called  when  a  string, 
file  name,  or  yes/no  answer  needs  to 
be  entered  by  a  user. 

Another  set  lets  you  implement  your 
own  commands  —  to  invoke  an  editor/ 
window  and  move  the  cursor  to  a  spe¬ 
cific  location  in  a  text  buffer,  for  exam¬ 
ple.  You  could  first  run  a  program  (such 
as  a  compiler)  and  then  use  the  results 
from  that  program  (and  this  set  of  com¬ 
mands)  to  go  to  the  position  in  the  file 
that  contains  an  error,  to  automatically 
search  for  and  replace  text,  and  so  on. 
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Figure  1:  Subset  of  the  Object  Profes¬ 
sional  object  hierarchy. 


(continued  from  page  62) 

In  addition,  the  text  editor  object, 
like  many  of  the  objects  in  Object  Pro¬ 
fessional  can  be  made  to  automatically 
detect  whether  a  mouse  driver  is  cur¬ 
rently  loaded,  and  if  so,  use  a  complete 
set  of  mouse  commands  for  moving, 
scrolling,  controlling  events,  and  so  on. 
You  can  also  create  mouse  command 
windows  (more  on  command  windows 
later)  and  incorporate  them  in  TSRs. 
This  can  be  accomplished  entirely  by 
using  objects  contained  in  the  toolbox. 

Data  Entry 

Object  Professional’s  data  entry  objects 
are  extensive,  making  it  easy  to  design 
systems  for  editing  single  variables  (such 
as  lines  or  fields)  and  groups  of  vari¬ 
ables  (such  as  screens).  Object  Profes¬ 
sional’s  line  editor  can  be  used  for 
prompting  users  for  file  names,  strings, 
and  numbers.  You  can  build  entry 
screens  for  editing  database  records, 
spreadsheets,  configuration  files,  com¬ 
mand  codes,  and  so  on. 

The  fundamental  structure  of  Object 
Professional’s  data  entry  system  is  the 
“abstract  field,”  which  is  derived  from 
a  DoubleListNode.  Any  field  derived 
from  an  abstract  field  possesses  the 
facilities  for  belonging  to  and  manipu¬ 
lating  a  list.  The  field  hierarchy  derived 
from  first  the  DoubleListNode  and  then 
the  abstract  field  looks  like  that  shown 
in  Figure  3. 

An  abstract  field  isn’t  associated  with 
any  data.  Instead  it  contains  the  meth¬ 
ods  for  formatting  the  variables  which 
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Figure  2:  Selected  children  of  the  Root 
object  type 
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Figure  3-'  The  field  hierarchy  derived 
from  DoubleListNode  and  the  abstract 
field. 
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(continued  from  page  64) 
will  be  displayed  on  the  screen  or  will 
be  printed.  An  abstract  field  is  the  link 
between  the  data  entry  and  printing 
facilities  in  the  toolbox. 

Using  Object  Professional’s  data  en¬ 
try  objects,  a  programmer  can  derive  a 
high-level  object,  such  as  an  En- 
tryScreen,  which  treats  all  fields  alike, 
without  knowing  exactly  which  type  a 
particular  field  contains.  An  EntryScreen 

Object  Professional  is 
primarily  built  up  from 
data  structures 


could  then  display  the  contents  of  a 
field,  for  example,  by  calling  the  par¬ 
ticular  field’s  draw  method,  which  de¬ 
cides  (or  knows)  how  to  display  the 
field.  It  can  display  the  field  itself,  call 
a  driver  to  display  it,  or  whatever.  This 
is  a  neat  implementation  of  polymor¬ 
phism  at  a  high  and  practical  level. 

The  data  entry  objects  and  units  are 
probably  the  most  complex  and  com¬ 
prehensive  in  the  toolbox.  The  manual 
devotes  250  pages  to  these  units  and 
the  source  code  disks  include  several 
useful  demos  and  examples  which  you’ll 
want  to  use  in  order  to  better  under¬ 
stand  the  Object  Professional  approach 
to  object-oriented  programming. 

Figure  4  shows  a  screen  captured 
from  one  of  the  data  entry  demos, 
MakeMenu.  You  can  use  MakeMenu 
to  design  a  menu  system  interactively. 
When  you’re  satisfied  with  the  menu 
system  you’ve  designed,  MakeMenu  gen¬ 
erates  the  source  code  for  the  menu 
system  for  you.  MakeScreen,  another 
demo  included  with  Object  Professional, 
lets  you  design  data  entry  screens  in¬ 
teractively,  and  then  generates  that 
source  code  for  you.  Nifty. 

TSRs 

One  of  the  most  sophisticated  units  in 
Object  Professional,  the  OPINT  unit, 
isn’t  really  object  oriented  —  it  man¬ 
ages  Interrupt  Service  Routines  (ISRs). 
You  can  use  this  unit  to  create  TSR 
(Terminate  and  Stay  Resident)  applica¬ 
tions,  which  can  automatically  deter¬ 
mine  the  presence  of  EMS  (expanded 
memory)  and/or  a  RAM  disk  or  hard 
drive,  and  swap  themselves  out  of  execut¬ 
able  memory  (the  first  640K)  accord¬ 
ingly. 

OPINT  is  basically  an  ISR  manager. 
In  short,  it  keeps  track  of  interrupt  han¬ 
dlers  via  interrupt  handles.  The  InitVec- 
tor  function  lets  you  specify  a  handle 
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for  each  TSR  (you  can  have  up  to  20), 
and  then  uses  that  handle  to  keep  track 
of  things.  If  you  need  to  restore  an 
interrupt  vector,  you  can  call  Restore- 
Vector  with  the  handle,  and  OPINT 
will  furnish  DOS  with  the  correct  inter¬ 
rupt  number  and  the  address  of  the  old 
service  routine.  OPINT  lets  you  build 
nearly  bulletproof  TSRs  while  program¬ 
ming  at  a  very  high  level. 

The  ISR  unit  also  contains  routines 
that  help  you  write  large,  complex  TSRs. 
These  routines  allocate  and  deallocate 
alternate  stacks,  allow  you  to  switch 
to  alternate  stacks,  and  call  another 
procedure  from  inside  an  ISR,  and  let 
you  chain  to  previous  interrupt  han¬ 
dlers.  Best  yet,  Object  Professional  in¬ 
cludes  several  demos  (with  source  code) 
that  are  not  only  useful,  but  can  be 
used  to  learn  the  nitty-gritty  details  of 
building  complex  TSRs  with  multiple, 
configurable  hot  keys. 

Listing  Two  (page  108)  shows  enough 
code  to  create  a  TSR,  which  automati¬ 
cally  swaps  itself  to  EMS  or  to  disk.  The 
kernel  that  remains  in  executable  mem¬ 
ory  is  only  6K  and  will  seldom  need  to 
be  more.  Because  Object  Professional’s 
ISR  routines  swap  all  but  the  manage¬ 
ment  kernel  out  of  executable  mem¬ 
ory,  larger  programs  don’t  need  to  use 
any  more  executable  memory  than 
smaller  ones  after  a  swap.  The  key  to 
keeping  the  resident  part  (the  kernel) 
of  a  swapping  TSR  small  is  to  keep  the 
main  program  small  because  the  main 
program  segment’s  code  is  always  kept 
in  memory. 

Command  Processing 

One  of  the  most  useful  units  in  Object 
Professional  is  OPCMD,  which  includes 


an  object  called  a  CommandProcessor. 
This  object  translates  key  sequences 
into  command  codes  —  numbers  that 
can  represent  all  the  commands  in  a 
program.  You  can  then  group  these 
command  codes  into  a  set  of  tables 
that  show  the  relationships  between 
key  sequences  and  commands  (or  ac¬ 
tions).  Any  object  (method,  function, 
or  procedure)  can  then  call  the  Com- 
mandProcessorwhich  gets  a  keystroke, 
scans  the  appropriate  table,  and  re¬ 
turns  the  correct  command  (or  action). 
An  object  using  the  CommandProces- 
sordoesn’t  have  to  know  anything  about 
the  actual  key  pressed.  It  simply  acts 
on  the  command  that’s  linked  to  the 
keystroke. 

To  get  you  started,  the  OPCMD  unit 
defines  a  set  of  standard  command 
codes  as  constants.  For  example,  con¬ 
sider  the  command  codes  shown  in 
Figure  5.  To  put  you  in  control,  OPCMD 
sets  aside  55  “user  exit  commands,” 
ccUserO  through  ccUser54.  You  can  as¬ 
sign  these  commands  to  a  keystroke 
or  a  set  of  keystrokes.  This  makes  it 
easy  to  add  hotkey  links  to  commands 
in  many  of  the  Object  Professional  units. 
For  example,  suppose  you  wanted  to 
link  the  hotkey  Ctrl  FI  to  a  hypertext 
help  system.  You’d  assign  it  a  user  exit 
command,  say,  ccUserl.  Then  any  ob¬ 
ject  using  the  command  processor 
would  automatically  recognize  the 
hotkey  and  return  control  of  the  sys¬ 
tem  to  the  command  assigned  to  the 
key.  By  using  more  than  one  table,  a 
key  can  be  linked  to  many  different 
commands,  depending  on  the  situation. 

Command  processing  of  this  type 
“protects”  you  from  the  low-level  de¬ 
tails  of  dealing  directly  with  the  key- 


Figure  4:  Screen  capture  from  the  MakeMenu  demo 
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board.  This  saves  a  little  programming 
time,  but  more  important:  Lets  you 
quickly  reassign  keystrokes  to  com¬ 
mands,  and  makes  it  easy  to  reconfig¬ 
ure  key  assignments. 

Listing  Three  (page  108)  shows  a 
short  program  that  creates  and  pro¬ 
cesses  a  command  window  by  associ¬ 
ating  keystrokes  with  the  command 
codes  defined  in  KeySet.  Note  that  a 
KeySet  is  an  array  that  can  hold  a  virtu¬ 
ally  unlimited  number  of  key  defini¬ 
tions.  The  array  size  is  determined  by 
the  size  of  the  constant  KeyMax. 

Command  Windows 

Object  Professional  implements  a  com¬ 
plete  set  of  windowing  objects,  which 
can  be  used  to  derive  complex  and 
colorful  window  objects.  These  include 
LoadableColorSet,  PackedWindow,  Win- 
dowStack ,  AbstractWindow,  RawWin- 
dow,  StackWindoui,  and  Command- 
Window. 

The  CommandWindow  object  links 
keyboard  and  mouse  input  to  the  vari¬ 
ous  ways  of  displaying,  viewing,  and 
editing  text.  A  CommandWindow  es¬ 
sentially  takes  control  of  the  keyboard 
(via  the  CommandProcessor),  and 
makes  it  easy  for  each  window  to  have 
its  own  commands  and  actions.  Text 
editors,  browsers,  pick  lists,  directo¬ 
ries,  status  lines,  and  so  on  can  be 
processed  within  Command  Windows. 
When  a  CommandWindow  takes  con¬ 
trol  (via  a  CommandProcess )  it  doesn’t 
need  to  know  anything  about  the  rest 
of  the  program.  It’s  an  object,  with  its 
own  shape,  state,  and  set  of  commands. 
Using  CommandWindows  (and  a  few 
other  Object  Professional  objects  and 
your  imagination)  you  can  create  a  desk¬ 
top  environment  that’s  comparable  to 
professional  environments  such  as 


ccQuit  =  004;  {  quit  processing  } 
ccMouseSel  =  006;  {  mouse  action  } 
ccUp  =  012;  { cursor  up } 

ccNewFile  =  1 1 2;  { read  a  file } 
ccSaveFile  =  113;  {save  a  file} 
ccSubNext  =  1 21 ;  { go  to  next  submenu} 
ccSubQuit  =  1 22;  {  quit  current  menu  } 

Figure  5:  Example  command  codes 

from  the  OPCMD  unit 


Products  Mentioned 

Object  Professional 
Turbo  Power  Software 
P.O.  Box  66747 
Scotts  Valley,  CA  950 66 
408-438-8608 
Price:  $150 

Requirements:  IBM  PC/compatible 
640KRAM 

Hard  disk,  Turbo  Pascal  5-5  or  later 


Turbo  C++. 

CommandWindow  also  includes 
hooks,  which  makes  it  easy  to  link  an 
error  handler  and  a  help  system  to  a 
CommandWindow.  The  error  handling 
hook  is  a  pointer  to  a  procedure  that’s 
automatically  called  whenever  there’s 
an  error.  The  help  hook  is  a  procedure 
for  accessing  topic-indexed  (for  exam¬ 
ple,  hyper)  help. 

Object  Professional  CommandWin¬ 
dows  are  immediately  useful,  instruc¬ 
tive,  and  trend  setting.  Useful  because 
they’re  powerful  and  require  a  mini¬ 
mum  of  effort  to  get  them  up  and  run¬ 
ning.  Instructive  and  trend  setting  be¬ 
cause  they’re  a  terrific  lesson  in  think¬ 
ing  about  programming  OBJECTively 
and  using  windows  as  objects. 

The  Object  Professional  approach  to 
command  windows  is  in  some  ways 
similar  to  the  approach  one  must  take 
in  order  to  program  in  graphic  environ¬ 
ments  such  as  Microsoft  Windows.  Com¬ 
mand  (or  message)  processing  is  the 
name  of  the  game  in  sophisticated 
graphic  environments.  Although  the  com¬ 
mand  windows  you  create  with  Object 
Professional  can’t  be  readily  used  in 
graphic  environments,  their  conceptu¬ 
alization  can  be. 

The  Downside? 

Really,  for  text  processing,  Object  Pro¬ 
fessional  doesn’t  have  a  “true”  down¬ 
side.  The  procedures,  functions,  and 
methods  included  in  this  toolbox  are 
tight  and  fast;  many  are  optimized  in 
assembly  language.  The  source  code 
is  complete,  and  well  documented  in 
the  listings  and  in  the  manuals.  The 
manuals  (all  1600  pages  of  them)  are 
top-notch.  The  organization,  with  chap¬ 
ters  corresponding  to  units,  is  excel¬ 
lent.  Each  method  includes  sections 
on  the  declaration,  purpose,  descrip¬ 
tion,  example,  and  “see  also.”  There  is 
usually  one,  or  at  most,  two  methods  to 
a  page.  The  index  could  (of  course)  be 
a  lot  better!  Nobody  (including  the  big 
guys!)  spends  enough  time  on  indices. 

Because  there  isn’t  much  I  don’t  like 
about  Object  Professional,  I’ll  conclude 
with  a  couple  of  (simple!)  additional 
objects  I’d  like  to  see.  In  short,  two 
more  Object  Professionals  —  one  for 
Turbo  C++  and  one  for  Microsoft  Win¬ 
dows.  A  toolkit  as  powerful  as  Object 
Professional  applied  to  an  important 
graphic  environment  (such  as  Windows) 
would  be  a  coup.  Are  you  listening 
Turbo  Power? 

DDJ 

(Listings  begin  on  page  108.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  6. 
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Kermit  for  OS/2 
Parti 


The  learning  curve  for  OS/2  may  be  steep, 
but  it’s  worth  the  price 


Brian  R.  Anderson 


I  am  one  of  the  many  DOS  curmud¬ 
geons  who  eschewed  OS/2  since 
its  introduction  three  years  ago. 
Too  expensive,  said  I.  Too  slow. 
Requires  too  much  memory.  Why 
does  one  user  need  multiple  tasks?  Why 
is  protected  memory  necessary  on  a 
single-user  system?  In  retrospect,  this 
seems  to  be  a  case  of  sour  grapes:  I 
could  not  afford  to  upgrade  my  per¬ 
sonal  computer  to  allow  me  to  run 
OS/2. 

I  recently  purchased  a  new  machine 
with  a  33-MHz  80386,  a  VGA  monitor, 
and  a  fast  150-Mbyte  hard  drive.  Every¬ 
thing  looks  very  different  from  this  new 
perspective.  Sure,  OS/2  has  much  more 
overhead  than  DOS,  but  at  33  MHz, 
you  don’t  really  notice.  Sure,  4  Mbytes 
is  a  lot  of  memory,  but  the  price  of 
RAM  has  declined  significantly.  Multi¬ 
tasking  really  does  make  sense  —  never 
having  to  wait  for  the  machine  to  finish 
one  task  before  I  can  start  another  in¬ 
creases  productivity.  And,  finally,  while 
developing  new  software,  protection 
from  your  own  errant  programs  is  a 
real  advantage  —  it  virtually  eliminates 
having  to  reboot  because  of  system 
crashes.  So  with  that  confession  and 
recantation  out  of  the  way,  let’s  talk 
project: 

Kermit  is  a  file-transfer  protocol  that 
allows  diverse  computers  to  communi¬ 
cate.  In  May  1989,  my  article  “Kermit 
Meets  Modula-2”  (also  here  in  DDJ)  de- 


Brian  is  an  instructor  of  computer  sys¬ 
tems  technology  at  the  British  Colum¬ 
bia  Institute  of  Technology.  He  can  be 
reached  at  3700  Willingdon  Ave., 
Burnaby,  B.C.,  Canada  V5G  3H2. 


scribed  the  PCKermit  protocol  and  my 
implementation  in  Modula-2.  This  article 
describes  how  I  ported  PCKermit  over 
to  the  OS/2  Presentation  Manager  (PM). 

OS/2  Mini-Primer 

OS/2  and  PM  are  very  large  systems. 
The  OS/2  kernel  has  over  250  func¬ 
tions;  PM  has  over  500.  This  collection 
of  functions  is  referred  to  as  the  Appli¬ 
cation  Program  Interface,  or  API.  The 
Kernel  API  provides  all  of  the  traditional 
operating  system  services,  including 
memory  management,  process  control, 
and  input/output.  Using  only  the  Ker¬ 
nel  API,  a  programmer  can  write  so¬ 
phisticated  character-based  programs 
without  ever  having  to  resort  to  direct 
access  to  the  hardware  (as  was  often 
required  under  DOS). 

The  Kernel  API  is  divided  into  four 
sections:  Dos,  Kbd,  Mou,  and  Vio.  The 
Kbd,  Mou,  and  Vio  provide  fast,  flex¬ 
ible  access  to  the  keyboard,  mouse, 
and  video  systems,  respectively,  and 
are  used  mainly  in  traditional  character- 
based  applications.  Presentation  Man¬ 
ager  takes  control  of  the  keyboard  and 
mouse,  so  the  Kbd  and  Mou  group  of 
functions  is  not  used  in  a  PM  applica¬ 
tion.  PM  has  many  options  available 
for  controlling  the  screen;  graphics  sup¬ 
port  (both  vector  and  raster)  is  avail¬ 
able,  as  is  support  for  various  propor¬ 
tional  and  non-proportional  fonts.  The 
Vio  group  of  functions,  in  a  slightly 
altered  form  called  “Advanced  Vio” 
( AVio )  is  also  available  to  a  PM  appli¬ 
cation.  (My  implementation  of  Kermit 
uses  AVio  functions  to  emulate  a  stan¬ 
dard  video  display  terminal  (VDT)  and 
thereby  allows  interaction  with  main¬ 


frame  computers.)  The  DOS  portion 
of  the  OS/2  kernel  provides  for  disk 
I/O,  task  management,  and  memory 
management  for  both  character-based 
and  PM  applications. 

The  Presentation  Manager  API  is  also 
divided  into  sections:  Dev,  Gpi,  and 
Win.  The  functions  in  the  Dev  group 
are  used  to  access  PM  device  drivers, 
which  allows  for  device-independent 
graphics.  The  Gpi  group  provides  the 
drawing  routines  (lines,  curves,  bitmaps, 
fonts,  and  so  on)  for  PM.  The  Win 
functions  manage  the  PM  windows  in¬ 
cluding  menus,  scroll  bars,  and  dialog 
boxes.  Each  Win  function  is  quite  “low 
level,”  which  often  makes  for  convo¬ 
luted  code  (several  functions,  each  with 
many  parameters,  must  be  called  to 
accomplish  some  small  task). 

Besides  the  function  libraries  just  de¬ 
scribed,  PM  makes  use  of  resource  files 
to  store  application-specific  informa¬ 
tion  about  menus,  dialog  boxes,  and 
so  on.  A  resource  file  is  a  text  file  of 
source  code  that  describes,  for  exam¬ 
ple,  the  form  of  a  pull-down  menu. 
The  resources  are  compiled  (with  a 
resource  compiler),  and  eventually 
linked  to  the  application.  The  source 
code  for  many  types  of  resources  can 
be  either  developed  manually  or  gen¬ 
erated  automatically  using  a  dialog  edi¬ 
tor,  for  example. 

On  the  Workbench 

To  develop  programs  for  OS/2  and  PM 
you  will  need  a  fairly  extensive  (and 
expensive)  set  of  tools.  Probably  the 
most  important  “tool”  is  the  documen¬ 
tation.  The  Microsoft  OS/2  Program¬ 
mers’s  Reference  (volumes  1-3)  is  es- 
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(continued  from  page  70) 
sential.  There  is  also  a  fourth  volume 
which  covers  OS/2  vl.2;  that  volume 
has  remained  on  my  shelf  because  I  am 
running  OS/2  vl.l.  Because  the  Micro¬ 
soft  manuals  are  a  bit  light  on  exam¬ 
ples,  you  will  also  want  to  get  Charles 
Petzold’s  Programming  the  OS/2  Pres¬ 
entation  Manager  (Microsoft  Press, 
1989),  and  either  Ray  Duncan’s  Ad¬ 
vanced  OS/2  Programming  (Microsoft 
Press,  1989)  or  Peter  Norton  and  Robert 
LaFore’s  Inside  OS/2  (Brady  Books, 
1988)  on  the  kernel.  Gordon  Letwin’s 
Inside  OS/2  (Microsoft  Press,  1988)  is 
also  a  good  overall  OS/2  primer.  For 
setting  up  and  running  (not  program¬ 
ming)  OS/2,  you  might  consider  Using 
OS/2  by  Halliday,  Minasi,  and  Gobel 
(Que  Books,  1989). 

Of  course,  you  will  need  a  compiler 
or  assembler  that  supports  OS/2  and 
PM.  Many  of  the  Microsoft  products 
obviously  qualify.  And  other  compilers 
are  starting  to  support  OS/2  and  PM. 
Whatever  language  you  choose  to  use, 
you  will  need  at  least  the  ability  to  read 
C  code  —  all  of  the  Microsoft  docu¬ 
mentation  is  written  in  C. 

For  this  project,  I  used  Stony  Brook 
Modula-2,  in  part  because  my  original 
implementation  of  Kermit  was  written 
in  Modula-2  (albeit  using  the  Logitech 
compiler),  and  in  part  because  1  prefer 
Modula-2  to  C.  The  Stony  Brook  com¬ 
piler  proved  an  excellent  choice;  al¬ 
though  much  of  the  system  was  still  in 
beta  test,  I  found  only  one  problem 
(which  I  was  able  to  correct  easily  be¬ 
cause  I  had  the  source  code  for  the 
offending  module). 

Finally,  you  will  need  the  resource  set: 
Icon  editor,  dialog  editor,  font  editor, 
resource  compiler,  and  a  few  other  mis¬ 
cellaneous  tools.  All  of  these  tools  are 
available  from  Microsoft  as  the  OS/2 
Softset.  Alternately,  you  can  purchase 
the  OS/2  PM  Software  Development 
Kit  which  includes  the  Microsoft  docu¬ 
mentation,  Petzold’s  book,  and  the  tools 
(but  no  compiler).  While  purchasing 
the  books  and  tools  separately  seems 
to  be  more  economical,  the  SDK  in¬ 
cludes  example  code  and  useful  pro¬ 
grams  (for  example,  PMCAP  —  a  screen 
capture  utility)  that  are  not  included 
with  the  Softset. 

Format  of  a  PM  Program 

Most  GUIs  (that  is,  GEM,  Windows, 
Macintosh,  and  OS/2-PM)  have  a  very 
similar  structure: 

1 .  The  main  program  sits  in  a  loop  fetch¬ 
ing  messages  from  the  operating  sys¬ 
tem  and  dispatching  those  messages 
to  a  window  procedure. 

2.  The  window  procedure  intercepts  the 


messages  (usually  with  a  very  long 
CASE  statement)  and  processes  the 
messages,  often  by  calling  other  func¬ 
tions. 

3.  Any  other  part  of  the  program  that 
wants  to  get  anything  done  must 
communicate  with  the  window  pro¬ 
cedure  by  posting  messages  (which 
the  mam  fetches  and  dispatches:  see 
steps  1  and  2). 

Virtually  everything  is  done  with  mes¬ 
sages.  For  example,  a  PM  program 
never  calls  a  function  such  as  getchar( ) 
or  Read ( )  to  get  a  character  from  the 
keyboard.  Instead,  a  program  must  con¬ 
tinually  look  for  a  WM_CHAR  message, 
and  then  translate  the  parameters  that 
come  along  with  the  message  to  find 
out  what  key  has  been  struck. 

One  tremendous  advantage  with 
OS/2  (compared  to  the  other  GUIs)  is 
that  preemptive  multitasking  allows  inde¬ 
pendent  threads  to  execute  in  the  back¬ 
ground  and  post  messages  to  the  main 
window  (to  let  the  user  know  what  is 
going  on).  PCKermit  makes  use  of  mul¬ 
tiple  threads  for  terminal  emulation  (con¬ 
necting  to  the  host),  as  well  as  for 
sending  and  receiving  files. 

Down  to  Business 

The  main  program  module,  PCKER- 
MIT.MOD  (see  Listing  One,  page  109), 
begins  on  line  1 .  (Note  that  the  listings 
are  sequentially  numbered  for  easy  ref¬ 
erence.)  PCKermit  initializes  the  win¬ 
dow  system  and  message  queue,  regis¬ 
ters  two  window  classes  (for  the  main 
window  and  a  child  window  —  the 
child  window  is  used  during  file  trans¬ 
fer),  creates  and  resizes  the  main  win¬ 
dow,  and  then  sits  in  the  message  loop 
waiting  for  termination. 

PCKermit  is  fairly  traditional  (for  PM), 
except  that  after  creating  the  main  win¬ 
dow,  PCKermit  immediately  determines 
the  size  and  position  of  the  desktop 
(see  line  99),  records  this  in  the  global 
variable  Pos,  and  then  expands  the  win¬ 
dow  to  nearly  full  size  (line  100-102). 
The  variable  Pos  is  used  again  in  the 
Shell  module  to  ensure  that  the  win¬ 
dow  is  always  correctly  sized  and  posi¬ 
tioned.  The  window  is  either  sized  to 
three  device  units  smaller  than  the  desk¬ 
top  (during  file  transfer),  or  is  maxi¬ 
mized  (during  terminal  emulation). 
When  the  window  is  maximized  or 
restored  from  maximum  (by  calling  the 
WinSetWindowPos  function  again),  an 
extra  term  must  be  included  in  the  final 
parameter:  Either  SWP__RESTORE  (line 
543-544)  or  SWP_MAXIMIZE  (line  552- 
554).  A  similar  strategy  is  used  to  keep 
the  child  window  properly  sized  (the 
child  window  is  used  for  displaying 
status  messages  during  file  transfer). 
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SHELL. DEF  (Listing  Two,  page  109) 
and  SHELL. MOD  (Listing  Nine,  Page 
111)  represent  the  most  important  mod¬ 
ule,  as  it  is  where  all  messages  are 
processed  (mostly  in  WindowProc ,  Do- 
Menu,  and  ChildWindowProc).  Several 
global  variables  and  constants  are  de¬ 
fined  here  (that  is,  Class  and  Client- 

Preemptive  multitasking 
allows  independent 
threads  to  execute  in 
the  background,  and 
post  messages  to  the 
main  window 


of  keyboard  information  (ASCII  code, 
scan  code,  Control/ Alt/Shift  condition, 
time  of  keypress,  and  several  flags).  In 
some  cases,  the  message  parameters 
are  not  used  at  all. 

One  of  the  messages  processed  by 
WindowProc,  WM_COMMAND,  is 
passed  on  to  DoMenu  (line  743).  This 
procedure  processes  all  messages  that 
result  from  the  user  clicking  on  a  menu 
or  using  one  of  the  accelerator  keys. 
This  user  interaction  often  results  in 
other  child  windows,  called  “dialog 
boxes,”  being  created.  When  the  dia¬ 
log  box  is  on  the  screen,  another  win¬ 
dow  procedure  takes  over.  For  exam¬ 
ple,  if  the  user  clicks  on  the  Options 


Window).  Besides  the  two  window  pro¬ 
cedures,  there  are  a  number  of  an¬ 
cillary  procedures  for  controlling  the 
windows:  SetFull,  SetRestore,  and  Set- 
Maximize  control  the  size  of  the  win¬ 
dow  (PCKermit  “insists”  on  a  full  win¬ 
dow  to  properly  emulate  the  TVL950 
video  screen);  Enable  and  Disable  “gray 
out”  any  menu  item  that  is  not  currently 
accessible;  Check  and  Uncheck  indicate 
the  currently  selected  video  color 
scheme;  DoMenu  is  called  from  Win¬ 
dowProc  to  process  WM_COMMAND 
messages  (these  are  mainly  commands 
that  result  from  the  user  interacting  with 
menus);  several  dialog  procedures  (for 
example,  BaudDlgProc)  allow  the  user 
to  make  choices  via  pop-up  dialog 
boxes  (each  dialog  box  is  a  window, 
and  therefore  needs  its  own  window 
procedure);  KeyTranslate processes  key¬ 
board  messages  and  translates  them 
into  standard  codes  (for  use  by  the 
Term  module). 

The  window  procedure,  WindowProc 
(line  1088),  is  called  only  by  PM.  Its 
purpose  is  to  process  messages  (in¬ 
cluding  standard  system  messages  such 
as  WM_CREATE,  WMJNTTMENU,  WM 
_COMMAND,  and  WM_PAINT,  as  well 
as  PCKermit  messages  such  as  WM_SET- 
FUL,  WM_SETRESTORE,  and  WM 
_TERM).  Besides  the  message  itself 
(which  is  really  just  an  integer),  the 
window  procedure  is  passed  two  mes¬ 
sage  parameters  ( mpl  &  mp2).  The 
form  of  these  two  parameters  depends 
upon  the  particular  message.  For  ex¬ 
ample,  in  the  case  of  the  WM_TERM 
message,  the  message  parameters  are 
used  to  pass  only  a  single  character. 
In  the  case  of  the  WM_CHAR  message, 
the  parameters  contain  a  wide  range 
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menu,  and  then  chooses  baud  rate  .  .  . , 
a  dialog  box  (with  radio  buttons  and  an 
OK  push  button)  appears  on  the  screen. 
While  this  dialog  box  is  on  the  screen, 
the  BaudDlgProc  (line  863),  takes  over 
control  of  the  window  (until  the  user 
clicks  on  OK,  or  presses  the  Return  or 
Esc  key).  Each  of  the  dialog  boxes  or 
messages  boxes  (PCKermit  has  nine) 
has  its  own  window  procedure. 

The  child  window  procedure,  Child¬ 
WindowProc  (line  1203),  is  also  called 
only  by  PM  (as  are  all  window  proce¬ 
dures),  and  processes  a  variety  of  sys¬ 
tem  and  PCKermit  messages.  The 
WM_PAD  and  PM_DL  messages  are 
from  the  PAD  (Packet  Assembler  Dis- 
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(continued  from  page  73) 
assembler)  and  DataLink  Modules,  re¬ 
spectively,  and  are  used  mainly  to  al¬ 
low  these  modules  (which  are  running 
as  independent  threads)  to  keep  the 
user  informed:  The  message  parame¬ 
ters  indicate  what  message  should  be 
displayed  on  the  screen. 

When  the  user  selects  Send  or  Re¬ 
ceive  (either  through  the  menus  or  via 
accelerator  keys),  a  fairly  complex  chain 
of  events  is  brought  into  play.  In  Do- 
Menu  at  lines  776  or  780  the  IDM_SEND 
or  IDMJREC  messages  are  recognized. 
In  the  case  of  IDM_SEND,  a  dialog  box 
is  invoked.  The  dialog  box  procedure 
SendFNDlgProc  on  line  983  allows  the 
user  to  enter  a  filename;  PM  returns  a 
pointer  to  the  filename  that  the  user 
enters. 

In  the  case  of  either  IDM_SEND  or 
IDM_REC,  the  MakeChild  procedure 
(line  630)  is  called  next.  This  proce¬ 
dure  first  forces  the  main  window  to 
full  size,  then  disables  several  menu 
items  (because  we  don’t  want  the  user 
to  try  to  change  the  baud  rate  halfway 
through  a  file  transfer,  line  639),  next 
creates  a  standard  window  (line  649), 
sizes  and  positions  the  window  (line 
661),  puts  an  appropriate  message  in 
the  window  (line  666),  and  finally  makes 
the  new  child  window  the  active  win¬ 
dow  (line  668). 

After  the  window  is  ready,  we  must 
set  it  up  so  that  we  can  send  messages. 
PCKermit  uses  the  AVio  for  this,  and 
lines  671-673  set  up  the  hvps  (Handle 
to  Vio  Presentation  Space).  Back  in  Do- 
Menu,  on  lines  779  or  782,  a  new  thread 
is  created.  OS/2  will  then  schedule  that 
thread  (which  will  either  send  or  re¬ 
ceive  a  file)  on  the  next  available  time 
slice.  The  thread  will  terminate  itself 
when  file  transfer  is  complete  (or  if  five 
consecutive  errors  occur).  Before  the 
thread  actually  terminates  itself  (by  call¬ 
ing  DosExit),  it  sends  messages  to  its 
window  procedure  to  remove  the  win¬ 
dow  and  restore  the  menus. 

When  the  user  selects  Connect  mode 
(either  through  menus  or  via  keyboard 
accelerator),  the  IDM_CONNECT  mes¬ 
sage  is  recognized  (line  762).  As  in  the 
case  of  Send  and  Receive,  various  menu 
items  are  disabled,  and  a  presentation 
space  is  set  up.  Unlike  Send  and  Re¬ 
ceive,  a  new  thread  is  not  started,  but 
an  existing  thread  is  resumed  (line  774); 
the  thread  was  set  up  during  initializa¬ 
tion  (line  1145)  and  then  immediately 
suspended  (next  line). 

Next  Time 

If  you’ve  examined  the  listings  up  to 
this  point,  you’ll  notice  that  I  haven’t 
mentioned  Listings  Three  through  Eight. 
These  are  the  definition  (.DEF)  files  for 


the  modules  to  be  covered  in  Part  II. 
Listing  Three,  (page  109)  for  example, 
is  the  .DEF  file  for  the  Term  module 
which  performs  TVI950  terminal  Emu¬ 
lation.  Also  note  the  definition  of  the 
ZWrprocedure  (line  176)  in  Listing  Three. 
Besides  displaying  a  directory,  this  func¬ 
tion  allows  the  user  to  log  onto  a  differ¬ 
ent  drive,  or  to  change  to  a  different 
directory.  This  feature  is  necessary  in 
a  Kermit  program,  as  only  a  file  name 
must  be  specified  when  sending  (you 
cannot  send  a  file  based  upon  a  com¬ 
plete  path).  Part  II  examines  these  is¬ 
sues  in  greater  detail. 

Screen. DEF  (Listing  Four,  page  109) 
gives  you  a  flavor  of  the  Screen  module 


to  be  presented  in  Part  II,  which  per¬ 
forms  low-level  screen  and  video  I/O 
using  OS/2’s  V70  functions.  And 
CommPort.DEF  (Listing  Seven,  page 
111)  presents  a  module  originally  sup¬ 
plied  by  Stony  Brook  that  I’ve  enhanced 
by  adding  extra  buffering,  for  instance, 
to  get  around  an  OS/2  limitation.  Of 
course,  I’ll  also  examine  some  of  the 
unexpected  problems  associated  with 
porting  PCKermit  to  OS/2.  Until  next 
time.  .  .  . 

DDJ 

(Listings  begin  on  page  109.) 
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Listing  One  (Text  begins  on  page  16.) 


DEFINITION  MODULE  ModPlot; 

(*  Title  :  High  level  Modula-2  Graphics  library  interface 
Author  :  Judy  Auping 
System  :  PC  Graphics 
Compiler:  LOGITECH  MODULA-2 /8 6 
*) 

FROM  DataDefs  IMPORT 

DeviceType, UnitsType, SizeType, AngleType, LineType, ColorType, 

FontType , Or iginType , Symbol Type , ModeType , STRING8  0 ; 

EXPORT  QUALIFIED 

Graphlnit, SetPlotDevice, SetPlotArea, SetScaledArea, SetScale,  SetUnits, 
SetCharSize, SetLabelAngle, SetLineType, SetPenColor, SetBackgroundColor, 
SetLabelOrigin, SetFixedDigits, ReturnRatio, SetFontType, 

Draw, Move, IncDraw, IncMove, DrawXAxis, DrawYAxis, DrawAxes,  DrawGrid, 
DrawLabel,DrawLabelledAxes,DrawLabelledGrid, DrawFrame,DrawSymbol, 
Where, NewScreen, CloseGraphics; 

PROCEDURE  Graphlnit; 

(*  Initializes  system-MUST  be  called  before  any  output  generated  *) 
PROCEDURE  SetPlotDevice (GraphDevice:  DeviceType); 

(*  Selects  output  device  for  subsequent  graphics  commands  *) 

PROCEDURE  SetPlotArea (XMin, XMax, YMin, YMax :  REAL) ; 

(*  Sets  the  'clip'  area  in  %  of  absolute  device  boundaries*) 

PROCEDURE  SetScaledArea (XMin, XMax, YMin, YMax :  REAL) ; 

(*  Sets  the  area  in  %  of  absolute  device  boundaries  to  which 
subsequent  SetScale  takes  effect*) 

PROCEDURE  SetScale (XMin, XMax, YMin, YMax:  REAL); 

(*  Sets  the  user  scale  *) 

PROCEDURE  SetUnits (GraphUnits:  UnitsType); 

(*  Sets  either  User  (Scaled  units)  or  Device  (absolute  units)  *) 
PROCEDURE  SetCharSize (CharSize:  SizeType); 

(*  Sets  character  size  for  subsequent  labels  *) 

PROCEDURE  SetLabelAngle (LabelRotation:  AngleType); 

(*  Sets  the  angle  of  rotation  of  subseqent  labels  *) 

PROCEDURE  SetLineType (LineTypeSelected:  LineType); 

(*  Sets  the  line  type  for  subsequent  Draw  commands  *) 

PROCEDURE  SetPenColor (PenColor:  ColorType) ; 

(*  Sets  the  pen  color  for  subsequent  output  *) 

PROCEDURE  SetBackgroundColor (BackgroundColor:  ColorType); 

(*  Sets  the  background  color  (screen  only)  *) 

PROCEDURE  SetLabelOrigin (LabelOrigin:  OriginType); 

(*  Determines  orientation  relative  to  current  position  with 
which  subsequent  labels  will  be  drawn  *) 

PROCEDURE  SetFixedDigits (XNumDigits, YNumDigits :  CARDINAL); 

(*  Sets  number  of  digits  to  right  of  decimal  point  for 
subsequent  DrawLabelledAxes  or  DrawLabelledGrid  *) 

PROCEDURE  ReturnRatio () :  REAL; 

(*  Returns  the  ratio  of  the  physical  dimensions  of  the 
plotting  area  of  the  current  device  *) 

PROCEDURE  SetFontType (FontTypeSelected:  FontType); 

(*  Sets  the  font  type  for  subsequent  label  commands  *) 

PROCEDURE  Draw (XCoord, YCoord:  REAL); 

(*  Draw  a  line  from  the  active  position  to  the  specified  coords  *) 
PROCEDURE  Move (XCoord, YCoord:  REAL); 

(*  Move  the  active  position  to  the  specified  coordinates  *) 

PROCEDURE  IncDraw (XIncr, YIncr :  REAL); 

(*  Do  an  incremental  draw  from  the  active  position  *) 

PROCEDURE  IncMove (XIncr, YIncr:  REAL); 

(*  Do  an  incremental  move  to  the  new  active  position  *) 

(*  In  the  following  set  of  axis  drawing  and  labelling  procedures, 
the  variables  XIntercept,  YIntercept,  XTicSpacing,  YTicSpacing 
XMin,  XMax,  YMin,  and  YMax  are  all  interpreted  according  to  the 
most  recent  SetUnits,  SetScaledArea,  and  Set  Scale  commands. 
MajorCount  is  an  integer  that  specifies  the  number  of  tic  intervals 
between  major  tic  marks.  In  DrawLabelledAxes  and  DrawLabelledGrid, 
if  MajorCount  is  positive,  tic  marks  are  drawn  perpendicular  to  the 
corresponding  axis;  if  negative,  tic  marks  are  parallel. 

MajorTicFrac  specifies  the  size  of  the  major  tics  as  a  percentage 
of  the  length  of  the  corresponding  axis.*) 

PROCEDURE  DrawXAxis (YIntercept, TicSpacing, XMin, XMax:  REAL; 

MajorCount:  INTEGER; 

MajorTicFrac:  REAL); 

(*  Draw  an  X-axis  from  XMin  to  XMax  at  the  specified  y-intercept*) 
PROCEDURE  DrawYAxis (XIntercept, TicSpacing, YMin, YMas:  REAL; 

MajorCount:  INTEGER; 

MajorTicFrac:  REAL); 

(*  Draw  a  Y-axis  from  YMin  to  YMax  at  the  specified  x-intercept*) 
PROCEDURE  DrawAxes (XIntercept, YIntercept, XTicSpacing, YTicSpacing:  REAL; 
XMa jorCount, YMa jorCount :  INTEGER; 

XMa jorTicFrac, YMa jorTicFrac:  REAL) ; 

(*  Draws  full-scale  axes  intersecting  at  XIntercept  and  YIntercept*) 
PROCEDURE  DrawGrid (XIntercept, YIntercept, XTicSpacing, YTicSpacing:  REAL; 
XMa jorCount, YMa jorCount:  INTEGER; 

XMinorTicFrac, YMinorTicFrac:  REAL) ; 

(*  Draws  a  full-scale  grid,  with  lines  spaced  symmetrically 
around  XIntercept, YIntercept  *) 

PROCEDURE  DrawLabel (LabelString:  ARRAY  OF  CHAR); 

(*  Writes  LabelString  at  the  current  active  position  according 

to  the  current  CharSize,  LabelOrigin,  and  LabelRotation  settings*) 
PROCEDURE  DrawLabelledAxes (XIntercept , YIntercept , XTicSpacing, 
YTicSpacing:  REAL; 

XMa jorCount, YMa jorCount :  INTEGER; 


XMa jorTicFrac, YMa jorTicFrac:  REAL) ; 

(*  Draws  a  pair  of  axes  in  the  same  manner  as  DrawAxes.  Puts 
labels  at  the  major  tic  marks  according  to  the  current 
CharSize,  XNumDigits,  and  YNumDigits  settings  *) 

PROCEDURE  DrawLabelledGrid (XIntercept , YIntercept , XTicSpacing, 

YTicSpacing:  REAL; 

XGridSpacing, YGridSpacing :  INTEGER; 

XMa jorTicFrac, YMa jorTicFrac:  REAL) ; 

(*  Draws  a  full-scale  grid  as  in  DrawGrid  and  labels  the  grid 
lines  as  in  DrawLabelledAxes  *) 

PROCEDURE  DrawFrame; 

(*  Draws  a  box  around  the  current  plotting  area  *) 

PROCEDURE  DrawSymbol (XCoord, YCoord:  REAL; 

Symbol:  SymbolType; 

Size:  REAL); 

(*  Draws  the  indicated  symbol  centered  at  XCoord, YCoord. 

Size  is  specified  in  mm  *) 

PROCEDURE  Where (VAR  XCoord, YCoord:  REAL); 

(*  Returns  the  coordinate  values  of  the  current  active  position*) 
PROCEDURE  NewScreen (Mode:  ModeType); 

(*  Clears  the  screen  and  sets  the  mode.  No  cursor  in  Menu  mode*) 
PROCEDURE  CloseGraphics; 

(*  Cleans  up  the  interrupts  and  restores  to  normal  *) 

END  ModPlot. 

End  Listing  One 


Listing  Two 

DEFINITION  MODULE  GDrlver; 

(*  Title  :  Low  Level  CRT  and  Plotter  Draw  module 
Author  :  Chris  Johnston 
System  :  Modula-2  Plotting  System 
Compiler:  LOGITECH  MODULA-2/86 
*) 

FROM  DataDefs  IMPORT  ModeType,  STRING80,  DevPresentType; 

EXPORT  QUALIFIED 

ReadDevices,  DrawAbs,  MoveAbs,  DrawString,  SetMode,  Cleanup; 

PROCEDURE  ReadDevices (VAR  DevicesPresent  :  DevPresentType); 

(*  Finds  out  what  devices  are  available:  EGA/CGA  and 
IBM7372A/IBM7372B/IBM7371.  An  HP  7470  is  reported 
as  an  IBM7371  and  the  HP  7475  is  reported  as  an 
IBM7372A  or  B  depending  upon  the  paper  size  selected  *) 

PROCEDURE  DrawAbs (XCoord,  YCoord  :  CARDINAL); 

(*  Draw  a  line  from  the  current  location  to  XCoord,  YCoord 

on  the  selected  device.  Line  type  and  color  read  from  system 
globals  *) 

PROCEDURE  MoveAbs (XCoord,  YCoord  :  CARDINAL); 

(*  Move  from  the  current  location  to  XCoord,  YCoord  on  the 
selected  device  with  the  pen  raised.  *) 

PROCEDURE  DrawString (XCoord,  YCoord  :  CARDINAL; 

LabelString  :  ARRAY  OF  CHAR) ; 

(*  Draw  the  character  string  LabelString  starting  at  XCoord,  YCoord. 

The  font,  color,  size,  and  rotation  are  selected  from  system 
globals  *) 

PROCEDURE  SetMode (  Mode  :  ModeType); 

(*  Set  the  mode  to  text  or  graphics  and  clear  the  screen.  This  call  has 
**  NO  EFFECT  **  if  the  selected  device  is  a  plotter  *) 

PROCEDURE  Cleanup; 

(*  clean  up  the  interrupt  drivers  and  the  character  set  at  the  end.  *) 

END  GDriver. 

End  Listing  Two 


Listing  Three 

DEFINITION  MODULE  DataDefs; 

(*  Title  :  Data  Definitions 
Author  :  Judy  Auping 
System  :  PC  Graphics 
Compiler:  LOGITECH  MODULA-2/86 
*) 

EXPORT  QUALIFIED 

DeviceType, UnitsType, SizeType, AngleType, LineType, ColorType, 
FontType,  OriginType, SymbolType, DevPresentType, ModeType, STRING80, 
GraphDevice, LineTypeSelected, CharSize, FontTypeSelected, 

PenColor, BackgroundColor, LabelRotation, DeviceXMax, DeviceYMax, 
Errorstring,  DriverError; 

TYPE 

DeviceType  =  (EGA, CGA, IBM7372A, IBM7372B, IBM7371) ; 

UnitsType  =  (User, Device) ; 

SizeType  =  (Small, Med, Large, XLarge) ; 

AngleType  =  (DegO, Deg45, Deg90, Degl35, Degl80, Deg225, Deg270, Deg315) ; 
LineType  =  (Solid,  EndPoint,  Dotted,  ShortDash,  LongDash) ; 
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ColorType  =  (Black, Blue, Green, Cyan, Red, Magenta, Brown, White, 

DarkGray, LightBlue, LightGreen, LightCyan, 

LightRed, LightMagenta, Yellow, IntensifiedWhite) ; 

FontType  =  (Standard, Italic) ; 

OriginType  =  (UpperRight,CenterRight, LowerRight, UpperMiddle, 
CenterMiddle, LowerMiddle, UpperLeft,  CenterLeft, 
LowerLeft) ; 

SymbolType  =  (Circle, Square, Triangle, Asterisk, Cross,  Plus) ; 
DevPresentType  =  ARRAY  DeviceType  OF  BOOLEAN; 

ModeType  =  (Graphics, Text, Menu) ; 

STRING80  =  ARRAY [0.. 79]  OF  CHAR; 

VAR 

GraphDevice:  DeviceType; 

LineTypeSelected:  LineType; 

CharSize:  SizeType; 

FontTypeSelected:  FontType; 

PenColor:  ColorType; 

BackgroundColor :  ColorType; 

LabelRotation:  AngleType; 

DeviceXMax, DeviceYMax:  CARDINAL; 

DriverError:  BOOLEAN; 

ErrorString:  STRING80; 

END  DataDefs. 

End  Listing  Three 


Listing  Four 

MODULE  Example; 

(*  Title:  Example  of  using  the  ModPlot  graphics  library 
Author:  Judy  Auping 
System:  PC  Graphics 
*) 

FROM  DataDefs  IMPORT 

DeviceType, SizeType, ColorType, OriginType; 

FROM  ModPlot  IMPORT 

Graphlnit, SetPlotArea, SetScaledArea, SetScale, DrawAxes, SetPenColor, 
Move, Draw, DrawFrame, NewScreen, CloseGraphics, SetLabelOrigin, DrawLabel, 
SetCharSize, IncDraw, SetPlotDevice; 

FROM  MathLibO  IMPORT  sin; 

FROM  InOut  IMPORT  Read, WriteString, WriteLn; 

TYPE 

CornerType  =  (UpLeft, UpRight, LowLeft, LowRight) ; 

CONST 

NPnts  =  1000;  pi  =  3.14159; 


VAR 

XValue:  ARRAY [1. .NPnts]  OF  REAL; 

YValue:  ARRAY  [UpLeft .. LowRight]  OF  ARRAY [1 . .NPnts]  OF  REAL; 

NumTerms:  ARRAY [UpLeft .. LowRight]  OF  CARDINAL; 

IPlot:  CornerType; 

IPnt, ITerm:  CARDINAL; 
x,NextTerm:  REAL; 

Input:  CHAR; 

PROCEDURE  GeneratePlot Arrays ; 

(*  This  procedure  generates  arrays  of  data  points  for  the  Fourier  series 
approximation  of  a  sawtooth  wave,  where 

y  =  2  (sin  x  -  sin(2x)/2  +  sin(3x)/3  -  sin(4x)/4  +  ...  ) 

The  XValue  array  contains  the  x  values  for  the  plot  in  units  of  pi,  where 
the  values  vary  from  zero  to  4pi. 

The  YValue  array  of  arrays  contains  four  arrays  of  y  values  for 
different  numbers  of  terms  in  the  summation  approximation.  *) 

BEGIN 

WriteString ("Generating  approximation  functions");  (*  Inform  user  *) 
NumTerms [UpLeft]  :=  5;  NumTerms [UpRight]  :=  10; 

NumTerms [LowLeft]  :=  20;  NumTerms [LowRight]  :=  100; 

FOR  IPnt  :=  1  TO  NPnts  DO 

IF  (IPnt  MOD  100) =0  THEN 

WriteString ("  .");  (*  Let  the  user  know  the  progress  of  *) 

END  (*  if  *);  (*  the  calculations.*) 

FOR  IPlot  :=  UpLeft  TO  LowRight  DO 

YValue[IPlot, IPnt]  :=  0.0;  (*  Initialize  the  terms.  *) 

END  (*  for  *); 

x  :=  FLOAT (IPnt)  *  (4.0  *  pi) /FLOAT (NPnts) ; 

XValue [IPnt]  :=  x/pi; 

FOR  ITerm  :=  1  TO  NumTerms [LowRight]  DO 

IF  (ITerm  MOD  2)=0  THEN  (*  even  terms  are  negative  *) 

NextTerm  :=  -2.0  *  sin (FLOAT (ITerm) *  x) /FLOAT (ITerm) ; 

ELSE  (*  odd  terms  are  positive,*) 

NextTerm  :=  2.0  *  sin (FLOAT (ITerm) *  x) /FLOAT (ITerm) ; 

END  (*  if  *); 

FOR  IPlot  :=  UpLeft  TO  LowRight  DO 
IF  ITerm<=NumTerms [IPlot]  THEN 
YValue [IPlot, IPnt]  :=  YValue [IPlot, IPnt]  +  NextTerm; 

END  (*  if  *); 

END  (*  for  *); 

END  (*  for  *); 

END  (*  for  *); 

END  GeneratePlotArrays;  (continued  OH  page  78) 
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MODULA-2 


Listing  Four  (Listing  continued,  text  begins  on  page  16.) 


BEGIN 

GeneratePlotArrays; 

Graphlnit; 

SetPlotDevice (IBM7372A) ; 

WriteLn;  WriteString ("Drawing  plot  .  .  (*Let  user  know  where  we  are*) 

FOR  IPlot  UpLeft  TO  LowRight  DO  (*Draw  a  plot  for  each  array*) 

CASE  IPlot  OF  (*  For  each  array,  choose  the  appropriate  plotting  area*) 
UpLeft : SetPlotArea {0 . 0, 45 . 0, 60 . 0, 100 . 0) ;  (*Upper  left  corner  *) 
SetScaledArea (5. 0,40. 0,62. 0,94.0) ; 

lUpRight:  SetPlotArea (55.0, 100.0, 60.0, 100.0) ;  (*Upper  right  corner*) 
SetScaledArea (60 . 0,  95. 0,  62 . 0, 94 . 0) ; 

I LowLeft: SetPlotArea (0. 0,45. 0,0. 0,40.0);  (*Lower  left*) 

SetScaledArea (5.0,40.0,2.0,34.0); 

I LowRight: SetPlotArea (55. 0,100. 0,0. 0,40.0);  (‘Lower  right*) 
SetScaledArea (60.0, 95 .0,2.0,34.0); 

END  ( *  case  * ) ; 

SetScale (0 . 0, 4 .0, -4 . 0, 4 . 0) ;  (*  remember,  x  is  in  units  of  pi  *) 
SetPenColor (Black) ; 

DrawAxes (0 . 0, 0 . 0, 1 . 0, 1 . 0, 2, 2, 3. 0, 2 . 0) ;  (*  draw  axes  without  labels  *) 

(*  Labels  are  drawn  separately  so  we  can  put  'pi'  on  x-axis  labels*) 
SetCharSize (Small) ;  (*  Label  the  axes  *) 

SetLabelOrigin(CenterLeft) ;  (*  First,  the  y-axis  *) 

Move(-0.05, 4.0) ;  DrawLabel ("4") ; 

Move (-0.05, 2.0) ;  DrawLabel ("2") ; 

Move (-0.05,0.0) ;  DrawLabel ("0") ; 

Move (-0 . 05, -2 . 0) ;  DrawLabel ( "-2" ) ; 

Move (-0.05, -4.0) ;  DrawLabel ("-4") ; 

SetLabelOrigin (LowerMiddle) ;  (*  Then  the  x-axis  *) 

Move (2.0, -0.5) ;  DrawLabel ("2pi") ; 

Move (4 . 0, -0.5) ;  DrawLabel ("4pi") ; 

CASE  IPlot  OF  (‘Set  a  new  pen  color  for  each  plot  *) 

UpLeft:  SetPenColor (Red) ; 

! UpRight :  SetPenColor (Green) ; 

! LowLeft:  SetPenColor (Blue) ; 

: LowRight :  SetPenColor (Magenta) ; 

END  ( *  case  * ) ; 

Move(0. 0,0.0) ;  (*  Start  at  the  origin  *) 

FOR  IPnt  :=  1  TO  NPnts  DO 

Draw(XValue[IPnt] ,YValue[IPlot, IPnt] ) ;  (‘Draw  to  each  point*) 

END  ( *  for  * ) ; 

SetPenColor (Black) ; 

DrawFrame;  (‘Draw  a  box  around  the  plot  for  this  array  *) 

Move (0.75,  4.7) ; 

SetLabelOrigin (CenterRight)  ; 

SetCharSize (Small)  ; 

CASE  IPlot  OF  (‘Put  the  appropriate  title  on  each  plot*) 

UpLeft:  DrawLabel ("5  terms  in  series"); 

! UpRight:  DrawLabel  ("10  terms  in  series"); 

; LowLeft : DrawLabel ("20  terms  in  series"); 

! LowRight: DrawLabel ("100  terms  in  series"); 

END  (*  case  *); 

END  (*  for  *); 

(‘Now  that  all  four  plots  have  been  drawn,  put  a  title  and 
the  formula  in  the  middle  area  on  the  page  *) 

SetPlotArea (0.0, 100. 0,0. 0,100.0);  (*  Set  to  full  screen  *); 

SetScaledArea (0.0, 100.0, 0.0, 100.0) ; 

SetScale (0.0, 100.0,0.0, 100.0) ; 

Move(9. 0,53.0) ; 

SetCharSize (Med) ; 

SetLabelOrigin (CenterRight) ; 

DrawLabel ("FOURIER  SERIES  APPROXIMATION  TO  A  SAWTOOTH  WAVE"); 

Move(17. 0,47.0); 

SetCharSize (Small) ; 

DrawLabel ("y  =  2  (sin(x)  -  sin(2x)/2  +  sin(3x)/3  -  sin(4x)/4  +  ...  }"); 

CloseGraphics;  (*  Clean  up  and  restore  the  system  *) 

END  Example. 


End  Listings 
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Listing  One  (Text  begins  on  page  26.) 

c 

PROGRAM  GLOBE 

C  PROGRAM  TO  DRAW  A  GLOBE  AT  A  USER  SPECIFIED  ANGLE  ON  A  GRAPHICS 

C  SURFACE.  INPUTS  ALSO  INCLUDE  LOCATION  OF  GRATING  LOBES  REFERENCED 

C  TO  LONGITUDE  AND  LATITUDE. 

AUTHOR:  SCIENTIFIC  CONCEPTS 

C  - 

IMPLICIT  NONE 
C 
C 

INTEGER* 2 
INTEGER* 2 
INTEGER* 2 
INTEGER* 2 
INTEGER*2 
INTEGER*2 
INTEGER*2 
INTEGER* 2 
INTEGER*2 
C 

REAL* 8 
REAL* 8 
REAL* 8 
REAL *8 
REAL* 8 
REAL *8 
REAL *8 
REAL *8 
REAL *8 
REAL *8 
REAL *8 
REAL *8 
REAL *8 
REAL *8 
C 

CHARACTER 
C 
C 

PARAMETER 
C 

TLU=6 
NUMLOBES=0 
PI-3. 14159265 
C 
C 

C  HORIZONTAL,  VERTICAL  ARE  COORDINATES  OF  ORIGIN 
C 


XPOS=HORI ZONTAL 

YPOS=VERTICAL+RADIUS* (SIN (ELEVATION) *COSCONVER 
+  -COS (ELEVATION) *SINCONVER) 

CALL  PLOT (XPOS, YPOS, PMOVE ) 

PENC=2 
DO  J-1,100 

AZIMUTH=J*2*PI/100.0 

IF  (SIN (ELEVATION) *SINCONVER+COS (ELEVATION) * 

+  COS ( AZ IMUTH ) *COSCONVER . GE . 0 . )  THEN 

XPOS=HORIZONTAL+RADIUS*COS (ELEVATION) *SIN (AZIMUTH) 
YPOS=VERTICAL+RADIUS* (SIN (ELEVATION) *COSCONVER 
+  -COS (ELEVATION) *COS (AZIMUTH) *SINCONVER) 

CALL  PLOT (XPOS, YPOS, PENC) 

PENC=2 
ELSE 
PENC=3 
END  IF 
END  DO 
END  DO 
C 

C  DRAW  LONGITUDES 
C 

DO  1=1,12 

AZIMUTH=I*PI/12 

YPOS=VERTICAL+RAD IUS  *COSCONVER 
CALL  PLOT (HORIZONTAL, YPOS, PMOVE) 

PENC=2 

DO  J-1,100 

ELEVATION=PI/2-J*2*PI/100 

IF  (SIN (ELEVATION) *SINCONVER+COS (ELEVATION) * 

+  COS (AZIMUTH) *COSCONVER.GE.O.)  THEN 

XPOS=HORI ZONTAL+RAD IUS  *COS (ELEVATION) *SIN (AZIMUTH) 
YPOS=VERTICAL+RADIUS* (SIN (ELEVATION) *COSCONVER 
+  -COS (ELEVATION) *COS (AZIMUTH) *SINCONVER) 

CALL  PLOT (XPOS, YPOS, PENC) 

PENC=2 
ELSE 
PENC-3 
END  IF 
END  DO 
END  DO 
C 
C 

C  DRAW  GRATING  LOBES 
C 

IF  (NUMLOBES.GT.O)  THEN 
DO  I=l,NUMLOBES 

XPOS=HORIZONTAL+GRLOBEX (I) +RADIUS 
YPOS=VERTICAL+GRLOBEY (I) 

CALL  PLOT (XPOS, YPOS, PMOVE) 


I 

ILOOP  COUNTER 

J 

! LOOP  COUNTER 

PMOVE 

! PEN  CONTROL  MOVE  COMMAND 

PDRAW 

!PEN  CONTROL  DRAW  COMMAND 

PENC 

! PEN  CONTROL:  2 -DRAW, 3 -MOVE 

TLU 

! TERMINAL  LOGICAL  UNIT  NUMBER 

ROW 

!TEXT  ROW  POSITION 

COLUMN 

!TEXT  COLUMN  POSITION 

NUMLOBES 

! NUMBER  OF  GRATING  LOBES  REQUESTED 

GRLOBEX (10) 

!X  LOCATION  FOR  GRATING  LOBE 

GRLOBEY (10) 

! Y  LOCATION  FOR  GRATING  LOBE 

XPOS 

! HORIZONTAL  PIXEL  POSITION 

YPOS 

! VERTICAL  PIXEL  POSITION 

HORIZONTAL 

! CALCULATED  HORIZONTAL  PIXEL  POSITION 

VERTICAL 

! CALCULATED  VERTICAL  PIXEL  POSITION 

RADIUS 

! RADIUS  OF  GLOBE  CIRCLE 

TILT 

!TILT  ANGLE  FOR  GLOBE 

PI 

! PI  CONSTANT 

COSCONVER 

!COS  CONVERSION  OF  TILT  IN  RADIANS 

SINCONVER 

! SIN  CONVERSION  OF  TILT  IN  RADIANS 

ELEVATION 

! CALCULATED  LONGITUDE  POSITION 

AZIMUTH 

! CALCULATED  LATITUDE  POSITION 

GLOBEINC 

! GRATING  LOBE  INCREMENT  (RADIANS) 

STEMP *8 

! TEMPORARY  STRING 

(PMOVE=3, PDRAW= 

=2) 

WRITE (TLU, *) 'ENTER  ORIGIN  COORDINATES  (TRY  300,200  FOR  EGA/VGA) ' 
READ (TLU, *) HORIZONTAL, VERTICAL 
C 

WRITE (TLU, *) 'ENTER  RADIUS  OF  CIRCLE  (TRY  160  FOR  EGA/VGA) ' 

READ (TLU,*) RADIUS 
C 

WRITE (TLU, *) 'ENTER  TILT  ANGLE  IN  DEGREES  (TRY  30)' 

READ (TLU,*) TILT 
C 

WRITE (TLU,*) 'HOW  MANY  GRATING  LOBES  (MAXIMUM=10)  ?  ' 

READ (TLU, *)NUMLOBES 
C 

IF  (NUMLOBES.GT. 10)  THEN 

WRITE (TLU, *) '  ERROR:  TOO  MANY  GRATING  LOBES  REQUESTED!' 

STOP 

ELSE  IF  (NUMLOBES.GT.O)  THEN 
DO  1=1 , NUMLOBES 

WRITE (TLU,*) 'ENTER  (X,Y)  COORDINATES  FOR  POINT  ',1 
READ ( TLU , * ) GRLOBEX (I)  , GRLOBEY ( I ) 

END  DO 
END  IF 
C 

C  INITIALIZE  IBM  PC  TO  MAXIMUM  RESOLUTION  ... 

C 

CALL  GINIT (TLU) 

C 

C  DRAW  '+'  AT  ORIGIN 
C 

XPOS=HORI ZONTAL- 4 . 5 

CALL  PLOT (XPOS, VERTICAL, PMOVE) 

XPOS=HORIZONTAL+4 . 5 

CALL  PLOT (XPOS, VERTICAL, PDRAW) 

YPOS=VERTICAL-3 . 6 

CALL  PLOT (HORIZONTAL, YPOS, PMOVE) 

YPOS=VERTICAL+3 . 9 

CALL  PLOT (HORIZONTAL, YPOS, PDRAW) 

C 

C  LABEL  FIGURE  WITH  PARAMETERS 
C 

ROW=24 

COLUMN-26 

WRITE (STEMP,  '  (F6.2)')TILT 

CALL  TEXTLABEL (ROW, COLUMN, 'TILT  ANGLE  (DEGREES) =' //STEMP) 

C 

C  DRAW  OUTER  CIRCLE 

C 

CALL  PLOT (HORIZONTAL+RADIUS, VERTICAL, PMOVE) 

DO  1=1,100 

XPOS=HORI ZONTAL+RAD IUS  *  COS (I*2*PI/100) 

YPOS=VERTICAL+RADIUS*SIN (I*2*PI/100) 

CALL  PLOT (XPOS, YPOS, PDRAW) 

END  DO 
C 

C  DRAW  LATITUDES 

C 

TILT=TILT*PI/180 . 0 
COSCONVER=COS (TILT) 

SINCONVER=SIN (TILT) 

C 


C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 


c 

c 

c 

c 

c 

c 


c 


c 

c 

c 

c 

c 

c 

c 


DO  J-1,100 

GLOBEINC=J*PI/50 

XPOS-HORI ZONTAL+GRLOBEX ( I ) +RADIUS  *COS (GLOBE INC+ . 04 ) 

YPOS -VERT I CAL+GRLOBE Y ( I ) +RADIUS*SIN (GLOBEINC+ . 04 ) 

IF ( (GRLOBEX ( I ) +RADIUS*COS (GLOBEINC) ) *  *2+ 

+  (GRLOBEY (I) +RADIUS*SIN (GLOBEINC) ) **2 .LT.RADIUS**2)  THEN 

CALL  PLOT (XPOS, YPOS, PDRAW) 

ELSE 

CALL  PLOT (XPOS, YPOS, PMOVE) 

END  IF 
END  DO 
END  DO 
END  IF 


PREPARE  TO  EXIT  GRAPHICS  AND  RETURN  TO  NORMAL  VIDEO  . . . 
CALL  EXITGRAPHICS (TLU) 

END 


INCLUDE  'FGRAPH.FI' 


SUBROUTINE  TEXTLABEL (ROW, COLUMN, STRING) 
************************************************************** 
SUBROUTINE  TO  WAIT  FOR  USER  SIGNAL  AND  EXIT  GRAPHICS  MODE.  TERMINAL 
IS  RESTORED  TO  PRE-VIDEO  CONDITIONS... 


IMPLICIT  NONE 
INCLUDE  ' FGRAPH.FD' 


INTEGER*2 

ROW 

!  TEXT 

ROW  POSITION 

INTEGER*2 

COLUMN 

!TEXT 

COLUMN 

POSITION 

CHARACTER 

STRING* (*) 

!TEXT 

STRING 

FOR  LABEL 

RECORD  /RCCOORD/  CURPOS 


OUTPUT  USER  SUPLIED  STRING  AT  ROW, COLUMN  ... 

CALL  SETTEXTPOSITION (ROW, COLUMN, CURPOS) 

CALL  OUTTEXT (STRING) 

RETURN 

END 


SUBROUTINE  EXITGRAPHICS (TLU) 


SUBROUTINE  TO  WAIT  FOR  USER  SIGNAL  AND  EXIT  GRAPHICS  MODE.  TERMINAL 
IS  RESTORED  TO  PRE-VIDEO  CONDITIONS... 


IMPLICIT  NONE 


DO  1=1,12 

ELEVATION=PI/2-PI/12*I 


(continued  on  page  82) 
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PORTING  FORTRAN 


Listing  One  (Listing  continued,  text  begins  on  page  26.) 

c 


c 


c 


INCLUDE  ' FGRAPH.FD' 

INTEGER*2  TLU 

INTEGER*2  DUMMY 

INTEGER*2  ROW 

INTEGER*2  COLUMN 

ROW=2  5 
COLUMN=28 


! TERMINAL  LOGICAL  UNIT  NUMBER 
! DUMMY  FUNCTION  ARGUMENT 
! TEXT  ROW  POSITION 
! TEXT  COLUMN  POSITION 


OUTPUT  PROMPT  AND  WAIT  FOR  ENTER  KEY  ... 


CALL  TEXTLABEL (ROW, COLUMN, 'PRESS  ENTER  TO  CONTINUE') 
READ (TLU,*) 

C 

C  RESET  VIDEO  MODE  AND  STOP 
C 

DUMMY=SETVIDEOMODE ($DEFAULTMODE) 

C 


C 

C 

C 

C 

C 

C 

c 

c 

c 


c 


c 


c 

c 

c 

c 

c 


c 


c 


c 

c 

c 

c 

c 

c 

c 

c 


RETURN 

END 


SUBROUTINE  GINIT (TLU) 


SUBROUTINE  TO  INITIALIZE  IBM  PC  GRAPHICS  MODE  TO  MAXIMUM 
AVAILABLE  RESOLUTION  ... 


IMPLICIT  NONE 


INCLUDE  'FGRAPH.FD' 


INTEGER*2 

ERRC 

(ERROR 

CODE  RETURNED 

INTEGER*2 

TLU 

(TERMINAL  LOGICAL  UNIT  NUMBER 

INTEGER*2 

DUMMY 

(DUMMY 

FUNCTION  ARGUMENT 

LOG I CAL *2 

WINDINVERT 

(INVERT  WINDOW  COORDINATES  IF  TRUE 

REAL* 8 

LOWERX 

(LOWER 

X  AXIS  CORNER  OF  WINDOW 

REAL *8 

LOWERY 

(LOWER 

Y  AXIS  CORNER  OF  WINDOW 

REAL *8 

UPPERX 

(UPPER 

X  AXIS  CORNER  OF  WINDOW 

REAL *8 

UPPERY 

! UPPER 

Y  AXIS  CORNER  OF  WINDOW 

INITIALIZE  VIDEO  MODE  TO  MAXIMUM  RESOLUTION  AVAILABLE 

ERRC=SETVIDEOMODE ($MAXRESMODE) 

IF  (ERRC.EQ.O)  THEN 

WRITE (TLU,*)'  ERROR:  CANNOT  SET  VIDEO  MODE' 

STOP 
END  IF 


LOWERX=-3 . 0 
LOWERY=3 . 0 
UPPERX=-3 . 0 
UPPERY=3 . 0 
WINDINVERT= . TRUE . 

DUMMY=SETWINDOW (WINDINVERT, LOWERX, LOWERY,  UPPERX,  UPPERY) 

RETURN 

END 


SUBROUTINE  PLOT (XPOS, YPOS, PENC) 


SUBROUTINE  TO  DRAW  OR  MOVE  TO  THE  USER  SPECIFIED  POSITION  'XPOS, 
YPOS'  WITH  PEN  CONTROL  AS  DESIGNATED  BY  'PENC'. 


IMPLICIT  NONE 


C 


C 


C 

c 


INCLUDE  'FGRAPH.FD' 

INTEGER* 2  DUMMY 

INTEGER* 2  PENC 

REAL* 8  XPOS 

REAL* 8  YPOS 

RECORD  /WXYCOORD/  XY 

IF  (PENC.EQ.2)  THEN 

DUMMY=LINETO_W (XPOS,  YPOS) 
ELSE 

CALL  MOVETO_W (XPOS,  YPOS,  XY) 
END  IF 


(DUMMY  FUNCTION  ARGUMENT 
(PEN  CONTROL:  2=DRAW, 3=MOVE 

(HORIZONTAL  PIXEL  POSITION 
(VERTICAL  PIXEL  POSITION 


C 


RETURN 

END 


Listing  Two 

Top  Level  Fragment 


PROGRAM  GLOBE 

C  ********************************************************** 

C 

C  PROGRAM  TO  DRAW  A  GLOBE  AT  A  USER  SPECIFIED  ANGLE  ON  A  GRAPHICS 
C  SURFACE.  INPUTS  ALSO  INCLUDE  LOCATION  OF  GRATING  LOBES  REFERENCED 
C  TO  LONGITUDE  AND  LATITUDE. 

C  AUTHOR:  SCIENTIFIC  CONCEPTS 
C 


CALL  GINIT  (INITIALIZE  GRAPHICS  DEVICE 


Layer  3:  Graphics  Primitives 


SUBROUTINE  GINIT 

C*** *************************************************** *c 

C  PURPOSE:  INITIALIZE  GRAPHICS  DEVICE  CURRENTLY 
C  SET  BY  GLOBAL  VARIABLE  'DEVICETYPE'  ... 


IF  (DEVICETYPE. EQ.HPGL)  THEN 
CALL  HPGLINIT 

ELSE  IF  (DEVICETYPE. EQ.IBMPC)  THEN 
CALL  IBMPCINIT 

ELSE  IF  ( DEVICETYPE . EQ . TEK )  THEN 
CALL  TEKINIT 

ELSE  IF  (DEVICETYPE. EQ.DECVT)  THEN 
CALL  DECVTINIT 

ELSE  IF  (DEVICETYPE. EQ.VAXSTA)  THEN 
CALL  VAXSTAINIT 


(HP  GRAPHICS  DEVICE 
(IBM  MODES  CGA-VGA 
(TEKTRONIX  DEVICES 
(DEC  VT340 

(DEC  VAXSTATION  2000 


ELSE 

CALL  INITERROR 
END  IF 


Layer  2:  Graphics  Device  Drivers 


c** 

C** 

c 

c 


*****************************************************c 
SUBROUTINE  IBMPCINIT 

PURPOSE:  INITIALIZE  CURRENT  IBM  PC  GRAPHICS  MODE 
COLORS,  RESOLUTION  ETC  ... 


C 

IF  ( I BMMODE . EQ . EGACOLOR )  THEN 
DUMMY=SETVIDEOMODE (SERESCOLOR) 
ELSE  IF  ( IBMMODE. EQ. HERCULES)  THEN 
DUMMY=SETVIDEOMODE ($HERCMONO) 


END  IF 
C 

RETURN 

END 

C 

c*******************************************************c 
SUBROUTINE  VAXSTAINIT 

C  PURPOSE:  INITIALIZE  VAXSTATION  200  GRAPHICS  DEVICE 
C  MODE,  VIEWPORT  . . . 


C 


C 


LOWLX=l . 0 
LOWLY=l . 0 
UPPRX=20 . 0 
UPPRY=20 . 0 
DISPWIDTH=20 . 0 
DISPHEIGHT=20 . 0 


(LOWER  LEFT  X  COORDINATE 
(LOWER  LEFT  Y  COORDINATE 
(UPPER  RIGHT  X  COORDINATE 
(UPPER  RIGHT  Y  COORDINATE 


VD_ID=UIS$CREATE_DISPLAY (LOWLX, LOWLY, UPPRX, UPPRY, 
+  DISPWIDTH, DISPHEIGHT) 

WD_ID=UIS$CREATE_WINDOW (VD_ID, ' SYS$WORKSTATION' ) 


RETURN 

END 

C 

C 


End  Listing  One 


End  Listings 
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PERSISTENT  OBJECTS 


Listing  One  (Text  begins  on  page  36.) 


UNIT  Shapes; 
INTERFACE 

USES  Graph,  Crt; 
TYPE 


{ - Shape  class - } 

Shape  =  OBJECT 
Color  :  BYTE; 

PROCEDURE  Draw;  VIRTUAL; 

END; 

ShapePtr  =  AShape; 

{ - Box  class - } 

Box  =  OBJECT  (Shape) 

LowerRightX,  LowerRightY  :  INTEGER; 

UpperLeftX,  UpperLeftY  :  INTEGER; 

CONSTRUCTOR  Create (ulx,  uly,  lrx,  lry,  c  :  INTEGER); 
PROCEDURE  Draw;  VIRTUAL; 

END; 


{ - Ring  class - ) 

Ring  =  OBJECT  (Shape) 

Xcenter,  Ycenter  :  INTEGER; 

Radius  :  INTEGER; 

CONSTRUCTOR  Create (x,  y,  rad,  c  :  INTEGER); 
PROCEDURE  Draw;  VIRTUAL; 

END; 


IMPLEMENTATION 


Shape  methods 


PROCEDURE  Shape. Draw; 

BEGIN 

(  Does  nothing;  it's  a  virtual  method  place-holder  ) 

END; 


Box  methods 


CONSTRUCTOR  Box. Create (ulx,  uly,  lrx,  lry, 
BEGIN 


UpperLeftX 

UpperLeftY 

LowerRightX 

LowerRightY 

Color 

END; 


=  ulx; 
=  uly; 
=  lrx; 
=  lry; 
=  c; 


PROCEDURE  Box. Draw; 

BEGIN 

SetColor (Color)  ; 

Rectangle (UpperLeftX,  UpperLeftY,  LowerRightX,  LowerRightY); 


- Ring  methods - } 

CONSTRUCTOR  Ring. Create (x,  y,  rad,  c  :  INTEGER); 
BEGIN 

Xcenter  :=  x; 

:=  y; 

:=  rad; 


Color 

END; 


Ycenter 
Radius 
:=  c; 


PROCEDURE  Ring. Draw; 

BEGIN 

SetColor (Color)  ; 

Circle (Xcenter,  Ycenter,  Radius); 

END; 

END.  {  UNIT  Shapes  } 

Listing  Two 

PROGRAM  Programl; 

USES  Graph,  Crt,  Shapes; 

VAR 

R  :  Ring; 

B  :  Box ; 

GrDriver,  GrMode,  GrResult  :  INTEGER; 
ch  :  CHAR; 

PROCEDURE  DrawShape(s  :  ShapePtr); 

BEGIN 

sA .Draw; 

END; 

BEGIN 

R. Create(100, 100, 90,2); 

B. Create (25, 10, 175, 175, 4) ; 

GrDriver  :=  DETECT; 

InitGraph (GrDriver, GrMode, 'd:\tp' ) ; 


End  Listing  One 


GrResult  :=  GraphResult; 

IF  GrResult  <>  GrOK  THEN 
BEGIN 

WriteLn ( ' Unable  to  initialize  BGI:  error  ',grResult); 
Halt  (1)  ; 

END; 

DrawShape (@R) ; 

DrawShape (@B) ; 

REPEAT  UNTIL  KeyPressed; 

Ch  :=  ReadKey; 

CloseGraph; 


End  Listing  Two 


Listing  Three 

PROGRAM  Program2; 

USES  Graph,  Crt,  Shapes; 

VAR 

Rl,  R2  :  Ring; 

Bl,  B2  :  Box; 

F  :  FILE; 

GrDriver,  GrMode,  GrResult  :  INTEGER; 
ch  :  CHAR; 

BEGIN 

Rl .Create (100, 100, 90, 2) ; 

R2 .Create (0, 0, 0,0) ; 

Bl .Create (25, 10, 175, 150, 4) ; 

B2. Create (0,0, 0,0,0) ; 

GrDriver  :=  DETECT; 

InitGraph (GrDriver, GrMode, 'd:\tp' ) ; 

GrResult  :=  GraphResult; 

IF  GrResult  <>  GrOK  THEN 
BEGIN 

WriteLn ('Unable  to  initialize  BGI:  error  ',grResult); 
Halt  (1) ; 

END; 

Assign (F, ' shapes . fil' ) ; 

Rewrite (F, 1) ; 


BlockWrite (F,R1, SizeOf (Rl) ) ; 
BlockWrite (F,B1, SizeOf (Bl) ) ; 


Assign (F, ' shapes . fil' ) ; 

Reset (F,l); 

BlockRead(F, R2,  SizeOf (R2) ) ; 
BlockRead(F, B2,  SizeOf (B2) ) ; 

R2 .Draw; 

B2 .Draw; 

REPEAT  UNTIL  KeyPressed; 
Ch  :=  ReadKey; 

Close (F); 

CloseGraph; 


Listing  Four 

UNIT  Shapes; 

INTERFACE 

USES  Graph,  Crt; 

TYPE 

{ -  Shape  class  - ) 

Shape  =  OBJECT 
Color  :  BYTE; 

PROCEDURE  Draw;  VIRTUAL; 

PROCEDURE  FWrite (VAR  f  :  FILE);  VIRTUAL; 
PROCEDURE  FRead (VAR  f  :  FILE);  VIRTUAL; 
END; 

ShapePtr  =  AShape; 


End  Listing  Three 


( - Box  class - 

Box  =  OBJECT  (Shape) 

UpperLeftX,  UpperLeftY 
LowerRightX,  LowerRightY 


INTEGER; 

INTEGER; 


CONSTRUCTOR  Create (ulx,  uly,  lrx,  lry, 
PROCEDURE  Draw;  VIRTUAL; 


( continued  on  page  86) 
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PERSISTENT  OBJECTS 


Listing  Four  (Listing  continued,  text  begins  on  page  36.) 

PROCEDURE  FWrite (VAR  f  :  FILE);  VIRTUAL; 

PROCEDURE  FRead (VAR  f  :  FILE);  VIRTUAL; 

END; 

( - Ring  class - ) 

Ring  =  OBJECT  (Shape) 

Xcenter,  Ycenter  :  INTEGER; 

Radius  :  INTEGER; 

CONSTRUCTOR  Create (x,  y,  rad,  c  :  INTEGER); 

PROCEDURE  Draw;  VIRTUAL; 

PROCEDURE  FWrite (VAR  f  :  FILE);  VIRTUAL; 

PROCEDURE  FRead (VAR  f  :  FILE);  VIRTUAL; 

END; 


IMPLEMENTATION 

{ -  Shape  methods  - } 

PROCEDURE  Shape. Draw; 

BEGIN 

END; 

PROCEDURE  Shape. FWrite (VAR  f  :  FILE); 

BEGIN 

END; 

PROCEDURE  Shape. FRead (VAR  f  :  FILE); 

BEGIN 

END; 


{ - Box  methods - } 

CONSTRUCTOR  Box. Create (ulx,  uly,  lrx,  Iry,  c  :  INTEGER); 

BEGIN 

UpperLeftX  :=  ulx; 

UpperLeftY  :=  uly; 

LowerRightX  :=  lrx; 

LowerRightY  :=  lry; 

Color  :=  c; 

END; 

PROCEDURE  Box. Draw; 

BEGIN 

SetColor (Color) ; 

Rectangle (UpperLeftX,  UpperLeftY,  LowerRightX,  LowerRightY); 

END; 

PROCEDURE  Box. FWrite (VAR  f  :  FILE); 


BEGIN 

BlockWrite (f,  Color,  SizeOf (INTEGER) ) ; 

BlockWrite(f, UpperLeftX,  SizeOf (INTEGER) ) ; 

BlockWrite (f, UpperLeftY,  SizeOf (INTEGER) ) ; 

BlockWrite (f, LowerRightX, SizeOf (INTEGER) )  ; 

BlockWrite (f, LowerRightY, SizeOf (INTEGER) ) ; 

END; 

PROCEDURE  Box. FRead (VAR  f  :  FILE); 

BEGIN 

BlockRead(f, Color,  SizeOf (INTEGER) ) ; 

BlockRead (f , UpperLeftX,  SizeOf ( INTEGER) ) ; 

BlockRead(f, UpperLeftY,  SizeOf (INTEGER) ) ; 

BlockRead (f, LowerRightX,  SizeOf (INTEGER) ) ; 

BlockRead (f, LowerRightY, SizeOf (INTEGER) ) ; 

END; 

{ - Ring  methods - } 

CONSTRUCTOR  Ring . Create (x,  y,  rad,  c  :  INTEGER); 

BEGIN 

Xcenter  :=  x; 

Ycenter  :=  y; 

Radius  :=  rad; 

Color  :=  c; 

END; 

PROCEDURE  Ring. Draw; 

BEGIN 

SetColor (Color) ; 

Circle (Xcenter,  Ycenter,  Radius); 

END; 

PROCEDURE  Ring. FWrite (VAR  f  :  FILE) ; 

BEGIN 

BlockWrite(f, Color,  SizeOf (INTEGER) ) ; 

BlockWrite (f, Xcenter,  SizeOf (INTEGER) ) ; 

BlockWrite (f, Ycenter,  SizeOf (INTEGER) ) ; 

BlockWrite (f, Radius,  SizeOf (INTEGER) ) ; 

END; 

PROCEDURE  Ring. FRead (VAR  f  :  FILE) ; 

BEGIN 

BlockRead ( f, Color,  SizeOf (INTEGER) ) ; 

BlockRead (f, Xcenter,  SizeOf (INTEGER) ) ; 

BlockRead (f, Ycenter,  SizeOf (INTEGER) ) ; 

BlockRead (f, Radius,  SizeOf (INTEGER) ) ; 

END; 

END.  I  UNIT  Shapes  )  End  Listing  Four 


Listing  Five 

PROGRAM  Program3; 

USES  Graph,  Crt,  Shapes; 


Rl,  R2  :  Ring; 

Bl,  B2  :  Box; 

F  :  FILE; 

GrDriver,  GrMode,  GrResult  :  INTEGER; 
ch  :  CHAR; 

BEGIN 

Rl. Create (100, 100, 90,2); 

R2 . Create ( 0 , 0 , 0 , 0 ) ; 

Bl. Create (25, 10, 175,150,4) ; 

B2 .Create (0, 0, 0, 0, 0) ; 

GrDriver  :=  DETECT; 

InitGraph (GrDriver, GrMode, 'd:\tp' ) ; 

GrResult  :=  GraphResult; 

IF  GrResult  <>  GrOK  THEN 
BEGIN 

WriteLn(' Unable  to  initialize  BGI:  error  ',grResult); 

Halt  (1) ; 

END; 

Assign (F, ' shapes. fil' ) ; 

Rewrite (F, 1) ; 

Rl. FWrite (F) ; 

Bl. FWrite (F) ; 

Close (F) ; 

Assign (F, ' shapes . fil' ) ; 

Reset (F, 1) ; 

R2. FRead (F) ; 

B2. FRead (F) ; 

R2 .Draw; 

B2 .Draw; 

REPEAT  UNTIL  KeyPressed; 

Ch  :=  ReadKey; 

Close (F) ; 

CloseGraph; 

End  Listings 
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FAST  SEARCH 


Listing  One  (Text  begins  on  page  42.) 


FUNCTION  FASTSRCH!  (BuffFile%,  RecLen!,  KeyLoc%,  KeyVal$,  StartRec%, 

LastRec%,  FoundRecs% () ) 

CONST  physbufflen%  =  10000 

DIM  FarBuff (Dum%)  AS  STRING  *  physbufflen  '*  string  buffer  in  the  far  heap 
MaxFound%  =  UBOUND (FoundRecs%)  '*  can  only  find  as  many  as  array  will  hold 
NumMatches!  =0  ' *  initialize  the  number  of  matches  found 


IF  KeyLoc%  =  RecLen%  THEN 
CompByte%  =  0  :  LastByte%  =  -1 
ELSE 

CompByte%=KeyLoc%  :  LastByte%=0 
END  IF 


if  key  is  the  last  byte  in  the  record: 
modulo  position  to  check  will  be  0 
and  when  calculating  record  number 
of  the  matching  record, 

1  must  be  subtracted 


RecsPerRead%  =  physbufflen  \  RecLen! 

'*  calc,  the  #  of  records  scanned  with  each  disk  read 
BuffLen!  =  RecsPerRead!  *  RecLen% 

' *  the  actual  number  of  bytes  in  the  buffer  being  used 
CurRec!  =  StartRec%  ' *  initialize  CurRec 

DO  ' *  OUTER  LOOP  *  This  loop  executes  for  each  disk  read 

BuffByteS  =  { (CurRec%  -  1&)  *  RecLen%)  +1  '*  first  byte  in  next  buffer 

GET  BuffFile%,  BuffByte&,  FarBuff (0)  '  *  perform  the  actual  disk  i/o 

Match%  =0  '  *  initialize  match  to  false 


IF  CurRec%  +  RecsPerRead%  -  1  >  LastRec!  THEN 

BuffLen!  =  (LastRec%  -  CurRec%  +1)  *  RecLen% 
END  IF 


when  the  last  disk 
read  goes  past  the 
number  of  records 
to  search,  shorten 
the  number  of  bytes 
in  buffer  to  scan 


' *  MIDDLE  LOOP  *  Loops  for  each  match  found  in  this  buffer 
DO  '*  INNER  LOOP  *  Loops  for  each  "false"  match 
Match%  =  INSTR (Match%  +  1,  FarBuff (0),  KeyVal$) 

Match%  >  BuffLen!  THEN  Match%  =  0 

'*  if  match  was  past  valid  data,  ignore  the  match 
IF  Match%  =  0  THEN  EXIT  DO  ' *  no  more  matches  in  this  buffer 
LOOP  WHILE  Match!  MOD  RecLen!  <>  CompByte! 

' *  keep  searching  if  the  match  was  in  the  wrong  position 
IF  Match!  >  0  AND  NumMatches!  <  MaxFound!  THEN 

'*  if  a  match  and  the  array  isn't  full 
NumMatches!  =  NumMatches!  +  1 

'  *  add  into  the  array  of  found  records 
FoundRecs! (NumMatches!)  =  _ 

((Match!  +  LastByte!)  \  RecLen!)  +  CurRec! 

'*  CALCULATE  THE  ACTUAL  RECORD  NUMBER  * 


END  IF 

LOOP  UNTIL  Match!  =0  ' *  no  more  matches  in  this  buffer,  exit  loop 

CurRec!  =  CurRec!  +  RecsPerRead!  '*  calc,  first  record  of  next  buffer 
LOOP  UNTIL  CurRec!  >  LastRec!  '*  if  1st  rec.  of  next  buffer  is  >  number 
'  *  of  recs  to  search  then  were  finished 
FASTSRCH!  =  NumMatches!  ' *  set  return  value  =  number  of  matches 

END  FUNCTION 


End  Listing  One 


Listing  Two 


DECLARE  FUNCTION  InstrASM!  (BYVAL  BuffSeg!,  BYVAL  BuffOff!,  BYVAL  BuffLen!,_ 
BYVAL  KeySeg!,  BYVAL  KeyOff!,  BYVAL  KeyLen!,  BYVAL  RecLen!) 

FUNCTION  InstrR!  (StRec!,  Buff()  AS  STRING  *  10000,  KeyVal$,  RecLen!, 

KeyPos!)  STATIC 


KeyLen!  =  LEN (KeyVal$) 
StartingOffs!  =■  ((StRec!  -  1) 


Get  the  length  of  the  key 


RecLen!)  +  KeyPos!  -  1 

' *  Calculate  the  1st  byte  to  search 
BuffLen!  =  LEN (Buff  (0))  -  StartingOffs!  '*  Calculate  #  of  bytes  to  search 
BuffSeg!  =  SSEG(Buff (0) )  '*  Locate  the  buffer's  segment 

BuffOff!  =  SADD (Buff (0) )  +  StartingOffs!  '*  and  offset. 


KeySeg! 

KeyOff! 


SSEG (KeyVal$) 
SADD (KeyValS) 


Locate  the  key's  segment 
and  offset. 


FoundPos!  =  InstrASM! (Buf fSeg!,  BuffOff!,  BuffLen!,  _ 
KeySeg!,  KeyOff!,  KeyLen!,  RecLen!) 


Perform  a  search 


IF  FoundPos!  =  0  THEN  ' *  If  no  match, 

InstrR!  =0  '*  set  the  record  number  to  0 

ELSE  ' *  otherwise  calculate  the  record  number 

InstrR!  =  (FoundPos!  +  StartingOffs!  +  RecLen!  -  1)  \  RecLen! 

END  IF 

END  FUNCTION 


End  Listing  Two 


Listing  Three 


.MODEL  MEDIUM,  BASIC 
.CODE 

INSTRASM  PROC 


PUSHF 

MOV 

MOV 

MOV 

MOV 

MOV 

MOV 

MOV 

ADD 

SUB 

CLD 

FinishedYet: 

CMP 

JA 

MOV 

MOV 

MOV 


ADD 

JMP 

NoMoreBuf f : 

XOR 

JMP 


USES  DS  SI  DI,  BuffSeg, Buff StartAdd, BuffLen, KeySeg,  \ 
KeyAddr, KeyLen, RecLen 


BX, BuffSeg 
ES,  BX 
BX, KeySeg 
DS,  BX 
AX, RecLen 
DX, BuffLen 
BX, Buff StartAdd 
DX,  BX 
DX,  1 


BX,  DX 

NoMoreBuf f 
DI,  BX 

SI, KeyAddr 
CX, KeyLen 


BX,  AX 

FinishedYet 


MOV 

SUB 

ADD 


POPF 

RET 


AX,  AX 
TheEnd 


AX,  BX 

AX, Buf fStartAdd 
AX,  1 


Move  the  Buffer  Segment 

into  the  EXTRA  SEGMENT  REGISTER 
Move  the  Key  String  Segment 

into  the  DATA  SEGMENT  REGISTER 
Move  the  Record  Length  to  AX 
Move  the  Length  of  the  Buffer  to  DX 
Move  Buffer  Starting  Address  to  BX 
Add  Buffer  Offset (BX)  to  Buffer  Length (DX) 
and  subtract  1  for  End  of  Buffer  Address 
Clear  the  direction  flag 


Next  Record  Address>End  Of  Buffer  Address? 
if  so,  quit. 

Move  Next  Record  Address  to  Dest.  Index 
Move  Key  Address  to  Source  Index 
Move  Key  Length  to  CX  as  REPE  counter 

Compare  strings  and  if  equal 

go  to  Match  (*  can  use  JA  or  JB  to  alter  *) 

Add  Record  Length (AX)  to  Next  Record  Address 
Loop  back  and  continue  checking  for  a  match 


Set  AX  to  0  for  return  in  function  value 
Go  to  end 


Move  Current  Record  Offset  to  AX  for  return 
Subtract  Starting  Address  of  Buffer  and 
add  1  to  get  actual  offset  w/i  Buffer 


INSTRASM  ENDP 
END 


End  Listings 
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ASSEMBLER 


Listing  One  (Text  begins  on  page  50.) 

/*  68A.C  -  Main  driver  for  generic  assembler.  */ 

#include  <stdio.h> 

♦include  <conio.h> 

♦include  <string.h> 

♦include  <time.h> 

♦include  <dir.h> 


♦include  "68defs.h" 

♦  include  "68err'.h" 
♦include  "68parse.h" 
♦include  "681ist.h" 
♦include  "68assem.h" 
♦include  "68symtab.h' 


void  assembler_print_errors  (  char  *  message  ,  char  *  add_mess  ) 

{ 

printf("  %s  %s  \n", message, add_mess  ); 

} 


main  () 

{_ 

int  error_count,  warning_count  ; 

FILE  *  outfile  ; 

FILE  *  in_file  ; 

char  fn [MAXPATH] , outname [MAXPATH] ,  temp [MAXPATH] ,  *ptr; 

char  drive [MAXDRIVE]  ,  dir [MAXDIR] ,  file [MAXFILE] ,  ext [MAXEXT] ; 

error_count  =  0  ; 

warning_count  =  0  ; 

e_printf  =  assembler_print_errors  ; 

puts("  Generic  Assembler.  Version  1.0\n"); 

puts("  Written  by  :  William  E.  Ives"); 

puts("  Copyright  (c)  1988  by  Michigan  Technological  University. \n") ; 
printf("  Absolute  or  Relative  assembly  ?  (A/R)  "); 
fn[0]  =  getcheO  ; 
putchar (' \n' ) ; 

am_assem_class  =  ((  f n [0 ]  ==  'a')l!(fn[0]  ==  'A'))  ? 

am_absolute  :  am_relative  ; 
printf("  Enter  source  file  name  [.ASM]  =>"); 
fn [0] =MAXPATH-1; 
ptr=cgets (fn) ; 
strcpy (fn,ptr) ; 
putchar ('  \n' )  ; 

fnsplit  (  fn,drive,dir,  file, ext)  ; 
if  (  !  (  *ext  )  ) 

fnmerge (  fn,  drive, dir,  file, " .ASM") ; 
fnmerge (  outname, drive, dir, file, " .LST") ; 
printf("  Enter  name  of  list  file  [%s]  =>", outname) ; 
temp [0] =MAXPATH-1; 
ptr  =  cgets(temp); 
putchar (' \n' ) ; 

if  (  temp[l]  )  strcpy (outname,  ptr) ; 
in_file  =  fopen(  fn, "r"); 
if  (  in_file  ==  NULL  )  { 
e_message (0, 30,  fn  ); 
return  30  ; 

} 

puts("  Assembling.."); 
e_hold_mes sages  =  TRUE  ; 

am_passl(  in_file  ,  &error_count,  &warning_count  ); 
e_hold_messages  =  FALSE  ; 
fclose (in_file) ; 

printf("  Total  Errors  %d  Total  Warnings  %d  \n", 
error_count,  warning_count  ); 
puts("  Writing  listing  file.Nn"); 
outfile  =  fopen(  outname, "w") ; 
if  (  outfile  ==  NULL  )  { 

ejnessage (0,  30,  outname  ); 
return  30  ; 

) 

l_printlisting(  outfile  ,TRUE  ); 

fprintf (outfile, "\n  Total  Errors  %d  Total  Warnings  %d  \n", 
error_count,  warning_count  ); 
fprintf (outfile, "\n\n  Name  of  file  :%s\n",fn); 
fclose (outfile) ; 
return  0  ; 

}  /*  main  */ 


End  Listing  One 


Listing  Two 

/*  68ASSEM.C  68000  Assembly  Module 7  Contains  procedures  to  handle  assembly.*/ 


♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦include  <ctype.h> 

♦include  "68defs.h" 

♦include  "68err.h" 

♦include  "68parse.h" 

♦include  "681ist.h" 

♦include  "68assem.h" 

♦include  "68symtab.h" 

♦include  "68pseudo.h" 

♦include  "68instr.h" 

♦define  LINELEN  80 
♦define  LOCAL  near  pascal 

line  , 

label [MAXSYMLEN]  , 
command [MAXSYMLEN] , 
size  , 

numterms  , 

termlist  )  ; 


void  p_assem_line  (  char 
char 
char 

p_size_type 

char 

am_term_type 


unsigned  long  int 

char 

char 

unsigned  long  int 
char 


char 

am_term_type 
am_a s  s em_t y pe 


am_location_counter 
am_end_found 
am_trunc_lines 
am_relbase 
am  relknown 


0L 

FALSE 

TRUE 

OL 

FALSE 


/*  size  of  absolute  address  in  words.  */ 

/*  1  -  abs  short,  2  -  abs  long.  */ 

am_abs_address_size  =1; 

am_term_list_head  =  NULL  ,  *  am_term_list_tail  : 
am  assem  class  =  am  absolute  ; 


int  am_resolve_symbol (  p_sym_type  *  symlist  ) 


register  int  symcount  =  0  ; 
unsigned  long  sum  =  OL  ; 
char  rel  ,  relcount  = 

p_sym_type  *  symbol  ,  *  temp 
temp  =  NULL  ; 
prev  =  NULL  ; 
symbol  =  symlist  ; 
while  (  symbol  )  { 

rel  =  (  symbol->sym[0]  ==  '* 
if  (  !rel  &&  symbol->sym(0] 
symcount++  ; 
prev  =  symbol  ; 
symbol  =  symbol->next  ; 


/*  set  relative  flag.*/ 

/*  if  there  is  a  symbol.*/ 


else  { 

if  (  symbol->operator  == 
if  (  rel  )  relcount  += 
sum  +=  symbol->val  ; 

) 

else  { 

if  {  rel  )  relcount  -= 
sum  -=  symbol ->val  ; 
symbol->operator  =  '+' 

) 

if  (  (temp  ) { 

temp  =  symbol  ; 
prev  =  symbol  ; 
symbol  =  symbol->next 


/*  there 
+'  )  ( 
symbol ->sym[l] 


value,  perform  calculations  */ 


symbol->sym[l] 


/*  if  temp  ==  null  */ 


} 

else  { 

prev->next  =  symbol->next 

free (symbol) ; 

symbol  =  prev->next  ; 


} 


] 


if  (  ! symcount  &&  relcount  ) 
if  (  am_relknown  )  ( 

sum  +=  (  relcount  *  am_relbase  )  ;  /*  resolve  relative  if  known.*/ 

relcount  =  0; 

) 

else 

symcount=l  ; 
if  (  temp  )  ( 

temp->val  =  sum  ; 
temp->operator  =  '+'  ; 
if  (  (relcount  )  temp->sym[0]  =  0  ; 
else  { 

temp->sym[0]  =  ' * '  ; 
temp->sym[l]  =  relcount  ; 

) 

} 

if  (  prev  )  prev->next  =  NULL  ; 
return  symcount  ; 

}  /*  am_resolve_symbol  */ 

int  am_resolve_term  (  am_term_type  *  termlist  ,  char  datatermcount  ) 

( 

register  int  termcount  =  0  ; 

am_term_type  *  term  ; 

char  okay  ,  count  ; 

term  =  termlist  ; 

okay  =  TRUE  ; 

count  =  1  ; 

while  (  term  &&  okay  )  { 

if  (  am_resolve_symbol (term->symptr  )  )  termcount++  ; 
term  =  term->next  ; 
count ++  ; 
if  (  term  ) 

okay  =  (  termlist->class  ==  am_first_instr_term  && 
term->class  ==  am_other_instr_term  )  ! ! 

(  termlist->class  ==  am_data_term  && 
term->class  ==  am_data_term  && 
count  <=  datatermcount  )  ; 

} 

return  termcount  ; 

)  /*  amresolveterm  */ 

void  am_delete_terms  (  am_term_type  **  termlist  ,  char  all  ) 

{ 

am_term_type  *  term  ; 
p_sym_type  *  sym  ; 
term  =  *termlist  ; 
if  (  all  )  { 

while  (  term  =  *termlist  )  { 

if  (  ( (term->modereg  »  8)  ==  7)  && 

( (term->modereg  &  15) ==10  )  )  { 
free (term->symptr) ;  /*  free  the  string.  */ 

term->symptr  =  NULL  ; 

) 

while  (  sym  =  term->symptr  )  { 

term->symptr  =  term->symptr->next  ; 
free (sym)  ; 

) 

*termlist  =  term->next  ; 
free (term) ; 

) 


else  { 

if  (  term  )  { 

if  I  ( {term->modereg  »  8)  —  7)  ss  (continued  OU page  94) 
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( (term->modereg  s  15) ==10  )  )  { 
free (term->symptr) ;  /*  free  the  string.  */ 

term->symptr  =  NULL  ; 

} 

while  (  sym  =  term->symptr  )  ( 

term->symptr  =  term->symptr->next  ; 
free (sym)  ; 

} 

*termlist  =  term->next  ; 

free (term) ; 


}  /*  am_delete_terms  */ 

void  am_add_terms_to_list  (  am_term_type  “  termlist  ) 


am_term_type  *  term  ; 

if  (  !  (*termlist)  )  return  ; 

if  (  ! am_term_list_tail  )  { 

am_term_list_head  =  *termlist  ; 
am_term_list_head->prev  =  NULL  ; 


/*  if  NULL  then  leave.  */ 
/*  list  is  empty  */ 


else  ( 

am_term_list_tail->next  =  *termlist  ; 
am_term_list_tail->next->prev  =  am_term_list_tail  ; 

) 

for  (  term  =  *termlist  ;  term  ;  term  =  term->next  )  /*  set  tail  */ 

am_term_list_tail  =  term  ; 

*termlist  =  NULL; 

return  ;  /*  return  used  to  avoid  compilier  warning.  */ 

}  /*  am_add_terms_to_list  */ 

void  am_remove_terms_from_list  (  am_term_type  “  termlist  ) 


am_term_type  *  term  ; 
char  i  ; 

if  (  !  (*termlist)  )  return  ;  /*  if  NULL  then  leave.  */ 

term  =  *termlist  ; 
i  =  1  ; 

if  (  term->class  ==  am_first_instr_term  )  { 
if  (  term->next  ) 

if  (  term->next->class  ==  am_other_instr_term  ) 
i  =  2  ; 

} 

if  (  term  ==  am_term_list_head  ) 

am_term_list_head  =  (  i  ==  1  )  ?  term->next  :  term->next->next  ; 
else 

term->prev->next  =  (  i  ==  1  )  ?  term->next  :  term->next->next  ; 
if  (  (  term  ==  am_term_list_tail  )  ! ! 

(  (  i  ==  2  )  SS  (  term->next  ==  am_term_list_tail  ) )  ) 
am_term_list_tail  =  term->prev  ; 
else 

if  (  i  ==  1  ) 

term->next->prev  =  term->prev  ; 
else 

if  (  term->next->next  )  term->next->next->prev  =  term->prev  ; 
if  (  i  ==  1  ) 

term->next  =  NULL  ; 
else 

term->next->next  =  NULL  ; 
am_delete_terms  (  Stem,  TRUE  ) ; 

*termlist  =  NULL; 

return  ;  /*  return  used  to  avoid  compilier  warning.  */ 

}  /*  am_remove_terms_from_list  */ 
void  am_backfill(  am_term_type  *  termlist  ) 

{ 

char  i,j,k,  reg  ; 

am_term_type  *  term  ; 
unsigned  int  opcode  ; 
l_line_type  *  lptr  ; 
lptr  =  termlist->lineptr  ; 

opcode  =  termlist->opcode;  /*  get  opcode  */ 

/*  write  opcode  to  listing  */ 
l_writetoline (1, opcode, 0, lptr) ; 
term  =  termlist  ; 

j  =  (  term->index  ==  0  )  ?  2  :  1  ; 

reg  =  (  opcode  S  7  )  ; 
for  (i=l,k=2  ;  i  <=  j  SS  term  ;  i++  )  { 
switch  (  reg  )  ( 
case  1  :  /*  abs.l  */ 

l_writetoline  (k,  term->symptr->val»16,  0,  lptr) ; 
k++  ; 

case  0  :  /*  abs.w  */ 

l_writetoline (k, term->symptr->val  &  OxFFFF  ,0,lptr); 
k++  ; 
break  ; 

) 

term  =  term->next  ; 
reg  =  ( (opcode»9)  S7)  ; 

} 

}  /*  am_backfill  */ 

static  int  LOCAL  am_readln  (  FILE  *  infile,  int  linelen, 

char  *  line  ,  char  *  linel,  char  *  blank  ) 

{ 

int  ch,  chi  ,  i  ; 

char  dqoute,  sqoute  ;  /*  flags  for  tracking  double  &  single  quotes  */ 
dqoute  =  sqoute  =  FALSE  ; 

♦blank  =  TRUE  ; 
i  =  0  ; 

while  (  ch=chl=fgetc (infile)  )  { 

if  (  ch  ==  '  \t'  )  {  /*  expand  tabs  into  8  spaces  */ 

for  (  ch  =  0  ;  ch  <  8  ;  ch  ++,  i++  )  { 
if  (  i  <  linelen  )  { 

line[i]  =  linel [i]  =  '  ' ; 
line [i+1]  =  linel [i+l]=  NULL; 


if  (  !  isprint (ch)  )  break  ; 

if  (  ch  ==  '\"  )  (if  (  ! dqoute  )  sqoute  =  ! sqoute  ;  } 


else  if  {  ch  ==  )  (if  (  Isqoute  )  dqoute  =  Idqoute  ; 

else  if  (!(  dqoute  \\  sqoute  ))  chi  =  toupper(ch)  ; 
if  (  i<  linelen  )  { 
line[i]=  ch  ; 
linel [i]=  chi  ; 

if  (  ‘blank  )  ‘blank  =  (  ch  =  '  '  ) ; 
line [i+1]  =  linel [i+1]  =  NULL  ; 


i++; 

} 

if  (  i  )  return  0  ; 
return  ch  ; 

}  /*  am_readln  */ 

void  am_passl  (  FILE  *  in_file  ,  int 

{ 


warning_count  ) 


int  i  ; 

ps_pseudos  pseudo_class  ; 

char  label [MAXSYMLEN],  command [MAXSYMLEN]  ; 

char  sizeinwords  ,  blank  ; 

p_size_type  size  ; 

p_sym_type  *  sym  ; 

char  numterms  ; 

am_term_type  *  termlist,  ‘term  ; 

unsigned  int  opcode  ; 

unsigned  int  index  ; 

char  prev_warnings  =  0  ; 

char  line [LINELEN],  linehold [LINELEN]  ; 

l_line_type  *  lptr  ; 

e_error. state  =  0  ; 

e_error. warnings  =  0  ; 

while  (  ! am_end_found  &&  !e_error.out_of_memory  && 

(  am_readln(in_file, LINELEN- 1, line, linehold, &blank)  !=  EOF  ))  { 


if  (  blank  ) { 

l_addline(  l_neither, 
continue  ; 


/*  skip  blank  lines  */ 


if  (  line[0]  ==  '*'  I  I  line[0]  ==  )  (  /*  skip  comment  lines  */ 

l_addline(  l_neither,  0,  line,  filptr  ); 
continue  ; 

} 

*error_count  +=  e_error. state  ;  /*  count  up  total  number  of  errors  */ 

e_error .state  =  0  ; 

label [0]  =  0  ; 

command [0]  =  0  ; 

size  =  p_unknown  ; 

numterms  =  0  ; 

sizeinwords=  0  ; 

termlist  =  NULL  ; 

p_assem_line  (  linehold,  label,  command,  Ssize,  &numterms,  Stermlist  ); 
if  (  e_error. state  )  [ 

/*  add  errors  to  listing  and  go  on  to  next  line  */ 
l_addline(  l_neither,  0,  line,  &lptr) ; 
am_delete_terms (Stermlist,  TRUE  ); 
l_add_errors (lptr) ; 

continue  ;  /*  skip  to  next  source  line.  */ 

} 

/*  if  command  is  psuedo  then  handle  it.  */ 

if  (  ps_lookup_pseudo  (  command,  Spseudo_class  )  )  { 

ps_pseudo(  label,  pseudo_class,  numterms,  Stermlist,  line); 
if  (  (  e_error. warnings  >  prev_warnings  )  I!  e_error. state  ) 
l_add_errors (l_line_head->prev) ; 
prev_warnings  =  e_error. warnings  ; 
continue  ;  /*  skip  to  next  source  line.  */ 

) 

if  (  am_location_counter  S  1  )  { 

e_message (0, 22, NULL) ;  /*  location  counter  is  odd  */ 

l_addline (l_neither,  0,  line,  Slptr) ; 
prev_warnings  =  e_error. warnings  ; 
l_add_errors (lptr) ; 

am_location_counter++;  /*  adjust  counter  so  error  does  not  repeat*/ 
continue  ; 

) 

/*  its  either  an  instruction  or  an  error  */ 
if  (  numterms  >  2  )  { 

e_message (0, 15, NULL)  ;  /*  too  many  terms  on  line.*/ 

l_addline (l_neither,  0,  line,  Slptr); 

prev_warnings  =  e_error. warnings  ; 

l_add_errors (lptr) ; 

continue  ; 

} 

/*  set  size  and  initial  opcode.  */ 
i  =  1  ; 

switch  (  numterms  )  ( 

case  0  :  /*  make  source  and  dest  empty  */ 

i  =  is_validate  (  Ssize  ,  command,  7,  5,  7,  5, 

Sopcode  ,  Ssizeinwords,  termlist  ,  Sindex  ) ; 

break; 

case  1  :  /*  make  source  empty  */ 

i  =  is_validate  (  Ssize  ,  command,  7,  5, 
termlist->modereg  »  8, 
termlist->modereg  s  15, 

sopcode  ,  ssizeinwords,  termlist  ,  sindex  ); 

break; 
case  2  : 

i  =  is_validate  (  ssize  ,  command, 

termlist->modereg  »  8, 
termlist->modereg  S  15, 
termlist->next->modereg  »  8, 
termlist->next->modereg  S  15, 

Sopcode  ,  Ssizeinwords,  termlist  ,  Sindex  ); 

break; 

} 

if  (  i  )  { 

l_addline (l_neither,  0,  line,  Slptr); 
prev_warnings  =  e_error .warnings  ; 
l_add_errors (lptr) ; 
continue  ; 


/*  process  line  label  if  there  is  one  */ 
if  (  label [0]  ) 


(continued  on  page  96) 
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if  (sym_add_label_symbol (label, am_location_counter, am_assem_class) ) ( 
l_addline (l_neither,  0,  line,  Slptr); 
ladderrors (lptr) ; 
prev_warnings  =  e_error .warnings  ; 
am_delete_terms(&termlist,  TRUE)  ; 

continue  ;  /*  skip  to  next  source  line.  */ 

1 

/*  resolve  already  known  symbols  */ 
for  (  term  =  termlist  ;  term  ;  term  =  term->next  ) 
for  (  sym  =  term->symptr  ;  sym  ;  sym  =  sym->next  ) 
if  (  sym->sym[0]  ) 

sym_add_operand_symbol (  sym,  term,  TRUE  ) ; 
l_addline(  l_firstinstr,  sizeinwords,  line,  Slptr  ); 
if  (  e_error .out_of_memory  )  ( 

am_delete_terms (&termlist, TRUE) ; 
break  ; 


} 

/*  its  either  an  instruction  or  an  error  */ 
if  (  e_error. warnings  >  prev_warnings  ) 
l_add_errors (lptr) ; 
prev_warnings  =  e_error .warnings  ; 
if  (termlist)  ( 

termlist->lineptr  =  lptr  ;  /*  hold  onto  line.*/ 

if  (  termlist->next  ) 

termlist->next->lineptr  =  lptr  ; 
termlist->index  =  index  ;  /*  hold  onto  index.*/ 

termlist->opcode  =  opcode  ;  /*  hold  onto  opcode.*/ 

} 

l_writetoline (0, am_location_counter, 0, lptr) ; 

l_writetoline (sizeinwords, 0, 3, lptr) ;  /*  put  '?'  in  listing.*/ 

/*  are  all  terms  knowm?  */ 
if  (  !  am_resolve_term (termlist, 0)  )  ( 
am_backfill(  termlist  ); 
if  (  e_error. warnings  >  prev_warnings  ) 
l_add_err°rs (lptr) ; 
prev_warnings  =  e_error. warnings  ; 
am_location_counter  +=  (  sizeinwords  «  1  )  ; 
am_delete_terms (Stermlist,  TRUE)  ; 

I 

else  { 

am_add_terms_to_list (  fitermlist  ) ; 
am_location_counter  +=  (  sizeinwords  «  1  )  ? 

} 

} 

if  (  e_error .out_of_memory  )  ( 

ladd  errors  (l_line_head->prev) ; 

‘error  count  +=  e  error. state  ; 


/*  Make,  sure  all  local  and  global  symbols  are  resolved  * 
e_error. state  =  0  ; 

*error_count  +=  sym_process_unresolved_locals ()  ; 
*warning_count  =  e_error .warnings  ; 

/*  Add  symbol  table  to  listing  */ 
sym_add_symtabtolisting() ; 

)  /*  am_passl  */ 


/ 


End  Listing  Two 


Listing  Three 


/*  68ERR.C  -  68000  error  handler  module  */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦include  "68defs.h" 

♦include  "68err.h" 

struct  e_struct  e_error  =  {  0, 0, 0, 0, FALSE,  NULL,  NULL  }; 
char  e_hold_messages  =  TRUE  ; 
e_printf_type  e_printf  ; 

/*  Global  error  list  array.  */ 
err_type  err_list [MAXERRORS]  = 

{{1  ,  0, "Error  1.  Unexpected  end  of  line."  , NULL, NULL  }, 

(  2  ,  0, "Error  2.  Unexpected  symbol. ",  NULL, NULL  ), 

{  3  ,  0, "Error  3.  Unexpected  token  char. ",  NULL, NULL  ), 

{  4  ,  0, "Error  4.  Symbol/Literal  contains  invalid  char .", NULL, NULL  }, 

{  10  ,  0, "Error  10.  Command  op  size  invalid. ",  NULL, NULL  ), 

(  11  ,  0, "Error  11.  Invalid  address  mode .", NULL, NULL  ), 

(  12  ,  0, "Error  12.  Unrecognized  command. ",  NULL, NULL  ), 

(  13  ,  0, "Error  13.  Command  operands  required. ",  NULL, NULL) , 

(  14  ,  0, "Error  14.  Forward  references  not  allowed  here. ",  NULL, NULL), 

(  15  ,  0, "Error  15.  Too  many  operands .", NULL, NULL) , 

{  16  ,  0, "Error  16.  Line  label  required.", NULL, NULL), 

{  17  ,  0, "Error  17.  Label  found  in  external  list .", NULL, NULL) , 

(  18  ,  0, "Error  18.  Label  already  resolved. ",  NULL, NULL), 

(  19  ,  0, "Error  19.  Operand  symbol  already  resolved. ",  NULL, NULL) , 

{  21  ,  0, "Error  21.  Address  collision. ",  NULL, NULL) , 

{  22  ,  0, "Error  22.  Location  counter  is  odd. ",  NULL, NULL) , 

{  23  ,  0, "Error  23.  Unresolved  symbol .", NULL, NULL) , 

{  30  ,  0, "Error  30.  File  not  found  or  unable  to  open. ",  NULL, NULL  }, 

{  31  ,  0, "Error  31.  Unexpected  end  of  file. ",  NULL, NULL  }, 

(  33  ,  0, "Error  33.  Disk  full  while  writing  file. ",  NULL, NULL) , 

{  41,  0,"Error  41.  Out  of  Dynamic  memory. ",  NULL, NULL  }, 

{  50  ,  0, "Warning  50.  Symbol  too  long.  Truncated. ",  NULL, NULL) , 

{  52  ,  0, "Warning  52.  Value  out  of  range .", NULL, NULL) , 

{  70  ,  0, "Warning  70.  Expression/Syntax  imprecise .", NULL, NULL) , 

{  71  ,  0, "Warning  71.  Command  op  size  not  specified. ",  NULL, NULL) , 

{  72  ,  0, "Warning  72.  Line  label  not  allowed.  Ignored. ",  NULL, NULL) , 

(  73  ,  0, "Warning  73.  Command  operands  not  allowed.  Ignored. ",  NULL, NULL), 

{  74  ,  0, "Warning  74.  Symbol  already  in  global  list.  Ignored. ",  NULL, NULL) , 

{  75  ,  0, "Warning  75.  Symbol  already  in  external  list.  Ignored. ",  NULL, NULL) , 

(  100,  0,”FSE  100.  Invalid  return  from  next_token. ",  NULL, NULL)  }; 
void  e_message (  char  pos  , 

char  code  , 

char  *  add_mess) 
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{ 

err_type  *  temp  ; 

int  i  ; 

char  *  tmp; 

temp  =  NULL  ; 

if  (  e_hold_messages  )  ( 

temp  =  (  err_type  *  )  malloc  (  sizeof (err_type)  )  ; 

if  (  !temp  )  code  =  41  ;  /*  change  code  to  that  of  'out  of  memory'  */ 
} 

i  =  0  ; 

while  ((  i  <  MAXERRORS  )  &&  (  err_list [i] .code  !=  code  ))  i  ++  ; 
if  (  code  ==  41  ) 

e_error .out_of_memory  =  TRUE  ; 
if  (  temp  )  { 

temp->message  =  (  i  <=  MAXERRORS  )  ?  err_list [i] .message  :  NULL  ; 
if  (  *add_mess  ) 

temp->add_mess  =  {  char  *  )  strdup  (  addjness  )  ; 
else 

temp->add_mess  =  NULL  ; 
temp->code  =  code  ; 
temp->position=  pos  ; 
temp->next  =  NULL  ; 
if  (  ! e_error .errptr  )  { 
e_error .errptr  =  temp  ; 
e_error.last  =  temp  ; 

} 

else  { 

e_error . last->next  =  temp  ; 
e_error.last  =  temp  ; 

} 

} 

tmp  =  (  char  *  )  (  i  <  MAXERRORS  )  ?  err_list [i] .message  :  NULL  ; 
if  (  e_error.curpos  ) 
pos  +=  e_error .curpos  ; 
e_printf (  tmp,  add_mess  ) ; 
if  (  (  code  <  50  )  I !  (  code  >=  100  )  )  { 
e_error .errors++  ; 
e_error .state++  ; 

> 

else 

e_error .warnings++; 

}  /*  e_message  */ 
void  e_delete_errors () 

{ 

err_type  *  temp  ; 
while  (  e_error .errptr  )  { 

temp  =  e_error .errptr->next  ; 
if  (  e_error.errptr->add_mess  ) 

free(  e_error .errptr->add_mess  )  ; 
free(  e_error .errptr  ); 
e_error .errptr  =  temp  ; 

> 

)  /*  e_delete_errors  */ 


End  Listing  Three 


Listing  Four 

/*  68INSTR.C  -  68000  Instruction  Set  Module  contains  procedures  to  handle 
instruction  set.*/ 

#include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <string.h> 


♦include  "68defs.h" 
♦include  "68err.h" 
♦include  "68parse.h" 
♦include  "681ist.h" 
♦include  "68assem.h" 
♦include  "68instr.h" 


♦define  LOCAL  near  pascal 
int  is_validate  (  p_size_type  * 
char  * 

char 
char 
char 
char 

unsigned  int 
char 

am_term_type 
unsigned  int 


size  , 
command, 
smode  , 
sreg  , 
dmode  , 
dreg  , 
opcode  , 
total_size  , 
termlist  , 
index  ) 


/*  error  if  destination  is  not  specified  */ 
if  (  (dmode==7)  &&  (  dreg==5  )  )  { 

e_message (0, 11, "  Destination  operand  required."); 
return  11  ; 


*total_size  =  1  ; 

/*  lookup  command  */ 

if  (  !  strcmp (command, "MOVE")  )  { 

/*  error  if  source  is  not  specified  */ 
if  (  (smode==7)  &&  {  sreg==5  )  )  { 

e_message (0, 11, "  Source  operand  required."); 
return  11  ; 

) 

if  (  *size  ==  p_unknown  )  { 

/*  assign  default  size  if  it's  unknown  */ 
e_message (0, 71, "  Assumed  Long."); 

*size  =  p_long  ; 

} 

termlist->sizeof reserve=am_abs_address_size  ; 
termlist->next->sizeofreserve=am_abs_address_size  ; 


(continued  on  page  98) 
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*total_size  +=  (  am_abs_address_size  «  1  ) ; 

♦opcode  =  (dreg  «  9  )  !  (  dmode  «6  )  !  (  smode  «3  )  !  sreg  ; 

♦opcode  !  =  (  *size  ==  p_long  )?  0x2000:  (*size==p_word) ?  0x3000:0x1000; 
♦index  =0; 

} 

else  if  (  !  strcmp (command, "JMP")  )  { 

♦opcode  =  0x4EC0  !  (  dmode  «  3  )  !  dreg  ; 
termlist->sizeofreserve=am_abs_address_size  ; 

*total_size  +=  am_abs_address_size  ; 

♦index  =  1  ; 

) 

else  ( 

ejnessage (0, 12, command) ; 
return  12  ; 

} 

return  0  ; 

}  /*  is_validate  */ 

End  Listing  Four 


} 

curline->lclass  =  (  class  ==  l_firstinstr  )  ?  l_otherinstr:l_data  ; 
curline->linenum  =(  class  ==  l_firstinstr  )  ?  1  number  of  lines++  :  0  ; 
}  -  -  - 

} 

♦lineptr  =  tcurline  ; 
return  0  ; 

}  /*  l_addline  */ 

void  l_writetoline (  int  spec  , 

unsigned  long  value  , 

char  option  , 

1  line  type  *  line  ) 

{ 

register  int  i  ; 

char  *  curline  ; 

if  (  !line  )  return  ; 

if  (  (spec  )  { 

if  (  option  ) 

strnset (line->line, '  ,  6) ; 

else  { 

sprintf (line->line, "%06X",  value) ; 

♦ (line->line+6)  =  '  '  ; 


Listing  Five 

/*  68LIST.C  -  68000  listing  module.  */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦include  <time.h> 

♦include  <ctype.h> 

♦include  "68defs.h" 

♦include  "68err.h" 

♦include  "681ist.h" 
l_line_type  ♦  l_line_head  =  NULL  ; 
char  *  l_header 

"  Generic  Assembler  Version  1.0  : 

char  *  l_blanks  =  "  "  ; 

int  l_number_of_lines  =  0  ; 

int  l_addline(  l_lclass_type  class  , 

char  numofwords  , 

char  *  line  , 

l_line_type  **  lineptr  ) 

I 

l_line_type  *  curline  ,  *  tcurline  ; 
register  int  i  ; 
long  secs  ; 

♦lineptr  =  NULL  ; 
curline  =  NULL  ; 

curline  =  (  l_line_type  *  )  malloc  (  sizeof (l_line_type)  )  ; 
if  (  Icurline  )  { 

ejnessage (0,41,"  Listing  "  )  ;  /*  out  of  memory  */ 
return  41  ; 

} 

curline->lclass  =  class  ; 

curline->linenum  =  (  class  !=  l_firstinstr  )  ?  0  :l_number_of_lines++  ; 
if  (  !l_line_head  )  { 

l_line_head  =  (  l_line_type  *  )  malloc  (  sizeof (l_line_type) ) ; 
if  ( ! l_line_head) ( 

ejnessage (0, 41  , "  Listing  "  )  ;  /*  out  of  memory  */ 
return  41  ; 

} 

l_line_head->line  =  l_header  ; 
time (Ssecs) ; 

strcpy  (  ( (l_line_head->line) +32) ,  asctime(  localtime (fisecs)  )  ); 
i  =  strlen (l_line_head->line) ; 

for (; ! isprint (l_line_head->line (i) ) ;i — )  l_line_head->line[i]=0; 

l_line_head->lclass  =  l_data  ; 

l_line_head->linenum  =  0  ; 

l_line_head->next  =  l_line_head  ; 

l_line_head->prev  =  l_line_head  ; 

) 

curline->line  =  (  char  *  )  malloc (  25  +  strlen (line)  ); 

if  (  ! (curline->line)  )  ( 

ejnessage (0, 41  ,"  Listing  "  )  ;  /*  out  of  memory  */ 
free (curline) ; 
return  41  ; 

) 

curline->next  =  l_line_head  ; 
curline->prev  =  l_line_head->prev  ; 
l_line_head->prev  =  curline  ; 
curline->prev->next  =  curline; 
if  (  class  !=  ljieither  )  { 

memset (  (curline->line)  ,'0',  6  ); 
memset (  ( (curline->line) +6) , '  ',18  ); 

> 

else 

memset (  (curline->line)  , '  ',24); 
strcpy (  ( (curline->line) +24)  , line); 
tcurline  =  curline  ; 
if  {  numofwords  >  3  )  { 

i  =  (numofwords  -  3)  /  3  ; 

if  (  (numofwords  -  3)  %  3  )  i++  ; 

for  (  ;  i  ;  i—  )  ( 

curline  =  (  l_line_type  *  )  malloc  (  sizeof (l_line_type)  )  ; 
if  (  Icurline  )  { 

ejnessage (0, 41  ,  NULL  )  ;  /*  out  of  memory  */ 
return  41  ; 

) 

curline->next  =  l_line_head  ; 
curline->prev  =  l_line_head->prev  ; 
l_line_head->prev  =  curline  ; 
curline->prev->next  =  curline; 
curline->line  =  strdup(  l_blanks  ); 
if  (  ! (curline->line)  )  ( 

e_message (0, 41  ,  NULL  )  ;  /*  out  of  memory  */ 
return  41  ; 


} 

else  ( 

i  =  (  spec  -  1  )  /  3  ; 
for  (  ;  i  ;  i —  ,  line  =  line->next  )  ( 
if  (  option  ==  2  )  ( 

sprintf (line->line+6, "  %04X  %04X  %04X", (  int  )  value, 

(  int  )  value,  (  int  )  value  ) ; 

* (line->line+23)  =  '  '; 

} 

else  if  (  option  ==  3  )  ( 

sprintf (line->line+6, "  ????  ????  ????"  ); 

* (line->line+23)  =  ' 

) 

) 

i  =  (  spec  -  1  )  %  3  ; 
curline  =  line->line  +  9  ; 
for  (  ;  i  ;  i —  ,  curline  +=  5  )  { 
if  (  option  ==  2  )  ( 

sprintf (  curline, "%04X", (  unsigned  int  )  value); 
*(curline+4)  =  '  '; 

) 

else  if  (  option  ==  3  ) 

strnset (  curline, '?', 4  ) ; 

) 

if  (  (  option  ==  0  )  : !  (  option  ==  2  )  )  { 

sprintf (curline, "%04X",  (  unsigned  int  )  value  )  ; 

* (curline+4) ='  ' ; 

) 

else  if  (  option  ==  4  )  ( 

sprintf (curline, "%02X",  (  unsigned  char  )  value  ); 

* (curline+2) ='  '; 


else 

strnset (curline, ' ?' , 4) ; 

) 


)  /*  l_writetoline  */ 

void  l_add_errors  (  l_line_type  *  lptr  ) 

{ 

*  tlptr  ; 

*  error  ; 
relink_list  ; 
message_buf [100]  ; 

/*  if  lptr  ==  NULL  */ 
lptr  =  l_line_head->prev  ; 

if  lptr  at  end  of  list  do  not  bother  relinking  listing.*/ 


l_line_type 

err_type 

char 

char 

if  (  llptr  ) 


/* 


relink_list  =  (  lptr->next  !=  l_line_head  ) 
for  (  error  =  e_error .errptr  ;  error  ;  error  =  error->next  )  { 
strcpy (  message_buf  ,  error->message  )  ; 

strcpy (  message_buf+strlen (error->message) ,  error->add_mess  ); 
laddline (l_neither,  0,  message_buf  ,  Stlptr  ); 
if  (  relink_list  )  { 

/*  unlink  the  line  */ 
tlptr->next->prev  =  tlptr->prev  ; 
tlptr->prev->next  =  tlptr->next  ; 

/*  link  the  line  into  listing  after  the  source  line  at  lptr  */ 

tlptr->next  =  lptr->next  ; 

tlptr->next->prev  =  tlptr  ; 

tlptr->prev  =  lptr  ; 

lptr->next  =  tlptr  ; 


} 

e_delete_errors ()  ; 

)  /*  l_add_errors  */ 

int  l_printlisting (  FILE  *  outfile,  char  withheader  ) 

( 

l_line_type  ♦  curline  ; 
if  (  withheader  ) 

fprintf (outfile, "%s\n", l_line_head->line) ; 
for  (  curline  =  l_line_head->next  ;  curline  !=  l_line_head  ; 
curline  =  curline->next  )  ( 

if  (  (curline->lclass  !=  l_neither) && (curline->lclass  !=  l_data)  )  ( 
if  (  fprintf (outfile, "%3d  %s\n",curline->linenum, 
curline->line)  ==  EOF  )  ( 
ejnessage (0, 33, NULL) ; 
return  33  ; 


else  if  (  fprintf (outfile, "  %s\n",  curline->line)  ==  EOF  )  ( 

ejnessage (0,33, NULL) ; 
return  33  ; 

} 


return  0  ; 

}  /*  l_printlisting  */ 

void  l_delete_listing(  char  deletehead  ,  char  resetcount  ) 
{ 


l_line  type  *  curline,  ♦  tline  ; 

(continued  on  page  100) 
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Listing  Five  (Listing  continued,  text  begins  on  page ,  50.) 

if  (  resetcount  )  l_number_of_lines  =  0  ; 
if  (  l_line_head  )  { 

1  line  head->prev->next  =  NULL  ; 
curline  =  l_line_head->next  ; 
l_line_head->next  =  l_line_head  ; 
l_line_head->prev  =  l_line_head  ; 
if  (  deletehead  )  { 
f ree (l_line_head) ; 
l_line_head  =  NULL  ; 

) 

while  (  curline  )  { 

tline  =  curline->next  ; 

if  (  curline->line  )  free(  curline->line  ); 
free (  curline  ) ; 
curline=tline  ; 


} 

}  /*  l_delete_listing  */ 

End  listing  Five 


Listing  Six 

/*  68MATH.C  -  68000  math  module.  */ 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  <ctype.h> 

♦include  "68defs.h" 

♦include  "68err.h" 

♦include  "68parse.h" 

unsigned  long  int  strtolong  (  register  char  *  str  , 
char  “  endptr  , 

char  base  ) 

( 

unsigned  long  int  sum  =  0L  ; 
register  char  shift  ; 


switch  (  base  )  ( 

case  10  :  for  (;  *str  ;  str++) 
if  (  isdigit (*str)  ) 

sum  =  (  sum  *  10  )  +  • 

(  *str  -  'O' 

else  ( 

‘endptr  =  str  ; 
return  0  ; 

) 

* endptr  =  str  ; 
return  sum  ; 


case 

2 

shift  =  1 

break 

case 

8 

shift  =  3 

break 

case 

16 

shift  =  4 

break 

} 

for  (;  *str  ;  str++  ) 


if  (  isdigit  (  *str 

)  && 

(  (  base  ==  10 

)  ! 1  (  base  ==  16  )  ! ! 

(  (base  ==  2) 

&&  (  *str  ==  '0'  !!  *str  ==  '1' 

(  (base  ==  8) 

&&  (  *str  <=  '7'  &&  *str  >=  '0' 

sum  =  (  sum  « 

shift  )  !  (  *str  -  'O'  )  ; 

else  if  (  isxdigit  ( 

*str)  &&  (  base  ==  16  )  ) 

sum  =  (  sum  «  shift  )  !  (  toupper (*str)  -  'A'  +  10  )  ; 
else  { 

*endptr  =  str  ; 
return  0  ; 

} 

*endptr  =  str  ; 
return  sum  ; 

}  /*  strtolong  */ 

int  m_symtoval (  char  *  sym  ,  unsigned  long  int  *  value  ) 

{ 

char  symbol [MAXSYMLEN]  ; 
char  ch  ,  *  last  ,  base  ; 

strncpy(  symbol,  sym,  MAXSYMLEN  );  /*  make  a  local  pass  by  value  symbol*/ 

symbol [MAXSYMLEN-1]  =  0  ; 

last  =  symbol+strlen (symbol) -1  ; 

‘value  =  0L  ; 

if  (  isdigit(  ch=*symbol  )  ) 

switch  (  toupper (  ‘last  )  )  { 

case  ' H'  :  ‘last  =  0  ;  base  =  16  ;  break  ; 

case  ' B'  :  ‘last  =  0  ;  base  =  2  ;  break  ; 

case  'Q'  : 

case  'O'  :  ‘last  =  0  ;  base  =  8  ;  break  ; 

case  'D'  :  ‘last  =  0  ; 

default  :  base  =  10  ;  break  ; 

) 

else  { 

switch  (  ch  )  { 

case  :  symbol [0]  =  '0'  ;  base  =  16  ;  break  ; 
case  '(§'  :  symbol  (0)  =  '0'  ;  base  =  8  ;  break  ; 

case  '%'  :  symbol [0]  =  '0'  ;  base  =  2  ;  break  ; 

case  '  \"  : 

/*  scan  line  until  next  '  */ 
last  =  strchr(  symbol+1,  ' \"); 
if  (  ! (‘last)  )  { 

e_message (0,  51, "End  quote  expected."); 
last  =  symbol+5  ; 

1 

‘last  =  0  ; 

if  (  last  -  symbol  >  5  )  ( 
e_message (0, 51, NULL) ; 
symbol [5]  =  0  ; 

) 

for  (  last  =  symbol+1  ;  ‘last  ;  last++  ) 

‘value  =  (  ‘value  «  8  )  !  ‘last  ; 
return  0  ; 
default  :  return  1  ; 

} 


) 

‘value  =  (  unsigned  long  int  )  strtolong (  symbol,  &last  ,  base  ); 
if  (  ‘last  )  e_message (0, 4, NULL)  ; 
return  (  ‘last  )  ?  4  :  0  ; 

}  /*  m_symtoval  */ 

End  Listing  Six 


Listing  Seven 


/*  68  PARSE. C  -  68000  parser  module.  */ 

♦include  <stdio.h> 

♦include  <alloc.h> 

♦include  <string.h> 

♦include  <ctype.h> 

♦include  "68defs.h" 

♦include  "68err.h" 

♦include  "68parse.h" 

♦include  "681ist.h" 

♦include  "68assem.h" 

♦include  "68math.h" 


♦define  LOCAL  near  pascal 

typedef  enum  (  symbol,  token,  none  ) 

typedef  enum  {  pn_sym  ,  /* 

pn_empty  ,  /* 

pn_error  /* 

)  p_addr_type  ; 
typedef  struct  ( 

p_addr_type 


p_tok  type  ; 
sym  *7 

empty  parse  node, 
error  */ 


*/ 


p_nodeclass;  /* 
regnum  ; 

symptr  ;  /*  symbol  list,  if  any.  */ 


tag  field 

char 

p_sym_type  * 

}  p_node_type 
char  symchars[38]  ; 

p_sym_type  curtoksym  ; 

char  curtok  ; 

static  p_tok_type  LOCAL  next_token (  char  *  line  ,  int 

int  line_len  ) ; 

static  int  LOCAL  p_symbol  (  char  *  line  ,  int  *  line_offset 

int  line_len  ,  char  symknown 

char  preop  ,  p_sym_type  “  symptr 

p_node_type  ‘  p_node  ) ; 
static  p_size_type  LOCAL  p_dotsize  (  char 

int 
int 
int 

static  void  LOCAL  p_parse_line  (  char  * 
int 

char  * 

static  p_tok_type  LOCAL  next_token (  char 


ABCDEFGH I JKLMNOPQRSTUVWXY Z1234567890_"  ; 

/*  current  token  symbol  from  next_token  */ 

/*  current  token  character  from  next_token*/ 
line  offset  , 


line 
*  line_offset  , 
line_len  , 
prev_offset  ); 

line  ,  int  *  line_offset 
line_len  ,  p_node_type  *  p_node 
done  )  ; 

line  ,  int  *  line  offset  , 


{ 


int 


line_len  ) 


char  *  tokpos,  *  tline  ; 

int  symlen  ; 

(*line_offset)  +=  strspn(  line  +  ‘line 
if  (  *line_offset  >=  line_len  ) 
return  none  ; 

tline  =  line  +  *line_offset  ; 
if  (  ‘tline  ==  '  \" )  ( 

tokpos  =  strchr(  tline+1,  '\"); 
if  (  ‘tokpos  ) 
tokpos++  ; 
else 

tokpos  =  (  tokpos  -  tline  >  5  ) 


\t");  /*  skip  blanks  */ 


/* 

/* 

/* 

/* 

tline  +  5  :  tokpos 


scan  for  next  quote.*/ 
if  found  set  tok  one  further.  */ 
if  not  ,  set  to  shortest  of  */ 
(5  forward  or  the  end)  */ 


else 

tokpos  =  strpbrk(  tline,  ".;-+()#/,  \"\t"); 
if  (  tokpos  !=  tline  )  ( 

/*  return  symbol  between  start  of  line  and  tokpos.  */ 

if  (  ! (‘tokpos)  )  tokpos  =  line  +  line_len  ;  /*  correct  for  NULL  */ 

symlen  =  tokpos  -  tline  ; 

(*line_offset)  +=  symlen; 

if  (  symlen  >=  MAXSYMLEN  )  e_message (*line_of fset, 50, NULL) ; 

symlen  =  (  symlen  >=  MAXSYMLEN  )  ?  MAXSYMLEN  -  1  :  symlen  ; 

strncpy(  curtoksym. sym,  tline,  symlen  )  ; 

curtoksym. sym [symlen]  =  0  ; 

if  (  isalpha (curtoksym. sym[0]  )  ) 

if  (  strspn(  curtoksym. sym,  symchars  )  ==  symlen  ) 
return  symbol  ; 
else  { 

e_message (*line_offset, 4, NULL) ; 
return  symbol  ; 

) 

e_error .curpos  =  *line_offset  ; 

if  (  (  !m_symtoval (curtoksym. sym, &curtoksym.val  )  )  && 

(  !e_error. state  )  ) 
curtoksym. sym[0]  =  0  ; 
e_error. curpos  =  0  ; 
return  symbol  ; 

} 

else 

( 

/*  the  token  is  at  the  start  of  the  line.  */ 
curtok  =  ‘tline  ; 

(*  line_offset  )  ++  ; 
return  token  ; 

} 

)  /*  next_token  */ 

static  int  LOCAL  p_symbol  (  char  *  line 

int  line_len 

char  preop 

p_node_type  *  p_node 


int  *  line_offset 
char  symknown 
p_sym_type  “  symptr 
) 


tok 


p_tok_type 
int  i 

if  (  symknown  ) 
tok  =  symbol 
else 
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tok  =  next_token(  line  ,  line_offset  ,  line_len)  ; 
switch  (  tok  )  { 

case  symbol  :  /*  Symbol  was  found  */ 

*symptr  =  (  p_sym_type  *  )  malloc  (  sizeof (p_sym_type) ) ; 
if  (  !  (*symptr)  )  {  /*  if  *symptr  ==  NULL  */ 

e_message (0, 41, "  Parser  "); 
return  41  ; 

) 

memcpy(  (*symptr)  ,  scurtoksym,  sizeof (p_sym_type)  ); 
(*symptr) ->operator  =  preop  ; 

(*symptr) ->next  =  NULL  ; 

i  =  *line_offset  ;  /*  hold  onto  line  offset  */ 
tok  =  next_token(  line  ,  line_offset  ,  line_len) ; 
switch  (  tok  )  { 
case  token  : 

switch  (  curtok  )  { 
case  '+'  : 
case  : 

i  =  p_symbol(  line,  line_offset, 

line_len,  FALSE,  curtok, 

&(  (*symptr) ->next  ),  p_node); 

return  i  ; 
default  : 

/*  un-get  the  token.  */ 

*line_offset  =  i  ; 
return  0; 

1 

case  symbol  :  e_message(*line_offset,2,NULL) ; 

return  2  ; 
case  none  :  return  0  ; 

default  :  ejnessage (*line_offset, 100, "p_symbol") ; 

return  100  ; 


case  ' W' :  return  p_word  ; 
case  ' L' :  return  p_long  ; 

} 

e_message (prev_of fset,  70,  "  ignored."); 

*line_offset  =  prev_offset  ; 
return  p_unknown  ; 

-} 

else  { 

*line_offset  =  prev_offset  ; 
return  p_unknown  ; 

} 

)  /*  p_dotsize  */ 

static  void  LOCAL  p_parse_line  (  char  *  line  ,  int  *  line_offset  , 
int  line_len  ,  p_node_type  *  p_node  , 

char  *  done  ) 

{ 

p_tok_type  tok  ; 

tok  =  next_token(  line  ,  line_offset  ,  line_len)  ; 
p_node->p_nodeclass  =  pn_empty  ; 
p_node->symptr  =  NULL  ; 
switch  (  tok  )  ( 
case  symbol  : 

p_node->p_nodeclass  =  pn_sym  ; 

p_symbol (line,  line_offset,  line_len  ,  TRUE, 

' & (p_node->symptr) , p_node  ) ; 

break; 

case  token  :  switch  (  curtok  )  ( 

case  :  *done  =  TRUE  ;  /*  Comment  found  */ 

break; 

default  :  ejnessage (*line_of fset, 3, NULL) ; 

*done  =  TRUE  ; 
break; 


case  token 
case  none 
default 


ejnessage (*line_of fset,  3,  NULL) ; 
return  3  ; 

e_message (*line_offset, 1,NULL) ; 
return  1  ; 

e_message (*line_of fset, 100, "p_symbol") ; 
return  100  ; 


) 

}  /*  p_symbol  */ 

static  p_size_type  LOCAL  p_dotsize  (  char 

int 

int 

int 

( 

p_tok_type  tok  ; 
if  (  curtok  ==  '  . '  )  I 
prev_offset  =  *line_offset  ; 
tok  =  next_token(  line  ,  line_offset, 
if  (  (tok  ==  symbol  )&& 

(  curtoksym. sym[l]  ==  NULL  )  ) 
switch  (  curtoksym. sym(0]  )  { 
case  ' B' :  return  p_byte  ; 


*  line  , 

*  line_offset  , 
line_len  , 
prev_offset  ) 


line_len) ; 


break  ; 

case  none  :  *done  =  TRUE  ;  /*  End  of  line  found  */ 

break  ; 

default  :  ejnessage (*line_of fset, 100, NULL) ; 

} 

*done  =  (  e_error. state  )  ?  TRUE: ‘done  ; 
if  (  !  ‘done  )  { 

tok  =  next_token(  line  ,  line_offset  ,  line_len)  ; 
switch  (  tok  )  ( 
case  symbol  : 

ejnessage (* line_of fset, 2, curtoksym. sym) ;  /*  Unexpected  symbol  */ 
‘done  =  TRUE  ; 
break  ; 
case  token  : 

switch  (  curtok  )  ( 
case  :  break; 

case  :  ‘done  =  TRUE  ;  /*  Comment  found  */ 

break; 

default  :  e_message (*line_of fset, 3, "  or  ;  exp."); 

‘done  =  TRUE  ; 

brealc;  ( continued  on  page  102) 
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Listing  Seven  (Listing  continued,  text  begins  on  page  50.) 

1 

break  ; 

case  none  :  *done  =  TRUE  ;  /*  End  of  line  found  */ 

break  ; 

default  :  e_message (*line_of fset, 100, NULL) ; 

*done  =  TRUE  ; 


if  (  e_error. state  )  p_node->p  nodeclass  =  pn_error  ; 

}  /*  p_parse_line  */ 

void  p_assem_line  (  char  *  line  , 

char  label [MAXSYMLEN]  , 

char  command [MAXSYMLEN ] , 

p_size_type  *  size  , 

char  *  numterms  , 

am_term_type  “  termlist  ) 


/*  current  parse  node. 


register  int  i  ; 

int  line_offset  =  0,  line_len; 

char  done  ,  mode,  reg  ; 

am_term_type  *  term  ,  *  prev  ; 

p_tok_type  tok  ; 

p_node_type  p_node  ;  /*  current  parse  node.  */ 

e_error .state  =  0  ; 

/*  clear  the  parameters  */ 
label [0]  =  0  ; 
command [0]  =  0  ; 

*size  =  p_unknown  ; 

*numterms  =  0  ; 

*termlist  =  NULL  ; 
line_len  =  strlen(line)  ; 

/*  read  the  line  label  */ 
if  (  isalpha(  line[0]  )  )  [ 

/*  scan  the  line  to  remove  the  label  string.  */ 
tok  =  next_token(  line  ,  &line_6ffset  ,  line_len)  ; 
if  (tok  ==  symbol) 

strncpy{  label, curtoksym.sym, MAXSYMLEN  ); 

) 

/*  read  the  command  */ 
i  =  line_offset  ; 

tok  =  next_token(  line  ,  &line_offset  ,  line_len)  ; 
switch  (  tok  )  { 

case  symbol  :  strncpy (command, curtoksym.sym, MAXSYMLEN) ; 

/*  check  for  size  identifier  */ 
i  =  line_offset  ; 

tok  =  next_token(  line  ,  &line_offset  ,  line_len)  ; 
switch  (  tok  )  ( 

case  symbol  :  line_offset  =  i  ;  break  ; 
case  token  :  *size  =  p_dotsize (line, &line_of fset, 
line_len, i) ; 

break; 

case  none  :  line  offset  =  i  ;  break  ; 


case  none  :  line_offset  =  i;  break  ; 

} 

i  =  0  ; 

done  =  FALSE  ; 

while  (  !  done  )  { 

p_parse_line (  line,  &line_offset, line_len, &p_node, &done) ; 
if  (  e_error .state  )  break  ; 
if  (  p_node .p_nodeclass  ==  pn_empty  )  break  ; 
switch  (  p_node.p_nodeclass  )  ( 
case  pn_sym  :  mode  =  7  ; 

reg  =  (  am_abs_address_size  ==  1  )?0:1  ;  break  ;  /*  sym  */ 
case  pn_empty  :  mode  =  7  ;  reg  =  5  ;  break  ;  /*  empty/none*/ 

case  pn_error  :  mode  =  7  ;  reg  =  11  ;  break  ;  /*  error  */ 


term  =  (  am_term_type  *  )  mal 
if  (  !term  )  ( 

e_message (0,  41,  "Parser")  ; 
break  ; 


)  malloc  (  sizeof (  am_term_type  )  ) 


/*  not  enough  memory 


term->modereg  =  (  mode  «  8  )  I  reg  ; 
term->symptr  =  p_node.symptr  ; 
term->next  =  NULL  ; 
term->prev  =  NULL  ; 
term->sizeofreserve  =  0  ; 
term->postword  =  0  ; 
term->class  =  am_other_instr_term  ; 

(* numterms) ++  ; 
if  (  ! (*termlist)  )  /*  if  termlist  =  NULL  */ 

*terralist  =  term  ; 
else  { 

term->prev  =  prev  ; 
prev->next  =  term  ; 

) 

prev  =  term  ; 

}  /*  while  */ 
if  (  *termlist  ) 

(*termlist) ->class  =  am_first_instr_term  ; 

)  /*  p_assem_line  */ 


Listing  Eight 


/*  68PSEUDO.C  -  68000  Pseudo  Module.  */ 

/*  Contains  procedures  for  psuedo  command  assembly.  */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦include  "68defs.h" 

♦include  "68err.h" 


♦include  "68parse.h" 
♦include  "681ist.h" 
♦include  "68assem.h" 
♦include  "68symtab.h" 
♦include  "68pseudo.h" 


typedef  struct  {  char  pseudo[10]; 

ps_pseudos  index  ; 

)  ps_pseudo_type  ; 

ps_pseudo_type  ps_pseudo_array  [7]  = 

(  (  "ABS_LONG"  ,  ps_abslong  ) 

(  "ABS_SHORT"  ,  ps_absshort) 

(  "END"  ,  ps_end  ) 

(  "EQU"  ,  ps_equate  } 

(  "EXTERN"  ,  ps_extern  ) 

(  "GLB"  ,  ps_global  } 

(  "ORG"  ,  ps_origin  ) 

int  ps_lookup_pseudo  (  char  *  pseudo  , 

ps_pseudos  *  pseudo_class  ) 


int  ps_lookup_pseudo  (  char 


ps_pseudo_type  *  indx  ; 

if  (  indx  =  (  ps_pseudo_type  *  )  bsearch(  pseudo,  ps_pseudo_array,  7, 
sizeof (ps_pseudo_type) , strcmp)  ) ( 

*pseudo_class  =  indx->index  ; 
return  1  ; 

} 

else 

return  0  ; 

}  /*  ps_lookup_pseudo  */ 

int  ps_one_symbol_only  (  p_sym_type  *  symlist  ) 

{ 

if  (  symlist  ) 

if  (  symlist->next  ) 
return  FALSE  ; 
else 

if  (  symlist->sym[0]  ) 
return  TRUE  ; 
else 

return  FALSE  ; 

else 

return  FALSE  ; 

)  /*  ps_one_symbol_only  */ 

int  ps_validate_pseudo  (  char  *  label  , 

char  numterms  , 

am_term_type  **  termlist  , 
char  onetermonly  , 

char  zeroterms  , 

char  forwardsallowed, 

char  labelrequired  , 

char  ignorlabel  , 

char  stringsallowed  , 

char  onesymbolonly  ) 

I 

am_term_type  *  term  ; 

p_sym_type  *  sym  ; 

int  i  ,  mode,  reg  ; 

if  (  (  onetermonly  &&  (  numterms  >  1  ))  !! 

(  zeroterms  &&  (  numterms  ))  )  ( 
e_message(0, 15, NULL)  ;  /*  requires  one  operand  */ 

i  =  15  ; 

goto  deleteterms  ; 


if  (  onetermonly  &&  (  numterms  ==  0 


e_message (0, 13, NULL) 
return  13  ; 


/*  requires  at  least  one  operand  */ 


/*  label  ignored. 


term=  term->next  )  { 


End  Listing  Seven 


if  (  labelrequired  &&  ! (*label)  )  { 

e_message(0, 16, NULL)  ;  /*  label  required  */ 

i  =  16  ; 

goto  deleteterms  ; 

) 

if  {  ignorlabel  &&  ‘label  ) 

ejnessage (0, 72, NULL  )  ;  /*  label  ignored.  */ 

if  (  numterms  ) 

/*  validate  each  term  */ 

for  (  term  =  ‘termlist  ;  term  ;  term=  term->next  )  { 
mode  =  term->modereg  »  8  ; 
reg  =  term->modereg  &  15  ; 

if  (  (  mode  ==  7  )  &&  (  reg  <=  1  )  )  { 

if  (  onesymbolonly  )  { 

if  (  !  ps_one_symbol_only (term->symptr)  )  { 
ejnessage (0, 11, NULL)  ;  /*  illegal  term  */ 
i  =  11  ; 

goto  deleteterms  ; 

} 

sym_add_operand_symbol (  term->symptr,  term,  FALSE 
if  (  (  term->symptr->sym[0]  ==  '*'  )  !! 

(  !term->symptr->sym[0]  ))  { 
ejnessage (0, 19, NULL) ; 
i  =  19  ; 

goto  deleteterms  ; 


else  { 

for  (  sym  =  term->symptr  ;  sym  ;  sym  =  sym->next  )  { 
if  (  sym->sym[0]  ) 

sym_add_operand_symbol (  sym,  term,  FALSE  ) ; 

} 

/*  compress  symbol  chain  and  hold  onto  number  of  unresolved  */ 

/*  symbols  in  postword  */ 

term->postword  =  am_resolve_symbol (term->symptr)  ; 

if  (  (  !  forwardsallowed  )  &&  (  term->postword  )  )  ( 

ejnessage (0, 14, NULL)  ;  /*  cannot  forward  reference  */ 

i  =  14  ; 

goto  deleteterms  ; 

) 

) 

) 

else  { 

if  (  !  (  stringsallowed  &&  (  mode  ==  7  )  &&  (  reg  ==  10  )  ))  { 
ejnessage (0, 11, NULL)  ;  /*  illegal  term  */ 
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i  =  11  ; 

goto  deleteterms  ; 

} 

} 

} 

return  0  ; 

deleteterms  :  /*  label  for  exit  with  deletion  of  terms  */ 

/*  i  will  contain  the  error  code  returned*/ 
if  (  numterms  )  /*  delete  all  terms  */ 

am_delete_terms (  termlist,  TRUE  ); 
return  i  ; 

}  /*  ps_validate_pseudo  */ 
int  ps_pseudo  (  char  *  label  , 

ps_pseudos  index  , 
char  numterms  , 

am_term_type  **  termlist  , 
char  *  line  ) 


am_term_type  *  term  ; 
int  i  ; 

l_line_type  *  lptr  ; 
switch  (  index  )  { 

case  ps_abslong  :  case  ps_absshort  : 
case  ps_even  :  case  ps_end  : 

l_addline(  l_neither  ,  0,  line,  &lptr);  /*  add  line  to  listing  */ 
if  (  *label  )  e_message (0, 72, NULL)  ;  /*  label  ignored.  */ 

if  (  numterms  )  e_message (0,73, NULL)  ;  /*  operands  ignored.  */ 
switch  (  index  )  { 

case  ps_abslong  :  am_abs_address_size  =  2  ;  break  ; 
case  ps_absshort  :  am_abs_address_size  =  1  ;  break  ; 
case  ps_even  :  if  (  am_location_counter  &  1  ) 
am_location_counter++  ; 
break; 

case  ps_end  :  am_end_found  =  TRUE  ;  break  ; 

} 

am_delete_terms (  termlist,  TRUE  )  ; 
return  0  ; 
case  ps_equate  : 

l_addline (l_neither,  0, line, Slptr)  ; 

/*  requires  one  term  only,  label  required.  */ 

if  {  i  =  ps_validate_pseudo  (  label,  numterms,  termlist, 

TRUE, FALSE, FALSE, TRUE, FALSE, FALSE, FALSE) ) 

return  i  ; 

/*  add  label  and  value  to  symbol  table  */ 
i  =  sym_add_label_symbol (  label,  (*termlist) ->symptr->val, 
am_absolute  )  ; 

am_delete_terms (  termlist,  TRUE  )  ; 
return  i  ; 
case  ps_extern  : 

l_addline (ljneither, 0, line,  & lptr)  ; 

/*  one  or  more  terms,  label  ignored,  one  symbol  per  each  term  */ 
if  (  i  =  ps_validate_pseudo  (  label,  numterms,  termlist, 

FALSE, FALSE, FALSE, FALSE, TRUE, FALSE, TRUE) ) 

return  i  ; 

/*  Add  each  symbol  to  the  external  symbol  list.  */ 
for  (  term  =  *termlist  ;  term  ;  term  =  term->next  ) 
if  (  i  =  sym_add_extern (term->symptr->sym)  )  { 
am_delete_terms (  termlist,  TRUE  ); 
return  i  ; 

} 

am_delete_terms (  termlist,  TRUE  ); 
return  0  ; 
case  ps_global  : 

l_addline (l_neither, 0, line, Slptr)  ; 

/*  one  or  more  terms,  label  ignored,  one  symbol  per  each  term  */ 
if  (  i  =  ps_validate_pseudo  (  label,  numterms,  termlist, 

FALSE, FALSE, FALSE, FALSE, TRUE, FALSE, TRUE) ) 

return  i  ; 

/*  Add  each  symbol  to  the  global  symbol  list.  */ 
for  {  term  =  *termlist  ;  term  ;  term  =  term->next  ) 
if  (  i  =  sym_add_global (term->symptr->sym)  )  { 
am_delete_terms (  termlist,  TRUE  ); 
return  i  ; 

} 

am_delete_terms (  termlist,  TRUE  ); 
return  0  ; 
case  ps_origin  : 

l_addline (l_neither, 0, line, &lptr)  ; 

/*  requires  one  term  only,  label  ignored.  */ 

if  (  i  =  ps_validate_pseudo  (  label,  numterms,  termlist, 

TRUE , FALSE , FALSE , FALSE , TRUE , FALSE , FALSE ) ) 

return  i  ; 

am_location_counter  =  (*termlist) ->symptr->val  ; 
am_delete_terms (  termlist,  TRUE  ); 
return  0  ; 

} 

return  0  ; 

)  /*  ps_pseudo  */ 

End  Listing  Eight 


Listing  Nine 

/*  68SYMTAB.C  -  68000  Symbol  table  Module.  Contains  those  */ 
/*  procedures  for  symbol  table.  */ 


#include  <stdio.h> 
♦include  <stdlib.h> 
♦include  <string.h> 


♦include 

♦include 

♦include 

♦include 

♦include 

♦include 


"68defs .h" 
"68err .h" 
"68parse.h" 
"681ist .h" 
"68assem.h" 
"68symtab.h' 


(continued  on  page  104) 
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Listing  Nine  (Listing  continued,  text  begins  on  page  50.) 

/*  Module  level  variable  */ 
sym_label_type  *  sym_glb_lab_head  =  NULL  ; 
sym  label_type  '  *  sym_local_lab_head  =  NULL  ; 

sym~operand_type  *  sym_ext_ref_head  =  NULL  ; 
sym  operand  type  *  sym_local_ref_head  =  NULL  ; 


/*  Local  prototypes  */ 

sym_operand_type  *  sym_lookup_extern (  char  *  symbol  )? 
sym_label_type  *  sym_lookup_local  (  char  *  symbol  ) ; 
int  sym_addtolocaloplist  (  p_sym_type  *  symptr  , 

am_term_type  *  termptr  )  ; 

void  sym_add_symtabtolisting() 

{ 

register  sym_label_type  *  labptr  ; 
sym_operand_type  *  refptr  ; 

l_line_type  *  lptr  ; 

char  *  message_buf  ,  *  chptr  ,  count  ; 

int  i  ; 

if  (  sym_glb_lab_head  ! !  sym_local_lab_head  ! !  sym_ext_ref_head  )  { 
l_addline (l_neither,  0, Slptr) ; 
l_addline (l_neither,  0, 

"  Symbol  Value  Class  ", Slptr); 

1  addline (1  neither,  0, 

H -  -  - ",  Slptr); 


} 

else 

return  ; 

message_buf  =  "  "  » 

for  (count  =  1  ;  count  <=  2  ;  count++  )  { 
if  (  count  ==  1  )  { 

strncpy (message_buf+33, "Global  ",7) ; 
labptr  =  sym_glb_lab_head  ; 

) 

else  { 

strncpy (message_buf +33, "Local  ",7) ; 
labptr  =  sym_local_lab_head  ; 

) 

for  (  ;  labptr  ;  labptr=  labptr->next  )  { 
i  =  strlen{  labptr->symbol  ); 
strncpy (  message_buf  +  1,  labptr->symbol,  i  ); 

for  (  chptr  =  message_buf  +  i  +  1  ;  i  <  MAXSYMLEN  ;  i++,  chptr++  ) 
*chptr  =  '  '  ; 

if  (  labptr->relative  ==  'V  )  { 

strncpy (  message_buf  +  23  ,"??????", 6  ); 
strncpy(  message_buf  +  43,"  Unknown  ",  10  ); 

1 


else  { 

sprintf(  message_buf+  23  , "%061X", labptr->val  ); 

message_buf [29]  =  '  '  ; 

if  (  labptr->relative  ==  '*'  ) 

strncpy(  message_buf  +  43,"  Relative  ",  10  ); 
else 

strncpy (  message_buf  +  43  , "  Absolute  ",  10  ); 

} 

l_addline(l_neither,  0,  message_buf  ,  Slptr  ); 

} 

} 

strncpy(  message_buf  +  23,  "??????", 6  ); 
strncpy(  message_buf  +  33,  "Extern  ",7); 
strncpy(  message_buf  +  43,  "  Unknown  ",  10  ); 

for  (  refptr  =  sym_ext_ref_head  ;  refptr  ;  refptr=  refptr->next  )  { 
i  =  strlen(  refptr->symbol  ); 
strncpy(  message_buf  +  1,  refptr->symbol,  i  ); 

for  (  chptr  =  message_buf  +  i  +  1  ;  i  <  MAXSYMLEN  ;  i++,  chptr++  ) 
*chptr  =  '  '  ; 

l_addline(l_neither,  0,  message_buf  ,  Slptr  ); 


}  /*  sym_add_symtabtolisting  */ 
int  sym_process_unresolved_locals () 


reflistptr  ; 
refptr  ; 
glbptr  ; 

lptr  ,  *  temp_lptr; 
error  ; 

message_buf [100]  ; 


int 

sym_ref_type 
s  ym_ope  r and_t  ype 
sym_label_type 
l_line_type 
err_type 
char 
i  =  0  ; 

/*  Process  global  label  list  first  */ 

for  (  glbptr  =  sym_glb_lab_head  ;  glbptr  ;  glbptr=  glbptr->next  )  { 
if  (  glbptr->relative  !=  'V  )  /*  if  its  known  then  go  to  next  one 

continue  ; 

e_message (0, 23,  NULL  ); 
i  ++  ; 

error  =  e_error .errptr  ; 

strcpy(  message_buf  ,  error->message  )  ; 

strcpy(  message_buf+strlen(error->message) ,  glbptr->symbol  ); 


l_addline (l_neither,  0,  message_buf  ,  Slptr  ); 
e_delete_errors {)  ; 

) 

/*  Process  the  local  reference  list.  */ 

for  (  refptr  =  sym_local_ref_head  ;  refptr  ;  refptr=  refptr->next  )  { 
e_message (0, 23,  refptr->symbol  ); 
i  ++  ; 

error  =  e_error .errptr  ; 

strcpy(  message_buf  ,  error->message  )  ; 

strcpy(  message_buf+strlen(error->message) ,  refptr->symbol  ); 
l_addline (l_neither,  0,  message_buf  ,  Slptr  ); 
l_addline (l_neither,  0,  message_buf  ,  Slptr  ); 

/*  unlink  the  second  redundant  line  */ 
lptr->next->prev  =  lptr->prev  ; 
lptr->prev->next  =  lptr->next  ; 

/*  link  second  line  into  listing  where  symbol  was  first  referenced  */ 

temp_lptr  =  refptr->list->termptr->lineptr  ; 

lptr->next  =  temp_lptr->next  ; 

lptr->next->prev  =  lptr  ; 

lptr->prev  =  temp_lptr  ; 

temp_lptr->next  =  lptr  ; 

e_delete_errors ()  ; 

} 


/*  delete  the  local  reference  list  */ 
while  (  refptr  =  sym_local_ref_head  )  { 
while  (  reflistptr  =  refptr->list  )  { 
refptr->list  =  refptr->list->next  ; 
free(  reflistptr  ); 

} 

sym_local_ref_head  =  refptr->next  ; 
free (  refptr  ) ; 


return  i  ; 

}  /*  sym_process_unresolved_locals  */ 
void  sym_delete_all_tables (  void  ) 

I 

sym_operand_type  *  refptr  ; 
sym_label_type  *  labptr  ; 
sym_ref_type  *  reflistptr  ; 

/*  delete  the  global  label  list  */ 
while  (  labptr  =  sym_glb_lab_head  )  { 
sym_glb_lab_head  =  labptr->next  ; 
free(  labptr  ); 

) 

/*  delete  the  local  label  list  */ 
while  (  labptr  =  sym_local_lab_head  )  { 
sym_local_lab_head  =  labptr->next  ; 
free(  labptr  ); 

) 

/*  delete  the  local  reference  list  */ 
while  (  refptr  =  sym_local_ref_head  )  { 
while  (  reflistptr  =  refptr->list  )  { 
refptr->list  =  refptr->list->next  ; 
free(  reflistptr  ); 

} 

sym_local_ref_head  =  refptr->next  ; 
free(  refptr  ); 

) 

/*  delete  the  external  reference  list  */ 
while  {  refptr  =  sym_ext_ref_head  )  { 

while  (  reflistptr  =  refptr->list  )  { 
refptr->list  =  refptr->list->next  ; 
free(  reflistptr  ); 

} 

sym_ext_ref_head  =  refptr->next  ; 
free(  refptr  ); 

) 

)  /*  sym_delete_all_tables  */ 

void  sym_resolve_back  (•  sym_label_type  *  symptr  ) 

{ 


unsigned  int  i  ; 

sym_operand_type  *  temp,  *  prev  ; 

sym_ref_type  *  refptr  ,  *  refhead  ,  *  tempref  ; 

p_sym_type  *  sym  ; 

am_term_type  *  termptr  ; 

int  warnings  ; 

prev  =  NULL  ; 

for  (  temp  =  sym_local_ref_head  ; 

temp  SS  strncmp(temp->symbol, symptr->symbol,  MAXSYMLEN  ; 
prev  =  temp  ,  temp  =  temp->next  ) ; 
if  (  !temp  )  return  ; 


/*  if  there  are  back  references  */ 

if  (  prev  )  /*  remove  the  operand  node  from  list.*/ 

prev->next  =  temp->next  ; 
else 

sym_local_ref_head  =  temp->next  ; 
refhead  =  temp->list  ; 
free(  temp  )  ; 
refptr  =  refhead  ; 
while  (  refptr  )  { 

termptr  =  refptr->termptr  ; 

for  (  sym  =  termptr->symptr  ;  sym  ;  sym=  sym->next  ) 

if  (  !  strncmp(  sym->sym,  symptr->symbol,  MAXSYMLEN  )  )  { 

/*  if  the  symbol  is  in  the  symbol  list  of  the  term  */ 

/*  then  resolve  it.  */ 
sym->val  =  symptr->val  ; 
sym->sym[0]  =  symptr->relative  ; 

sym->sym[l]  =  1  ;  /*  for  relative  put  in  count  after  it 

) 

refptr  =  refptr->next  ; 

} 

/*  compress  ref  list  so  that  only  unique  termlists  are  refered  to.  */ 


*/ 


refptr  =  refhead  ; 
while  (  refptr  )  { 

termptr  =  refptr->termptr  ; 
if  (  termptr  ) 
switch  (  termptr->class  )  { 
case  am_first_instr_term  : 

/*  get  rid  of  any  term  pointers  which  refer  to  the  */ 

/*  next  term  if  its  class  is  am_other_instr  */ 

/*  this  works  since  instructions  can  have  only  2  terms  */ 
if  (  termptr->next  ) 

if  {  termptr->next->class  ==  am_other_instr_term  )  ( 

for  (  tempref  =  refhead;  tempref  ;  tempref =tempref->next) 
if  (  tempref->termptr  ==  termptr->next  ) 
tempref->termptr  =  NULL  ; 


break  ; 

case  am_other_instr_term  : 

/*  back  up  to  first  instr  term  and  do  same  as  in  case  above*/ 
if  (  termptr->prev  )  /*  there  should  always  be  a  prev  term  */ 

if  (  termptr->prev->class  ==  am_first_instr_term  )  { 

for  (  tempref  =  refhead;  tempref  ;  tempref =tempref->next) 
if  (  tempref->termptr  ==  termptr->prev  ) 
tempref->termptr  =  NULL  ; 

) 

refptr->termptr  =  termptr->prev  ;  /*  set  ptr  to  first  term  */ 
break  ; 

case  am_data_term  : 

/*  resolve  only  one  data  term  at  a  time,  no  compression  */ 
break; 


refptr  =  refptr->next  ; 


(continued  on  page  106) 
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listing  Nine  ( Listing  continued,  text  begins  on  page  50.) 

/*  resolve  terms  and  dispose  of  reference  list.  */ 
refptr  =  refhead  ; 
while  (  refptr  )  { 

termptr  =  refptr->termptr  ; 

tempref  =  refptr->next  ; 

free (refptr) ; 

refptr  =  tempref  ; 

if  (  ! termptr  )  continue  ; 

i=am_resolve_term(  termptr, (  termptr->class  ==  am_data_term) ?1 : 0) ; 
if  (  ! i  )  {  /*  if  all  resolved  */ 

warnings  =  e_error. warnings  ; 
am_backf ill (  termptr  ); 
if  (  e_error .warnings  >  warnings  ) 
l_add_errors (  termptr->lineptr  ); 
warnings  =  e_error .warnings  ; 
am  remove_terms_from_list (Stermptr)  ; 

) 

} 

}  /*  sym_resolve_back  */ 

sym_label  type  *  sym_lookup_global (  char  *  symbol  ) 

{ 

sym_label_type  *  temp  ; 

for  (  temp  =  sym_glb_lab_head  ; 

temp  &&  strncmp (temp->symbol, symbol,  MAXSYMLEN  )  ; 
temp  =  temp->next  ) ; 

return  temp  ;  ■■ 

)  /*  sym_lookup_global  */ 

int  sym_add_global (  char  *  symbol  ) 

{ 

sym_label_type  *  temp  ; 

if  (  sym_lookup_global (  symbol  )  )  { 

e jnessage (0,74, NULL)  ;  /*  WARNING  symbol  already  in  gib  list.*/ 

return  0  ; 

} 

if  (  temp  =  (  sym_label_type  *  )  malloc  (  sizeof (sym_label_type)  )  )  ( 
strncpy(  temp->symbol,  symbol,  MAXSYMLEN  ); 
temp->relative  =  '?'  ; 
temp->next  =  sym_glb_lab_head  ; 
temp->val  =  0L  ; 
sym_glb_lab_head  =  temp  ; 
return  0  ; 

I 

e_message (0, 41, NULL)  ;  /*  out  of  memory  */ 
return  41  ; 

}  /*  sym_add_global  */ 

sym_operand_type  *  sym_lookup_extern (  char  *  symbol  ) 

{ 

sym_operand_type  *  temp  ; 
for  (  temp  =  sym_ext_ref_head  ; 

temp  &&  strncmp (temp->symbol, symbol,  MAXSYMLEN  )  ; 
temp  =  temp->next  ) ; 
return  temp  ; 

)  /*  sym_lookup_ext  */ 

int  sym_add_extern(  char  *  symbol  ) 

{ 

sym_operand_type  *  temp  ; 

if  (  sym_lookup_extern(  symbol  )  )  ( 

e_message (0,75, NULL)  ;  /*  WARNING  symbol  already  in  extern  list.*/ 

return  0  ; 

} 

if  (  temp  =  (  sym_operand_type  *  )  malloc  (  sizeof (sym_operand_type)  )  )  { 
strncpy(  temp->symbol,  symbol,  MAXSYMLEN  ); 
temp->next  =  sym_ext_ref_head  ; 
temp->list  =  NULL  ; 
sym_ext_ref_head  =  temp  ; 
return  0  ; 

) 

ejnessage (0, 41, NULL)  ;  /*  out  of  memory  */ 
return  41  ; 

}  /*  sym_add_extern  */ 

sym_label_type  *  sym_lookup_local (  char  *  symbol  ) 

{ 

sym_label_type  *  temp  ; 

for  (  temp  =  sym_local_lab_head  ; 

temp  &&  strncmp (temp->symbol, symbol,  MAXSYMLEN  )  ; 
temp  =  temp->next  ) ; 
return  temp  ; 

}  /*  sym_lookup_local  */ 

int  sym_add_label_symbol  (  char  *  symbol  , 

unsigned  long  val  , 
am_assem_type  relative  ) 

{ 

sym_label_type  *  temp  ; 

if  (  sym_lookup_extern (  symbol  )  )  ( 

e_mes sage (0, 17, NULL)  ;  /*  label  symbol  already  in  extern  list.*/ 

return  17;  /*  cannot  resolve  locally.  */ 

} 

if  (  temp  =  sym_lookup_global (  symbol  )  )  {  /*  in  global  list  */ 

if  (  temp->relative  =='?'){  /*  not  resolved  yet.  */ 

temp->relative  =  (  relative  ==  am_relative  )  ?  '*'  :  0  ; 
temp->val  =  val  ; 

/*  resolve  back  references  */ 

sym_resolve_back (  temp  ); 
return  0  ; 

1 

else  ( 

e_mes sage (0, 18, NULL)  ;  /*  symbol  already  resolved  */ 

return  18  ; 


if  (  sym_lookup_local (  symbol  )  )  ( 

ejnessage (0, 18, NULL)  ;  /*  symbol  already  resolved  in  local  list.*/ 

return  18  ; 

} 

if  (  temp  =  (  sym_label_type  *  )  malloc (  sizeof (sym_label_type) )  )  ( 
strncpy(  temp->symbol,  symbol,  MAXSYMLEN  ); 
temp->relative  =  (  relative  ==  am_relative  )?'*':  0  ; 
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temp->next  =  sym_local_lab_head  ; 
temp->val  =  val  ; 
sym_local_lab_head  =  temp  ; 

/*  resolve  back  references  */ 

sym_resolve_back (  temp  ) ; 
return  0  ; 

} 

else  { 

ejnessage (0, 41, NULL)  ;  /*  out  of  memory  */ 

return  41  ; 

} 

}  /*  sym_add_label_symbol  */ 

int  sym_add_operand_symbol  (  p_sym_type  *  symptr  , 

am_term_type  *  termptr  , 

char  addref  ) 

( 

sym  operand_type  *  temp  ; 
sym_ref_type  *  temp2  ; 
sym_label_type  *  temp3  ; 

if  (  temp  =  sym_lookup_extern (  symptr->sym  )  )  {  /*  in  extern  list  */ 

if  (  !  addref  )  return  0  ; 

if  (  temp2  =  (  sym_ref_type  *  )  malloc (  sizeof (sym_ref_type) )  )  ( 
temp2->termptr  =  termptr  ; 
temp2->next  =  temp->list  ; 
temp->list  =  temp2  ; 
return  0  ; 

} 

else  { 

ejnessage (0, 41, NULL)  ;  /*  not  enough  memory  */ 

return  41  ; 

} 

if  (  temp3  =  sym_lookup_global (  symptr->sym  )  )  {  /*  in  global  list  */ 

if  (  temp3->relative  ==  '?'  )  /*  not  resolved  yet.  */ 

if  (  !  addref  )  return  0  ; 

else  return  sym_addtolocaloplist (  symptr,  termptr  )  ; 
else  { 

symptr->val  =  temp3->val  ;  /*  resolve  the  symbol  */ 

symptr->sym(0]  =  temp3->relative  ; 

symptr->sym[l]  =  1  ;  /*  set  relative  count  to  1  */ 

return  0  ; 

) 

} 

if  (  temp3  =  sym_lookup_local (  symptr->sym  )  )  { 

symptr->val  =  temp3->val  ;  /*  resolve  the  symbol*/ 

symptr->sym[0]  =  temp3->relative  ; 

symptr->sym[l]  =  1  ;  /*  set  relative  count  to  1  */ 

return  0  ; 

} 

else 

if  (  !  addref  )  return  0  ; 

else  return  sym_addtolocaloplist (  symptr,  termptr  )  ; 

}  /*  sym_add_operand_symbol  */ 

int  sym_addtolocaloplist  (  p_sym_type  *  symptr  , 
am_term_type  *  termptr  ) 

{ 

sym_operand_type  *  temp  ; 
sym_ref_type  *  temp2  ; 

for  (  temp  =  sym_local_ref_head  ; 

temp  &&  strncmp(temp->symbol,symptr->sym,  MAXSYMLEN  )  ; 
temp  =  temp->next  ) ; 
if  (  temp  ) 

if  (  temp2  =  (  sym_ref_type  *  )  malloc(  sizeof (sym_ref_type) )  )  { 
temp2->termptr  =  termptr  ; 
temp2->next  =  temp->list  ; 
temp->list  =  temp2  ; 
return  0  ; 

) 

else  { 

ejnessage (0, 41, NULL)  ;  /*  not  enough  memory  */ 
return  41  ; 

} 

else 

if  (  temp  =  (  sym_operand_type  *  )  malloc  (sizeof (sym_operand_type) )  ) 
if  (  temp2  =  (  sym_ref_type  *  )  malloc (  sizeof (sym_ref_type) )  )  { 
strncpy(  temp->symbol,  symptr->sym,  MAXSYMLEN  ); 
temp->next  =  sym_local_ref_head  ; 
temp->list  =  temp2  ; 
sym_local_ref_head  =  temp  ; 
temp2->termptr  =  termptr  ; 
temp2->next  =  NULL  ; 
return  0  ; 

} 

else  { 

free (temp) ; 

e_message (0, 41, NULL) ;  /*  not  enough  memory  */ 

return  41  ; 

1 

else  { 

e_message (0, 41, NULL) ;  /*  not  enough  memory  */ 

return  41  ; 

) 

}  /*  sym_addtolocaloplist  */ 


End  Listings 
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EXAMINING  ROOM 


Window  coordinates 
ColorSet  } 

Win  options  ) 
Buffer  size  } 


InitStatus) ; 


Listing  One  (Text  begins  on  page  62.) 

program  Edit; 

uses  OpCrt,  OpRoot,  OpCmd,  OpFrame,  OpWindow,  OpMemo,  OpEditor; 
var 

TE  :  TextEditor; 

FSize  :  Longlnt; 

ExitCommand  :  Word; 

AllDone  :  Boolean; 
begin 

if  not  TE. InitCustom(2,  4,  79,  24, 

DefaultColorSet, 

DefWindowOptions  or  wBordered, 

65521) 

then 
begin 

WriteLn (' Failed  to  init  TextEditor.  Status 
Halt; 
end; 

(  use  built-in  status  and  error  handlers  provided  by  OPMEMO  } 
TE.SetStatusProc(MemoStatus) ; 

TE.SetErrorProc (MemoError) ; 

1  Create  and  Read  a  text  file  } 

TE .ReadFile (' AnyFile' ,  FSize); 

AllDone  :=  False; 
repeat 
TE. Process; 

ExitCommand  :=  TE.GetLastCommand; 
case  ExitCommand  of 

ccSaveExit,  {  Save  and  exit  —  file  already  saved  } 

ccAbandonFile,  (  Abandon  file  } 

ccError  :  (  Fatal  error  ) 

AllDone  :=  True; 

{...user  exit  commands..} 
end; 

until  AllDone; 

TE. Erase ; 

TE.Done; 

ClrScr; 

end. 

End  Listing  One 

Listing  Two 

program  HelloWorld; 

Uses  HWMain,  OpSwap; 
begin 

HelloWorldMain; 

end; 

unit  HWMain; 
interface 

uses 

OpInLine,  OpSwapl; 


procedure  HelloWorldMain; 

implementation 

const 

HotKey  =  $080F  {  code  for  ALT-TAB  ) 

Swapl  =  ' Hellol .SWP' ; 

Swap2  =  ' Hello2 . SWP' ; 

{ $F+ } 

procedure  PopUpEntryPoint; 
begin 

Writeln (' Hello  World'); 
end; 

{ $F— } 

procedure  HelloWorldMain; 
begin 

SetSwapMsgOn (  not  WillSwapUseEMS (ParagraphsToKeep)  ); 

{  define  the  popup  } 

if  DefinePop (HotKey,  PopUpEntryPoint,  Ptr ($SSeg, SPtr) )  then 
begin 

Writeln (' PopUp  loaded,  press  <ALT><TAB>  to  activate.'); 

{  Make  Popup  routines  active.  ) 

PopUpsOn; 

{  Try  to  go  resident.  } 

StayResSwap (ParagraphsToKeep,  0,  Swapl,  Swap2,  True) ; 
end; 

{  If  we  get  here,  report  failure.  } 

Writeln ('Unable  to  go  resident.  '); 
end; 

end. 


End  Listing  Two 


Listing  Three 


program  CommandWindowExample;  (EXCMDWIN.PAS) 
uses 

OpCrt,  OpRoot,  OpCmd,  OpFrame,  OpWindow; 
const 

(Define  a  trivial  KeySet  of  a  few  cursor  commands 
KeyMax  =  18; 

KeySet  :  array [0. .KeyMax)  of  Byte 


(length  keys  command  type 

3,  $00,  $48,  ccUp, 

3,  $00,  $50,  ccDown, 

3,  $00,  $4B,  ccLeft, 

3,  $00,  $4D,  ccRight, 

2,  $1B,  ccQuit) ; 

type 

SampleWindow  = 

object ( Comma ndWindow) 

procedure  Process;  virtual; 
end; 

var 

Commands  :  CommandProcessor; 
CmdWin  :  SampleWindow; 

Finished  :  Boolean; 
procedure  SampleWindow. Process; 
begin 
repeat 

(Get  a  command) 
GetNextCommand; 
case  GetLastCommand  of 


=  ( 

key  sequence) 
(Up) 

( Down ) 

(Left) 

(Right ) 

(Esc) 


WriteLn (' ccUp' ) ; 
WriteLn ('ccDown' ) ; 
WriteLn ('ccLeft' )  ; 
WriteLn ('  ccRight' )  ; 
WriteLn ('  ccQuit' )  ; 
WriteLn (' ccChar :  ', 
WriteLn (' ccNone' ) ; 


Char (Lo (GetLastKey) ) 


(Window  coordinates) 
(Color  set) 

(Window  options) 
(Command  processor) 
(Unit  code) 

InitStatus) ; 


ccUp  : 
ccDown  : 
ccLeft  : 
ccRight 
ccQuit  : 
ccChar  : 
else 
end; 

until  (GetLastCommand  =  ccQuit)  or  (GetLastCommand  =  ccError); 
end; 
begin 

(Make  a  small  CommandProcessor) 

Commands . Init (@KeySet,  KeyMax); 

(Make  a  bordered  CommandWindow) 
if  not  CmdWin. InitCustom (30,  5,  50,  15, 

DefaultColorSet, 
wBordered+wClear+wSaveContents, 

Commands, 
ucNone) 

then  begin 

WriteLn ('Failed  to  init  CommandWindow.  Status  = 

Halt; 
end; 

(Add  headers  and  draw  window) 

CmdWin. wFrame . AddHeader ('  Command  window  ',  heTC); 

CmdWin. wFrame .AddHeader ('  <Esc>  to  Quit  ',  heBC) ; 

CmdWin. Draw;  p7  3 
(Get  and  process  commands) 

Finished  :=  False; 
repeat 

CmdWin . Process ; 
case  CmdWin. GetLastCommand  of 
ccQuit  :  Finished  :=  True; 
ccError  :  begin 

WriteLn (' Error :  ', 

Finished  :=  True; 
end; 

ccUserO. .ccUser55  :  WriteLn (' user  command'); 
end; 

until  Finished; 

(Clean  up) 

CmdWin. Done; 

Commands .  Done ;  End  Listings 

end. 


(Quit) 

(Error) 


CmdWin. GetLastError) ; 


(Handle  exit  command) 
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Listing  One  (Text  begins  on  page  70.) 


1: 

2:  ( 
3:  ( 
4:  ( 

5:  ( 
6:  ( 
7:  ( 
8:  ( 
9:  ( 
10:  ( 
in  ( 
12:  ( 

13!  ( 

14;  ( 

15!  ( 

16! 

17: 

is: 

19: 

20: 

21! 

22! 

23! 

241 

25! 

26! 

27! 

281 

291 

30 : 
31: 
32: 
33: 
34: 
35: 

36: 

37: 
38! 
391 
40 : 
41: 
42: 
43: 
44: 
45: 

46: 

47: 

48: 

49! 

50! 

51! 

52! 

53! 

54! 

55! 

56: 

571 

58! 

591 

60! 

61 : 

62! 

631 

64: 

65! 

66! 

67! 

681 

691 

70 : 

71! 

72! 

73! 

74! 

75! 

76! 

77! 

78! 

79: 

80: 

81! 

82: 

83: 

84: 

85! 

86! 

87: 

88: 

89: 

90 : 

91: 

92: 

93: 

94: 

95: 

96: 

97: 

98: 

99: 

100: 

101: 

102: 

103: 

104: 

105: 

106: 

107: 

108: 

109: 


MODULE  PCKermit; 


*  *) 

*  PCKermit  —  by  Brian  R.  Anderson  *) 

*  Copyright  (c)  1990  *) 

*  PCKermit  is  an  implementation  of  the  Kermit  file  transfer  protocol  *) 

*  developed  at  Columbia  University.  This  (OS/2  PM)  version  is  a  *) 

*  port  from  the  DOS  version  of  Kermit  that  I  wrote  two  years  ago.  *) 

*  My  original  DOS  version  appeared  in  the  May  1989  issue  of  DDJ.  *) 

*  The  current  version  includes  emulation  of  the  TVI950  Video  Display  *) 


*  The  current  version  includes  emulation  of  the  TVI950  Video  Display  *) 

*  Terminal  for  interaction  with  IBM  mainframes  (through  the  IBM  7171).*) 


FROM  SYSTEM  IMPORT 
ADR; 

FROM  OS2DEF  IMPORT 

HAB,  HWND,  HPS,  NULL,  ULONG; 

FROM  PMWIN  IMPORT 

MPFROM2SHORT,  HMQ,  QMSG,  CS_SIZEREDRAW,  WS_VISIBLE,  FS_ICON, 
FCF_TITLEBAR,  FCF_SYSMENU,  FCF_SIZEBORDER,  FCF_M INMAX,  FCF_ACCELTABLE, 
FCF_SHELLPOSITION,  FCFJTASKLIST,  FCF_MENU ,  FCF_ICON, 

SWP_MOVE,  SWP_SIZE,  SWP_MAXIMIZE, 

HWND_DESKTOP ,  FID_SYSMENU,  SC_CLOSE,  MIA_DISABLED,  MM_SETITEMATTR, 
Winlnitialize,  WinCreateMsgQueue,  WinGetMsg,  WinDispatchMsg,  WinSendMsg, 
WinRegisterClass,  WinCreateStdWindow,  WinDestroyWindow,  WinWindowFromID, 
WinDestroyMsgQueue,  WinTerminate,  WinSetWindowText, 

WinSetWindowPos ,  WinQueryWindowPos ; 

FROM  KH  IMPORT 
IDM_KERMIT; 

FROM  Shell  IMPORT 

Class,  Title,  Child,  WindowProc,  ChildWindowProc, 

FrameWindow,  ClientWindow,  SetPort,  Pos; 


CONST 

QUEUE_SIZE  =  1024;  (*  Large  message  queue  for  async  events  *) 

VAR 

AnchorBlock  :  HAB; 

MessageQueue  :  HMQ; 

Message  :  QMSG; 

FrameFlags  :  ULONG; 
hsys  :  HWND; 


BEGIN  (*  main  *) 

AnchorBlock  :=  Winlnitialize  (0) ; 

IF  AnchorBlock  #  0  THEN 

MessageQueue  :=  WinCreateMsgQueue  (AnchorBlock,  QUEUE_SIZE); 

IF  MessageQueue  #  0  THEN 

(*  Register  the  parent  window  class  *) 

WinRegisterClass  ( 

AnchorBlock, 

ADR  (Class), 

WindowProc, 

CS_SIZEREDRAW,  0) ; 

(*  Register  a  child  window  class  *) 

WinRegisterClass  ( 

AnchorBlock, 

ADR  (Child), 

ChildWindowProc, 

CS_SIZEREDRAW,  0) ; 

(*  Create  a  standard  window  *) 

FrameFlags  :=  FCF_TITLEBAR  +  FCF_MENU  +  FCF_MINMAX  + 

FCF_SYSMENU  +  FCF_SIZEBORDER  +  FCF_TASKLIST  + 
FCF  ICON  +  FCF  SHELLPOSITION  +  FCF  ACCELTABLE; 


FrameWindow  :=  WinCreateStdWindow  ( 


) ; 


HWND_DESKTOP , 
WS_VISIBLE  +  FS_ICON, 
FrameFlags, 

ADR (Class) , 

NULL, 

WS_VISIBLE, 

NULL, 

IDM_KERMIT, 
ClientWindow  (* 


(*  handle  of  the  parent  window 
(*  the  window  style  *) 

(*  the  window  flags  *) 

(*  the  window  class  *) 

(*  the  title  bar  text  *) 

(*  client  window  style  *) 

(*  handle  of  resource  module 
(*  resource  id  *) 
returned  client  window  handle  *) 


*) 


IF  FrameWindow  #  0  THEN 

(*  Disable  the  CLOSE  item  on  the  system  menu  *) 
hsys  :=  WinWindowFromID  (FrameWindow,  FID_SYSMENU) ; 
WinSendMsg  (hsys,  MM_SETITEMATTR, 

MPFROM2 SHORT  (SC_CLOSE,  1), 

MPFROM2 SHORT  (MIA_DISABLED,  MIA_DISABLED) ) ; 


(*  Expand  Window  to  Nearly  Full  Size,  And  Display  the  Title  *) 
WinQueryWindowPos  ( HWND_DESKTOP ,  ADR  (Pos)); 

WinSetWindowPos  (FrameWindow,  0, 

Pos.x  +  3,  Pos.y  +  3,  Pos.cx  -  6,  Pos.cy  -  6, 

SWP_MOVE  +  SWP_SIZE) ; 

WinSetWindowText  (FrameWindow,  ADR  (Title) ) ; 


SetPort;  (*  Try  to  initialize  communications  port  *) 

WHILE  WinGetMsg (AnchorBlock,  Message,  NULL,  0,  0)  #  0  DO 
WinDispatchMsg (AnchorBlock,  Message) ; 

END; 


no: 

111  I  WinDestroyWindow (FrameWindow) ; 

112:  END; 

113 1  WinDestroyMsgQueue (MessageQueue) ; 

1141  END; 

115 :  WinTerminate (AnchorBlock) ; 

116:  END; 

1171  END  PCKermit. 

118: 

119: 


End  Listing  One 


Listing  Two 

120 : 

DEFINITION  MODULE  Shell; 

121 : 

122: 

FROM  OS2DEF  IMPORT 

123: 

USHORT,  HWND; 

124: 

125: 

FROM  PMWIN  IMPORT 

126: 

MPARAM,  MRESULT,  SWP; 

127: 

128: 

EXPORT  QUALIFIED 

129: 

Class,  Child,  Title,  FrameWindow,  ClientWindow, 

130 : 

ChildFrameWindow,  ChildClientWindow,  Pos,  SetPort, 

131 : 

WindowProc,  ChildWindowProc; 

132: 

133: 

CONST 

134: 

Class 

=  "PCKermit"; 

135: 

Child 

="Child"; 

136: 

Title 

=  "PCKermit  —  Microcomputer  to  Mainframe  Communications 

137: 

138: 

139: 

VAR 

140 

FrameWindow  :  HWND; 

141 

ClientWindow  :  HWND; 

142: 

ChildFrameWindow  :  HWND; 

143: 

ChildClientWindow  :  HWND; 

144: 

Pos  : 

SWP;  (*  Screen  Dimensions:  position  &  size  *) 

145: 

comport  :  CARDINAL; 

146: 

147: 

148: 

PROCEDURE  SetPort; 

149! 

150 

PROCEDURE  WindowProc  ['WindowProc']  { 

151 

hwnd 

HWND; 

152: 

msg 

USHORT; 

153: 

mpl 

MPARAM; 

154: 

mp2 

MPARAM)  :  MRESULT  [LONG,  LOADDS] ; 

155: 

156: 

PROCEDURE  ChildWindowProc  ('ChildWindowProc']  ( 

157: 

hwnd 

HWND; 

158: 

msg 

USHORT; 

159: 

mpl 

MPARAM; 

160 

mp2 

MPARAM)  :  MRESULT  [LONG,  LOADDS]; 

161 

162! 

END  Shell. 

163: 

164: 

End  Listing  Two 


Listing  Three 

1651  DEFINITION  MODULE  Term;  (*  TVI950  Terminal  Emulation  For  Kermit  *) 

1661 

167!  EXPORT  QUALIFIED 

168!  WM_TERM,  WM_TERMQUIT, 

1691  Dir,  TermThrProc,  InitTerm,  PutKbdChar,  PutPortChar; 

170 : 

171 :  CONST 

172:  WM_TERM  =  4000H; 

173!  WM_TERMQUIT  =  4001H; 

174! 

175: 

176:  PROCEDURE  Dir  (path  :  ARRAY  OF  CHAR); 

177,'  (*  Displays  a  directory  *) 

178: 

17-9:  PROCEDURE  TermThrProc; 

180 1  (*  Thread  to  get  characters  from  port,  put  into  buffer,  send  message.*) 

181 : 

182!  PROCEDURE  InitTerm; 

183!  (*  Clear  Screen,  Home  Cursor,  Get  Ready  For  Terminal  Emulation  *) 

1841 

185:  PROCEDURE  PutKbdChar  (chi,  ch2  :  CHAR); 

186:  (*  Process  a  character  received  from  the  keyboard'*) 

1871 

188:  PROCEDURE  PutPortChar  (ch  :  CHAR); 

1891  (*  Process  a  character  received  from  the  port  *) 

190 : 

191 :  END  Term. 

1921 


Listing  Four 


End  Listing  Three 


193:  DEFINITION  MODULE  Screen; 

194:  (*  Module  to  perform  "low  level"  screen  functions  (via  AVIO)  *) 

1951 

1961  FROM  PMAVIO  IMPORT 
1971  HVPS; 

1981 

(continued  on  page  110) 
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Listing  Four  (Listing  continued,  text  begins  on  page  70.) 


199: 
200: 
201: 
202: 
203: 
204: 
205: 
206! 
207: 
208: 
209: 
210: 
211: 
212: 
213: 
214: 
2.-15: 
216: 
217: 
218: 
219: 
220: 
221: 
222: 
223: 
224: 
225: 
226: 
227! 
2281 
2291 
230 : 

231 : 

232! 
233! 
234! 
2351 
2361 
237! 
238! 
239! 
240 : 

241 : 

242: 

243: 

244! 
245! 
246! 
2471 
248: 
249: 
250 : 

251 : 


EXPORT  QUALIFIED 

NORMAL,  HIGHLIGHT,  REVERSE,  attribute,  ColorSet,  hvps. 
White,  Green,  Amber,  Colorl,  Color2, 

ClrScr,  ClrEol,  GotoXY,  GetXY, 

Right,  Left,  Up,  Down,  Write,  WriteLn,  WriteString, 
Writelnt,  WriteHex,  WriteAtt; 


VAR 

NORMAL  :  CARDINAL; 

HIGHLIGHT  :  CARDINAL; 

REVERSE  :  CARDINAL; 
attribute  :  CARDINAL; 

ColorSet  :  CARDINAL; 

hvps  :  HVPS;  (*  presentation  space  used  by  screen  module  *) 


PROCEDURE  White; 

(*  Sets  up  colors:  Monochrome  White  *) 


PROCEDURE  Green; 

(*  Sets  up  colors:  Monochrome  Green  *) 


PROCEDURE  Amber; 

(*  Sets  up  colors:  Monochrome  Amber  *) 


PROCEDURE  Colorl; 

(*  Sets  up  colors:  Blue,  Red,  Green  *) 


PROCEDURE  Color2; 

(*  Sets  up  colors:  Green,  Magenta,  Cyan  *) 


PROCEDURE  ClrScr; 

(*  Clear  the  screen,  and  home  the  cursor  *) 


PROCEDURE  ClrEol; 

(*  clear  from  the  current  cursor  position  to  the  end  of  the  line  *) 


PROCEDURE  Right; 

(*  move  cursor  to  the  right  *) 


PROCEDURE  Left; 

(*  move  cursor  to  the  left  *) 


PROCEDURE  Up; 

(*  move  cursor  up  *) 


PROCEDURE  Down; 

(*  move  cursor  down  *) 


PROCEDURE  GotoXY  (col,  row  :  CARDINAL); 
(*  position  cursor  at  column,  row  *) 


252!  PROCEDURE  GetXY  (VAR  col,  row  :  CARDINAL); 

253!  (*  determine  current  cursor  position  *) 

2541 

2551  PROCEDURE  Write  (c  :  CHAR); 

2561  (*  Write  a  Character,  Teletype  Mode  *) 

2571 

2581  PROCEDURE  WriteString  (str  :  ARRAY  OF  CHAR); 

259!  (*  Write  String,  Teletype  Mode  *) 

260 : 

261 1  PROCEDURE  Writelnt  (n  :  INTEGER;  s  :  CARDINAL); 

262,'  (*  Write  Integer,  Teletype  Mode  *) 

2631 

2641  PROCEDURE  WriteHex  (n,  s  :  CARDINAL); 

265!  (*  Write  a  Hexadecimal  Number,  Teletype  Mode  *) 

2661 

267:  PROCEDURE  WriteLn; 

2681  (*  Write  <cr>  <lf>.  Teletype  Mode  *) 

269! 

270 1  PROCEDURE  WriteAtt  (c  :  CHAR); 

271 !  (*  write  character  and  attribute  at  cursor  position  *) 

2721 

2731  END  Screen. 

2741 

2751 

End  Listing  Four 

Listing  Five 

276!  DEFINITION  MODULE  PAD;  (*  Packet  Assembler/Disassembler  for  Kermit  *) 
2771 

2781  FROM  PMWIN  IMPORT 

2791  MPARAM; 

280 : 

281 :  EXPORT  QUALIFIED 

2821  WM_PAD,  PAD_Quit,  PAD_Error,  PacketType,  yourNPAD,  yourPADC,  yourEOL, 
283!  Aborted,  sFname,  Send,  Receive,  DoPADMsg; 

284! 

2851  CONST 

2861  WM_PAD  =  5000H; 

2871  PAD_Quit  =  0; 

28  8  f  PAD_Error  =  20; 

2891 

290 :  TYPE 

291 :  (*  PacketType  used  in  both  PAD  and  DataLink  modules  *) 

2921  PacketType  =  ARRAY  [1 . .100]  OF  CHAR; 

2931 

294!  VAR 

295!  (*  yourNPAD,  yourPADC,  and  yourEOL  used  in  both  PAD  and  DataLink  *) 

296!  yourNPAD  :  CARDINAL;  (*  number  of  padding  characters  *) 

297!  yourPADC  :  CHAR;  (*  padding  characters  *) 

2981  yourEOL  :  CHAR;  (*  End  Of  Line  —  terminator  *) 

2991  sFname  :  ARRAY  [0..20]  OF  CHAR; 

300 :  Aborted  :  BOOLEAN; 

301 : 

302 :  PROCEDURE  Send; 

303!  (*  Sends  a  file  after  prompting  for  filename  *) 

304: 

3051  PROCEDURE  Receive; 

3061  (*  Receives  a  file  (or  files)  *) 

3071 

3081  PROCEDURE  DoPADMsg  (mpl,  mp2  :  MPARAM); 

3091  (*  Output  messages  for  Packet  Assembler/Disassembler  *) 

310 : 

311 :  END  PAD. 

312: 

End  Listing  Five 


Listing  Six 

313!  DEFINITION  MODULE  DataLink;  (*  Sends /Receives  Packets  for  PCKermit  *) 

3141 

315:  FROM  PMWIN  IMPORT 

316:  MPARAM; 

317: 

318:  FROM  PAD  IMPORT 

319!  PacketType; 

320 : 

321 :  EXPORT  QUALIFIED 

322!  WM_DL,  FlushUART,  SendPacket,  ReceivePacket,  DoDLMsg; 

3231 

3241  CONST 

325:  WMDL  =  6000H; 

3261 

3271  PROCEDURE  FlushUART; 

328!  (*  ensure  no  characters  left  in  UART  holding  registers  *) 

3291 

330 !  PROCEDURE  SendPacket  (s  :  PacketType); 

331 1  (*  Adds  SOH  and  Checksum  to  packet  *) 

3321 

3331  PROCEDURE  ReceivePacket  (VAR  r  :  PacketType)  :  BOOLEAN; 

3341  (*  strips  SOH  and  checksum  —  returns  status:  TRUE  =  good  packet  *) 

3351  (*  received;  FALSE  =  timed  out  waiting  for  packet  or  checksum  error  *) 

3361 

3371  PROCEDURE  DoDLMsg  (mpl,  mp2  :  MPARAM); 

338!  (*  Process  DataLink  Messages  *) 

3391 

340  I  END  DataLink. 

341 : 

End  Listing  Six 


Listing  Seven 

343:  j* 

3441  (*  Copyright  (C)  1988,  1989 

3451  (*  by  Stony  Brook  Software 

3461  (* 

347!  (*  All  rights  reserved. 

3481  (* 


**) 

*) 

*) 

*) 

*) 

*) 

*) 

**) 
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350 : 

351 : 

352! 
353: 
354: 
355: 
356: 
357: 
358: 
359: 
360 : 
361 : 
362! 
363: 
364: 
365! 
366: 
367! 
368: 
369: 
370 : 

371 : 

3721 
373! 
374: 
375! 
3761 
377! 
378! 
3791 
380 : 
381 : 
382! 
383! 
384: 
3851 
386! 
3871 
3881 
3891 
390 : 

391 : 

392: 

393: 

394: 

395: 

396: 

397! 


DEFINITION  MODULE  CommPort; 

TYPE 

CommStatus  =  ( 

Success, 

InvalidPort, 

InvalidParameter, 

AlreadyReceiving, 

NotReceiving, 

NoCharacter, 

FramingError, 

OverrunError, 

ParityError, 

BufferOverflow, 

TimeOut 

) ; 


BaudRate  =  ( 

BaudllO, 

Baudl50, 

Baud300, 

Baud600, 

Baudl200, 

Baud2400, 

Baud4800, 

Baud9600, 

Baudl9200 

) ; 


DataBits  =  [7.  .8] ; 

StopBits  =  (1 . .2] ; 

Parity  =  (Even,  Odd,  None) ; 


PROCEDURE  InitPort (port  :  CARDINAL;  speed  :  BaudRate;  data  :  DataBits; 

stop  :  StopBits;  check  :  Parity)  :  CommStatus; 

PROCEDURE  StartReceiving (port,  bufsize  :  CARDINAL)  :  CommStatus; 

PROCEDURE  StopReceiving (port  :  CARDINAL)  :  CommStatus; 

PROCEDURE  GetChar (port  :  CARDINAL;  VAR  ch  :  CHAR)  :  CommStatus; 

PROCEDURE  SendChar (port  :  CARDINAL;  ch  :  CHAR;  modem  : 

BOOLEAN)  :  CommStatus; 

END  CommPort. 

End  Listing  Seven 


Listing  Eight 

398:  DEFINITION  MODULE  Files;  (*  File  I/O  for  Kermit  *) 

399! 

400!  FROM  FileSystem  IMPORT 

401 :  File; 

402: 

403!  EXPORT  QUALIFIED 

4041  Status,  FileType,  Open,  Create,  CloseFile,  Get,  Put,  DoWrite; 

405! 

406!  TYPE 

407!  Status  =  (Done,  Error,  EOF); 

4081  FileType  =  (Input,  Output); 

409! 

410 1  PROCEDURE  Open  (VAR  f  :  File;  name  :  ARRAY  OF  CHAR)  :  Status; 

411 :  (*  opens  an  existing  file  for  reading,  returns  status  *) 

412: 

413!  PROCEDURE  Create  (VAR  f  :  File;  name  :  ARRAY  OF  CHAR)  :  Status; 

414!  (*  creates  a  new  file  for  writing,  returns  status  *) 

4151 

416:  PROCEDURE  CloseFile  (VAR  f  :  File;  Which  :  FileType)  :  Status; 

417!  (*  closes  a  file  after  reading  or  writing  *) 

418! 

419:  PROCEDURE  Get  (VAR  f  :  File;  VAR  ch  :  CHAR)  :  Status; 

420 1  (*  Reads  one  character  from  the  file,  returns  status  *) 

421 : 

422;  PROCEDURE  Put  (ch  :  CHAR); 

423!  (*  Writes  one  character  to  the  file  buffer  *) 

424: 

425:  PROCEDURE  DoWrite  (VAR  f  :  File)  ;  Status; 

426!  (*  Writes  buffer  to  disk  only  if  nearly  full  *) 

427! 

428!  END  Files. 

429: 


End  Listing  Eight 


Listing  Nine 

430 :  IMPLEMENTATION  MODULE  Shell; 

431 : 

432:  FROM  SYSTEM  IMPORT 

433!  ADDRESS,  ADR; 

4341 

435!  IMPORT  ASCII; 

436: 

437!  FROM  OS2DEF  IMPORT 

438!  LOWORD,  HI WORD,  HWND,  HDC,  HPS,  RECTL,  USHORT,  NULL,  ULONG; 

439! 

440 i  FROM  Term  IMPORT 

441 :  WM_TERM,  WMJTERMQUIT, 

442!  Dir,  TermThrProc,  InitTerm,  PutKbdChar,  PutPortChar; 

4431 

4441  FROM  PAD  IMPORT 

4451  WM_PAD,  PAD_Quit,  PAD_Error,  DoPADMsg,  Aborted,  sFname,  Send, 


(continued  on  page  112) 
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Listing  Nine  (Listing  continued,  text  begins  on  page  70.) 


4471  FROM  DataLink  IMPORT 

4481  WM_DL,  DoDLMsg; 

4491 

450:  FROM  Screen  IMPORT 


451! 

4521 

4531 

4541 

455! 

4561 

4571 

458! 
459: 
460 : 
461 : 
462! 
4631 
464! 
4651 
4661 
467! 
468! 
469! 
470 : 
471 : 
472: 
473: 

474  : 

475: 

476: 

477: 

478: 

479: 

480 : 
481 : 
482: 
483: 
484: 
485: 
486: 
487: 
488: 
489: 

490: 

491: 

492: 

493: 

494: 

495: 

496: 

497: 

498: 

499: 

500: 

501: 

502: 

503: 

504! 

505: 

506: 

507! 

508: 

509: 

510: 

511: 

512: 

513: 

514! 

515: 

516: 

517! 

518: 

519: 

520: 

521: 

522: 

523: 

524: 

525: 

526: 

527: 

528: 

529! 

530: 

531: 

532: 

533: 

534: 

535: 

536: 

537: 

538: 

539: 

540: 

541: 

542: 

543: 

544: 

545: 

546: 

547: 

548: 

549: 

550: 


hvps,  ColorSet,  White,  Green,  Amber,  Colorl,  Color2,  ClrScr, 

WriteLn; 


FROM  DosCalls  IMPORT 

DosCreateThread,  DosSuspendThread,  DosResumeThread,  DosSleep; 

FROM  PMAVIO  IMPORT 

VioCreatePS,  VioAssociate,  VioDestroyPS,  VioShowPS, 

WinDefAVioWindowProc, 

FORMAT_CGA,  HVPS; 

FROM  PMWIN  IMPORT 

MPARAM,  MRESULT,  SWP,  PSWP, 

WS_VISIBLE,  FCF_TITLEBAR,  FCF_SIZEBORDER,  FCF_SHELLPOSITION, 
WM_SYSCOMMAND,  WM_MINMAXFRAME,  SWP_MINIMIZE,  HWND_DESKTOP, 

WM_PAINT,  WM_QUIT,  WM_COMMAND,  WM_INITDLG,  WM_CONTROL,  WM_HELP, 
WM_INITMENU,  WM_SIZE,  WM_DESTROY,  WM_CREATE,  WM_CHAR, 

BM_SETCHECK,  MBID_OK,  MB_OK,  MB_OKCANCEL, 

KC_CHAR,  KC_CTRL,  KC_VIRTUALKEY,  KC_KEYUP, 

SWP_SIZE,  SWP_MOVE,  SWP_MAXIMIZE,  SWP_RESTORE, 

MB_ I CONQUE  S T I ON ,  MB_ICONASTERISK,  MB_ICONEXCLAMATION, 

FID_MENU,  MM_SETITEMATTR,  MM_QUERYITEMATTR, 

MIA_DISABLED,  MIA_CHECKED,  MPFROM2SHORT, 

WinCreateStdWindow,  WinDestrcyWindow, 

WinOpenWindowDC,  WinSendMsg,  WinQueryDlgltemText,  WinlnvalidateRect, 
WinDefWindowProc,  WinBeginPaint,  WinEndPaint,  WinQueryWindowRect, 
WinSetWindowText,  WinSetFocus,  WinDlgBox,  WinDefDlgProc, 

WinDismissDlg, 

WinMessageBox,  WinPostMsg,  WinWindowFromID,  WinSendDlgltemMsg, 
WinSetWindowPos,  WinSetActiveWindow; 

FROM  PMGPI  IMPORT 
GpiErase; 

FROM  KH  IMPORT 

IDM_KERMIT,  IDM_FILE,  IDM_OPTIONS,  IDM_SENDFN,  ID_SENDFN, 

IDM_DIR,  IDM_CONNECT,  IDM_SEND,  IDM_REC,  IDM_DIRPATH,  ID_DIRPATH, 
IDM_DIREND,  IDM_QUIT,  IDM_ABOUT,  IDM_HELPMENU,  IDM_TERMHELP, 
IDM_COMPORT,  IDM_BAUDRATE,  IDM_DATABITS,  IDM_STOPBITS,  IDM_PARITY, 
COM_OFF ,  ID_C0M1,  ID_COM2,  PARITY_OFF,  ID_EVEN,  ID_ODD,  ID_NONE, 
DATA_OFF,  ID_DATA7,  ID_DATA8,  STOP_OFF,  ID_ST0P1,  ID_STOP2, 

BAUD_OFF ,  ID_B110,  ID_B150,  ID_B300,  ID_B600,  ID_B1200,  ID_B2400, 
ID_B4800,  ID_B9600,  ID_B19K2, 

IDM_COLORS,  IDM_WHITE,  IDM_GREEN,  IDM_AMBER,  IDM_C1,  IDM_C2; 

FROM  CommPort  IMPORT 

CommStatus,  BaudRate,  DataBits,  StopBits,  Parity,  InitPort, 
StartReceiving,  StopReceiving; 

FROM  Strings  IMPORT 

Assign,  Append,  AppendChar; 


CONST 

WM_SETMAX  =  7000H; 

WM_SETFULL  =  7001H; 

WM_SETRESTORE  =  7002H; 

NONE  =  0;  (*  no  port  yet  initialized  *) 

STKSIZE  =  4096; 

BUFSIZE  =  4096;  (*  Port  receive  buffers:  room  for  two 

full  screens  *) 

PortError  =  "Port  Is  Already  In  Use  —  EXIT?  (Cancel  Trys 

Another  Port)"; 


ESC  =  33C; 


FrameFlags  :  ULONG; 

TermStack  :  ARRAY  [1.. STKSIZE]  OF  CHAR; 

Stack  :  ARRAY  [1.. STKSIZE]  OF  CHAR; 

TermThr  :  CARDINAL; 

Thr  :  CARDINAL; 
hdc  :  HDC; 

frame_hvps,  child_hvps  :  HVPS; 

TermMode  :  BOOLEAN; 

Path  :  ARRAY  [0..60]  OF  CHAR; 

Banner  :  ARRAY  [0..40]  OF  CHAR; 

PrevComPort  :  CARDINAL; 

Settings  :  ARRAY  [0..1]  OF  RECORD 

baudrate  :  CARDINAL; 
databits  :  CARDINAL; 
parity  :  CARDINAL; 
stopbits  :  CARDINAL; 
END; 


PROCEDURE  SetFull; 

(*  Changes  window  to  full  size  *) 

BEGIN 

WinSetWindowPos  (FrameWindow,  0, 

Pos.x  +  3,  Pos.y  +  3,  Pos.cx  -  6,  Pos.cy  -  6, 
SWP_MOVE  +  SWP_SIZE) ; 

END  SetFull; 


PROCEDURE  SetRestore; 

(*  Changes  window  to  full  size  FROM  maximized  *) 

BEGIN 

WinSetWindowPos  (FrameWindow,  0, 

Pos.x  +  3,  Pos.y  +  3,  Pos.cx  -  6,  Pos.cy  -  6, 
SWP_MOVE  +  SWP_SIZE  +  SWP_RESTORE) ; 

END  SetRestore; 


PROCEDURE  SetMax; 

(*  Changes  window  to  maximized  *) 


551 : 
5521 
5531 
5541 
5551 
556: 
5571 
5581 
5591 

560 : 
561 : 
562: 
563: 
564: 
565 : 
566: 
567: 
568: 
569: 
570 : 

571 : 

572: 
573: 
574: 
575: 
576: 
577! 
578: 
579: 
580 : 
581 : 
582: 
583: 
584! 
585! 
5861 
5871 
5881 
5891 
590 : 
591 : 
592: 
593; 
594: 
595: 
596: 
597: 
598: 
599! 
600 : 
601 : 
602: 
603: 
604: 
605: 
606: 
607: 
608: 
609: 
610 : 
6ii : 
612: 
613: 

614: 

615: 
616: 
617: 
618: 
619: 
620 : 
621 : 
622: 
623: 
624: 
625: 
626! 
6271 
6281 
6291 
630 : 
631 : 
632: 
633: 
634: 
635: 
636; 
637: 
638: 
639: 
640 : 
641 : 
642: 
643: 
644: 
645: 
646: 
647: 
648: 
649: 
650 : 
651 : 
652; 
653: 
654! 
655: 
656: 
657: 
658! 
659: 


BEGIN 

WinSetWindowPos  (FrameWindow,  0, 

Pos.x  +  3,  Pos.y  +  3,  Pos.cx  -  6,  Pos.cy  -  6, 
SWP_MOVE  +  SWP_SIZE  +  SWP_MAXIMIZE) ; 

END  SetMax; 


PROCEDURE  SetBanner; 

(*  Displays  Abbreviated  Program  Title  +  Port  Settings  in 

Title  Bar  *) 


CONST 

PortName  :  ARRAY  [0..1]  OF  ARRAY  [0..5]  OF  CHAR  = 

[ ( "COM1 : ",  0C],  ("COM2:",  0C] ] ; 

BaudName  :  ARRAY  [0..8]  OF  ARRAY  (0..5]  OF  CHAR  = 

[["110",  0C],  ["150",  0C],  ["300",  0C], 

["600",  0C],  ["1200",  0C],  ["2400",  0C], 

["4800",  0C],  ["9600",  0C] ,  ["19200",  0C] ] ; 

ParityName  :  ARRAY  [0..2]  OF  CHAR  =  ['E',  'O',  ' N' ] ; 

BEGIN 

WITH  Settings [comport  -  COM_OFF]  DO 
Assign  (Class,  Banner); 

Append  (Banner,  "  —  "); 

Append  (Banner,  PortName [comport  -  COM_OFF]); 

Append  (Banner,  BaudName [baudrate  -  BAUD_OFF]); 
AppendChar  (Banner,  ' , ' ) ; 

AppendChar  (Banner,  ParityName [parity  -  PARITY_OFF] ) ; 
AppendChar  (Banner,  ','); 

AppendChar  (Banner,  CHR  ((databits  -  DATA_OFF )  +  30H) ) ; 
AppendChar  (Banner,  ','); 

AppendChar  (Banner,  CHR  ((stopbits  -  STOP_OFF)  +  30H) ) ; 
WinSetWindowText  (FrameWindow,  ADR  (Banner) ) ; 

END; 

END  SetBanner; 


PROCEDURE  SetPort; 

(*  Sets  The  Communications  Parameters  Chosen  By  User  *) 
VAR 

status  :  CommStatus; 
rc  :  USHORT; 


BEGIN 

IF  PrevComPort  #  NONE  THEN 

StopReceiving  (PrevComPort  -  COM_OFF); 
END; 


WITH  Settings [comport  -  COM_OFF]  DO 
status  :=  InitPort  ( 
comport  -  COM_OFF, 

BaudRate  (baudrate  -  BAUD_OFF) , 

DataBits  (databits  -  DATA_OFF) , 

StopBits  (stopbits  -  STOP_OFF) , 

Parity  (parity  -  PARITY_OFF) , 

) ; 

END; 

IF  status  =  Success  THEN 

StartReceiving  (comport  -  COM_OFF,  BUFSIZE) ; 

PrevComPort  :=  comport; 

ELSE 

rc  :=  WinMessageBox  (HWND_DESKTOP,  FrameWindow, 

ADR  (PortError), 

0,  0,  MB_OKCANCEL  + 

MB-IONEXCLAMATION); 

IF  rc  =  MBID_OK  THEN 

WinPostMsg  (FrameWindow,  WM_QUIT,  0,  0); 

ELSE  (*  try  the  other  port  *) 

IF  comport  =  ID_COMl  THEN 
comport  :=  ID_COM2; 

ELSE 

comport  :=  ID_COMl; 

END; 

SetPort;  (*  recursive  call  for  retry  *) 

END; 

END; 

SetBanner; 

END  SetPort; 


PROCEDURE  MakeChild  (msg  :  ARRAY  OF  CHAR) ; 

(*  Creates  a  child  window  for  use  by  send  or  receive  threads  *) 


VAR 

c_hdc  :  HDC; 

BEGIN 

WinPostMsg  (FrameWindow,  WM_SETFULL,  0,  0); 

Disable  (IDM_CONNECT) ; 

Disable  (IDM_SEND) ; 

Disable  (IDM_REC) ; 

Disable  (IDM_DIR) ; 

Disable  (IDM_OPTIONS) ; 

Disable  (IDM_COLORS) ; 


(*  Create  a  client  window  *) 

FrameFlags  :=  FCF_TITLEBAR  +  FCF_SIZEBORDER; 


ChildFrameWindow  :=  WinCreateStdWindow  ( 

ClientWindow,  (*  handle  of  the  parent  window  *) 

WS_VISIBLE,  (*  the  window  style  *) 


FrameFlags, 

ADR (Child) , 

NULL, 

WS_VISIBLE, 

NULL, 

IDM_KERMIT, 

ChildClientWindow 

) ; 


(*  the  window  flags  *) 

(*  the  window  class  *) 

(*  the  title  bar  text  *) 

(*  client  window  style  *) 

(*  handle  of  resource  module  *) 
(*  resource  id  *) 

(*  returned  window  handle  *) 
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660 : 
661 : 
662! 
663! 
6641 
665! 
6661 
667! 
668: 
669: 
670 : 
671 : 
672', 
673: 
674  : 
675: 
676! 
677: 
678: 
679: 
680 : 
681 : 
682: 
683: 
684: 
685: 
686: 
687: 
688: 
689! 
690 : 
691 : 
692: 
693: 
694: 
695! 
696: 
697: 
698: 
699: 

700 : 
701 : 

702: 

703: 

704: 

705: 

706: 

707; 

708! 

709! 

710 : 
711 : 

712: 

713: 


WinSetWindowPos  (ChildFrameWindow,  0, 

Pos.cx  DIV  4,  Pos.cy  DIV  4, 

Pos.cx  DIV  2,  Pos.cy  DIV  2-3, 

SWP_MOVE  +  SWP_SIZE) ; 

WinSetWindowText  (ChildFrameWindow,  ADR  (msg) ) ; 

WinSetActiveWindow  (HWND_DESKTOP,  ChildFrameWindow) ; 

c_hdc  :=  WinOpenWindowDC  (ChildClientWindow) ; 
hvps  :=  child_hvps; 

VioAssociate  (c_hdc,  hvps); 

ClrScr;  (*  clear  the  hvio  window  *) 

END  MakeChild; 


PROCEDURE  Disable  (item  :  USHORT); 

(*  Disables  and  "GREYS"  a  menu  item  *) 

VAR 

h  :  HWND; 

BEGIN 

h  :=  WinWindowFromID  (FrameWindow,  FID_MENU) ; 
WinSendMsg  (h,  MM_SETITEMATTR, 

MPFROM2SHORT  (item,  1), 

MPFROM2SHORT  (MIA_DISABLED,  MIA_DISABLED) ) ; 
END  Disable; 


PROCEDURE  Enable  (item  :  USHORT) ; 

(*  Enables  a  menu  item  *) 

VAR 

h  ;  HWND; 
atr  :  USHORT; 

BEGIN 

h  :=  WinWindowFromID  (FrameWindow,  FID_MENU) ; 
atr  :=  USHORT  (WinSendMsg  (h,  MM_QUERYITEMATTR, 

MPFROM2 SHORT  (item,  1), 

MPFROM2 SHORT  (MIA_DISABLED,  MIA_DISABLED) ) ) ; 
atr  :=  USHORT  (BITSET  (atr)  *  (BITSET  (MIA_DISABLED) 

/  BITSET  (-1) ) ) ; 

WinSendMsg  (h,  MM_S ET I TEMATTR , 

MPFROM2SHORT  (item,  1), 

MPFROM2SHORT  (MIA_DISABLED,  atr)); 

END  Enable; 


PROCEDURE  Check  (item  :  USHORT); 

(*  Checks  a  menu  item  —  indicates  that  it  is  selected  *) 
VAR 


7141 
715: 
716: 
7171 
718: 
719: 
720 : 

721 : 

722: 
723: 
724: 
725: 
726: 
727: 
728: 
729: 
730 : 

731 : 

732: 

733: 

734: 

735: 

736: 

737: 
738: 
739: 
740 : 

741 : 

742: 

743: 

744: 

745! 

746: 

747: 

748: 

749: 

750: 

751 : 

752! 

753: 

754: 

755: 

756: 

757: 

758: 

759: 

760 : 
761 : 
762: 
763: 


h  :  HWND; 

BEGIN 

h  :=  WinWindowFromID  (FrameWindow,  FID_MENU) ; 
WinSendMsg  (h,  MM_SET I TEMATTR, 

MPFROM2SHORT  (item,  1), 

MPFROM2 SHORT  (MIA_CHECKED,  MIA_CHECKED) ) ; 
END  Check; 


PROCEDURE  UnCheck  (item  :  USHORT); 

(*  Remove  check  from  a  menu  item  *) 

VAR 

h  :  HWND; 
atr  :  USHORT; 

BEGIN 

h  :=  WinWindowFromID  (FrameWindow,  FID_MENU) ; 
atr  :=  USHORT  (WinSendMsg  (h,  MM_QUERY I TEMATTR, 

MPFROM2 SHORT  (item,  1), 

MPFROM2SHORT  (MIA_CHECKED,  MIA_CHECKED) ) ) ; 
atr  :=  USHORT  (BITSET  (atr)  *  (BITSET  (MIA_CHECKED)  / 

BITSET  { - 1 ) ) ) ; 

WinSendMsg  (h,  MM_SETITEMATTR, 

MPFROM2SHORT  (item,  1), 

MPFROM2 SHORT  (MIA_CHECKED,  atr)); 

END  UnCheck; 


PROCEDURE  DoMenu  (hwnd  :  HWND;  item  :  MPARAM) ; 
(*  Processes  Most  Menu  Interactions  *) 


rcl  :  RECTL; 
rc  :  USHORT; 

BEGIN 

CASE  LOWORD  (item)  OF 
IDM_DIR: 

SetFull; 

WinQueryWindowRect  (hwnd,  rcl) ; 

WinDlgBox  (HWND_DESKTOP,  hwnd,  PathDlgProc,  0, 

IDM_DIRPATH,  0)  ; 

hvps  :=  frame_hvps; 

VioAssociate  (hdc,  hvps); 

Dir  (Path); 

WinDlgBox  (HWND_DESKTOP,  hwnd,  DirEndDlgProc,  0, 

IDM_DIREND,  0); 

VioAssociate  (0,  hvps); 

WinlnvalidateRect  (hwnd,  ADR  (rcl),  0); 

I  IDM_CONNECT: 

TermMode  :=  TRUE; 
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(Listing  continued,  text  begins  on  page  70.) 


7641 
7651 
7661 
7671 
7681 
7691 
770 : 

771 : 

772: 

773: 

774! 

775: 

776: 

777: 

778: 
779: 
780 : 
781 : 
782: 
783: 
784! 
785: 
786: 

787: 
788: 
789: 
790 : 

791 : 

792: 

793: 

794: 

795! 

796: 

797: 

798: 

799: 
800 : 
801 : 

802: 

803: 

804: 

805: 
806: 
807: 
808: 
809! 
810 : 
811 : 
812: 

813: 
814: 
815: 
816: 
817: 
818: 
819: 
820 : 
821 : 
822: 
823: 
824: 
825: 
826: 
827: 
828: 
829: 
830 : 
831 : 
832: 

833: 

834: 

835: 

836: 

837: 

838: 


846: 

847: 

848: 

849: 

850 : 
851 : 
852: 
853! 
854: 
855: 
856: 
857: 
858: 
859! 
860 : 
861 : 
862: 
863: 


Disable  (IDM_CONNECT) ; 

Disable  (IDM_SEND) ; 

Disable  (IDM_REC) ; 

Disable  <IDM_DIR) ; 

Disable  (IDM_OPTIONS) ; 

Disable  (IDM_COLORS) ; 

(*  MAXIMIZE  Window  —  Required  for  Terminal  Emulation  *) 
SetMax; 

hvps  :=  frame_hvps; 

VioAssociate  (hdc,  hvps); 

DosResumeThread  (TermThr) ; 

InitTerm; 

I  IDM_SEND: 

WinDlgBox  (HWND_DESKTOP,  hwnd,  SendFNDlgProc,  0, 

IDM_SENDFN,  0); 

MakeChild  ("Send  a  File"); 

DosCreateThread  (Send,  Thr,  ADR  (Stack [STKSIZE] )) ; 

I  IDM_REC: 

MakeChild  ("Receive  a  File"); 

DosCreateThread  (Receive,  Thr,  ADR  (Stack [STKSIZE] )) ; 

I  IDM_QUIT: 

rc  :=  WinMessageBox  ( H WND_DE S KTOP ,  ClientWindow, 

ADR  ("Do  You  Really  Want  To  EXIT  PCKermit?") , 
ADR  ("End  Session"),  0,  MB_OKCANCEL  + 

MB_ I CONQUE S T I ON ) ; 

IF  rc  =  MBID_OK  THEN 

StopReceiving  (comport  -  COM_OFF) ; 

WinPostMsg  (hwnd,  WM_QUIT,  0,  0) ; 

END; 

!  IDM_COMPORT : 

WinDlgBox  (HWND_DESKTOP,  hwnd,  ComDlgProc,  0, 

IDM_COMPORT,  0); 

SetPort; 

I  IDM_BAUDRATE : 

WinDlgBox  (HWND_DESKTOP,  hwnd,  BaudDlgProc,  0, 

IDM_BAUDRATE,  0) ; 

SetPort; 

I  IDM_DATABITS : 

WinDlgBox  (HWND_DESKTOP,  hwnd,  DataDlgProc,  0, 

IDM_DATABITS,  0); 

SetPort; 

I  IDM_STOPBITS : 

WinDlgBox  (HWND_DESKTOP,  hwnd,  StopDlgProc,  0, 

IDM_STOPBITS,  0); 

SetPort; 

I  IDM_PARITY: 

WinDlgBox  (HWND_DESKTOP,  hwnd,  ParityDlgProc,  0, 

IDM_PARITY,  0); 

SetPort; 

!  IDM_WHITE: 

UnCheck  (ColorSet); 

ColorSet  :=  IDM_WHITE; 

Check  (ColorSet); 

White; 

I  IDM_GREEN: 

UnCheck  (ColorSet); 

ColorSet  IDM_GREEN; 

Check  (ColorSet); 

Green; 

I  IDM_AMBER: 

UnCheck  (ColorSet); 

ColorSet  :=  IDM_AMBER; 

Check  (ColorSet); 

Amber; 

I  IDM_C1 : 

UnCheck  (ColorSet); 

ColorSet  :=  IDM_C1; 

Check  (ColorSet); 

Colorl; 

I  IDM_C2 : 

UnCheck  (ColorSet); 

ColorSet  :=  IDM_C2; 

Check  (ColorSet); 

Color2; 

!  IDM_AB0UT: 

WinDlgBox  (HWND_DESKTOP,  hwnd,  AboutDlgProc,  0, 

I DM  ABOUT,  0); 

ELSE 

(*  Don't  do  anything...  *) 

END; 

END  DoMenu; 


839: 

PROCEDURE  ComDlgProc 

'ComDlgProc']  ( 

840 : 

(*  Process  Dialog  Box 

for  choosing  COM1/COM2  * 

841 : 

hwnd 

:  HWND; 

842! 

msg 

:  USHORT; 

843: 

mpl 

:  MPARAM; 

844: 

mp2 

:  MPARAM) 

:  MRESULT  [LONG,  LOADDS] 

8451 

BEGIN 

CASE  msg  OF 
WM_INITDLG: 

WinSendDlgltemMsg  (hwnd,  comport,  BM_SETCHECK,  1,  0)  ; 
WinSetFocus  (HWND_DESKTOP,  WinWindowFromID 

(hwnd,  comport)); 

RETURN  1; 

:  WM_CONTROL : 

comport  :=  LOWORD  (mpl); 

RETURN  0; 

WM_COMMAND : 

WinDismissDlg  (hwnd,  1) ; 

RETURN  0; 

ELSE 

RETURN  WinDefDlgProc  (hwnd,  msg,  mpl,  mp2) ; 

END; 

END  ComDlgProc; 


PROCEDURE  BaudDlgProc  ['BaudDlgProc']  ( 
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864: 

(*  Process 

Dialog  Box 

for  choosing  Baud  Rate  * 

865! 

hwnd 

:  HWND; 

866! 

msg 

:  USHORT; 

867! 

mpl 

:  MPARAM; 

8681 

mp2 

:  MPARAM) 

:  MRESULT  [LONG,  LOADDS] 

869: 

BEGIN 

870 : 
871 : 
872: 
873: 
874; 

875: 
876: 
877: 
878: 
879: 
880 : 
881 : 
882: 
883: 
884: 
885: 
886: 
887: 


WITH  Settings [comport  -  COM_OFF]  DO 
CASE  msg  OF 
WM_INITDLG: 

WinSendDlgltemMsg  (hwnd,  baudrate,  BM_SETCHECK,  1,  0); 
WinSetFocus  {HWND_DESKTOP,  WinWindowFromID 

(hwnd,  baudrate) ) ; 

RETURN  1; 

:  WM_CONTROL : 

baudrate  :=  LOWORD  (mpl); 

RETURN  0; 

I  WM_COMMAND : 

WinDismissDlg  (hwnd,  1); 

RETURN  0; 

ELSE 

RETURN  WinDefDlgProc  (hwnd,  msg,  mpl,  mp2); 

END; 

END; 

END  BaudDlgProc; 


889 

890 

891 

892 

893 

894 

895 

896 

897 

898 

899 

900 

901 : 
902! 
903: 
904! 
9051 
906: 
907: 
908; 
909: 

910 : 
911 : 

912! 

913: 

914: 

915: 

916: 


9381 
939: 
940 : 
941 : 
942: 


947; 
948: 
949: 
950 : 
951 : 
952: 

953: 
954: 
955: 
956: 
957: 
958: 
959; 
960 : 
961 : 
962: 
963: 
964: 
965: 
966: 


PROCEDURE  DataDlgProc  ['DataDlgProc']  ( 

(*  Process  Dialog  Box  for  choosing  7  or  8  data  bits  *) 
hwnd  :  HWND; 

msg  :  USHORT; 

mpl  :  MPARAM; 

mp2  :  MPARAM)  :  MRESULT  [LONG,  LOADDS]; 

BEGIN 

WITH  Settings [comport  -  COM_OFF]  DO 
CASE  msg  OF 
WM_INITDLG: 

WinSendDlgltemMsg  (hwnd,  databits,  BM_SETCHECK,  1,  0) ; 
WinSetFocus  (HWND_DESKTOP,  WinWindowFromID 

(hwnd,  databits) ) ; 

RETURN  1; 

:  WM_CONTROL : 

databits  :=  LOWORD  (mpl); 

RETURN  0; 

I  WM_COMMAND : 

WinDismissDlg  (hwnd,  1); 

RETURN  0; 

ELSE 

RETURN  WinDefDlgProc  (hwnd,  msg,  mpl,  mp2); 

END; 

END; 

END  DataDlgProc; 


PROCEDURE  StopDlgProc  [ ' StopDlgProc' ]  ( 

(*  Process  Dialog  Box  for  choosing  1  or  2  stop  bits  *) 


917: 

hwnd  :  HWND; 

918: 

msg  :  USHORT; 

919! 

mpl  :  MPARAM; 

920 : 

mp2  :  MPARAM)  :  MRESULT  [LONG, 

LOADDS] ; 

921 : 

BEGIN 

922: 

WITH  Settings [comport  -  COM_OFF] 

DO 

923: 

CASE  msg  OF 

924: 

WM_INITDLG: 

925! 

WinSendDlgltemMsg  (hwnd, 

stopbits 

926! 

WinSetFocus  (HWND_DESKTOP,  WinWin 

927: 

RETURN  1; 

928: 

:  WM_CONTROL : 

929: 

stopbits  :=  LOWORD  (mpl) 

; 

930 : 

RETURN  0; 

931 : 

:  WM_COMMAND : 

932: 

WinDismissDlg  (hwnd,  1); 

933: 

RETURN  0; 

934: 

ELSE 

935: 

RETURN  WinDefDlgProc  (hwnd, 

msg,  mpl 

936: 

END; 

937: 

END; 

(hwnd,  stopbits)); 


END  StopDlgProc; 


PROCEDURE  ParityDlgProc  ['ParityDlgProc']  ( 

(*  Process  Dialog  Box  for  choosing  odd,  even,  or  no  parity  *) 


943: 

hwnd 

:  HWND; 

944 : 

msg 

:  USHORT; 

945! 

mpl 

:  MPARAM; 

946: 

mp2 

:  MPARAM) 

MRESULT  [LONG,  LOADDS 

BEGIN 

WITH  Settings [comport  -  COM_OFF]  DO 
CASE  msg  OF 
WM_INITDLG: 

WinSendDlgltemMsg  (hwnd,  parity,  BM_SETCHECK,  1,  0); 
WinSetFocus  (HWND_DESKTOP,  WinWindowFromID 

(hwnd,  parity) ) ; 

RETURN  1; 

I  WM_CONTROL : 

parity  :=  LOWORD  (mpl); 

RETURN  0; 

:  WM_COMMAND : 

WinDismissDlg  (hwnd,  1); 

RETURN  0; 

ELSE 

RETURN  WinDefDlgProc  (hwnd,  msg,  mpl,  mp2)  ; 

END; 

END; 

END  ParityDlgProc; 


(continued  on  page  116) 
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(Listing  continued) 


PROCEDURE  AboutDlgProc  ['AboutDlgProc']  ( 
(*  Process  "About"  Dialog  Box  *) 


cl  :=  CHR  (code); 

c2  :=  CHR  (code  DIV  256); 

IF  ORD  (cl)  =  OEOH  THEN  (*  function  *) 
cl  :=  OC; 


hwnd 

:  HWND; 

1078: 

IF  CT 

msg 

:  USHORT; 

10791 

cl 

mpl 

mp2 

:  MPARAM; 

:  MPARAM) 

:  MRESULT  [LONG,  LOADDS]; 

1080! 

END; 

BITSET  (1FH) ) ) 


BEGIN 

IF  msg  =  WM_COMMAND  THEN 
WinDismissDlg  (hwnd,  1); 

RETURN  0; 

ELSE 

RETURN  WinDefDlgProc  (hwnd,  msg,  mpl,  mp2) ; 
END; 

END  AboutDlgProc; 


PROCEDURE  SendFNDlgProc  [' SendFNDlgProc' ]  ( 

(*  Process  Dialog  Box  that  obtains  send  filename  from  user  *) 


hwnd  :  HWND; 

msg  :  USHORT; 

mpl  :  MPARAM; 

mp2  :  MPARAM)  :  MRESULT  [LONG,  LOADDS]; 

BEGIN 

CASE  msg  OF 
WM_INITDLG: 

WinSetFocus  (HWND_DESKTOP,  WinWindowFromID 

(hwnd,  ID_SENDFN) ) 

RETURN  1; 

!  WM_COMMAND : 

WinQueryDlgltemText  (hwnd,  ID_SENDFN,  20,  ADR  (sFname) ) ; 
WinDismissDlg  (hwnd,  1); 

RETURN  0; 

ELSE 

RETURN  WinDefDlgProc  (hwnd,  msg,  mpl,  mp2); 

END; 

END  SendFNDlgProc; 


PROCEDURE  PathDlgProc  ['PathDlgProc']  ( 

(*  Process  Dialog  Box  that  obtains  directory  path  from  user  *) 
hwnd  :  HWND; 

msg  :  USHORT; 

mpl  :  MPARAM; 

mp2  :  MPARAM)  :  MRESULT  (LONG,  LOADDS]; 

BEGIN 

CASE  msg  OF 
WM_INITDLG: 

WinSetFocus  (HWND_DESKTOP,  WinWindowFromID 

(hwnd,  ID_DIRPATH) ) ; 

RETURN  1; 

I  WM_COMMAND : 

WinQueryDlgltemText  (hwnd,  ID_DIRPATH,  60,  ADR  (Path)); 
WinDismissDlg  (hwnd,  1); 

RETURN  0; 

ELSE 

RETURN  WinDefDlgProc  (hwnd,  msg,  mpl,  mp2); 

END; 

END  PathDlgProc; 


PROCEDURE  DirEndDlgProc  [ ' DirEndDlgProc' ]  ( 

(*  Process  Dialog  Box  to  allow  user  to  cancel  directory  *) 


hwnd 

:  HWND; 

msg 

:  USHORT; 

mpl 

:  MPARAM; 

mp2 

:  MPARAM) 

MRESULT  [LONG,  LOADDS] 

BEGIN 

IF  msg  =  WM_COMMAND  THEN 
WinDismissDlg  (hwnd,  1); 

RETURN  0; 

ELSE 

RETURN  WinDefDlgProc  (hwnd,  msg,  mpl,  mp2) ; 
END; 

END  DirEndDlgProc; 


PROCEDURE  HelpDlgProc  ('HelpDlgProc' ]  ( 
(*  Process  Dialog  Boxes  for  the  HELP  *) 


hwnd  :  HWND; 

msg  :  USHORT; 

mpl  :  MPARAM; 

mp2  :  MPARAM)  :  MRESULT  [LONG,  LOADDS]; 

BEGIN 

IF  msg  =  WM_COMMAND  THEN 
WinDismissDlg  (hwnd,  1); 

RETURN  0; 

ELSE 

RETURN  WinDefDlgProc  (hwnd,  msg,  mpl,  mp2); 
END; 

END  HelpDlgProc; 


PROCEDURE  KeyTranslate  (mpl,  mp2  :  MPARAM;  VAR  cl,  c2  :  CHAR) 

:  BOOLEAN; 

(*  Translates  WM_CHAR  message  into  ascii  keystroke  *) 


code  :  CARDINAL; 
fs  :  BITSET; 

VK,  KU,  CH,  CT  :  BOOLEAN; 


fs  :=  BITSET  (LOWORD  (mpl));  < 

VK  :=  (fs  *  BITSET  (KC_VIRTUALKEY) )  #  (}; 

KU  :=  (fs  *  BITSET  (KC_KEYUP) )  #  {}; 

CH  :=  (fs  *  BITSET  (KC_CHAR) )  #  {}; 

CT  :=  (fs  *  BITSET  (KC_CTRL) )  #  {); 

IF  (NOT  KU)  THEN 

code  :=  LOWORD  (mp2) ;  (*  character  code  *) 


RETURN  TRUE; 
ELSE 

RETURN  FALSE; 
END; 

END  KeyTranslate; 


PROCEDURE  WindowProc  [' WindowProc' ]  ( 

(*  Main  Window  Procedure — Handles  message  from  PM  and  elsewhere  *) 


hwnd  : 

HWND; 

msg  : 

USHORT; 

mpl  : 

MPARAM; 

mp2  : 

MPARAM)  : 

ch  :  CHAR; 

hps 

:  HPS; 

pswp 

:  PSWP; 

cl,  c2 

:  CHAR; 

BEGIN 

CASE  msg  OF 
WM_HELP : 

IF  TermMode  THEN 

WinDlgBox  (HWND_DESKTOP,  hwnd,  HelpDlgProc, 

0,  IDM_TERMHELP,  0) ; 

ELSE 

WinDlgBox  (HWND_DESKTOP,  hwnd,  HelpDlgProc, 

0,  IDM_HELPMENU,  0) ; 

END; 

RETURN  0; 

1  WM_SETFULL : 

SetFull; 

RETURN  0; 

I  WM_SETRESTORE : 

SetRestore; 

RETURN  0; 

I  WM_SETMAX : 

SetMax; 

RETURN  0; 

:  WM_MINMAXFRAME : 

pswp  :=  PSWP  (mpl); 

IF  BITSET  (pswpA . f s )  *  BITSET  (SWP_MINIMIZE)  #  [}  THEN 
(*  Don't  Display  Port  Settings  While  Minimized  *) 
WinSetWindowText  (FrameWindow,  ADR  (Title) ) ; 

ELSE 

WinSetWindowText  (FrameWindow,  ADR  (Banner) ) ; 

IF  TermMode  AND 

(BITSET  (pswpA . f s)  *  BITSET  (SWP_RESTORE) # ( } )  THEN 
(*  Force  window  to  be  maximized  in  terminal  mode  *) 
WinPostMsg  (FrameWindow,  WM_SETMAX,  0,  0); 

ELS IF  (NOT  TermMode)  AND 

(BITSET  (pswpA . f s )  *  BITSET  (SWP_MAXIMIZE) # { } )  THEN 
(*  Prevent  maximized  window  EXCEPT  in  terminal  mode  *) 
WinPostMsg  (FrameWindow,  WM_SETRESTORE,  0,  0); 

ELSE 

(*  Do  Nothing  *) 

END; 

END; 

RETURN  WinDefWindowProc  (hwnd,  msg,  mpl,  mp2) ; 

!  WM_CREATE : 

hdc  :=  WinOpenWindowDC  (hwnd); 

VioCreatePS  (frame_hvps,  25,  80,  0,  FORMAT_CGA,  0); 
VioCreatePS  (child_hvps,  16,  40,  0,  FORMAT_CGA,  0); 
DosCreateThread  (TermThrProc,  TermThr,  ADR 

(TermStack [STKSIZE] ) ) ; 

DosSuspendThread  (TermThr) ; 

RETURN  0; 

1  WMJCNITMENU: 

Check  (ColorSet); 

RETURN  0; 

I  WM_COMMAND : 

DoMenu  (hwnd,  mpl); 

RETURN  0; 

;  WM_TERMQUIT: 

TermMode  :=  FALSE; 

DosSuspendThread  (TermThr) ; 

VioAssociate  (0,  hvps) ; 

(*  Restore  The  Window  *) 

SetRestore; 

Enable  (IDM_CONNECT) ; 

Enable  (IDM_SEND) ; 

Enable  (IDM_REC) ; 

Enable  (IDM_DIR) ; 

Enable  (IDM_OPTIONS) ; 

Enable  (IDM_COLORS) ; 

RETURN  0; 

1  WM_TERM : 

PutPortChar  (CHR  (LOWORD  (mpl)));  (*  To  Screen  *) 

RETURN  0; 

I  WM_CHAR: 

IF  TermMode  THEN 

IF  KeyTranslate  (mpl,  mp2,  cl,  c2)  THEN 
PutKbdChar  (cl,  c2) ;  (*  To  Port  *) 

RETURN  0; 

ELSE 

RETURN  WinDefAVioWindowProc  (hwnd, msg, mpl, mp2 ) ; 

END; 

ELSE 

RETURN  WinDefWindowProc  (hwnd,  msg,  mpl,  mp2); 

END; 

1  WM  PAINT: 
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ii82: 

1183: 

11841 

1185: 

1186! 

11871 

ii88: 

ii89: 

1190 : 
1191 : 

1192! 

ii93: 

1194! 

ii95: 

1196: 

ii97: 

1198: 

1199! 

1200 : 
1201 : 
1202: 
1203! 
1204: 
1205! 
1206: 
1207! 
1208: 
1209! 
1210! 
1211 : 
1212! 
1213! 
12141 
1215! 
12161 
1217,' 
1218: 
1219! 
1220! 
1221! 
1222! 
1223! 
1224! 
12251 
1226! 
12271 
1228! 
12291 
12301 
1231! 
1232! 
1233! 
12341 
12351 
12361 


hps  :=  WinBeginPaint  (hwnd,  NULL,  ADDRESS  (NULL) ) ; 

1237! 

ADR  (Class),  0, 

MB  OK 

GpiErase  (hps) ; 

+ 

MB_ICONEXCLAMATION) 

VioShowPS  (25,  80,  0,  hvps) ; 

12381 

ELSE 

WinEndPaint  (hps) ; 

12391 

WinMessageBox  (HWND_DESKTOP,  hwnd. 

RETURN  0; 

1240: 

ADR  ("File  Transfer  Completed"), 

I  WM  SIZE: 

1241 : 

ADR  (Class), 

0,  MB  OK 

IF  TermMode  THEN 

+  MB_ICONASTERISK) 

RETURN  WinDefAVioWindowProc  (hwnd, 

msg,  mpl,  mp2); 

1242: 

END; 

ELSE 

1243: 

DosSleep  (2000); 

RETURN  WinDefWindowProc  (hwnd,  msg, 

mpl,  mp2); 

1244: 

VioAssociate  (0,  hvps); 

END; 

1245: 

WinDestroyWindow(ChildFrameWindow] 

; 

I  WM_DESTROY: 

1246: 

Enable  (IDM  CONNECT); 

VioDestroyPS  (frame  hvps); 

1247: 

Enable  (IDM  SEND); 

VioDestroyPS  (child  hvps); 

1248: 

Enable  (IDM  REC) ; 

RETURN  0; 

1249: 

Enable  (IDM  DIR); 

ELSE 

1250! 

Enable  (IDM  OPTIONS); 

RETURN  WinDefWindowProc  (hwnd,  msg,  mpl, 

mp2) ; 

1251 : 

Enable  (IDM  COLORS); 

END; 

1252! 

ELSE 

END  WindowProc; 

12531 

DoPADMsg  (mpl,  mp2); 

12541 

END; 

12551 

RETURN  0; 

PROCEDURE  Chi ldWindowP roc  ['ChildWindowProc']  ( 

12561 

I  WM_DL: 

(*  Window  Procedure  for  Send/Receive  child  windows 

*) 

12571 

DoDLMsg  (mpl ,  mp2 ) ; 

hwnd  :  HWND; 

1258: 

RETURN  0; 

msg  :  USHORT; 

12591 

:  WM_SIZE: 

mpl  :  MPARAM; 

1260: 

WinSetWindowPos  (ChildFrameWindow,  0, 

mp2  :  MPARAM)  :  MRESULT  [LONG,  LOADDS] ; 

1261 : 

Pos.cx  DIV  4,  Pos.cy  DIV  4, 

VAR 

1262: 

Pos.cx  DIV  2,  Pos.cy  DIV  2-3, 

1263! 

SWP  MOVE  +  SWP  SIZE); 

mp  :  USHORT; 

12641 

RETURN  WinDefAVioWindowProc  (hwnd,  msg,  mpl,  mp2) ; 

hps  :  HPS; 

12651 

ELSE 

cl,  c2  :  CHAR; 

12661 

RETURN  WinDefWindowProc  (hwnd,  msg,  mpl, 

mp2) ; 

1267! 

END; 

BEGIN 

12681 

END  ChildWindowProc; 

CASE  msg  OF 

1269! 

WM  PAINT: 

1270: 

hps  :=  WinBeginPaint  (hwnd,  NULL,  ADDRESS  (NULL)); 

1271! 

BEGIN  (*  Module  Initialization  *) 

GpiErase  (hps); 

1272! 

WITH  Settings [ID_C0M1  -  COM_OFF]  DO 

VioShowPS  (16,  40,  0,  hvps); 

1273! 

baudrate  :=  ID  B1200; 

WinEndPaint  (hps); 

12741 

parity  :=  ID  EVEN; 

RETURN  0; 

1275! 

databits  :=  ID  DATA7 ; 

I  WM_CHAR : 

12761 

stopbits  :=  ID  STOP1; 

IF  KeyTranslate  (mpl,  mp2,  cl,  c2)  AND 

(Cl  =  ESC)  THEN 

12771 

END; 

Aborted  :=  TRUE; 

1278! 

RETURN  0; 

1279! 

WITH  Settings [ID_COM2  -  COM_OFF]  DO 

ELSE 

1280: 

baudrate  :=  ID_B19K2; 

RETURN  WinDefWindowProc  (hwnd,  msg, 

mpl ,  mp2 ) ; 

1281 : 

parity  ID_EVEN; 

END; 

1282! 

databits  :=  ID_DATA7; 

:  WM_PAD : 

12831 

stopbits  ID  STOP1; 

mp  :=  LOWORD  (mpl); 

1284: 

END; 

IF  (mp  =  PAD  Error)  OR  (mp  =  PAD  Quit) 

THEN 

1285! 

PrevComPort  :=  NONE; 

WriteL.., 

12861 

comport  ID  COM1; 

IF  mp  =  PAD  Error  THEN 

12871 

TermMode  :=  FALSE; (*  Not  Initially  in  Terminal  Emulation  Mode  *) 

WinMessageBox  (HWND  DESKTOP,  hwnd, 

12881 

END  Shell. 

ADR  ("File  Transfer  Aborted"), 

12891 

End  Listings 
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Do  You  Have  a 
Future  in  Vegetative 
Virtuality? 


My  garden  will  never  make  me  famous, 
I’m  a  horticultural  ignoramus, 

I  can 't  tell  a  string  bean  from 
a  soybean, 

Or  even  a  girl  bean  from  a  boy  bean. 

—  Ogden  Nash 

I  think  that  I  see  an  undiscovered 
product  niche.  It’s  a  vertical  prod¬ 
uct  niche,  with  thousands  of  poten¬ 
tial  customers  and  the  prospect  of 
multiple  sales  to  each  customer.  The 
niche  is  virtual  shrubs. 

Macintosh -Aided  Design  magazine 
recently  ran  a  good  article  on  land¬ 
scape  design,  3-D  graphics,  and  vege¬ 
table  verisimilitude.  Daniel  Earle’s 
“Three-Dimensional  Representation  of 
Plants  in  Landscape  Design”  (June, 
1990)  described  how  landscape  design¬ 
ers  and  architects  can  use  3-D  model¬ 
ing  tools  to  produce  the  perspective 
views  of  trees  and  shrubs  necessary  in 
their  work. 

Current  2-D  object-based  approaches, 
according  to  Earle,  allow  creating  li¬ 
braries  of  plant  symbols,  and  freehand 
drawing  programs  produce  acceptable 
freehand  results;  but  3-D  modeling  ap¬ 
proaches  have  not  been  impressive: 
Present  computer  approaches  that  cre- 


Michael  Swaine 


ate  plants  that  look  like  lollipops,  rock¬ 
ets,  or  shaped  concrete  do  not  ade¬ 
quately  satisfy  planting  design  consid¬ 
erations.  It’s  necessary  that  plant  forms 
exhibit  freedom,  variety,  and  organic 
form,  otherwise  they  look  like  exten¬ 
sions  to  the  hardscape  around  them, 
rather  than  offering  a  contrast. 

Earle  proposes  using  3-D  graphic 
tools  to  model  trees  and  shrubs,  rather 


than  just  patching  together  a  few  geo¬ 
metric  forms.  He  identifies  essential  ele¬ 
ments  of  structure  and  form  of  plants, 
and  shows  how  to  develop,  without 
excessive  effort,  workable  plant  forms. 

It  struck  me  as  I  read  the  article  that 
it  ought  to  be  possible  to  do  better  than 
workable  plant  forms  and  that  it  ought 
to  be  easier.  Earle’s  approach  definitely 
leads  to  better-looking  trees  and  shrubs, 
but  it’s  ultimately  not  different  in  kind, 
but  only  in  degree,  from  the  2-D  plane 
geometry  models  he  criticizes.  Trees 
aren’t  really  made  up  of  plane  geome¬ 
try  objects  and  conic  sections.  Why  not 
use  fractals? 

As  I’ve  pointed  out  here  before,  frac¬ 
tal  geometry,  the  new  branch  of  mathe¬ 
matics  that  Lucas  films  has  used  to 
produce  pseudonatural  forms  in  sci¬ 
ence  fiction  movies,  is  remarkably  good 
at  modeling  natural  forms  such  as  coast¬ 
lines,  mountain  ranges,  and  foliage.  Cer¬ 
tain  classes  of  fractals  are  particularly 
good  at  mimicking  trees  and  shrubs. 
This  is  because,  so  far  as  I  can  under¬ 
stand  it,  the  recursive  growth  pattern 
of  the  fractal  reflects  a  similar  growth 
pattern  in  nature.  Fractals  know  some 
of  Nature's  algorithms. 

My  own  explorations  through  the 
maze  of  these  shrubby  fractals  have 
run  up  against  two  thorny  hedges:  perfor¬ 
mance  and  predictability.  Fractal  algo¬ 
rithms  are  viciously  recursive,  and  any 
more  than  a  few  levels  of  recursion 
takes  unacceptably  long  to  execute  on 
my  hardware  (and  more  to  the  point, 
in  my  code,  but  improving  the  code 
will  only  shift  the  performance  barrier 
back  a  few  levels).  Further,  although  I 
have  generated  some  attractive  and  natu¬ 
ral-looking  plant  forms,  the  process  is 
hit-or-miss:  I  don’t  know  the  relation¬ 
ship  between  the  parameters  I  can  ma¬ 


nipulate  and  the  defining  features  of 
the  sorts  of  plants  I  can  model. 

For  the  needs  of  landscape  design¬ 
ers,  it  seems  to  me,  the  performance 
problem  is  not  critical.  Their  needs  are 
for  simple  but  evocative  and  recogniz¬ 
able  images.  A  picture  should  be  rec¬ 
ognizably  a  birch  tree  or  a  particular 
variety  of  succulent,  but  rich  detail  is 
not  desirable.  Even  the  simple  algo¬ 
rithms  and  implementations  I’ve  played 
around  with  should  be  able  to  meet 
these  performance  requirements. 

If  the  predictability  problems  were 
solved,  fractals  would,  I  think,  take  over 
the  field.  The  advantages  are  compel¬ 
ling: 

•  Greater  naturalness.  The  controlled 
randomness  of  fractal  techniques  gives 
a  more  natural  image  than  does  build¬ 
ing  from  conventional  geometric 
forms. 

•  Deep  naturalness.  Fractal  geometry 
apparently  accurately  models  the  pro¬ 
cess  of  growth  and  the  underlying 
grammar  of  the  natural  forms  it  simu¬ 
lates. 

•  Greater  efficiency.  Fractal  images  have 
absurdly  modest  storage  requirements, 
if  stored  in  the  form  of  the  generator 
function  and  generated  at  need. 

•  Greater  power.  Fractal  techniques  use 
recursive  image  generation  to  allow 
any  level  of  detail  to  be  produced 
from  a  single  stored  generator  func¬ 
tion. 

Now,  apparently,  the  predictability 
problem  has  been  solved.  Michael 
Barnsley,  co-founder  of  Iterated  Sys¬ 
tems,  Norcross,  Georgia,  has  found  that 
by  starting  with  a  digitized  natural  im¬ 
age,  say,  of  a  coastline,  and  mapping 
segments  of  it  to  a  large  library  of  stan- 
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dard  fractal-like  transformations,  you 
can  turn  the  image  into  a  formula  that 
does  a  credible  job  of  reproducing  the 
image,  at  an  acceptable  video  rate,  with 
a  compression  ratio  of  perhaps  500:1! 
Barnsley  has  turned  the  insight  into  a 
business,  but  he  doesn’t  seem  to  be 
filling  the  niche  I  think  I  see,  and  the 
basic  insight  is  not  proprietary. 

So  I  think  that  somebody  is  going  to 
make  money  selling  libraries  of  virtual 
shrubbery.  Libraries  of  natural-looking 
trees  and  shrubs  ought  to  speed  the 
landscape  designer’s  work,  and  ought 
to  sell  well. 

The  simplest  implementation  of  the 
idea  would  be  to  set  up  a  plant  plant 


120 

858 


(wait,  make  that  a  virtual  shrubbery 
nursery),  and  to  crank  out  libraries  of 
plant  forms  in  a  standard  3-D  format. 
This  approach,  though,  would  lose 
some  of  the  benefits  of  using  fractals. 
The  desired  amount  of  detail  could 
vary,  and  a  fractal  generator  function 
can  lay  on  as  much  detail  as  you  can 
sit  still  for.  Perhaps  a  better  distribution 
model  would  be  as  a  smart  picture; 
some  sort  of  object,  containing  the  gen¬ 
erator  function,  an  interface  allowing 
the  input  of  a  recursion  level,  and  the 
minimal  code  required  to  execute  the 
generator  function,  to  unfold  the  func¬ 
tion  into  a  graphic  image.  The  recur¬ 
sion  level  would  control  the  degree  of 


detail  in  the  resulting  image. 

By  creating  such  smart  plants,  one 
would  belie  the  old  saying,  “You  can 
speed  up  horticulture  but  you  cannot 
make  it  think.” 

Is  Compiled  Hype  Faster  than  Interpreted 
Hype? 

After  three  years  we  still  don’t  know 
what  HyperCard  is,  but  it’s  now  a  full¬ 
blown  product  category.  I  don’t  mean 

Certain  classes  of 
fractals  are  particularly 
good  at  mimicking  trees 
and  shrubs  because  the 


recursive  growth  pattern 
of  the  fractal  reflects  a 
similar  growth  pattern 
in  nature 


stackware;  I  mean  —  well,  that  cate¬ 
gory  of  uncategorizable  tools  that  peo¬ 
ple  are  using  to  do  product  prototyp¬ 
ing  or  to  produce  online  help  systems, 
front-ends  to  remote  databases,  stand¬ 
alone  kiosk  systems,  as  well  as  simple 
databases  of  text,  pictures,  sounds,  and 
code.  Apple’s  HyperCard,  Silicon 
Beach’s  SuperCard,  Symmetry’s  Plus, 
Asymmetrix’s  ToolBook:  I’ve  taken  to 
calling  these  tools  hypermedia  author¬ 
ing  systems,  a  pompous-sounding  ex¬ 
pression  that  is,  at  least,  nebulous 
enough  to  capture  a  lot  of  their  uses. 

And  they  have  a  lot  of  uses;  or  better, 
people  are  putting  them  to  a  lot  of 
uses.  These  products,  including  Tool¬ 
Book,  which  is  only  a  few  months  old, 
have  bent  to  winds  from  all  quarters. 
ToolBook  is  already  in  use,  for  exam¬ 
ple,  in  hardware  and  software  firms; 
Mac  developers,  traditional  DOS  ven¬ 
dors,  and  mainframe  software  vendors; 
multimedia  software  vendors,  database 
companies,  and  compiler  vendors. 

The  mere  fact  that  people  are  using 
them  for  a  wide  variety  of  purposes 
doesn’t  mean  that  they  are  good  tools 
for  any  of  those  purposes.  In  fact,  an 
argument  could  be  made  that  —  within 
certain  limits  —  widespread  use  of  a 
development  tool  is  evidence  of  its  un¬ 
suitability  for  serious  development 
work.  There  are,  after  all,  only  so  many 
serious  developers  in  the  world,  and 
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(continued  from  page  120) 
any  tool  being  used  by  more  people 
than  there  are  serious  developers  is 
ipso  facto  not  a  serious  development 
tool.  The  argument  is  slippery,  but  the 
conclusion  it  reaches  is  one  that  most 
serious  developers  would  accept:  Hy¬ 
perCard  and  its  ilk  are  not  serious  de¬ 
velopment  tools. 

I  can’t  challenge  the  conclusion  head 
on,  but  there  are  degrees  of  serious¬ 
ness,  and  I’d  like  to  present  the  case 
for  an  important  increase  in  the  seri¬ 
ousness  of  these  tools.  I  have  just  fin¬ 
ished  writing  reviews,  for  various  pub¬ 
lications,  of  the  latest  versions  of  all 
four  of  these  products  (the  latest  ver- 


122 


sion  was  also  the  first  version  in  the 
case  of  ToolBook).  My  cumulative  im¬ 
pression  after  doing  all  the  reviews  is 
that  the  current  versions  of  these  prod¬ 
ucts  represent  a  new  level  of  serious¬ 
ness  for  the  product  category;  that’s 
my  impression,  and  I’ll  present  the  evi¬ 
dence  so  you  can  decide. 

Apple  took  a  long  time  in  releasing 
HyperCard  2.0,  but  managed  to  justify 
the  wait.  If  you  are  familiar  with  Hyper¬ 
Card  1.x  but  haven’t  seen  2.0,  you 
should  appreciate  the  new  features.  If 
you  are  unfamiliar  with  HyperCard,  you 
may  be  surprised  at  the  essential  ele¬ 
ments  of  a  development  tool  that  it  was 
missing.  Either  way,  it  should  be  clear 


that  the  new  version  is  a  significant 
improvement. 

First,  HyperCard  now  gives  much 
greater  control  over  the  user  interface. 
Formerly,  it  restricted  you  to  the  Hy- 
perGhetto  of  a  single  window  of  fixed 
size,  menu  structure,  and  appearance. 
You  could  always  spot  a  HyperCard 
application.  Now,  you  can  create  arbi¬ 
trary-sized  and  -shaped  windows,  open 
several  windows  (hence  several  stacks) 
simultaneously,  and  control  the  menus 
completely.  You  can  create  external 
windows  (more  about  that  momentar¬ 
ily)  and  floating  palettes.  You  can  also 
trap  all  keyboard  events. 

Second,  the  development  environ¬ 
ment  is  more  serious.  HyperTalk  is  now 
compiled,  the  script  editor  is  more  use¬ 
ful,  and  there’s  an  integrated  debugger. 

The  modal  dialog  box  that  served 
as  a  script  editor  in  HyperCard  1  .x  was 
one  of  its  more  annoying  features.  Hy¬ 
perCard  2.0  has  a  new  script  editor  that 
fully  supports  the  edit  menu,  horizon¬ 
tal  scrolling,  multiple  script  editing  win¬ 
dows,  search  and  replace,  and  triple¬ 
clicking  to  select  a  line.  You  can  com¬ 
ment  or  uncomment  blocks  of  code 
automatically.  The  script  editor  uses 
document  windows,  so  you  can  move 
freely  between  the  card  window  and 
the  script  editor  window.  HyperTalk 
code  is  now  compiled  to  RAM  rather 
than  being  interpreted,  and  only  source 
code  is  saved  on  disk;  the  script  editor 
always  loads  the  script  from  disk  to 
edit  it. 

The  script  editor  is  integrated  with  a 
debugger,  and  errors  now  bring  up  a 
dialog  box  allowing  you  to  jump  to  the 
offending  line  in  the  script  under  the 
script  editor  or  under  the  debugger. 
The  debugger  supports  setting  multi¬ 
ple  permanent  or  temporary  break¬ 
points,  and  there  are  two  windows  for 
tracking  the  values  of  variables  and  all 
messages  sent.  You  have  some  options 
in  what  messages  get  tracked:  Unused 
and  idle  messages  are  by  default  not 
tracked,  but  can  be. 

Third,  there’s  a  new  external  com¬ 
mand  (XCMD)  interface,  which  Apple 
used  to  create  the  new  development 
environment.  The  script  editor,  debug¬ 
ger,  message  watcher,  and  variable 
watcher  all  are  XCMDs.  As  a  result,  you 
can  replace  any  of  them  with  third- 
party  tools  simply  by  changing  the  name 
of  a  global  variable.  The  new  XCMD 
interface  is  different  enough  that  exist¬ 
ing  XCMDs  that  make  assumptions 
about  memory  allocation  may  not  work 
with  HyperCard  2.0.  But  the  new  inter¬ 
face  is  such  an  improvement  that  most 
existing  XCMDs  probably  ought  to  be 
rewritten  to  take  advantage  of  its  new 
features,  anyway. 
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XCMDs  can  now  run  concurrently 
with  each  other  and  with  HyperCard. 
You  can  set  an  XCMD’s  priority  by 
specifying  the  time  between  idle-time 
calls  to  the  XCMD.  Note,  too,  that  Hy¬ 
perTalk  scripts  now  run  in  the  back¬ 
ground  under  MultiFinder. 

XCMDs  can  now  create  and  manage 
their  own  windows.  These  new  exter¬ 
nal  windows  can  be  document  win¬ 
dows  or  windoids,  and  can  use  color 
if  color  QuickDraw  is  available.  Any 
event  pertaining  to  the  window,  such 
as  mouseDown  or  activateEvt,  will  be 
passed  to  the  XCMD  that  created  it. 
The  standard  HyperTalk  get  and  set 
syntax  for  properties  has  been  extended 
to  external  windows.  Mostly,  the  XCMD 
controlling  the  window  should  handle 
the  properties  of  the  window,  but  Hy¬ 
perTalk  will  handle  the  loc  and  visible 
properties  of  an  external  window  if  its 
XCMD  doesn’t.  A  separate  tool,  freely 
available  but  not  packaged  with  Hy¬ 
perCard  2.0,  will  support  the  creation 
of  palette  windows. 

Fourth,  the  language  has  been  en¬ 
hanced  in  many  ways  that  increase  pro¬ 
gramming  flexibility  and  power.  The 
message  hierarchy  can  be  modified. 
The  do  command  now  handles  multi- 
line  containers.  The  commands  start 
using  and  stop  using  manage  the  addi¬ 
tion  and  deletion  of  stacks  to  the  mes¬ 
sage-passing  hierarchy;  up  to  ten  stacks 
can  be  added  between  the  present  stack 
and  the  Home  stack.  And  there  is  now 
syntax  in  HyperTalk  for  checking  for 
the  existence  of  an  object,  similar  to 
SuperTalk’s  exists  function. 

Commands  that  in  the  past  brought 
up  a  modal  dialog  box  and  therefore 
could  not  be  automated  have  been 
changed  to  allow  dialog  box  choices 
to  be  passed  as  parameters.  Dialog 
boxes  now  size  themselves  to  the  text 
supplied  (up  to  approximately  240  char¬ 
acters).  In  the  case  of  the  ask  com¬ 
mand,  this  applies  to  the  prompt  string 
and  the  default  response.  And  all  dia¬ 
log  boxes  can  be  dismissed  by  Com¬ 
mand-period. 

ToolBook  has  capabilities  that  make 
it  particularly  interesting,  partly  the  re¬ 
sult  of  its  knowing  how  to  use  DOS 
and  Windows  capabilities.  While  I’ve 
enjoyed  playing  with  the  toy  applica¬ 
tions  Apple  supplied  to  developers  to 
demonstrate  the  interapplication  com¬ 
munications  capabilities  coming  some¬ 
day  in  System  7,  I’ve  actually  written 
ToolBook  applications  that  message  one 
another  via  DDE,  doing  today  what  Ap¬ 
ple  is  promising  for  next  year.  And  Tool¬ 
Book’s  DLLs  are  a  step  beyond  even 
HyperCard’s  new  XCMD  interface. 

Like  so  many  other  things,  this  cate¬ 
gory  of  software  has  been  made  more 
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(continued  from,  page  123) 
significant  by  the  release  of  Windows 
3.0.  HyperCard  stacks  will  soon  be  port¬ 
able  to  ToolBook  format,  ToolBook 
runtime  is  being  bundled  with  Win¬ 
dows,  Zenith  is  bundling  ToolBook  with 
all  its  386  machines.  If  there  was  a 
market  for  the  products  you  develop 
with  these  tools,  and  there  was  (it  just 
wasn’t  the  market  a  lot  of  people 
thought  it  would  be),  then  the  market 
is  suddenly  an  order  of  magnitude 
larger.  I’m  taking  it  seriously  enough; 
as  I’ve  mentioned  here  before,  I’ve  been 
putting  together  a  newsletter  for  users 
of  hypermedia  authoring  tools,  and  the 
first  issue  is  finally  about  to  go  to  press. 
Working  on  the  newsletter,  talking  to 
the  developers,  I  began  to  see  that 
something  is  indeed  afoot.  ToolBook 
was  released  at  a  press  conference  fea¬ 
turing  26  third-party  developers  and 
has  already  spawned  a  dedicated  news¬ 
letter;  and  HyperCard  2.0  comes  out 
the  chute  with  three  books,  and  more 
to  come  (my  HyperCard  bookshelf  has 
over  two  dozen  volumes). 

Of  course,  given  the  memory  de¬ 
mands  of  these  tools,  one  could  argue 
that  it’s  Macintosh,  System  7  and  Micro¬ 
soft  Windows  that  are  giving  them  credi¬ 
bility,  by  forcing  everyone  to  install 
more  memory. 

Further  Reading 

For  more  information  on  fractal  horti¬ 
culture,  see  Daniel  Earle,  “Three-Di¬ 
mensional  Representation  of  Plants  in 
Landscape  Design,”  Macintosh-Aided 
Design,  June,  1990;  A.K.  Dewdney, 
“Mathematical  Recreations:  Creating  Frac¬ 
tal  Landscapes  With  a  Home  Computer,” 
Scientific  American,  May,  1990;  or  Mike 
Swaine,  “Fractals:  A  New  Dimension 
in  Scripting,”  HyperLink magazine,  No- 
vember-December,  1989.  Or  send  for 
Barnsley’s  book,  Fractals  Everywhere, 
or  his  book-and-disk  system,  The  Desk¬ 
top  Fractal  System,  both  from  Academic 
Press. 

For  more  support  for  my  argument 
on  the  maturation  of  hypermedia  author¬ 
ing  tools,  see  my  article,  “Author! 
Author!”  Personal  Workstation,  August, 
1990;  my  reviews  of  the  latest  versions 
of  SuperCard,  Plus,  and  HyperCard, 
slated  for  the  October  issue  of  MacUser 
magazine;  or  issue  #\  of  my  new  hy¬ 
permedia  authoring  journal,  HyperPub. 
For  details,  write  to  “The  Prose  Lab,” 
Dept.  DDJ,  31  Patrick  Road,  Santa  Cruz, 
CA  95060.  Or  call  me  at  408-459-8564. 
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Hacks,  Spooks,  and 
Data  Encryption 


The  lexicon  keeps  mutating.  In  days 
gone  by  “hackers”  were  honored 
souls  who  rummaged  in  the  in¬ 
nards  of  computer  systems  find¬ 
ing  clever  and  tricky  ways  to  do  things 
within  the  bounds  of  official  sanction. 
A  good  algorithm  was  called  a  “good 
hack.”  A  generation  of  computer  in¬ 
vaders  and  the  media  have  likewise 
pilfered  the  word  so  that  now  a  hacker 
is  someone  who  steals  computer  time 
and  information.  This  column  is  about 
how  the  hackers  of  yore  can  protect 
their  users  from  the  new  generation  of 
punk  hackers.  We’ll  discuss  the  basics 
of  data  encryption  and  implement  two 
encryption  algorithms  in  C. 

I  just  finished  reading  The  Cuckoo’s 
Eggby  Clifford  Stoll  (1989,  Doubleday). 
It’s  not  about  C  (although  C  is  men¬ 
tioned  and  Unix  is  a  major  player),  but 
all  programmers  will  enjoy  and  relate 
to  the  true  story  about  a  mysterious 
computer  break-in  artist  and  the  pro¬ 
grammer  who  relentlessly  sniffed  out 
the  devious  interloper’s  location  and 
identity.  It’s  a  compelling  book.  Plan 
enough  time  to  read  it  in  one  sitting 
because  you’ll  need  it.  Stoll  is  the  pro¬ 
grammer,  and  he  writes  about  how  a 
seemingly  mundane  assignment  to  find 
a  75  cent  discrepancy  in  his  employer’s 
computer  accounting  system  turned  into 
a  one  year  trek  through  the  holes  in 
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Unix  and  VMS,  the  careless  neglect  and 
ignorance  that  most  system  managers 
have  about  system  security,  and  the 
mindless,  motionless  bureaucracies  of 
federal  law  enforcement  and  intelligence 
agencies. 

You  will  learn  from  this  book  about 
computer  pirates  and  how  they  rou¬ 
tinely  gain  unauthorized  access  to  com¬ 
puter  systems  by  finding  the  unlocked 


back  doors  and  unplugged  holes.  You’ll 
also  learn  how  the  computers  of  gov¬ 
ernment,  universities,  and  research  cen¬ 
ters  are  linked  together  in  complex  net¬ 
works  by  Tymnet  and  other  communi¬ 
cations  services.  And,  if  you’ve  never 
worked  inside  your  government,  you’ll 
gain  from  Stoll’s  novitiate  insight  into 
the  bewildering  and  confounding  na¬ 
ture  of  Potomac  fever  and  lethargy. 
Character  development  is  weak,  and 
some  of  the  dialogue  is  obviously  con¬ 
trived  to  explain  things,  but  the  book 
is  loaded  with  suspense,  and  you  will 
not  want  to  put  it  down. 

Data  Encryption 

Reading  The  Cuckoo ’s  Egg  brings  us  to 
the  subject  of  data  encryption.  Data 
encryption  means  that  you  take  some 
entity  of  data  that  has  meaning  in  its 
original  form  and  mangle  it  beyond 
recognition  so  that  unauthorized  peep¬ 
ing  persons  can  neither  understand  nor 
use  it.  Later,  you  or  someone  who  has 
authorized  access  to  the  information 
can  unscramble  it  and  use  it.  The  idea, 
of  course,  is  to  scramble  it  in  a  way 
known  only  to  those  of  the  inner  sanc¬ 
tum.  The  stuff  of  spies. 

Computer-aided  encryption  involves 
at  the  very  least  an  algorithm  and  often 
much  more.  The  complexity  of  your 
encryption  scheme  will  depend  on  the 
measure  of  protection  you  require  or 
your  level  of  paranoia,  whichever  is 
greater.  For  a  well-developed  treatment 
of  the  various  techniques  of  encryp¬ 
tion,  see  “Cloak  and  Data”  by  Rick 
Grehan  in  Byte  Magazine,  June  1990. 

The  other  side  of  encryption  is  de¬ 
cryption.  Usually,  but  not  always,  you 
need  to  decrypt  something  in  order  to 
use  it.  When  would  you  not?  The  sign- 
on  password  is  an  example.  When  you 
select  a  password  for  access  to  a  sys¬ 
tem,  the  computer  will  often  encrypt  it 
before  it  records  it,  forgetting  the  origi¬ 


nal.  The  encryption  algorithm  is  de¬ 
signed  so  that  no  one  can  derive  the 
original  password  from  its  encrypted 
form.  If  someone  gets  hold  of  the  pass¬ 
word  file,  they  cannot  use  its  contents 
to  sign  onto  someone  else’s  account. 
When  you  sign  on,  the  system  encrypts 
the  password  you  enter  and  compares 
it  to  what  is  stored.  This  approach  pre¬ 
vents  the  system  from  making  a  perma¬ 
nent  record  of  passwords. 

Stoll  compared  such  password  en¬ 
cryption  schemes  to  sausage  grinders. 
You  can’t  run  the  ground  meat  back¬ 
wards  through  the  grinder  and  get  a 
sausage.  And  so  he  wondered  why  his 
ersatz  user  kept  downloading  the  use¬ 
less  password  files.  Later  he  learned 
that  the  Unix-encryption  algorithm  is 
common  knowledge,  and  his  anony¬ 
mous  burglar  had  used  the  algorithm 
to  encrypt  all  the  words  in  an  English 
spelling  dictionary.  He  would  compare 
the  downloaded  encrypted  passwords 
with  the  ones  from  his  dictionary  and 
thus  learn  the  passwords  of  those  users 
who  innocently  selected  English  words. 

There  are  some  very  practical  uses 
for  data  encryption  in  the  world  of 
shared  computers.  Every  complex  sys¬ 
tem  must  have  a  superuser,  a  system 
manager,  a  supervisor  account,  or  what¬ 
ever,  so  that  the  systems  programmers 
can  maintain  the  operating  system. 
Some  other  users  —  users  of  applica¬ 
tions  —  are  responsible  for  information 
so  sensitive  that  it  must  not  be  seen  by 
others,  not  even  the  system  supervisor. 
Payroll  records,  cost  proposals,  hostile 
takeover  bids,  employee  health  records, 
and  such  are  all  compartmentalized  in¬ 
formation  to  be  viewed  only  by  those 
who  have  the  need  to  know. 

Many  successful  unauthorized  sys¬ 
tem  penetrations  involve  the  perpetra¬ 
tor’s  ability  to  gain  superuser  status 
through  knowledge  of  a  bug  in  the 
system.  With  that  status,  all  the  files 
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and  programs  are  wide  open  to  the 
spook.  Encryption  adds  one  more  level 
of  protection  against  inquiring  minds. 

Electronic  mail  is  a  hot  new  item 
among  local  and  wide  area  networks. 
With  all  that  text  roaming  around  all 
those  systems  with  so  many  varied  de¬ 
grees  of  protection  and  privilege,  there 
is  always  a  potential  for  that  confiden¬ 
ce  complexity  of  your 
encryption  scheme  will 
depend  on  the  measure 
of  protection  you 
require  or  your  level  of 
paranoia,  whichever  is 
greater 


tial  memo,  love  letter,  or  football  pool 
to  be  seen  by  the  wrong  eyes.  Trouble 
usually  follows. 

As  an  example,  the  Novell  network 
provides  a  measure  of  protection  by 
allowing  the  system  supervisor  to  grant 
read  and  write  privileges  to  users  at  the 
network  subdirectory  level.  If  the  sys¬ 
tem  is  properly  configured,  I  can  write 
to  your  mail  subdirectory  but  I  cannot 
read  it.  I  can  read  the  subdirectory  where 
the  software  is  stored  but  I  cannot  write 
it.  I  can  read  and  write  to  my  own  mail 
subdirectory.  When  mail  leaves  my  lo¬ 
cal  area  network  to  go  to  someone 
somewhere  else,  I  must  depend  on  the 
integrity  of  that  remote  site  to  similarly 
protect  my  precious  data  from  prying 
eyes.  Let’s  make  the  absurd  assump¬ 
tion  that  all  systems  are  secure  and  that 
all  system  supervisors  are  trustworthy. 
Is  there  a  back  door  into  this  scheme 
of  protection,  one  that  would  admit 
an  intruder?  Of  course  there  is. 

Novell  network  applications  ex¬ 
change  messages  between  networks 
by  using  a  delivery  agent  program  called 
the  Message  Handling  Service  (MHS). 
MHS  has  become  a  standard,  and  be¬ 
cause  of  its  acceptance,  other  platforms 
such  as  MCI  Mail  and  CompuServe  have 
or  are  developing  gateway  processes 
that  exchange  messages  between  them¬ 
selves  and  MHS  installations.  Big  stuff. 
Now  suppose  that  you  and  I  are  com¬ 
mon,  unprivileged  users  on  a  network 
that  uses  MHS  and  I  want  to  intercept 
your  incoming  mail.  Our  network  has 
a  hub  name  and  password  that  the 
MHS  administrator  assigns.  The  hubs 


call  one  another  and  use  those  data 
elements  to  identify  and  verify  one  an¬ 
other.  All  I  need  to  do  to  get  your  mail 
is  set  up  another  system,  assign  it  our 
hub  name  and  password  and  have  it 
connect  to  the  guys  who  send  stuff  to 
you.  How  do  I  learn  the  hub’s  pass¬ 
word?  Simple.  MHS  records  it  in  the 
public  directory  file  that  everyone  can 
read.  Dumb.  But  typical.  And  reason 
enough  to  consider  adding  encryption 
to  our  message  exchanging  systems. 

One-  and  Two-Key  Encryption 

Usually  you  encrypt  a  file  by  specifying 
a  key  value  to  the  encrypting  algo¬ 
rithm.  The  intended  receiver  of  the  file 
must  know  the  key  value  in  order  to 
decrypt  and  use  the  data.  This  often 
presents  a  dilemma.  If  you  want  to 
remember  only  one  key  —  mind,  you 
mustn’t  write  it  down  or  keep  it  in  a 
file  —  but  have  a  lot  of  people  to  send 
mail  to,  then  every  one  of  them  must 
know  your  key.  The  more  of  them 
there  are,  the  greater  potential  there  is 
for  compromise  and  the  less  substan¬ 
tial  the  protection.  If  you  exchange  mail 
with  a  lot  of  people  who  do  not  know 
your  key,  then  you  need  to  remember 
all  their  keys.  Although  propriety  pre¬ 
vents  you  from  making  any  kind  of 
permanent  record,  no  one  can  remem¬ 
ber  so  many  keys,  and  the  stuff  gets 
written  down  somewhere. 

A  better  scheme  for  encryption  in 
electronic  mail  systems  involves  two 
keys,  a  public  one  and  a  private  one. 
Your  public  key  is  known  to  everyone 
and  only  you  know  the  private  one. 
On  the  other  hand  you  know  the  pub¬ 
lic  keys  of  the  other  users.  The  public 
key  is  a  function  of  the  private  key,  and 
like  the  password  discussed  above,  one 
cannot  usually  reverse-engineer  the  pri¬ 
vate  key  from  the  public  one.  Everyone 
sends  things  to  you  that  are  encrypted 
with  the  public  key.  But  only  the  pri¬ 
vate  key  can  decrypt  the  messages.  You 
need  to  remember  only  one  key  for 
yourself,  and  you  can  record  the  public 
keys  of  your  correspondents  wherever 
you  like,  even  in  your  electronic  mail 
address  book.  Grehan’s  article  in  Byte 
explains  several  algorithms  for  devel¬ 
oping  a  two-key  encryption  system. 

In  one-on-one  exchanges,  a  single 
key  system  seems  to  work  better.  You 
and  your  pen  pal  know  the  key,  and 
no  one  else  does.  You  freely  exchange 
encrypted  messages.  When  it  is  neces¬ 
sary,  the  two  of  you  agree  to  change 
the  key. 

CRYPTO 

Listing  One,  page  147,  is  crypto. c,  an 
implementation  of  a  small  encryption 
algorithm.  It’s  all  the  encryption  most 
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(continued  from  page  128) 
of  us  would  ever  need.  Unless  you  are 
in  a  really  hostile  environment  where 
highly  sensitive  records  are  kept,  en¬ 
cryption  usually  serves  only  to  keep 
the  curious  honest.  In  Stoll’s  book,  al¬ 
though  the  intruder  tried  for  a  year  to 
get  at  something  classified,  he  never 
did.  The  lax  security  he  consistently 
found  allowed  him  to  purloin  only  from 
unclassified  systems. 

CRYPTO  reads  a  key  word  and  two 
filenames  from  the  command  line.  If 
you  run  the  program  against  an  en¬ 
crypted  file,  CRYPTO  decrypts  it.  The 
algorithm  is  simple.  The  program  reads 
the  input  file  in  64-bit  blocks,  does  an 
exclusive  OR  of  the  block  and  the  key¬ 
word,  and  writes  the  block  to  the  out¬ 
put  file.  To  decrypt  the  encrypted  file, 
you  run  it  against  the  same  CRYPTO 
program  by  using  the  same  password. 

To  the  uninitiated,  the  encrypted  file 
seems  to  contain  random  byte  values. 
Even  if  a  snooper  has  the  CRYPTO 
program,  without  the  keyword  the  file 
is  useless.  This  algorithm  is  much  bet¬ 
ter  than  a  simple  character  substitution 
encryption  scheme  because  each  char¬ 
acter’s  modification  is  a  function  of  its 
position  in  the  8-byte  block  and  the 
corresponding  character  in  the  key¬ 
word.  This  technique  is  not  immune 


to  code-breaking  techniques,  but  it  will 
keep  your  code-breaker  busy  for  a 
while.  Encryption  sometimes  serves  its 
purpose  if  it  merely  delays  when  the 
information  goes  public.  If  your  mes¬ 
sage  says,  “We  attack  at  high  noon,” 
who  cares  if  the  code-breakers  figure 
it  out  by  1  P.M.? 

Data  Encryption  Standard 

The  government  has  sanctioned  a  stan¬ 
dard  algorithm  for  single-key  encryp¬ 
tion  called  the  Data  Encryption  Stan¬ 
dard  (DES).  You  can  get  a  copy  of  the 
standard  from  most  government  librar¬ 
ies  by  requesting  the  Federal  Informa¬ 
tion  Processing  Standards  Publication 
(FIPS  PUB)  46.  The  algorithm  is  com¬ 
plex,  and  FIPS  PUB  46  is  not  the  clear¬ 
est  documentation  you’ll  ever  read.  I’ll 
try  to  explain  it  better  and  at  the  same 
time  demonstrate  it  with  C  programs 
that  implement  the  algorithm. 

Encryption  with  DES 

DES  encrypts  data  64  bits  at  a  time.  It 
mangles  the  64  bits  by  way  of  a  several- 
step  algorithm  that  includes  a  64-bit 
key  value  supplied  by  the  user.  The 
standard  specifies  a  key  of  eight  8-bit 
bytes  and  does  not  use  the  most  signifi¬ 
cant  bit  of  each  byte  in  the  key,  reserv¬ 
ing  that  as  a  parity  bit  if  needed. 


DES  works  with  bit  strings  and  refers 
to  bit  1,  bit  2,  and  so  on.  You  have  to 
read  the  standard  carefully  all  the  way 
through  to  determine  that  bit  1  is  the 
most  significant  bit  of  an  8-bit  byte  or 
of  a  64-bit  block  and  that  bit  numbers 
read  from  left  to  right.  They  are  unspe¬ 
cific  about  the  integer  and  long  integer 
configuration  of  the  architecture,  so  you 
must  be  careful  about  the  last-byte-first 
view  of  data  in  most  16-  and  32-bit 
machines. 

The  encryption  algorithm  works  on 
the  data  file  in  64-bit  blocks.  It  begins 
by  rearranging  the  bits  in  the  block 
according  to  an  initial  permutation  ta¬ 
ble.  Then  it  separates  the  block  into 
two  32-bit  halves,  a  left  half  and  a  right 
half.  There  are  16  iterations  of  a  man¬ 
gling  process  designed  to  mutate  the 
data  beyond  recognition  with  the  key 
playing  a  major  part.  The  result  of  these 
iterations  is  a  final  pair  of  32-bit  halves. 
The  algorithm  permutes  this  64-bit  block 
by  using  a  permutation  table  that  is  the 
inverse  of  the  initial  permutation  table. 
The  output  from  this  permutation  is  the 
encrypted  64-bit  block.  An  interesting 
property  of  this  inverse  permutation  is 
that  if  your  input  file  does  not  use  the 
most  significant  eighth  bit,  neither  will 
the  encrypted  file.  This  means  that  if 
you  transmit  ASCII  text  data  files  over 
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(continued  from  page  130) 
serial  lines  with  7-bit  data  byte  commu¬ 
nications  protocols,  your  encrypted  files 
will  transmit  correctly. 

That  seems  simple  enough.  Now 
things  begin  to  get  complicated.  The 
1 6  iteration  data-mangling|  process  goes 
like  this: 

For  each  iteration,  the  left  half  of  the 
block  is  exclusive  ORed  with  the  32-bit 
output  of  a  function  called  f.  Then, 
except  for  the  sixteenth  iteration,  the 
halves  are  exchanged.  That’s  not  so 
bad.  Now  let’s  consider  the /function, 
which  is  appropriately  named. 

The /function  takes  the  32-bit  right 
half  of  the  block  and  the  48-bit  output 
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of  the  KS  (key  schedule)  function  as  its 
arguments.  The  right  half  is  called  “R.” 
The  function  permutes  the  32  bits  of  R 
into  48  bits.  This  permutation  is  called 
“E,”  and  it  is  exclusive  ORed  with  the 
48-bit  output  from  the  KS  function.  The 
48-bit  result  is  then  segmented  into  eight 
6-bit  values.  The  5 function  compresses 
each  of  these  a  4-bit  value.  The  eight 
4-bit  values  combine  into  one  32-bit 
value,  which  is  then  permuted  through 
a  permutation  table  called  “P.”  That 
permuted  value  is  the  output  from  the 
/function.  Whew. 

The  S  function  consists  of  eight  dif¬ 
ferent  subfunctions  (SI,  S2,  S3  .  .  . )  de¬ 
pending  on  whether  it  is  compressing 


the  first,  second,  third,  etc.  6-bit  block. 
There  are  eight  tables,  one  for  each 
subfunction.  The  tables  are  arrays  of 
two  dimensions  with  4  columns  and 
16  rows.  Each  entry  in  the  array  con¬ 
tains  a  value  between  0  and  15  repre¬ 
senting  the  4-bit  compressed  represen¬ 
tation  of  the  6-bit  input.  The  6-bit  value 
to  be  compressed  provides  the  array 

The  government  has 
sanctioned  a  standard 
algorithm  for  single-key 
encryption  called  the 
Data  Encryption 
Standard  (DES) 


subscripts  in  this  bizarre  manner:  Bits 
1  and  6  combine  to  be  the  row  sub¬ 
script  0-3.  Bits  2-5  are  the  column 
subscript  0  -  15.  The  S function  returns 
the  4-bit  value  taken  from  the  proper 
array  as  the  result  of  these  subscripts. 
We’re  not  done  yet. 

The  KS  function  returns  a  48-bit  value 
based  on  the  64-bit  key.  Its  arguments 
are  the  iteration  number  of  the  16  itera¬ 
tions  discussed  earlier  and  the  key  value 
for  the  encryption.  For  the  first  itera¬ 
tion,  the  function  permutes  the  key 
value  by  using  the  Permuted  Choice  1 
table.  The  key  divides  into  two  halves 
and  these  halves  are  each  shifted  one 
or  two  bits  to  the  left  depending  on 
which  iteration  is  running.  A  table  con¬ 
trols  the  shift  values.  Each  iteration  af¬ 
ter  the  first  uses  the  shifted  value  of  the 
previous  iteration  as  its  input,  does  its 
own  shift,  and  then  permutes  the  value 
once  more  by  using  the  Permuted 
Choice  2  table. 

Decryption  with  DES 

Decryption  reverses  the  encryption  pro¬ 
cedure.  Because  the  initial  and  inverse- 
initials  permutations  are  reciprocal,  the 
decryption  steps  are  the  same  except 
that  the  decryption  reverses  the  half 
exchanges  during  the  iterations  and 
uses  the  permuted  key  values  returned 
by  the  KS  function  in  the  reverse  order 
of  that  used  by  encryption. 

ENCRYPT  and  DECRYPT 

Listing  Two,  page  147,  is  des.h,  the 
header  file  that  defines  the  global  for¬ 
mats,  function  prototypes,  and  exter¬ 
nal  data  names.  The  file  also  defines 
the  preprocessor  macros  that  the  pro- 
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gram  uses  to  build  permutation  tables. 
See  the  discussion  on  permutations  later 
for  an  explanation  of  these  macros. 

Listing  Three,  page  147,  is  encrypt.c, 
the  program  that  scrambles  a  data  file. 
You  run  it  by  entering  the  keyword, 
which  should  be  eight  characters,  the 
name  of  the  input  file  and  the  name  of 
the  encrypted  output  file.  The  program 
reads  the  file  64  bits  at  a  time  and 
encrypts  those  64  bits  with  the  DES 
algorithm.  It  permutes  the  input  with 
the  initial  permutation  table  and  does 
the  16  iterations  of  right-  and  left-half 
exchanges  and  key-dependent  block 
modifications.  Then  it  uses  the  inverse 
initial  permutation  table  to  permute  the 
output. 

Note  that  the  program  computes  the 
1 6-key  schedules  into  an  array  at  the 
beginning  of  the  program.  These  val¬ 
ues  are  constant  for  the  entire  process 
and  do  not  need  to  be  recomputed  for 
every  iteration  that  uses  them. 

The  output  file  will  always  be  an 
even  multiple  of  8  bytes.  This  is  neces¬ 
sary  because  the  encryption  process 
scrambles  in  64-bit  chunks. 

Listing  Four,  page  148,  is  decrypt. c, 
which  is  similar  to  encrypt.c  except 
that  it  reverses  the  order  of  right-left 
exchanges  and  fetches  from  the  key 
schedule  array.  The  decrypted  file  is 
the  length  of  the  encrypted  file,  an 
even  multiple  of  8  bytes  with  the  ex¬ 
cess  bytes  padded  with  zeros.  This  pad¬ 
ding  could  be  a  problem,  particularly 
with  files  of  fixed  format  where  an 
application  appends  records.  If  this  is 
the  case,  you  could  modify  the  encryp¬ 
tion  program  to  write  a  control  value 
as  part  of  the  encrypted  file.  The  value 
would  specify  the  length  of  the  original 
data  file.  You  can  modify  the  decryp¬ 
tion  program  to  use  this  value  to  trun¬ 
cate  the  excess  bytes  in  the  decrypted 
file.  You  could  decide  to  bypass  en¬ 
crypting  the  last  block  if  it  is  less  than 
8  bytes.  Beware,  though.  If  the  user’s 
message  to  his  boss’s  secretary  ends 
with  “Love,  Ed”,  there  might  be  some 
explaining  due. 

Listing  Five,  page  148,  is  des.c,  which 
contains  the  DES  functions.  I  explained 
most  of  them  in  the  discussion  on  the 
algorithms.  The  terse  function  names  f 
S,  and  KS  come  from  the  DES  specifica¬ 
tion.  The  discussion  on  permutations 
that  follows  explains  the  permute  and 
inverse _permute  functions.  The  sixbits 
function  might  need  some  explanation. 
Its  purpose  is  to  extract  and  return  a 
6-bit  value  from  within  a  48-bit  block. 
None  of  this  is  readily  supported  by  the 
typical  8-  and  1 6-bit  architectures  most 
of  us  use,  so  the  sixbits  function  uses 
a  brute  force  method.  A  table  named 
“ex6”  contains  an  entry  for  each  of  the 


eight  6-bit  values.  Each  entry  identifies 
the  2  bytes  that  contain  the  spread  of  6 
bits.  One  element  specifies  the  number 
of  bits  to  shift  the  byte  left  and  another 
specifies  the  number  to  shift  right.  Those 
two  elements  are  mutually  exclusive. 
Another  element  specifies  the  mask  for 
ANDing  off  the  excess  bits. 

Listing  Six,  page  149,  is  tables. c.  I 
put  the  tables  into  a  separate  source 
file  because  they  compile  so  slowly. 
The  next  discussion  explains  why. 

DES  Permutations 

I  have  mentioned  the  various  permuta¬ 
tions  that  DESlperforms.  A  permutation 
of  a  data  block  consists  of  rearranging 
the  bits  into  a  specified  order.  The  DES 
specification  provides  tables  that  iden¬ 
tify  what  the  permuted  order  of  the  bits 
will  be  for  each  permutation.  There  are 
several  ways  that  you  could  implement 
such  permutations  in  C.  I  built  an  array 
of  bit  masks  for  each  of  the  64  bits  in  a 
permutation.  Each  array  entry  contains 
a  64-bit  value  with  one  bit  set  on.  Its 
position  in  the  table  associates  it  with 
the  bit  that  it  will  change.  So,  if  the 
third  table  entry  has  its  fifth  bit  set,  then 
the  permuted  output  will  have  its  fifth 
bit  set  only  if  the  input  has  its  third  bit 
set.  For  testing  the  64  input  bit  posi¬ 
tions,  I  built  a  general-purpose  table 
with  the  bits  set  in  ascending  order  — 
the  first  bit  is  set  in  the  first  entry,  the 
second  in  the  second,  and  so  on.  Some 
of  this  could  be  done  more  efficiently 
in  assembly  language  with  shifts  and 
carry  tests.  The  C  language  as  imple¬ 
mented  on  the  PC,  however,  does  not 
have  a  convenient  64-bit  shift  operator. 
Consequently  I  chose  the  bit  test  mask 
and  bit  set  mask  approach  described 
here. 

To  make  building  the  bit  masks  easier 
and  reduce  the  potential  for  transcription 
errors,  I  developed  the  preprocessor  mac¬ 
ros  in  DES.H.  By  coding  the  p(n)  macro 
with  a  number  between  1  and  64  as  its 
argument,  you  tell  the  preprocessor  to 
define  a  comma-separated  set  of  eight 
integral  values  with  seven  of  them  of 
value  0  and  one  of  them  having  a  value 
with  a  single  bit  (1,  2,  4,  8,  0x10,  0x20, 
0x40,  or  0x80)  set.  The  value  1  sets  the 
left-most  bit  of  the  left-most  byte.  Sub¬ 
sequent  ascending  values  set  the  next 
sequential  bit  to  the  right.  The  p(n) 
expressions  can  then  be  coded  into  the 
initializers  for  a  character  array. 

By  using  this  technique,  I  was  able 
to  lift  the  permutation  table  values  di¬ 
rectly  out  of  the  DES  standard  docu¬ 
ment  and  code  them  into  the  p(n)  ex¬ 
pressions.  Observe  the  macros.  When 
you  code  a  p(n)  expression,  it  expands 
to  eight  calls  to  the  b(n,r)  macro,  one 
for  each  byte  in  the  64-bit  mask.  The  r 
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argument  identifies  which  of  the  8  bytes 
the  b(n,  r)  macro  expands.  The  macro 
uses  that  value  to  test  the  range  of  the 
n  argument  to  see  if  its  corresponding 
bit  falls  within  the  byte.  If  not,  the 
expression  expands  to  a  zero  value  for 
the  byte.  If  so,  the  macro  calls  the  ps(n) 
macro  passing  an  argument  in  the  range 
1-8  that  is  computed  from  the  n  and 
r  arguments  to  the  b(n,  r)  macro.  The 
ps(n)  macro  expands  the  byte  to  a  value 
with  a  single  bit  shifted  into  the  correct 
position. 

This  exercise  illustrates  the  power 
of  the  C  preprocessor.  By  coding  these 
macros  I  am  able  to  express  the  permu¬ 
tation  tables  with  more  readable  lan¬ 


guage  and  less  margin  for  error.  But 
there  is  a  cost.  There  are  several  of 
those  tables  in  the  program,  and  all 
that  preprocessor  activity  slows  a  20- 
MHz  386  to  a  crawl  when  the  tables. c 
file  compiles.  The  first  time  it  happened, 
I  thought  that  Turbo  C  had  hung  up. 

DES  Performance 

The  DES  algorithm  is  complex  and  slow. 
The  ENCRYPT  program  published  here 
takes  one  minute,  ten  seconds  to  en¬ 
crypt  the  text  of  this  column,  about  25K 
bytes,  and  the  DECRYPT  program  uses 
the  same  time  to  decrypt  it.  I  made 
these  measures  on  a  20-MHz  386  with 
Turbo  C  2.0  for  the  compiler.  By  com¬ 


parison,  the  simpler  CRYPTO  program 
takes  about  3.5  seconds  to  perform  the 
same  task.  The  poor  showing  of  the 
DES  programs  could  reflect  a  bad  im¬ 
plementation  (who,  me?)  or  a  non¬ 
optimum  compile.  I  haven’t  tried  it  on 
a  4.77-MHz  PC.  Pack  a  lunch  and  bring 
a  toothbrush. 

The  algorithms  in  DES.C  assume  a 
32-bit  long  integer  and  an  8-bit  byte.  I 
used  the  PCs  long  integer  to  imple¬ 
ment  the  halves  of  the  64-bit  key  and 
data  block  because  it  was  convenient 
and  offered  the  best  chance  for  effi¬ 
ciency.  A  more  portable  program  would 
adapt  itself  to  the  correct  integral  data 
type  for  the  compiler  and  might  not 
work  as  well.  Perhaps  the  permutation 
functions  could  be  optimized.  A  pro¬ 
filer  will  show  that  those  functions  oc¬ 
cupy  most  of  the  algorithm’s  time.  Op¬ 
timization  would,  though,  be  compiler- 
dependent.  You  can  look  at  the  64 
iterations  of  the  permute  function  and 
decide  to  use  subscripts  instead  of  point¬ 
ers,  or  use  64  discrete  in-line  bit  tests 
and  ORs  to  avoid  the  loop  overhead. 
Code  it  one  way  or  another,  and  the 
program’s  performance  could  improve 
or  degrade  depending  on  the  C  com¬ 
piler  you  use. 

Because  DES  is  defined  by  the  Na¬ 
tional  Bureau  of  Standards,  a  truly  con¬ 
forming  device  or  program  must  be 
validated,  and  these  programs  have  not 
been  tested  and  blessed.  My  copy  of 
the  standard  does  not  identify  the  vali¬ 
dation  procedures.  Perhaps  a  good  test 
would  be  to  see  if  a  candidate  im¬ 
plementation  can  successfully  exchange 
encrypted  files  with  an  approved  de¬ 
vice.  The  specification  implies,  how¬ 
ever,  that  an  implementer  has  some 
leeway  in  the  design  of  the  various 
permutation  tables.  If  this  is  so,  then 
the  encrypted  files  would  not  be  com¬ 
patible  between  different  implementa¬ 
tions. 

Epilogue 

Farewell  to  Howard  Benner,  the  author 
of  TAPCIS.  I  never  met  Howard,  but  I 
use  his  work  every  day.  So  do  many 
others.  Howard  was  a  programmer  in 
a  relatively  new  craft,  one  that  is  only 
about  40  years  old.  When  I  began  pro¬ 
gramming  32  years  ago,  the  program¬ 
mers  were  all  young,  too,  and  there 
were  not  very  many  of  us.  I  still  think 
of  us  all  as  young  people.  It  does  not 
seem  right  somehow  that  programmers 
should  die. 
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Pieces  of 
Charlie 


While  hunting  for  houses  in  Cave 
Creek,  we  saw  a  large-eared 
skinny  brown  dog  trot  across 
the  highway  close  ahead  of 
us  with  no  hint  of  a  look  over  its  shoul¬ 
der.  He  knew  we  were  there;  the  ears 
said  it  all.  This  was  obviously  a  crea¬ 
ture  that  knew  man  and  automobiles 
and  wasn’t  much  fazed  by  either.  In 
short,  we  met  the  much-maligned  coy¬ 
ote  who,  at  the  parting  of  the  genes 
ages  ago,  chose  the  glorious  life  over 
the  long  one,  perhaps  because  he  some¬ 
how  foresaw  that  we  would  take  wolves 
and  turn  them  into  poodles. 

For  all  his  persecution,  the  coyote  is 
doing  surprisingly  well  in  the  Valley 
of  the  Sun.  In  defiance  of  conventional 
wisdom,  there  are  (if  my  sources  are 
correct),  more  coyotes  living  in  North 
Phoenix  today  than  there  were  20  years 
ago,  even  with  the  incredible  building 
growth  the  area  has  seen  in  that  time. 
The  two  interlocking  reasons  aren’t  sur¬ 
prising  when  you  think  about  them: 
More  places  to  hide,  and  more  things 
to  eat. 

Twenty  years  ago  there  were  few  cul¬ 
verts  or  storm  drains  in  Phoenix.  Now, 
after  two  hundred-year  floods  in  close 
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succession,  culverts  are  everywhere,  and 
they  carry  water  perhaps  three  days  out 
of  the  year.  The  rest  of  the  time,  they  are 
bone-dry  —  perfect  for  waiting  out  the 
blazing  Phoenix  days  or  raising  pups 
in  perfect  safety. 

And  things  to  eat,  lordy  .  .  .  who’d 
chase  a  stringy  old  roadrunner  when 
you  can  gorge  on  leftover  French  fries 
behind  the  dumpster  at  Carl’s  Junior? 


And  for  those  atavist  coyotes  who  pre¬ 
fer  chasing  down  dinner,  there  is  no 
shortage  of  free-roaming  house  cats. 
(Though  fewer  in  recent  years,  I’ve 
heard:  Nothing  teaches  a  cat  owner  a 
sense  of  responsibility  like  finding 
pieces  of  Charlie  underneath  the  palo 
verde  tree  in  the  empty  lot  down  the 
street .  .  .  .) 

Ecological  Niches 

Actually,  hearing  of  the  Phoenix  coy¬ 
ote  population  explosion  surprised  me 
less  than  hearing  last  year  that  Jensen 
&  Partners  was  bringing  out  yet  an¬ 
other  C  compiler,  or  this  year  hearing 
that  JPI  would  be  bringing  out  a  new 
Pascal  compiler.  It  seemed  odd  (or  ex¬ 
cessively  gutsy)  only  at  first.  As  with 
the  coyotes’  role  in  keeping  cat  doo- 
doo  out  of  my  flower  beds,  I  had  over¬ 
looked  an  important  ecological  niche 
in  the  structured  language  world  that 
was  not  being  well-filled:  The  area  of 
multi-language  development. 

The  idea,  in  short,  is  to  write  a  pro¬ 
gram  in  C  and  call  routines  written  in 
Pascal  ...  or  to  write  a  program  in  Pas¬ 
cal  and  call  routines  written  in  Modu- 
la2  .  .  .  or  some  other  permutation  of 
the  major  languages.  This  is  a  difficult 
business  for  a  great  many  reasons,  and 
the  major  vendors  haven’t  done  much 
to  make  it  easier.  Microsoft  started  out 
down  the  right  road  years  ago,  by  pro¬ 
viding  specific  instructions  on  linking 
code  written  in  their  various  languages, 
but  they  never  took  it  very  far,  and 
even  at  its  best  the  process  was  some¬ 
thing  I  would  consider  an  ordeal. 
Borland  does  provide  some  small  .DOC 
files  on  calling  Turbo  Pascal  from  Turbo 
C  and  vice  versa,  but  it  seemed  lots 
more  trouble  than  it  was  worth. 


Polymorphic  Compilation 

The  TopSpeed  solution  to  multi-lan¬ 
guage  programming  is  bold:  When  you 
buy  a  TopSpeed  language,  you  get  the 
TopSpeed  interactive  development  en¬ 
vironment  (IDE).  When  you  buy  a  sec¬ 
ond  (or  third)  TopSpeed  language,  it 
installs  so  that  it  can  be  invoked  from 
within  the  same  copy  of  the  IDE  (which 
is  not  installed  a  second  time),  as  a 
peer  with  any  other  installed  TopSpeed 
languages.  The  various  languages  rec¬ 
ognize  certain  file  extensions  as  their 
“own”  and  the  IDE  will  automatically 
invoke  the  correct  language  when  a 
given  source  file  is  specified  for  compi¬ 
lation.  In  other  words,  if  you  compile 
CHARLIE. C,  the  IDE  invokes  TopSpeed 
C  without  explicit  instruction  from  you; 
or  if  you  compile  CHARLIE. MOD,  the 
IDE  will  invoke  TopSpeed  Modula-2. 

There  is  already  A  TopSpeed  Assem¬ 
bler.  TopSpeed  Pascal  is  in  its  final 
testing  stages,  and  may  well  be  ship¬ 
ping  by  the  time  you  read  this.  JPI  has 
expressed  intention  of  delivering  a 
TopSpeed  C++  and  a  TopSpeed  Ada 
sometime  in  1991,  and  both  will  fit 
right  into  the  larger  scheme. 

Building  CHARLIE.EXE  from  multi¬ 
ple  pieces  written  in  multiple  languages 
requires  a  central  blueprint,  and  this  is 
provided  by  JPI’s  excellent  automatic 
MAKE  facility.  Unlike  MAKE  utilities  in 
the  traditional  C  world,  TopSpeed  MAKE 
is  built  into  the  TopSpeed  compilers. 
The  programmer  provides  a  project  file 
containing  instructions  to  the  compiler: 
Memory  model  to  be  used,  compiler 
options  to  invoke,  which  files  are  in¬ 
volved  and  must  be  linked  together, 
and  so  on.  The  MAKE  facility  follows 
this  plan  to  produce  the  final  .EXE  file, 
taking  into  account  the  time  stamps  of 
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involved  source  and  object  files  so  that 
it  doesn’t  recompile  anything  needlessly. 

Why  Bother? 

JPI  has  managed  to  get  multi-language 
development  over  the  line  into  the  realm 
of  the  possible.  But  the  question  does 
remain,  Why  bother  at  all?  Especially 
today,  when  you  can  do  just  about 
anything  you  want  in  just  about  any 
commercial  implementation  of  any  struc¬ 
tured  language.  The  reasons  are  few 
but  they  can  be  compelling: 

1 .  Retaining  existing  investment  in  code 
libraries.  Say  you’re  in  a  shop  that  has 
always  done  its  development  in  Modu- 
la2,  and  Corporate  issues  a  proclama¬ 
tion  that  all  future  development  is  to 
be  done  in  C.  Hokay  .  .  .  except  that 
that  means  that  maybe  five  years’  worth 
of  existing  libraries  have  to  be  rewrit¬ 
ten.  If  you  can  rig  things  so  as  to  call 
the  existing  Modula  libraries  from  the 
new  modules  written  in  C,  you  can  get 
the  work  done  in  C  and  convert  the 
older  libraries  to  C  as  time  allows  ...  if 
you  bother  at  all. 

2.  Making  use  of  specialty  commercial 
libraries  in  different  languages.  Perhaps 
you  do  all  your  work  in  C,  but  the  only 
third-party  library  you’ve  found  that 
provides  a  certain  difficult  function  is  in 
Pascal  or  Modula-2.  A  real-life  example 
would  involve  the  Solid  Link  Modula-2 
library  I  described  in  my  July  column. 

1  have  numerous  communications  li¬ 
braries  for  various  languages  in  my  collec¬ 
tion,  but  Solid  Link  is  the  only  one  that 
implements  the  ZModem  protocol, 
which  is  hairy  in  the  extreme  to  imple¬ 
ment  yourself.  By  using  TopSpeed  C, 
you  could  have  your  C  and  ZModem 
too. 

3.  Maintaining  multiple-platform  librar¬ 
ies.  If  your  shop  must  support  different 
platforms  than  DOS,  like  the  Sun  under 
Unix,  or  the  Amiga  or  Macintosh,  it  can 
make  sense  to  identify  what  functions 
can  be  implemented  identically  across 
all  platforms  in  a  single  highly-stan- 
dard  source  file.  User  interface  hassles 
might  confine  this  to  computational 
things  such  as  fast  Fourier  transforms 
and  so  on,  but  it  can  still  be  worth 
doing.  The  only  language  all  platforms 
might  have  in  common  is  ANSI  C,  but 
a  cross-language  system  would  allow 
you  to  develop  under  DOS  in  the  lan¬ 
guage  of  your  choice  and  still  use  the 
common-platform  C  libraries. 

On  the  flipside,  there  are  things  that 
are  not  reasons  to  work  cross-language. 
This  is  the  big  one: 

1.  Working  cross-language  will  not  gain 
you  execution  speed.  (Unless,  of  course, 
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one  of  the  languages  is  assembler.) 
One  of  the  significant  happenings  of 
the  past  few  years  is  that  code-genera¬ 
tion  technology  has  improved  across 
the  board,  and  there  is  no  longer  any 
automatic  penalty  for  working  in 
Modula-2  or  Pascal.  The  recent  Modu- 
la2  compilers  from  Stony  Brook  and 
JPI,  in  fact,  are  so  good  that  you  might 

A  memory  model  is  a 
set  of  assumptions  about 
how  memory  is 
addressed  beneath  the 
surface  of  a  high-level 
language 


incur  a  performance  penalty  for  work¬ 
ing  in  some  implementations  of  C.  Cer¬ 
tainly,  within  the  TopSpeed  language 
family,  you  can  assume  that  the  code 
generation  technology  for  all  languages 
is  similar  and  that  code  performance 
will  be  about  the  same  no  matter  which 
language  you’re  using. 

And  a  lesser  one: 

2.  Working  cross-language  will  not  give 
you  additional  functionality.  If  there’s 
anything  C  can  do  that  current  com¬ 
mercial  implementations  of  Modula-2 
can’t  do,  I’ve  yet  to  see  it.  I’ll  provi¬ 
sionally  say  the  same  for  JPI’s  own 
dialect  of  Pascal  (which  will  not  be  a 
clone  of  Turbo  Pascal)  but  we’ll  ad¬ 
dress  this  issue  later  on  when  I’ve  had 
time  to  play  with  TopSpeed  Pascal. 

My  own  conclusion:  If  you  need  to 
work  cross-language,  JPI  is  currently 
the  only  way  to  go. 

Memory  Addressing  and  Memory  Models 

Working  cross-language  opens  up  a 
whole  Pandora’s  box  of  things  you  have 
to  keep  straight  to  stay  out  of  lockup- 
land.  The  single  most  important  of  these 
is  the  issue  of  memory  models.  Turbo 
Pascal  people  have  rarely  had  to  think 
about  memory  models,  because  Turbo 
Pascal  only  supports  one  memory 
model.  (Much  of  the  problem  in  con¬ 
verting  old  Turbo  Pascal  3  0  apps  to 
Turbo  Pascal  4.0  and  later  lies  in  the 
fact  that  the  conversion  involves  a 
change  of  memory  model.)  Most 
Modula-2  compilers  have  provided 
more  than  one  memory  model,  but  the 
majority  of  Modula-2  programmers 
choose  the  default  memory  model  and 


simply  stick  with  it  to  avoid  having  to 
understand  what  changing  from  one 
to  another  really  means. 

Simply  put,  a  memory  model  is  a  set 
of  assumptions  about  how  memory  is 
addressed  beneath  the  surface  of  a  high- 
level  language.  But  before  I  go  further 
down  that  road,  let’s  review  how  mem¬ 
ory  is  addressed  in  the  8086/8088  CPU 
and  in  real  mode  of  the  286/386/486. 

86-family  real  mode  memory  is  lim¬ 
ited  to  220  bytes,  or  1,048,580  bytes, 
alias  1  Mbyte.  An  86-family  register, 
however,  contains  only  16  bits,  which 
can  specify  only  216  (65,536  or  64K) 
locations  when  used  as  an  address. 
How,  then,  do  you  address  a  full  mega¬ 
byte  with  16-bit  registers?  The  answer 
is  to  use  two  registers  side-by-side.  The 
high-order  16-bit  register  specifies  one 
of 65,536  starting  points  within  the  mega¬ 
byte  of  memory.  Each  starting  point 
begins  16  bytes  higher  in  memory  than 
the  one  before  it.  The  low-order  regis¬ 
ter  specifies  an  offset  from  some  start¬ 
ing  point.  This  offset  may  be  up  to 
65,535  bytes  away  from  the  starting 
point. 

The  65,536  bytes  beginning  at  any 
starting  point  is  called  a  “segment,” 
and  the  number  of  the  starting  point 
that  begins  any  given  segment  is  called 
its  “segment  address.”  Segment  0  has 
its  starting  point  at  the  very  bottom  of 
memory,  in  the  very  first  byte  of  the 
memory  system.  Segment  1  begins  16 
bytes  up-memory  from  Segment  0.  Seg¬ 
ment  2  begins  32  bytes  up-memory 
from  Segment  0,  and  so  on.  Segment 
65,535  begins  only  16  bytes  down  from 
the  very  last  byte  in  the  1,048,580  bytes 
addressable  by  the  86  family. 

From  this  you  should  be  able  to  see 
that  by  choosing  the  right  segment  and 
the  right  offset  within  that  segment, 
you  can  uniquely  specify  any  single 
byte  in  the  whole  1,048,580  of  them. 
Doing  this  choosing,  however,  requires 
two  registers,  which  we  generally  call 
a  “segment  register”  and  an  “offset  reg¬ 
ister.”  The  86  architecture  has  several 
segment  registers  and  several  other  reg¬ 
isters  that  may  act  as  offset  registers. 
To  pinpoint  a  location  in  a  megabyte 
of  memory,  you  have  to  put  a  segment 
address  in  a  segment  register,  and  an 
offset  address  in  another  register.  Be¬ 
tween  the  two  of  them,  you  can  point 
anywhere  in  memory. 

Looking  Far  and  Near 

Needless  to  say,  the  language  compiler 
worries  about  all  this  so  that  you  don’t 
have  to.  The  compiler  takes  care  of 
keeping  data  variables  in  an  area  of 
memory  that  it  knows  how  to  find  later 
on,  and  knows  how  to  find  a  proce¬ 
dure  or  function  in  memory  when  that 
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procedure  or  function  has  to  be  called. 
The  assumptions  that  a  compiler  uses 
to  locate  code  and  data  comprise  the 
memory  model  the  compiler  is  cur¬ 
rently  using.  There  are  several  such 
models. 

First  of  all,  consider  a  program  that 
has  a  lot  of  code  but  not  much  data. 

If  all  the  data  a  program  will  need 
to  work  with  can  fit  into  a  single  64K 
segment,  the  compiler  arranges  things 
so  that  all  data  is  put  together  within 
one  segment,  and  makes  the  assump¬ 
tion  that  data  will  only  be  found  in  that 
segment.  One  segment  register  is  given 
the  segment  address  of  this  data  seg¬ 
ment  when  the  program  begins  execu¬ 
tion,  and  when  data  must  be  read  or 
written,  only  the  offset  portion  of  the 
address  must  be  changed.  With  only 
one  register  to  modify,  operations  on 
data  can  be  done  more  quickly  than  if 
both  a  segment  and  an  offset  address 
must  be  specified  every  time  data  is 
accessed. 

When  all  of  a  program’s  data  is  placed 
together  in  a  single  64K  segment,  we 
call  it  “near  data.” 

Now,  that  same  program  has  lots  of 
code,  more  than  will  fit  in  a  single 
segment.  So  the  compiler  sets  up  as 
many  segments  as  it  takes  to  contain 
all  the  program’s  code,  and  when  one 
routine  calls  another,  it  must  specify 
both  the  segment  address  and  the  off¬ 
set  address  of  the  routine  to  be  called. 
Code  addressed  this  way  is  called  “far 
code.” 

It  can  work  the  other  way  around  for 
both  code  and  data.  If  a  program  has 
only  a  little  code,  all  that  code  can  be 
placed  together  in  a  single  segment 
with  a  single  fixed  segment  address. 
All  calls  from  one  routine  to  another 
may  then  be  made  using  a  single  16-bit 
offset  address.  This  scheme  (called 
“near”  code)  uses  less  memory  and  is 
faster  than  when  a  full  32-bit  address 
must  be  used.  Similarly,  programs  with 
loads  of  data  (say,  several  very  large 
arrays)  can  arrange  to  place  their  data 
in  multiple  segments  and  address  the 
data  with  full  32-bit  addresses.  This  is 
somewhat  slower  and  bulkier  than  near 
data,  but  it  does  allow  you  to  use  a 
great  deal  more  data  in  a  program. 


All  the  Myriad  Models 

The  memory  model  used  by  a  compiler 
is  predicated  on  what  combination  of 
code  and  data  assumptions  will  be 
made.  The  memory  model  in  which 
there  is  both  near  code  and  near  data 
(and  hence  only  two  64K  segments)  is 
called  the  “small  model.”  The  memory 
model  in  which  there  is  both  far  code 
and  far  data  is  called  the  “large  model.” 

The  really  ugly 
barrier  to  cross¬ 
language  development, 
however,  lies  in  some¬ 
thing  called  “calling 
conventions” 


In  between  are  two  intermediate  stages 
called  the  “compact  model”  (near  code, 
far  data)  and  the  “medium  model”  (far 
code,  near  data).  See  Table  1  for  a 
summary  of  the  various  models. 

There  are  two  slightly  peculiar  mu¬ 
tant  models,  one  on  each  end  of  the 
scale.  If  both  code  and  data  are  small 
enough  so  that  both  can  fit  into  the 
same  64K  segment  without  tromping 
on  one  another,  we  call  that  the  “tiny 
model.”  The  tiny  model’s  sole  virtue  is 
that  it  is  the  only  memory  model  that 
can  be  massaged  into  a  .COM  file  by 
the  EXE2BIN  DOS  utility. 

There  is  one  more  model,  the  “huge 
model,”  that’s  slightly  tougher  to  ex¬ 
plain.  In  all  other  models,  there  is  an 
assumption  that  no  single  data  item 
may  be  larger  than  a  single  segment. 
In  other  words,  even  though  the  large 
model  may  have  as  many  data  seg¬ 
ments  as  it  likes,  no  data  item  may  span 
more  than  one  segment.  The  huge  mem¬ 
ory  model  allows  a  single  data  item  to 
span  more  than  one  segment. 

This  sounds  simple,  but  when  you 
start  to  mull  what  it  means  the  whole 
concept  starts  to  collapse.  You  can  only 


Tiny 

Small 

Compact 

Medium 

Large 

Huge 

Code 

Near 

Near 

Near 

Far 

Far 

Far 

Data 

Near 

Near 

Far 

Near 

Far 

Far 

Max. 

prog. 

size 

64K 

128K 

1MB 

1MB 

1MB 

1MB 

NOTE: 

The  huge  and  large  models  differ  primarily  in  how  data  is  addressed;  in  the 
huge  model,  data  items  may  span  multiple  segments. 

I  Table  1:  The  standard  Intel  86-family  memory  models 
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make  sense  of  it  by  understanding  how  the  procedure  headers  involved  with  If  you’re  working  cross-language 
data  is  addressed  by  the  CPU,  and  the  the  {$F+}  and  /XT-/ compiler  directives,  within  the  TopSpeed  environment,  you 
best  example  is  a  large  array.  Turbo  Pascal,  by  the  way,  uses  the  avoid  trouble  by  making  sure  that  all 

An  ordinary  array  in  any  data  model  medium  memory  model:  Near  data  in  the  languages  involved  in  creating  old 
but  the  huge  model  begins  at  some  one  64K  data  segment,  and  far  code  CHARLIE.EXE  are  working  within  the 
offset  from  the  segment  address.  To  residing  in  as  many  code  segments  as  same  memory  model.  The  TopSpeed 
read  an  item  in  the  array,  the  CPU  you  need,  with  each  unit  getting  its  languages  support  all  models  except 
places  the  offset  address  of  the  array  own  code  segment.  This  can  get  in  the  the  tiny  model  and  the  huge  model, 
in  an  offset  register,  and  calculates  yet  way  if  you  try  to  declare  several  very  The  default  small  model  is  good  enough 
another  offset  based  on  the  desired  large  arrays.  The  way  around  Turbo  for  most  small  projects  —  and  certainly 
array  index.  For  example,  if  the  array  Pascal’s  near  data  limitations  is  to  use  for  getting  the  hang  of  things, 
is  an  array  of  records  where  each  rec-  the  heap  and  create  a  linked  list  rather 

ord  is  32  bytes  long,  and  you  want  to  than  try  to  declare  an  enormous  array  Calling  All  Conventions 
access  the  thirteenth  element  in  the  in  one  piece.  (The  heap  is  wholly  an  The  really  ugly  barrier  to  cross-language 
array,  the  CPU  multiplies  32  by  12](you  artifact  of  the  high-level  language  you’re  development,  however,  lies  in  some- 
count  elements  from  0)  to  calculate  this  using  and  does  not  really  involve  the  thing  called  “calling  conventions.”  Like 
secon  d  offset.  The  second  offset  is  then  memory  model.)  memory  models,  calling  conventions 

added  to  the  array  offset  to  find  the  - 

specific  desired  array  element. 

The  problem  should  begin  to  come 
clear:  The  sum  of  the  two  offsets  must 
still  fit  into  a  single  1 6-bit  register  to  act 
as  an  offset  from  the  array’s  segment 
address.  A  16-bit  register  can  only  count 
to  65,535  —  hence  the  array  is  limited 
to  64K  in  size. 

In  the  huge  memory  model,  the  CPU 
must  perform  some  considerably  more 
sophisticated  calculations  to  access  any 
element  of  a  “huge”  array.  Each  ele¬ 
ment  of  the  array  has  its  own  segment 
and  offset  address,  and  both  must  be 
calculated  each  time  an  element  of  the 
array  is  specified.  Needless  to  say,  this 
takes  lots  more  time  than  when  an 
array  must  fit  into  64K. 

Marrying  Models 

You  have  to  keep  all  this  stuff  in  mind 
when  you  begin  to  butt  one  piece  of 
code  from  one  language  up  against 
another  piece  of  code  from  another 
language.  If  you  call  a  piece  of  near 
code  from  a  piece  of  far  code,  you’ll 
probably  crash  the  system.  The  near 
code  pushes  only  one  address  (the  off¬ 
set  address)  onto  the  stack  when  the 
call  is  made,  but  the  far  code  pops  two 
addresses  from  the  stack  when  it  re¬ 
turns.  It’ll  take  the  one  address  the 
calling  code  pushed,  and  grab  the  next 
two  bytes  on  the  stack  as  well,  no 
matter  what  those  2  bytes  actually 
are  .  .  .  and  then  launch  off  to  the  32- 
bit  address  represented  by  the  genuine 
offset  address  and  the  bogus  segment 
address.  Where  it  stops,  well,  nobody 
knows. 

This  might  sound  a  touch  familiar  to 
Turbo  Pascal  people.  In  Turbo  Pascal, 
calls  made  within  a  unit  are  near  calls. 

Calls  made  to  a  unit  from  outside  the 
unit  are  far  calls.  The  compiler  handles 
this  transparently  for  you  unless  you’re 
going  to  define  things  like  INLINE  mac¬ 
ros  or  assembly  language  externals.  Then 
you’d  better  make  sure  that  all  code  is 
forced  to  be  far  code  by  bracketing  all 
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are  sets  of  assumptions  the  compiler 
makes  when  setting  up  a  program. 

When  one  routine  calls  another  rou¬ 
tine,  several  things  must  happen:  The 
return  address  must  get  pushed  onto 
the  stack;  any  parameters  to  be  passed 
as  part  of  the  call  must  be  pushed  onto 
the  stack;  control  must  be  transferred 
to  the  called  routine;  and  finally,  some¬ 
thing  must  return  the  stack  to  its  previ¬ 
ous  state  when  the  called  routine  re¬ 
turns  control  to  the  caller. 

These  things  can  be  done  in  differ¬ 
ent  orders  in  different  ways.  There  are 
two  traditionally  recognized  calling 
conventions  in  the  86-family  world: 

In  the  Pascal  calling  convention,  pa¬ 
rameters  are  passed  from  left  to  right.  In 
other  words,  given  the  following  call: 

GrimblerCFoo, Bar, Bas, Beep); 

the  parameter  Foo  will  be  pushed  on 
the  stack  first,  then  Bar ,  then  Bas ,  then 
Beep.  Just  before  the  called  procedure 
returns  control  to  the  caller,  it  performs 
some  work  on  the  registers  that  causes 
the  parameters  to  disappear  from  the 
stack.  So  by  the  time  procedure  Grimb- 
ler returns  control  to  whatever  called  it, 
Foo ,  Bar,  Bas,  and  Beep  are  simply 
gone,  and  the  stack  is  in  the  same  state 
it  was  before  the  call  to  Grimbler  began. 

In  the  C  calling  convention,  things 
are  pretty  much  the  other  way  around. 
Parameters  are  pushed  on  the  stack  from 
right  to  left.  Consider  this  C  function: 

fumbler(foo, bar, bas, beep); 

Following  the  C  calling  conventions, 
the  beep  parameter  goes  onto  the  stack 
first,  followed  by  bas,  and  then  bar, 
and  finally  foo.  The  parameters  are 
pushed  this  way  so  that  the  number  of 
parameters  passed  to  a  C  function  may 
vary  from  call  to  call. 

The  sincerest  hope  is  that  when  a 
variable  number  of  parameters  is  being 
passed,  the  last  parameter  pushed  onto 
the  stack  —  and  hence  the  only  one 
the  called  procedure  is  certain  to  be 
able  to  identify  using  stack  pointer  SP  — 
is  the  number  of  parameters  passed 
on  that  particular  call.  The  called  pro¬ 
cedure  can  then  use  this  count  to  iden¬ 
tify  and  access  the  remaining  parame¬ 
ters,  which  lie  further  up  the  stack. 

Weird?  I  used  to  think  so,  but  it’s 
growing  on  me.  The  problem  is  that 
the  cleanup  of  the  stack  is  not  some¬ 
thing  that  can  be  parametrized.  The 
code  must  know  how  much  stack  space 
is  used  on  each  call  at  compile  time  to 
be  able  to  restore  the  stack  to  its  state 
that  existed  before  the  call  was  made. 
If  the  same  C  function  can  be  called 
with  three  parameters  at  one  point  in 
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the  program  and  with  seven  parame¬ 
ters  at  another  point  in  the  program, 
there’s  no  way  the  function  itself  can 
clean  up  the  stack.  Only  the  code  that 
calls  the  function  knows  at  compile 
time  how  much  stack  space  is  needed 
for  the  call.  Therefore,  in  the  C  calling 
convention,  the  code  that  calls  a  func¬ 
tion  takes  the  stack  back  from  the  called 
function  with  all  the  parameters  still 
there.  The  caller  then  removes  the  pa¬ 
rameters  from  the  stack  and  restores 
the  stack  to  its  pre-call  state. 

These  two  conventions  are  utterly 
incompatible.  You  cannot  call  C  code 
compiled  using  the  C  calling  conven¬ 
tions  from  a  Pascal  routine  compiled 
with  the  Pascal  calling  conventions.  The 
tug-o-war  over  stack  cleanup  alone  will 
send  your  DOS  session  into  the  bushes, 
regardless  of  parameter  order. 

In  most  systems  that  have  allowed 
C  and  Pascal  to  call  one  another,  the  C 
code  is  directed  (via  a  compiler  toggle 
of  some  sort)  to  generate  a  call  using 
the  Pascal  calling  conventions  when  it 
calls  Pascal  code.  Similarly,  when  Pas¬ 
cal  calls  a  C  function,  that  C  function 
must  have  been  compiled  using  the 
Pascal  calling  conventions.  I  have  never 
yet  seen  a  Pascal  compiler  that  can 
generate  calls  using  the  C  calling 
conventions,  but  I  know  of  no  reason 
why  it  couldn’t  be  done. 

JPI  makes  the  two  languages  meet 
in  the  middle  by  creating  its  own  call¬ 
ing  convention,  in  which  parameters 
are  passed  from  left  to  right,  as  in  Pas¬ 
cal,  but  in  which  the  caller  cleans  up 
the  stack,  as  in  C.  Furthermore,  when 
CPU  registers  are  available  to  carry  pa¬ 
rameters  between  caller  and  callee, 
those  registers  are  used,  making  for 
much  faster  procedure  calls. 

The  central  point  to  be  made  about 
calling  conventions  is  that  both  ends 
of  the  call  must  agree  on  the  conven¬ 
tion  used.  Get  confused  and  you  go 
bye-bye.  If  you’re  going  to  work  cross¬ 
language,  you  must  understand  calling 
conventions  completely.  This  begins 
by  reading  whatever  the  compiler  ven¬ 
dor  or  vendors  provide  in  the  way  of 
calling  convention  documentation,  but 
the  smart  hacker  goes  in  with  a  good 
debugger  and  watches  exactly  what 
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happens  —  at  an  assembly  language 
level  —  when  a  call  is  made. 

From  the  Land  of  Lost  Books 

Many  thanks  to  the  people  who  wrote 
and  called  to  say  they  had  seen  my 
books  on  the  stands  here  and  there. 
The  bad  news  is  that  Scott,  Foresman 
&  Company  was  sold  earlier  this  year 
to  Harper  &  Row,  which  last  month 
shut  down  the  Scott,  Foresman  trade 
books  division.  When  supplies  are  gone, 
that’s  that  —  my  books  are  in  limbo,  I 
can’t  revert  rights,  and  I’m  a  man  with¬ 
out  a  publisher.  So  it  goes  with  corpo¬ 
rate  megamergers. 

But  the  programming  business  con¬ 


tinues  to  improve.  Actor  3  0  has  ap¬ 
peared,  coincident  with  Microsoft  Win¬ 
dows  3-0.  Modula-2  from  JPI  now  has 
object  extensions  almost  identical  to 
those  of  Turbo  Pascal  5.5.  Stony  Brook’s 
upgraded  Modula-2  and  new  Pascal 
products  push  the  frontier  of  code  op¬ 
timization  even  further  into  the  strato¬ 
sphere.  More  on  that  in  a  future  col¬ 
umn,  along  with  real  code  for  some 
Modula-2  objects,  promise  .... 

.  . .  drat,  there’s  that  cat  again!  Quick, 
where’s  my  coyote  call? 

DDJ 
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Microprocessors 
From  the 
Programmers 
Perspective 


Like  everyone  else,  programmers 
generally  prefer  high-end  ma¬ 
chines.  Many  PC  programmers, 
however,  mastered  instruction  sets, 
addressing  modes,  and  registers  on  the 
8088  or  68000,  never  really  corning  to 
grips  with  the  ins-and-outs  of  the  fun¬ 
damentally  different,  though  backward 
compatible,  chips  such  as  the  80386 
or  68030.  Although  they  use  80386s, 
many  PC  programmers  are  still  8088 
programmers  at  heart,  possessing  a  sur¬ 
prising  ignorance  of  high-end  micro¬ 
processor  architecture. 

Then  there  are  basic  questions  such 
as,  What  is  RISC?  Are  the  Intel  80486 
and  Motorola  68040  RISC  chips?  What 
is  the  architecture  of  the  new  IBM  Sys¬ 
tem/6000  family  or  the  Sun  SPARCsta- 
tions?  and  How  do  you  program  one 
of  those  things? 

To  address  questions  like  these, 
Robert  Dewar  and  Matthew  Smosna’s 
Microprocessors:  A  Programmer's  View 
provides  a  solid  introduction  to  the 
new  chips.  As  the  subtitle  indicates, 
this  book  is  for  programmers,  not  hard¬ 
ware  design  engineers;  there  are  no 
descriptions  of  pins  here,  but  instead, 


Andrew  Schulmon 


lots  of  code  examples. 

After  an  opening  chapter  on  general 
issues  —  register  sets,  addressing 
modes,  and  instruction  formats  —  the 
authors  present  an  in-depth  look  at  the 
Intel  80386  (three  chapters)  and  Mo¬ 
torola  68030  (two  chapters).  This  is 
followed  by  one  chapter  each  on  the 
most  important  Reduced  Instruction  Set 
Computer  (RISC)  architectures:  MIPS, 


Microprocessors: 
A  Programmer’s 
View 

Robert  B.K.  Dewar  and 
Matthew  Smosna, 

New  York:  McGraw-Hill, 

1990,  462  pages,  hardcover, 
$39.95. 


Sun  SPARC,  Intel  i860,  IBM  (both  the 
ROMP  architecture  found  in  the  IBM 
RT,  and  the  RIOS  used  in  the  new 
System/6000  family),  and  INMOS 
transputer. 

The  RISC  microprocessors  require  less 
explanation  than  the  more  conventional 
Intel  or  Motorola  offerings,  simply  be¬ 
cause  the  RISC  chips  really  do  have  a 
simpler  architecture.  As  Dewar  and 
Smosna  point  out,  one  reason  for  this 
is  that  RISC  manufacturers  started  with 
a  clean  slate  while  Intel  and  Motorola 
were  largely  driven  by  the  need  for 
backward  compatibility. 

Microprocessors  also  contains  a  lot  of 
anecdotal  material,  and  reflects  a  knowl¬ 
edge  of  the  real  world  that  is  surprising 
in  a  treatise  on  computer  architecture. 
One  section,  “A  Sad  Story,”  talks  about 
how  Intel  thinks  INT  5  means  one  thing, 
how  IBM  thinks  it  means  another,  and 
how  this  led  to  the  IBM  PCjr  not  using 
the  Intel  80188  chip.  Another  story, 
which  comes  in  the  middle  of  a  discus¬ 
sion  of  the  256-byte  instruction  cache 
on  the  68020,  describes  a  misaligned 
loop  in  Peter  Norton’s  SI  benchmark¬ 
ing  program  for  the  PC.  A  brief  digres¬ 
sion  on  patent  law  describes  how  DEC 
patented  the  use  of  the  instruction 
pointer  (IP)  as  a  general  register. 


A  Background  in  Compilers 

Dewar  and  Smosna  are  both  professors 
at  the  NYU  Courant  Institute  of  Mathe¬ 
matical  Sciences.  Between  them,  they 
have  over  25  years  experience  working 
on  compilers,  including  the  well-re¬ 
spected  Realia  COBOL  and  Alsys  Ada 
for  the  IBM  PC,  the  SPITBOL  compiler, 
and  NYU’s  SETL  language. 

Why  is  a  background  in  compilers 
useful  when  writing  a  book  on  the  new 
hardware?  Because,  for  better  or  for 
worse,  most  code  that  is  run  on  high- 
end  processors  is  generated  by  compil¬ 
ers.  Thus,  compiler  writers  determine 
to  a  large  extent  which  features  of  a 
microprocessor  are  used.  The  funda¬ 
mental  observation  that  inspired  the 
original  RISC  research  was  that  only  a 
small  subset  of  the  instruction  set  and 
addressing  modes  of  most  processors 
is  commonly  executed.  Who  better  than 
a  compiler  writer  to  tell  us  which  fea¬ 
tures  are  important  and  which  ones, 
however  interesting  sounding,  will 
never  be  used. 

If  an  instruction  exists  and  almost  no 
one  uses  it,  can  its  real  estate  on  the  chip 
be  put  to  better  use?  For  example,  it  is 
difficult  for  a  compiler  to  take  advantage 
of  many  of  the  niftier  features  of  the 
80386  instruction  set.  The  80386  has  a 
special  three-operand  form  of  the  IMUL 
instruction  that  can  manipulate  64-bit 
integers,  but  there  is  no  corresponding 
C  data  type  for  64-bit  integers,  so  the 
instruction  is  hardly  ever  used  —  even 
in  code  that  needs  to  manipulate  64-bit 
integers!  (In  their  wonderfully  idiosyn¬ 
cratic  style,  Dewar  and  Smosna  explain 
all  this  with  an  anecdote  involving  the 
typesetting  firm  owned  by  one  of  their 
brothers-in-law. ) 
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So,  just  because  a  microprocessor 
has  an  instruction  to  work  with  64-bit 
integers,  it  doesn’t  mean  that  code  that 
handles  64-bit  integers  will  in  fact  use 
the  instruction.  More  likely,  existing 
code  will  never  be  changed  to  take 
advantage  of  the  new  “hardware  sup¬ 
port”  for  64-bit  integers. 

Furthermore,  say  the  authors,  code 
shouldn’t  often  be  changed  to  use  a 
new  feature.  “Do  not  assume  that  an 
instruction  should  be  used  just  because 
it  is  there.”  By  way  of  example  they 
provide  an  in-depth  look  at  the  Intel 
ENTER  and  LEAVE  instructions. 

“Hardware  support”  for  a  feature 
sounds  like  it  should  always  be  better 
than  “doing  it  in  software.”  Dewar  and 
Smosna  present  a  cogent  argument  that 
this  ain’t  necessarily  so.  Again,  the  80386 
provides  many  examples.  The  authors 
discuss  how  “simply”  by  executing  a 
FAR  JMP  whose  target  is  a  task  state 
segment  (TSS),  one  performs  a  386  con¬ 
text  switch.  Sounds  terrific.  Why  does 
multitasking  software  for  the  386  ig¬ 
nore  this  magnificent  hardware  sup¬ 
port,  and  instead  do  context  switches 
in  software?  Because  the  hardware- 
supported  context  switch  can  easily 
take  300  clock  cycles! 

Why  RISC? 

This  entire  discussion  of  complex  in¬ 
structions  that  hardly  anyone  uses  di¬ 
rectly  leads  into  the  authors’  discussion 
of  RISC.  Quoting  Dan  Prener  of  IBM, 
the  authors  note  that  RISC  is  not  a 
reduced  set  of  instructions,  but  a  set 
of  reduced  instructions. 

The  goal  of  RISC  is  to  execute  one 
instruction  per  clock  cycle.  This  re¬ 
quires  not  only  simplified  instructions, 
but  also  optimal  use  of  the  processor’s 
instruction  pipeline.  As  Dewar  and 
Smosna  explain,  while  a  single  instruc¬ 
tion  may  have  a  latency  of  five  clock 
cycles,  if  the  instruction  fetch,  decode, 
and  execution  can  be  broken  into  five 
stages  that  can  be  overlapped  with  simi¬ 
lar  stages  for  other  instructions,  then 
average  throughput  can  equal  one  in¬ 
struction  per  clock  cycle. 

The  key  way  that  RISC  reduces  the 
complexity  of  the  instruction  set  is  by 
introducing  a  “load/store”  architecture. 
The  only  instructions  that  interface  with 
memory  are  LOAD  (read  memory-to- 
register)  and  STORE  (write  register-to- 
memory).  All  other  instructions  are  reg- 
ister-to-register.  This  greatly  reduces  the 
number  of  addressing  modes,  which, 
in  turn,  simplifies  the  processor’s  in¬ 
struction  decode  unit. 

But  a  load/store  architecture  isn’t  just 
aesthetically  pleasing.  It  also  provides 
the  opportunity  for  a  potentially  large 
performance  boost.  Access  times  for 


memory  will  always  be  slower  than 
clock  speeds  for  microprocessors. 
Caches  only  partially  deal  with  this  prob¬ 
lem.  Because  a  load/store  architecture 
gates  all  memory  access  through  two 
instructions,  we  can  boost  performance 
by  introducing  a  new  rule:  The  mem¬ 
ory  operand  to  a  LOAD  is  not  yet  avail- 

The  authors  present  an 
in-depth  look  at  the  Intel 
80386,  Motorola  68030, 
and  each  of  the  most 
important  Reduced 
Instruction  Set 
Computer  (RISC) 
architectures 


able  when  the  instruction  following  the 
LOAD  starts  executing.  With  this  rule, 
the  processor  can  start  executing  that 
instruction  before  the  read  from  mem¬ 
ory  has  completed.  The  only  require¬ 
ment  is,  of  course,  that  this  next  in¬ 
struction  not  need  the  result  of  the 
LOAD. 

What  then  do  we  do  with  the  in¬ 
struction  after  a  LOAD?  Many  pages  in 
Dewar  and  Smosna’s  book  are  devoted 
to  this  topic.  Obviously,  we  can  insert 
a  NOP,  but  then  we  are  back  where 
we  started.  In  fact,  a  good  optimizing 
compiler  can  usually  reorganize  code 
so  that  useful  things  can  be  done  in  the 
slot  after  a  LOAD.  But  this  means  that 
good  optimizing  compilers  are  neces¬ 
sary  to  take  advantage  of  RISC  architec¬ 
ture.  Rather  than  try  to  hide  them,  RISC 
exposes  hardware  features  such  as  the 
speed  difference  between  processors 
and  memory.  RISC  programming  means 
mastering  the  concept  of  software  pipe¬ 
lining.  Good  compilers  are  needed  so 
that  most  programmers  will  not  have 
to  remember  that  a  LOAD  from  mem¬ 
ory  is  a  physical  act  that  actually  takes 
time. 

The  various  RISC  architectures  ex¬ 
plored  in  this  book  differ  greatly  in  the 
extent  to  which  they  hide  or  expose 
the  instruction  pipeline.  The  MIPS  chips, 
for  example,  based  on  the  Stanford 
RISC  research,  rely  on  software 
conventions  rather  than  hardware  in¬ 
terlocks  for  handling  what  is  called  the 
“load  delay  slot.”  In  fact,  MIPS  origi¬ 


nally  stood  for  “Microprocessor  with¬ 
out  Interlocked  Pipeline  Stages.” 

The  Intel  i860  is  even  more  non¬ 
transparent.  As  explained  by  Dewar 
and  Smosna,  i860  programming  looks 
as  though  it  consists  almost  entirely  of 
pipeline  manipulation.  For  a  good  ex¬ 
ample,  look  in  the  index  to  Dewar  and 
Smosna  under  “Breadcrumbs,”  and  read 
the  indicated  page.  (I’m  not  kidding!) 

On  the  other  hand,  the  RIOS  archi¬ 
tecture  used  in  the  IBM  System/6000 
sounds  a  lot  easier  to  deal  with.  Ac¬ 
cording  to  Dewar  and  Smosna,  RIOS 
has  an  advantage  over  chips  like  the 
i860  that  “with  just  a  little  knowledge 
of  what  is  going  on  —  basically  little 
more  than  the  rule  that  you  should  not 
use  results  you  just  computed  —  the 
programmer  can  write  code  that  com¬ 
piles  in  a  highly  efficient  manner,  with¬ 
out  needing  a  sophisticated  optimizing 
compiler.” 

The  authors  conclude  that,  “Rather 
than  thinking  of  RISC  as  a  clearly  de¬ 
fined  characteristic  of  microprocessors, 
it  is  better  to  think  of  RISC  a  being  a 
term  for  a  collection  of  design  tech¬ 
niques  used  to  improve  performance.” 

Often  processor’s  niftiest  features  are 
difficult  to  take  advantage  of  in  a  high- 
level  language.  Chip  underutilization 
is  a  major  problem  in  our  industry.  It 
is  often  said  that  software  lags  behind 
hardware.  The  RISC  solution  is  to  de¬ 
sign  simpler  chips.  Another  solution  is 
to  make  heavier  use  of  assembly  lan¬ 
guage.  Another  solution,  in  the  case  of 
the  underutilization  of  the  80386,  is  to 
use  a  DOS  extender,  so  that  one  is  using 
the  machine  as  something  other  than 
a  “fast  XT.” 

Dewar  and  Smosna  are  wonderfully 
opinionated.  Following  their  lengthy 
discussion  of  the  rather  baroque  pro¬ 
tection  mechanism  on  the  80386,  the 
authors  forthrightly  state,  “The  previ¬ 
ous  section  is  virtually  incomprehensi¬ 
ble.  You  probably  have  to  read  it  sev¬ 
eral  times  to  understand  it,  and  it  is  still 
easy  to  get  the  DPLs,  CPLs,  and  RPLs 
hopelessly  mixed  up.”  The  title  of  this 
section  is  “Is  All  This  Worthwhile?”  A 
discussion  of  the  insane  number  of 
addressing  modes  on  the  Motorola 
68030  asks,  “Had  enough  of  this?”  As 
computer  books  seem  to  be  becoming 
more  and  more  homogenized,  it  was  a 
pleasure  to  read  Microprocessors ,  a  piece 
of  technical  writing  which  maintains 
the  authors’  voices  from  beginning  to 
end. 
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Listing  One  (Text  begins  on  page  127.) 

/* - crypto. c -  */ 

/* 

*  Simple,  single  key  file  encryption/decryption  filter 

*  Usage:  crypto  keyvalue  infile  outfile 
*/ 

♦include  <stdio.h> 

♦include  <string.h> 

void  main(int  argc,  char  *argv[]) 

( 

FILE  *fi,  *fo; 
int  ct; 
char  ip [8] ; 

char  *cpl,  *cp2; 

if  (argc  >  3)  ( 

if  {(fi  =  fopen  (argv[2] ,  "rb"))  !=  NULL)  { 

if  ( ( f o  =  fopen (argv[3] ,  "wb"))  !=  NULL)  { 
while  ( (ct  =  fread(ip,  1,  8,  fi))  !=  0)  { 

cpl  =  argv[l]; 
cp2  =  ip; 

while  (*cpl  &&  cpl  <  argv[l]+8) 

*cp2++  A=  *cpl++; 
fwrite(ip,  1,  ct,  fo); 

) 

f close (fo) ; 

) 

f close (fi) ; 


} 


struct  ks  ( 

char  ki [6] ; 

}; 

/* - macros  to  define  a  permutation  table - */ 

♦define  ps(n)  ((unsigned  char) (0x80  »  (n-1))) 

♦define  b(n,r)  ( (n>r ! !n<r-7) ?0:ps (n-  (r-8) ) ) 

♦define  p(n)  b(n,  8) ,b (n, 16) ,b (n, 24) ,b (n, 32) , \ 

b(n,40),b(n,48),b(n,  56)  ,b  (n,  64) 

/*  - prototypes -  */ 

void  inverse_permute (long  *op,  long  *ip,  long  *tbl,  int  n) ; 
void  permute (long  *op,  long  *ip,  long  *tbl,  int  n) ; 
long  f(long  blk,  struct  ks  ky) ; 
struct  ks  KS(int  n,  char  *key) ; 


/* - tables - */ 

extern  unsigned  char  Pmask[]; 
extern  unsigned  char  IPtbl [ ] ; 
extern  unsigned  char  Etbl[]; 
extern  unsigned  char  Ptbl [ ] ; 
extern  unsigned  char  stbl [8] [4] [16] ; 
extern  unsigned  char  PCltbl[); 
extern  unsigned  char  PC2tbl[]; 
extern  unsigned  char  ex6[8] [2] [4] ; 

End  Listing  Two 


Listing  Three 

/* - encrypt,  c - */ 

/* 

*  Data  Encryption  Standard  encryption  filter 

*  Usage:  encrypt  keyvalue  infile  outfile 
*/ 


End  Listing  One 


Listing  Two 

/*  - des.h - */ 

/* 

*  Header  file  for  Data  Encryption  Standard  algorithms 
*/ 

/* - two  halves  of  a  64-bit  data  block - *7 

struct  LR  ( 
long  L; 
long  R; 


/* - 48-bit  key  permutation - */ 


♦include  <stdio.h> 

♦include  "des.h" 

void  main (int  argc,  char  *argv[]) 

( 

int  i; 

struct  LR  op,  ip; 

FILE  *fi,  *fo; 
struct  ks  keys [16]; 

for  (i  =  0;  i  <  16;  i++) 

keys [i]  =  KS(i,  argv(lj); 
if  (argc  >  3)  ( 

if  ((fi  =  fopen (argv[2] ,  "rb"))  !=  NULL)  { 

if  ((fo  =  fopen (argv[3] ,  "wb"))  !=  NULL)  ( 

(continued  on  page  148) 
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Listing  Three  (Listing  continued,  text  begins  on  page  127.) 

while  (fread(&ip,  1, 

sizeof  (struct  LR) ,  fi)  !=  0)  { 

int  n; 

/* - initial  permuation - */ 

permute (&op.L,  &ip.L,  (long  *)IPtbl,  64); 

/* - swap  and  key  iterations - */ 

for  (n  =  0;  n  <  16;  n++)  { 

ip.L  =  op.R; 

ip.R  =  op.L  A  f(op.R,  keys[n]); 

op.R  =  ip.R; 
op.L  =  ip.L; 

) 

/*  -  inverse  initial  permuation  -  */ 

inverse_permute (Sop.L,  &ip.L, 

(long  *)IPtbl,  64); 

fwrite(&op,  1,  sizeof (struct  LR) ,  fo) ; 

/* - to  pad  the  last  block - */ 

ip.L  =  ip.R  =  0; 

} 

fclose (fo) ; 

) 

fclose (fi) ; 


End  listing  Three 


Listing  Four 

/* - decrypt. c - */ 

/* 

*  Data  Encryption  Standard  encryption  filter 

*  Usage:  decrypt  keyvalue  infile  outfile 
*/ 

♦include  <stdio.h> 

♦include  "des.h" 

void  main (int  argc,  char  *argv[]) 

{ 

int  i; 

struct  LR  op,  ip; 

FILE  *fi,  *fo; 
struct  ks  keys [16]; 

for  (i  =  0;  i  <  16;  i++) 

keys[i]  =  KS(i,  argv[l]); 
if  (argc  >  3)  { 

if  ((fi  =  fopen(argv[2] ,  "rb"))  !=  NULL)  { 

if  ((fo  =  fopen (argv[3] ,  "wb"))  !=  NULL)  ( 


while  (fread(&ip,  1, 

sizeof (struct  LR) ,  fi)  !=  0)  [ 

int  n; 

/* - initial  permuation - */ 

permute (&op. L,  &ip.L,  (long  *)IPtbl,  64); 

/* - swap  and  key  iterations - */ 

for  (n  =  15;  n  >=  0;  — n)  { 
ip.R  =  op.L; 

ip.L  =  op.R  A  f(op.L,  keys[n]); 

op.R  =  ip.R; 
op.L  =  ip.L; 

} 

/*  -  inverse  initial  permuation  -  */ 

inverse_permute (Sop.L,  &ip.L, 

(long  *)IPtbl,  64); 

fwrite(&op,  1,  sizeof (struct  LR) ,  fo) ; 

/* - to  pad  the  last  block - */ 

ip.L  =  ip.R  =  0; 

} 

fclose (fo) ; 

» 

fclose (fi) ; 

} 

) 

End  Listing  Four 


Listing  Five 

/* - des.c - */ 

/* 

*  Functions  and  tables  for  DES  encryption  and  decryption 
*/ 

♦include  <stdio.h> 

♦include  "des.h" 

static  void  rotate (unsigned  char  *c,  int  n) ; 
static  long  S (struct  ks  ip); 
static  int  fourbits (struct  ks,  int  s); 
static  int  sixbits (struct  ks,  int  s); 

/*  -  inverse  permute  a  64-bit  string  -  */ 

void  inverse_permute (long  *op,  long  *ip,  long  *tbl,  int  n) 

I 

int  i; 

long  *pt  =  (long  *)Pmask; 

*op  =  *(op+l)  =  0; 
for  (i  =0;  i  <  n;  i++)  { 

if  ( (*ip  &  *pt)  ::  (*  (ip+1)  &  *  (pt+1) ) )  { 

*op  :=  *tbl; 

* (op+1 )  :=  * (tbl+l) ; 

] 

tbl  +=  2; 
pt  +=  2; 


/* - permute  a  64-bit  string - */ 

void  permute (long  *op,  long  *ip,  long  *tbl,  int  n) 

( 

int  i; 

long  *pt  =  (long  *)Pmask; 

*op  =  *(op+l)  =  0; 

for  (i  =  0;  i  <  n;  i++)  ( 

if  ( (*ip  &  * tbl )  ::  (* (ip+1)  &  * (tbl+l)))  { 

*op  1=  *pt; 

* (op+1)  1=  * (pt+1) ; 

} 

tbl  +=  2; 
pt  +=  2; 

1 

} 

/*  -  Key  dependent  computation  function  f(R,K)  -  */ 

long  f(long  blk,  struct  ks  key) 

{ 

struct  LR  ir  =  (0,0); 
struct  LR  or; 

union  ( 

struct  LR  f; 
struct  ks  kn; 

}  tr  =  (0,0),  kr  =  (0,0); 
ir.L  =  blk; 
kr.kn  =  key; 

permute (&tr. f.L,  &ir.L,  (long  *)Etbl,  48); 

tr.f.L  A=  kr .f.L; 
tr.f.R  A=  kr.f.R; 

ir.L  =  S (tr .kn) ; 

permute (Sor.L,  &ir.L,  (long  *)Ptbl,  32); 
return  or.L; 


/*  -  convert  48-bit  block/key  permutation  to  32  bits  -  */ 

static  long  S (struct  ks  ip) 

I 

int  i; 

long  op  =  0; 

for  (i  =  8;  i  >  0;  — i)  { 

long  four  =  fourbits (ip,  i); 
op  !=  four  «  ( ( i— 1 )  *  4); 

} 

return  op; 
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/* - extract  a  4-bit  stream  from  the  block/key - */ 

static  int  fourbits (struct  ks  k,  int  s) 

{ 

int  i  =  sixbits(k,  s); 

int  row,  col; 

row  =  ((i  »  4)  &  2)  !  (i  &  1); 

col  =  (i  »  1)  &  Oxf; 

return  stbl [8-s] [row] [col] ; 

} 

/*  -  extract  6-bit  stream  fr  pos  s  of  the  block/key  -  */ 

static  int  sixbits (struct  ks  k,  int  s) 

{ 

int  op  =  0; 

int  n  =  (8-s) ; 

int  i; 

for  (i  =  0;  i  <  2;  i++)  { 

int  off  =  ex6[n] [i] [0] ; 
unsigned  char  c  =  k.ki[off]; 
c  »=  ex6  [n]  [i]  [1] ; 
c  «=  ex6  [nj  [i]  [2] ; 
c  &=  ex6[n] [i] [3] ; 
op  ! =  c ; 

) 

return  op; 


/* - DES  Key  Schedule  (KS)  function - */ 

struct  ks  KS(int  n,  char  *key) 

{ 

static  unsigned  char  cd[8]; 

static  int  its  [ ]  =  [1, 1,2, 2, 2, 2, 2, 2, 1,2, 2, 2, 2,2, 2,1}; 
union  { 

struct  ks  kn; 
struct  LR  filler; 

)  result; 

if  (n  ==  0) 

permute ( (long  *)cd,  (long  *)  key,  (long  *)PCltbl,  64); 

rotate (cd,  its[n]); 
rotate (cd+4,  its[n]); 

permute (^result . filler . L,  (long  *)cd,  (long  *)PC2tbl,  48); 
return  result. kn; 


/*  -  rotate  a  4-byte  string  n  positions  to  the  left  -  */ 

static  void  rotate (unsigned  char  *c,  int  n) 

( 

int  i; 

unsigned  j,  k; 
k  =  *c  »  (8  -  n) ; 
for  (i  =  3;  i  >=  0;  — i)  { 

j  =  ( * (c+i )  «  n)  +  k; 
k  =  j  »  8; 

* (c+i)  =  j; 

} 


End  Listing  Five 


); 

/* - permutation  table  P  for  f  function - */ 

unsigned  char  Ptbl[]  =  { 

P  (16) ,  p  (  7),p(20),p(21),p(29),p(12),p(28),p(17), 
p(  1) , p ( 15 )  ,p(23) , p ( 2 6)  ,p(  5)  ,p (18) , p (31) , p (10) , 
p(  2) ,  p  (  8),p(24),p(14),p(32),p(27),p(  3),p(  9), 

P (19) , p (13) , p (30) , p  (  6) , p (22) , p (11) ,  p  (  4) , p (25) 

}; 

/*  —  table  for  converting  six-bit  to  four-bit  stream  —  */ 
unsigned  char  stbl [8] [4] [16]  =  ( 

/* - sl - */ 

14,4,13,1,2,15,11,8,3,10,6,12,5,9,0,7, 

0,15,7,4,14,2,13,1,10,6,12,11,9,5,3,8, 

4,1,14,8,13,6,2,11,15,12,9,7,3,10,5,0, 

15,12,8,2,4,9,1,7,5,11,3,14,10,0,6,13, 

/* - s2 -  */ 

15,1,8,14,6,11,3,4,9,7,2,13,12,0,5,10, 

3,13,4,7,15,2,8, 14,12,0,1,10,6, 9,11,5, 
0,14,7,11,10,4,13,1,5,8,12,6,9,3,2,15, 

13,8,10, 1,3,15,4,2,11,6,7,12,0,5,14,  9, 

/* - s3 - */ 

10,0,9,14,6,3,15,5,1,13,12,7,11,4,2,8, 

13,7,0,9,3,4,6,10,2,8,5,14,12,11,15,1, 

13,6,4,9,8,15,3,0,11,1,2,12,5,10,14,7, 

I, 10,13,0,6,9,8,7,4,15,14,3,11,5,2,12, 

/* - S4 -  */ 

7,13,14,3,0,6,9, 10,1,2,8,5,11,12,4,15, 
13,8,11,5,6,15,0,3,4,7,2,12,1,10,14,9, 
10,6,9,0,12,11,7,13,15,1,3,14,5,2,8,4, 
3,15,0,6,10,1,13,8,9,4,5,11,12,7,2,14, 

/* - s5 - */ 

2,12,4,1,7,10,11,6,8,5,3,15,13,0,14,  9, 
14,11,2,12,4,7,13,1,5,0,15,10,3,9,8,6, 
4,2,1,11,10,13,7,8,15,9,12,5,6,3,0,14, 

II, 8,12,7,1,14,2,13,6,15,0,9,10,4,5,3, 

/* - s6 - */ 

12,1,10,15,9,2,6,8,0,13,3,4,14,7,5,11, 
10,15,4,2,7,12,9,5,6,1,13,14,0,11,3,8, 
9,14,15,5,2,8,12,3,7,0,4,10,1,13,11,6, 
4,3,2,12,9,5,15,10,11,14, 1,7,6,0,8,13, 

/* - s7 -  */ 

4,11,2,14,15,0,8,13,3,12,9,7,5,10,6,1, 

13,0,11,7,4,9,1,10,14,3,5,12,2,15,8,6, 

1,4,11,13,12,3,7,14,10,15,6,8,0,5,9,2, 

6,11,13,8,1,4,10,7,9,5,0,15,14,2,3,12, 

/* - s8  -  */ 

13,2,8,4,6,15,11,1,10,9,3,14,5,0,12,7, 

1,15,13,8,10,3,7,4,12,5,6,11,0,14,9,2, 

7,11,4,1,9,12,14,2,0,6,10,13,15,3,5,8, 

2,1,14,7,4,10,8,13,15,12,9,0,3,5,6,11 

}; 

/*  -  Permuted  Choice  1  for  Key  Schedule  calculation  -  */ 

unsigned  char  PCltblf]  =  j 

p(57),p(49),p(41),p(33),p(25),p(17),p(  9) ,  p  (  0), 
p(  l),p(58),p(50),p(42),p(34),p(26),p(18),p(  0), 
p  (10) ,  p  (  2),p(59),p(51),p(43),p(35),p(27),p(  0), 
p(19) ,  p  ( 1 1 )  ,p(  3) ,  p  ( 60 ) ,  p  ( 52 ) ,  p  ( 4  4 )  ,p(36)  ,p(  0), 
p(63),p(55),p(47),p(39),p(31),p(23),p(15),p(  0), 
p(  7),p(62),p(54),p(46),p(38),p(30),p(22),p(  0), 
p(14)  ,p{  6),p(61),p(53),p(45),p(37),p(29),p(  0), 
p  (21) ,  p  (13) ,  p  (  5),p(28),p(20),p(12),p(  4),p(  0) 

); 


Listing  Six 

/*  - tables. c - *7 

/* 

*  tables  for  the  DES  algorithm 
*/ 

♦include  "des.h" 


/*  -  Permuted  Choice  2  for  Key  Schedule  calculation  -  */ 

unsigned  char  PC2tbl[]  =  [ 

p(14),p(17),p(ll),p(24),p(  l),p(  5) ,  p  (  3) ,  p  (28) , 

P  (15) ,  p  (  6),p(21),p(10),p(23),p(19),p(12),p(  4), 

P  (26) ,  p  (  8)  ,p(16)  ,p(  7)  ,p(27)  ,p(20)  ,p(13)  ,p(  2), 
p(41),p(52),p(31),p(37),p(47),p(55),p(30),p(40), 
p(51),p(45),p(33),p(48),p(44),p(49),p(39),p(56), 
p(34),p(53),p(46),p(42),p(50),p(36),p(29),p(32) 

); 


/* - permutation  masks - */ 

unsigned  char  Pmaskf]  =  { 

p(  l),p(  2) , p (  3) , p (  4) ,p (  5) ,p (  6) , p (  7) , p (  8), 
p(  9),p(10),p(ll),p(12),p(13),p(14),p(15),p(16), 
p(17),p(18),p(19),p(20),p(21),p(22),p(23),p(24), 
p  (25) ,  p  (26) ,  p  (27)  ,p(28),p(29),p(30),p(31),p(32), 
p(33),p(34),p(35),p(36),p(37),p(38),p(39),p(40), 
p(41),p(42),p(43),p(44),p(45),p(46),p(47),p(48), 
p(49),p(50),p(51),p(52),p(53),p(54),p(55),p(56), 
p(57),p(58),p(59),p(60),p(61),p(62),p(63),p(64) 

); 


/*  -  initial  and  inverse-initial  permutation  table 

unsigned  char  IPtbl[]  =  ( 

P(58),p(50),p(42),p(34),p(26),p(18),p(10),p(  2), 

P (60) ,p (52) ,p (44) ,p (36) , p (28) ,p(20) ,p (12) ,p (  4), 
p(62),p(54),p(46),p(38),p(30),p(22),p(14),p(  6), 
p(64),p(56),p(48),p(40),p(32),p(24),p(16),p(  8), 
p(57),p(49)  ,p(41),p(33),p(25),p(17),p(  9),p(  1), 
P(59),p(51),p(43),p(35),p(27),p(19),p(ll),p(  3), 
p(61),p(53),p(45),p(37),p(29),p(21),p(13),p(  5), 
p(63),p(55),p(47),p(39),p(31),p(23),p(15),p(  7) 


/*  -  For  extracting  6-bit  strings  from  64-bit  string  -  */ 

unsigned  char  ex6 [8] [2] [4]  =  ( 

/*  byte,  »,  «,  &  */ 

/*  - —  s  =  8  - V 


0,2,0, 0x3f , 

0,2,0, 0x3f , 

/*  ____  s  =  7  - */ 

0,0,4,0x30, 

1,4,0, OxOf , 

/* - s  =  6  - */ 

1,0,2, 0x3c, 

2,6,0,0x03, 


2,0,0, 0x3f , 

2,0,0, 0x3f , 

/* - s  =  4 - */ 

3,2,0, 0x3f , 

3,2,0, 0x3f , 

/* - s  =  3 - */ 

3,0,4,0x30, 

4,4,0, OxOf , 


/* - permutation  table  E  for  f  function - */ 

unsigned  char  Etbl[]  =  { 

p (32) ,p (  l),p(  2) , p (  3) ,p(  4) , p (  5), 
p(  4)  ,p  (  5)  ,p  (  6) ,  p  (  7) ,  p  (  8)  ,p  (  9), 
p(  8) ,p (  9),p(10),p(ll),p(12),p(13), 
p(12),p(13),p(14),p(15),p(16),p(17), 
p(16),p(17),p(18),p(19),p(20),p(21), 
p(20),p(21),p(22),p(23),p(24),p(25), 
p(24),p(25),p(26),p(27),p(28),p(29), 
P(28),p(29),p(30),p(31),p(32),p(  1) 


/* - s  = 

5,0,0, 0x3f , 
5,0,0, 0x3f 


End  listings 
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Ray  Tracing 


Rendering  3-D  solid  objects  is  easier  than  you  think 


Daniel  Lyke 


I  have  always  been  fascinated  by 
computer  rendered  three-dimen¬ 
sional  (3-D)  images,  especially 
those  that  strive  for  realism.  Vari¬ 
ous  approaches  exist  for  drawing 
3-D  images,  ranging  from  algorithms 
for  wire -frame  drawings,  where  all  ob¬ 
jects  can  be  seen  through,  and  only  the 
edges  are  shown,  to  techniques  that 
create  solid  opaque  objects,  mirrored 
surfaces,  shading  for  light  sources,  and 
shadows. 

Of  all  the  methods  to  render  solids, 
ray  tracing  is  probably  the  easiest  to 
understand.  Basically,  you  take  a  straight 
line  (ray),  drawn  from  your  eye  through 
a  pixel  on  the  screen,  and  see  what 
objects  it  hits  in  the  computer  universe. 
You  then  find  whichever  object  is  clos¬ 
est  to  the  origin  of  that  line  (your  eye), 
and  color  the  pixel  on  the  screen  the 
color  of  the  object.  If  that  object  re¬ 
flects  or  refracts,  you  just  need  to  com¬ 
pute  the  new  direction  of  the  line  and 
repeat  the  process  from  the  new  origin. 
Pretty  simple,  really.  The  hard  part  is 
representing  the  universe. 

The  Universe 

Starting  at  the  lowest  level,  a  ray  has 
an  origin  and  a  direction  vector.  The 
origin  is  a  point  in  three-dimensional 
Cartesian  space  (x,y,z),  and  the  direc¬ 
tion  is  a  change  in  each  of  the  three 
axes.  For  the  purposes  of  finding  how 
far  it  is  to  an  object,  we’ll  multiply  the 
vector  by  a  “time”  or  distance. 

For  the  purposes  of  this  article,  the 


Daniel  is  a  programmer  for  Signal  Data 
and  he  can  be  contacted  at 54 75 Hixson 
Pike,  Suite  1-202,  Hixson,  TN 37343- 


objects  I  use  are  a  sphere  and  a  plane. 
The  sphere  is  easy:  It  merely  has  an 
origin  and  a  radius;  although  for  sim¬ 
pler  calculations  the  radius  can  be  stored 
as  the  radius  squared.  The  plane  is  a 
little  more  complicated. 

Rather  than  express  a  plane  as  its 
equation  in  3-D  space  (something  such 
as  “ax  +  by  +  cz  =  d”),  I’ll  represent  it 
as  a  vector  normal  (perpendicular)  to 
the  plane  (which  really  means  taking 
the  “a,”  “b,”  and  “c”  constants  in  the 
expression  above  and  using  them  as 
directions)  and  a  point  on  the  plane. 

Before  going  further,  I  should  men¬ 
tion  that  in  the  context  of  this  article, 
the  “  ■  ”  operator  (not  to  be  confused 


with  which  is  the  structure  element 
selection  operator  in  C)  means  multi¬ 
ply  the  individual  components  of  the 
specified  vector  together  and  sum  them 
(for  example,  rayl  •  ray2  results  in 
ray  lx  *  ray2x  +  rayl.y  *  ray2.y  + 
rayl.z  *  ray2.z ).  Where  it  applies  to 
items  with  multiple  components,  multi¬ 
plication  by  scalars  means  that  you  mul¬ 
tiply  every  component  of  the  item  by 
that  scalar. 

Finding  the  Intersection  of  a  Ray 
and  a  Sphere 

The  sphere,  in  its  simplest  form,  is 
expressed  as  the  equation  x2  +  y2  +  z2 
=  r2.  This  is  why  we  store  the  radius 


Figure  1:  Ray  tracing  in  action 
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as  the  radius  squared.  If  we  offset  the 
ray’s  origin  by  the  center  of  the  sphere 
and  use  “time”  to  express  where  along 
the  direction  vector  the  ray  intersects 
the  sphere,  we  end  up  with  this: 

( time  ■  ray_direction  -  ray_origin)2 
=  sphere_radius  2 

which,  when  expanded,  leads  to: 

a  time  2  +  b  time  +  c  =  0 

where: 

a  =  ray_direction  ■  ray_direction 

b  =  2(ray_origin  -  sphere_origin) 

■  ray_  direction 

c  =  (ray_origin  -  sphere_origin)  ■ 

( ray_origin  -sphere_origin) 

-sphere_radius  2 

Delving  into  my  old  math  textbooks, 

I  come  up  with  the  equations  for  solv¬ 
ing  such  a  quadratic: 

V  B2  -  4  ac 

time  =  -b  ±  - 

2  a 

We  get  two  results  because  the  ray 
can  intersect  the  sphere  at  two  points, 
when  it  enters  the  sphere  and  when  it 
leaves  it.  There’s  a  third  possibility, 
which  is  that  the  argument  to  the  square 
root  is  negative,  in  which  case  the  ray 
never  intersects  the  sphere  at  all.  The 
function  that  does  all  of  this  returns  the 
shortest  positive  time  to  intersection, 
or  a  negative  number  if  the  ray  never 
intersects  the  sphere. 

To  find  the  intersection  of  a  ray  with 
a  plane,  follow  this  procedure: 

a  =  plane_point  ■  plane_normal 
b  =  plane_normal  •  ray_origin 
c  =  ray_direction  ■  plane_normal 

a-  b 

time  =  - 

c 

Now  we  have  the  means  to  draw  all 
of  our  objects.  We  merely  take  a  ray 
through  a  screen  pixel,  find  the  time 
to  intersect  with  all  of  our  objects,  take 
the  color  of  the  object  that  intersects 
in  the  shortest  time,  and  color  the  pixel 
the  color  of  that  object.  Life  is  nice  in  a 
non-reflecting  universe.  Unfortunately, 
interesting  pictures  aren’t  so  easy.  To 
do  things  like  putting  patterns  on  sur¬ 
faces  (such  as  the  plane)  or  finding 
where  to  reflect  objects  that  aren’t  flat 
(such  as  the  sphere),  you  need  to  find 
the  x,  y,  and  z  coordinates  of  the  point 
of  intersection  by  multiplying  the  di¬ 
rection  of  the  ray  by  the  time,  and  add 
it  to  the  origin  of  the  ray.  To  find  the  x 
coordinate  use  the  equation: 


x_intersect  =  ray_origin_x  + 

ray_direction_x  (time). 
Repeat  the  sequence  for  the  y  and  z 
coordinates,  respectively. 

Reflections 

To  determine  reflection,  use  an  inci¬ 
dent  vector  (the  one  that  I’m  trying  to 
reflect)  and  the  normal  vector  (the  one 
perpendicular  to  the  surface  that  we’re 
reflecting  from).  You  can  split  the  inci¬ 
dent  vector  into  two  component  vec¬ 
tors,  the  sum  of  which  is  the  incident 
vector. 

The  basic  ray  tracing 
technique  has  many 
applications,  including 
video  special  effects  and 
examination  of  archi¬ 
tectural  lighting 
problems 


If  one  of  these  components  is  the 
normal  vector,  the  other  is  the  compo¬ 
nent  of  the  vector  perpendicular  to  the 
normal  vector.  So  if  you  subtract  this 
perpendicular  vector  from  the  normal 
vector,  you  end  up  with  the  reflected 
vector.  The  perpendicular  vector  is 
shown  in  Example  1 . 

If  you  subtract  this  vector  perpen¬ 
dicular  to  the  normal  vector  from  the 
incident  vector  we  get  the  normal  vec¬ 
tor  and  we  can  subtract  two  times  the 
reflected  vector  from  the  incident  vec¬ 
tor  to  get  the  reflected  vector,  shown 
in  Example  2. 

About  the  Program 

The  program  presented  here  compiles 
and  runs  with  Zortech  C++  2.x  and 
Flash  Graphics  on  an  EGA  in  640  x  350 
mode.  I’ve  hardcoded  it  for  a  specific 
mode  so  that  the  screen  sizes  could  be 
constants  (and  thereby  nursed  a  few 
extra  clock  cycles  from  the  system)  and 
so  that  I  could  make  the  colors  on  the 
sphere  darker  versions  of  the  reflected 
colors.  Listing  One  (page  158)  is  the 
header  file  RAYTRACE.HPP  and  Listing 
Two  (page  158)  is  the  C++  source.  Addi¬ 
tionally,  Listing  Three  (page  159)  lists 
a  C  version  of  the  program. 

My  first  version  ran  on  a  CGA  in 
four-color  mode,  so  it  should  be  rela¬ 
tively  easy  to  port  this  to  anything  else. 
The  machine-specific  parts  are  in  main( ) 
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and  plot(),  with  some  color-specific 
information  in  PlanePattern( )  and  the 
defines  WIDTH  and  HEIGHT  being  the 
screen  width  and  height.  Figure  1  illus¬ 
trates  the  output  of  the  program. 

For  ease  of  programming,  I’ve  put 
the  eye  at  the  origin  (0,0,0).  The  screen 
is  one  unit  in  front  of  the  eye:  The  delta 


Example  1:  Perpendicular  vector 


Example  2:  Reflected  vector 


(change)  in  the  z  component  of  the 
vector  is  1.  From  there,  calculate  the 
position  of  each  pixel  relative  to  the 
center  of  the  screen  and  put  that  into 
the  x  and  y  components  of  the  vector. 

trace( )  follows  a  ray  through  a  pixel 
on  the  screen  (the  parameter)  until  it 
hits  something,  in  this  case  through 


SPHERE: :Intersect(  )  and  PLANE: -.Inter¬ 
sect.  ).  Then  it  just  checks  the  sphere 
and  the  plane  to  see  which  one  has  the 
shortest  time  to  intersection.  If  both  of 
the  times  are  negative,  the  ray  goes  off 
into  black  sky  and  trace( )  returns  0. 

If  we  hit  the  plane,  we  need  to  find 
out  where,  and  draw  some  sort  of  tiling 
pattern  so  that  the  sphere  has  something 
interesting  to  reflect.  PLANE: :Pattem(  ) 
takes  a  ray  and  a  time  to  intersection 
and  returns  the  appropriate  color. 

Of  all  the  methods  to 
render  solids,  ray 
tracing  is  probably  the 
easiest  to  understand 


incident 

.  normal 

perpendicular  vector  =  - 

-  normal 

normal  . 

normal 

incident 

.  normal 

normal  . 

normal 

normal 

If  the  ray  hits  the  sphere,  we  need 
to  find  the  point  of  intersection  with 
the  sphere  and  create  a  ray  with  that 
as  an  origin,  which  is  reflected  about 
the  normal  line  from  the  center  of  the 
sphere  through  that  point  of  intersec¬ 
tion.  This  is  all  done  in  SPHERE:: Re¬ 
flect  ).  If  the  ray  then  hits  the  plane, 
PLANE::  PatternC )  colors  the  spot  ap¬ 
propriately.  If  the  reflected  ray  does 
not  hit  the  plane,  then  the  spot  is  col¬ 
ored  blue  so  that  we  can  distinguish  it 
from  the  black  of  the  background. 

Note  that  we  call  it  with  a  trailing  0 
PLANE:: PatternC)  here  so  that  these 
points  are  darker  than  the  others. 

Possible  Enhancements 

Before  you  get  into  the  heavy  work  of 
new  algorithms,  some  possibilities  for 
enhancement  exist.  You  could  make 
the  program  draw  the  screen  in  low 
resolution,  working  upward  fairly  eas¬ 
ily,  so  that  the  form  of  the  image  is 
apparent  after  a  few  of  the  points,  and 
you  can  tell  if  the  objects  you’re  look¬ 
ing  for  actually  show  up  in  your  view¬ 
port  without  rendering  the  entire  im¬ 
ages.  Or  add  another  pattern  to  the 
plane  or  another  sphere  (to  make  things 
simple,  non-reflective). 

You  could  also  calculate  several  im¬ 
ages,  save  them  on  a  fast  disk  or  in 
memory,  and  flash  them  quickly  to  the 
screen  for  animation.  There’s  still  quite 
a  bit  of  precision  loss  at  the  far  ends  of 
the  rays  and  reflections.  I’ve  got  a  cou¬ 
ple  of  ideas  on  ways  to  solve  this  but  I 
want  to  play  with  the  theory  a  bit  first. 
Also,  there  are  several  places  where  cal¬ 
culations  could  be  optimized  (and  quite 
a  few  places  where  they  can  be  done 
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(continued  from  page  154) 
in  parallel,  given  the  right  hardware). 

Several  additions  suggest  themselves 
immediately,  none  terribly  complex. 
Most  notable  are  bounded  planes,  light 
sources  (for  shadowing  and  shading), 
and  refraction.  Refraction  is  one  of  the 
easiest,  just  a  modification  of  the  re¬ 
flection  routine.  Consult  any  physics 
textbook  for  the  equations. 

Light  sources  are  also  straightforward. 
Start  by  defining  a  point  as  a  light  source, 
and  at  each  intersection  to  be  displayed, 
trace  a  ray  to  the  light  source.  If  the  ray 
hits  nothing  color  the  pixel  as  lighted, 
otherwise  it’s  dark.  Using  angles  rela¬ 
tive  to  the  incident  ray,  glossy  (but 
nonreflective)  surfaces  can  be  handled 
with  displays  that  have  enough  color 
to  give  the  subtleties  of  shading.  The 
only  problem  with  this  method  is  that 
it  doesn’t  allow  for  the  diffraction  of 
light  around  the  edges  of  objects  (soft 
edged  shadows  have  got  to  be  faked) 
and  prisms,  lenses,  and  focusing  mir¬ 
rors  don’t  work  on  the  light. 

To  do  more  serious  modeling,  the 
algorithms  here  need  to  be  expanded 
to  work  with  bounded  planes,  so  that 
more  complex  shapes  are  possible.  One 
way  to  do  this  is  to  bound  each  plane 
as  a  convex  shape  with  other  planes. 
I’m  still  playing  with  ideas  for  clean 
data  structures  for  all  of  this. 

The  basic  ray  tracing  technique  has 
many  applications,  including  video  spe¬ 
cial  effects  and  examination  of  archi¬ 
tectural  lighting  problems  —  special 
effects  to  commercials  to  architects  figur¬ 
ing  lighting  problems.  I’d  love  to  see 
what  others  are  coming  up  with  and 
welcome  your  comments. 

Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
online.  To  order  the  disk,  send  $14.95 
(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  M&T’s  Telepath  on-line  ser¬ 
vice  (via  TYMNET)  and  through  the  DDJ 
Forum  on  CompuServe  (type  GO  DDJ). 


DDJ 

(Listings  begin  on  page  158.) 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  8. 
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Listing  One  (Text  begins  on  page  152.) 

/*  RAYTRACE .  HPP  */ 
class  RAY 
{ 

double  dx,  dy,  dz;  /*  Direction  vector  */ 
double  ox,  oy,  oz;  /*  Origin  */ 
public: 

RAY (double  x,  double  y,  double  z,  double  vx,  double  vy,  double  vz); 
friend  class  PLANE; 
friend  class  SPHERE; 

}; 

class  PLANE 
( 

double  nx,  ny,  nz;  /*  Vector  normal  (perpendicular)  to  plane  */ 

double  px,  py,  pz;  /*  Point  on  plane  */ 

public: 

PLANE (double  x,  double  y,  double  z,  double  vx,  double  vy,  double  vz); 
double  Intersect (RAY  ray); 

int  Pattern(RAY  ray,  double  time,  int  light); 

}; 

class  SPHERE 
( 

double  cx,  cy,  cz;  /*  Center  of  sphere  */ 
double  r2;  /*  Radius  squared  */ 
public: 

double  Intersect (RAY  ray) ; 

Reflect (RAY  iray, double  time,  RAY  firray); 

SPHERE (double  x,  double  y,  double  z,  double  r) ; 

}; 

class  VECTOR 
{ 

public: 

double  dx,  dy,  dz;  /*  Three  dimensional  vector  */ 

); 

End  Listing  One 


Listing  Two 

/*  RAYTRACE. CPP  */ 

((include  <fg.h> 

♦include  <math.h> 

♦include  <stdio.h> 

♦include  <conio.h> 

♦include  "raytrace.hpp" 

♦define  WIDTH  640 
♦define  HEIGHT  350 

inline  void  plot (int  x,int  y,int  c) 

( 

fg_drawdot (c,  FG_MODE_SET, ~0,x,  y) ; 


int  PlanePattern (unsigned  int  x,  unsigned  int  y,  int  light) 

( 

/*  Put  code  for  different  plane  patterns  in  here  */ 

//  return  ( (x  +  y)  %  8)  +  8  *  light; 

//  return  (x  %  8)  A  (y  %  8)  +  8  *  light; 

return  ((x*x+y*y)  %  8)  +8*  light; 

)  /* - End:  PlanePattern ()  - */ 

RAY: : RAY (double  x,  double  y,  double  z,  double  vx,  double  vy,  double  vz) 

( 

this->ox  =  x; 
this->oy  =  y; 
this->oz  =  z; 
this->dx  =  vx; 
this->dy  =  vy; 
this->dz  =  vz; 

)  /* - End:  RAY :  : RAY  ( )  - */ 

SPHERE: : SPHERE (double  x,  double  y,  double  z,  double  r) 

{ 

this->cx  =  x; 
this->cy  =  y; 
this->cz  =  z; 
this->r2  =  r  *  r; 

)  /* - End.  SPHERE: : SPHERE - */ 

double  SPHERE: : Intersect (RAY  ray) 

{ 

double  a,  b,  c,  tl,  t2,  t3,  close,  farther; 
a  =  ray.dx  *  ray.dx  +  ray.dy  *  ray.dy  +  ray.dz  *  ray.dz; 
close  =  farther  =  -1.0; 
if  (a) 

{ 

b  =  2.0  *  ((ray. ox  -  this->cx)  *  ray.dx 
+  (ray.oy  -  this->cy)  *  ray.dy 
+  (ray.oz  -  this->cz)  *  ray.dz); 
c  =  (ray. ox  -  this->cx)  *  (ray. ox  -  this->cx) 

.  +  (ray.oy  -  this->cy)  *  (ray.oy  -  this->cy) 

+  (ray.oz  -  this->cz)  *  (ray.oz  -  this->cz)  -  this->r2; 
tl  =  b  *  b  -  4.0  *  a  *  c; 
if  (tl  >  0) 

{ 

t2  =  sqrt (tl) ; 

t3  =  2.0  *  a; 

close  =  -(b  +  t2)  /  t3; 

farther  =  -(b  -  t2)  /  t3; 

} 

} 

return  (double) ( (close  <  farther)  ?  close  :  farther); 
j  /* -  End:  SPHERE: : Intersect ()  - */ 

SPHERE: : Reflect (RAY  iray,  double  time,  RAY  Srray) 

{ 


VECTOR  normal;  /*  Used  for  readability  */ 
double  ndotn;  /*  Used  for  readability  */ 
double  idotn;  /*  Used  for  readability  */ 
double  idotn_div_ndotn_x2;  /*  Used  for  optimization  */ 

rray.ox  =  iray.dx  *  time  +  iray. ox;  /*  Find  the  point  of  */ 
rray.oy  =  iray.dy  *  time  +  iray.oy;  /*  intersection  between  */ 
rray.oz  =  iray.dz  *  time  +  iray.oz;  /*  iray  and  sphere.  */ 

normal. dx  =  rray.ox  -  this->cx;  /*  Find  the  ray  normal  */ 
normal. dy  =  rray.oy  -  this->cy;  /*  to  the  sphere  at  the  */ 
normal. dz  =  rray.oz  -  this->cz;  /*  intersection^  */ 


ndotn  =  ( norma l.dx  *  normal. dx  + 
normal. dy  *  normal. dy  + 
normal. dz  *  normal. dz); 
idotn  =  (normal. dx  *  iray.dx  + 
normal. dy  *  iray.dy  + 
normal. dz  *  iray.dz); 

idotn_div_ndotn_x2  =  (2.0  *  (idotn)  /  ndotn); 

rray.dx  =  iray.dx  -  idotn_div_ndotn_x2  *  normal. dx; 
rray.dy  =  iray.dy  -  idotn_div_ndotn_x2  *  normal. dy; 
rray.dz  =  iray.dz  -  idotn_div_ndotn_x2  *  normal. dz; 

)  /* -  End:  SPHERE: : Reflect ()  - */ 

PLANE: : PLANE (double  x,  double  y,  double  z,  double  vx,  double  vy,  double  vz) 

{ 

this->nx  =  vx; 
this->ny  =  vy; 
this->nz  =  vz; 

this->px  =  x; 
this->py  =  y; 
this->pz  =  z; 

}  /* - End:  PLANE:  : PLANE  () - */ 

int  PLANE: : Pattern (RAY  ray,  double  time,  int  light) 

{ 

PlanePattern ( (unsigned) (time  *  ray.dz  +  ray.oz), 

(unsigned) (time  *  ray.dx  +  ray. ox) , light) ; 
j  /* - End:  PLANE: : Pattern - */ 

double  PLANE: : Intersect (RAY  ray) 

{ 

double  pi,  p2,  p3; 

pi  =  this->px  *  this->ny  +  this->py  *  this->ny  +  this->pz  *  this->nz; 

p2  =  ray. ox  *  this->nx  +  ray.oy  *  this->ny  +  ray.oz  *  this->nz; 

p3  =  ray.dx  *  this->nx  +  ray.dy  *  this->ny  +  ray.dz  *  this->nz; 

return  (double) ( (pl-p2) /p3) ; 

)  /* -  End:  PLANE: : Intersect ()  - */ 

int  trace (double  x,  double  y) 

{ 

static  PLANE  plane(-8.0,  0.0,  0.0,  0.0,  1.0,  0.001); 

static  SPHERE  sphere (  0.0,  0.0,  5.0,  1.0  ); 

RAY  ray(0.0,0.0,0.0, (X  -  (double) WIDTH  /  2.0)  *.75, 
y  -  (double) HEIGHT  /  2. 0, HEIGHT); 
double  timel,  time2,; 
timel  =  sphere. Intersect (ray) ; 
time2  =  plane. Intersect (ray) ; 

if (timel  >  0.0  &&  (time2  <  0.0  !!  time2  >  timel))  /*  Circle  in  fore  */ 

{ 

sphere. Reflect (ray, timel, ray) ; 
time2  =  plane. Intersect (ray) ; 
if(time2  >  0.0) 

{ 

return  plane . Pattern (ray, time2, 0) ; 


{ 

return  1; 

) 

) 

else  if (time2  >  0.0) 

( 

return  plane. Pattern (ray, time2, 1) ; 

) 

return  0; 

j  /* - End:  trace ()  - */ 

draw  () 

{ 

int  x,y; 

for (x  =  0;  x  <  WIDTH  &&  ! kbhit () ;  x  ++) 

{ 

for (y  =  0;  y  <  HEIGHT;  y  ++) 

{ 

plot (x, y, trace ( (double) x, (double) y) ) ; 
) 

1 

)  /* - End:  draw ( )  - */ 

main ( ) 

{ 

fg_init_egaecd ( )  ; 
draw()  ; 
getch () ; 
fg_term() ; 


End  Listing  Two 
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Listing  Three 


#include  <fg.h> 
tinclude  <raath.h> 
tinclude  <dos.h> 

tdefine  WIDTH  640 
#define  HEIGHT  350 
#define  QUIT_OUT  ( ! kbhit ( ) ) 

plot (x,y, c) 
int  x,y,c; 

( 

fg_drawdot (c, FG_MODE_SET, "0,  x, HEIGHT  -  y) ; 

} 

typedef  struct  S_RAY 

{ 

double  dx,  dy,  dz;  /*  Direction  vector  */ 
double  ox,  oy,  oz;  /*  Origin  */ 

}  RAY; 


typedef  struct  S_PLANE 

{ 

double  nx,  ny,  nz;  /*  Vector  normal  (perpendicular)  to  plane  */ 
double  px,  py,  pz;  /*  Point  on  plane  */ 

)  PLANE; 


typedef  struct  S_SPHERE 

{ 

double  cx,  cy,  cz;  /*  Center  of  sphere  */ 
double  r2;  /*  Radius  squared  */ 

)  SPHERE; 


typedef  struct  S_VECTOR 

{ 

double  dx,  dy,  dz;  /*  Three  dimensional  vector  */ 
)  VECTOR; 


double  sphere_intersect (RAY,  SPHERE); 
double  plane_intersect (RAY,  PLANE); 
void  ref lect (VECTOR  *,  VECTOR  *,  VECTOR  *) ; 
double  sphere_intersect (RAY  ray,  SPHERE  sphere) 

( 

double  a,  b,  c,  tl,  t2,  t3,  close,  farther; 
a  =  ray.dx  *  ray.dx  +  ray.dy  *  ray.dy  +  ray.dz  *  ray.dz; 
close  =  farther  =  -1.0; 
if  (a) 


b  =  2.0  *  ((ray. ox  -  sphere. cx)  *  ray.dx 
+  (ray.oy  -  sphere. cy)  *  ray.dy 

+  (ray.oz  -  sphere.cz)  *  ray.dz); 

c  =  (ray. ox  -  sphere. cx)  *  (ray. ox  -  sphere. cx) 

+  (ray.oy  -  sphere. cy)  *  (ray.oy  -  sphere. cy) 

+  (ray.oz  -  sphere.cz)  *  (ray.oz  -  sphere.cz) 

tl  =  b  *  b  -  4.0  *  a  *  c; 
if (tl  >  0) 

{ 

t2  =  sqrt(tl); 


t3  =  2.0  *  a; 
close  =  - (b  +  t2)  /  t3; 
farther  =  - (b  -  t2 )  /  t3; 
} 


} 

return  (double) ( (close  <  farther)  ?  close  :  farther); 
j  /* - End:  sphere_intersect  () - */ 


sphere. r2; 


double  plane_intersect (RAY  ray,  PLANE  plane) 

{ 

double  pi,  p2,  p3; 

pi  =  plane. px  *  plane. ny  +  plane. py  *  plane. ny  +  plane. pz  *  plane. nz; 
p2  =  ray. ox  *  plane. nx  +  ray.oy  *  plane. ny  +  ray.oz  *  plane. nz; 
p3  =  ray.dx  *  plane. nx  +  ray.dy  *  plane. ny  +  ray.dz  *  plane. nz; 
return  (double) ( (pl-p2) /p3) ; 

}  /* -  End:  plane_intersect ()  - */ 


void  ref lect (VECTOR  ‘normal,  VECTOR  ‘incident,  VECTOR  *r) 
< 


double  ndotn,  idotn; 

ndotn  =  (normal->dx  ‘  normal->dx  + 

normal->dy  *  normal->dy  + 
normal->dz  *  normal->dz); 
idotn  =  (normal->dx  *  incident->dx  + 

normal->dy  *  incident->dy  + 
normal->dz  *  incident->dz) ; 

r->dx  =  incident->dx  -  (2.0  *  (idotn)  /  ndotn)  *  normal->dx; 

r->dy  =  incident->dy  -  (2.0  *  (idotn)  /  ndotn)  *  normal->dy; 

r->dz  =  incident->dz  -  (2.0  *  (idotn)  /  ndotn)  *  normal->dz; 

}  /* - End:  reflect  () - */ 


int  plane_pattern (int  x,  int  y,  int  light) 

( 

return  ( (x  +  16384)  %  8)  A  ( (y  +  16384)  %  8)  +  8  *  light; 

}  /* - End:  plane_pattern ()  - */ 

int  trace (int  x,  int  y) 

{ 

static  PLANE  plane  =  (  0.0,  1.0,  0.001,  -8.0,  0.0,  0.0); 
static  SPHERE  sphere  =  {  0.0,  0.0,  5.0,  9.0  }; 

VECTOR  vl,  v2,  v3; 

RAY  ray; 

double  tl,  t2,  time; 

ray. ox  =  0.0;  /*  Set  the  ray  origin  to  the  eye  */ 

ray.oy  =  0.0; 
ray.oz  =  0.0; 

ray.dz  =  1.0;  /*  Set  the  direction  through  the  pixel  */ 

ray.dy  =  -( (double) y  -  (double) HEIGHT  /  2.0)  /  100; 
ray.dx  =  ( (double) x  -  (double) WIDTH  /  2.0)  /  120; 


tl  =  sphere_intersect (ray, sphere) ; 
t2  =  plane_intersect (ray,  plane) ; 

if (tl  >  0.0  &&  (t2  <0.0  ::  t2  >  tl))  /*  Circle  in  fore  */ 

{ 

vl.dx  =  ray.dx;  vl.dy  =  ray.dy;  vl.dz  =  ray.dz; 

v2.dx  =  ((ray.dx  *  tl  +  ray. ox)  -  sphere. cx); 

v2.dy  =  ((ray.dy  *  tl  +  ray.oy)  -  sphere. cy); 

v2.dz  =  ((ray.dz  *  tl  +  ray.oz)  -  sphere.cz); 

reflect (&v2, &vl,  &v3) ; 

ray. ox  +=  ray.dx  *  tl;  ray.oy  +=  ray.dy  *  tl;  ray.oz  +=  ray.dz  *  tl; 
ray.dx  =  v3.dx;  ray.dy  =  v3.dy;  ray.dz  =  v3.dz; 
t2  =  plane_intersect (ray, plane) ; 
if (t2  >  0.0) 

{ 

return  plane_pattern ( (int) (t2  *  ray.dz  +  ray.oz) , (int)  (t2  * 

ray.dx  +  ray. ox), 0); 

) 

else 

{ 

return  1; 

) 

} 

else  if (t2  >0.0) 

{ 

return  plane_pattern ( (int) (t2  *  ray.dz  +  ray.oz) , (int) (t2  * 

ray.dx  +  ray.ox),l); 

) 

return  0; 

j  /* - End:  trace () - */ 

draw ( ) 

{ 

int  x,y; 

for (x=0;x<  WIDTH  &&  QUIT_OUT;  x++) 

{ 

for (y  =  0;  y  <  HEIGHT;  y++) 

{ 

plot (x, y, trace (x, y) ) ; 

} 

) 

)  /* - End:  draw () - */ 

main () 

{ 

fg_init_all  () ; 
draw ( ) ; 

while (QUIT_OUT) ; 
getch() ; 
fg_term()  ; 

} 

End  Listings 
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OF  INTEREST 


The  folks  at  Hyperkinetix  have  re¬ 
leased  Version  1.21  of  The  Builder,  a 
batch  file  compiler  and  language  ex¬ 
tender  that  includes  menus  as  com¬ 
mand  syntax.  DDJ  met  with  Hyperki- 
netix’s  “master  codeblaster,”  Tom 
Campbell,  who  demonstrated  Builder’s 
simplicity  and  ease  of  use.  Tom  com¬ 
bined  aspects  he  liked  in  C,  Basic,  and 
Hypertalk;  thus  Builder  is  English-like 
yet  efficient  —  Tom  wrote  a  simple 
menu  shell  program  with  four  or  five 
lines  of  Builder  code. 

You  can  create  custom  menus  and 
distribute  them  freely,  rather  than  pur¬ 
chase  canned  programs  for  every  ma¬ 
chine  you  need  menus  for.  You  can 
hide  details  of  a  program  so  that  users 
cannot  tamper  with  it,  filter  out  un¬ 
wanted  keystrokes,  and  display  boxes, 
colored  text,  and  position  the  cursor 
directly  (without  using  ANSI. SYS). 

Builder  imports  .BAT  files  and  trans¬ 
lates  them  into  compiled  .COM  or  .EXE 
programs.  All  batch  commands  are  du¬ 
plicated,  and  structures  such  as  Case, 
While,  and  Repeat  and  functions  such 
as  DiskReady  and  Input  are  included. 
DiskFree  determines  the  amount  of  avail¬ 
able  disk  space,  RenSub  renames  sub¬ 
directories,  FileSize  returns  the  size  of 
a  file  in  bytes,  ReadLine  and  WriteLine 
give  full  I/O  capabilities,  and  GetKey 
processes  keystrokes,  including  func¬ 
tion  keys.  Builder’s  variable  types  in¬ 
clude  integer  and  Longlnt,  and  subrou¬ 
tines  allow  you  to  create  your  own 
keywords.  You  can  build  PopUp  or 
DropDown  menus  that  act  as  block 
structure  statements,  and  Builder  pro¬ 
grams  automatically  use  a  Microsoft- 
compatible  mouse  if  one  is  present. 
Sells  for  $149-95,  and  includes  a  money- 
back  guarantee  and  telephone,  BBS, 
and  CompuServe  tech  support.  Reader 
service  no.  20. 

Hyperkinetix,  Inc. 

666  West  Baker,  Ste.  405 
Costa  Mesa,  CA  92626 
714-668-9234 

CodeTAP  386  is  a  source-level,  run¬ 
time  debugging  tool  for  80386  embed¬ 
ded  systems,  from  Applied  Microsys¬ 
tems  Corp.  It  provides  a  transparent 
window  into  the  internal  functioning 
of  the  80386  while  executing  code  in 
the  target  environment,  using  emula- 
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tion  technology  integrated  in  a  custom 
chip.  Developers  currently  use  native 
debuggers  and  software  monitors  for 
debugging,  and  use  emulators  for  full 
system  integration  and  for  solving  real¬ 
time  problems.  CodeTAP  bridges  these 
technologies. 

A  major  difference  between  Code¬ 
TAP  and  software  monitors  is  Code- 
TAP’s  ability  to  monitor  and  control 
code  execution  in  the  target  without 
utilizing  target  memory,  I/O,  or  requir¬ 
ing  prior  code  modification  —  it  is  elec¬ 
trically  transparent  in  the  target,  allow¬ 
ing  engineers  to  single  step  or  operate 
at  full  clock  speeds  up  to  33  MHz  with 
no  wait  states. 

A  source-level  debugger  is  included 
for  both  high-level  language  and  as¬ 
sembly  debugging.  Combined  with  Phar 
Lap’s  386  ASM/LinkLoc,  the  debugger 
software  supports  Intel  OMF-compat- 
ible  languages,  Microsoft  C,  and  other 
popular  compilers. 

The  company  claims  CodeTAP’s  great¬ 
est  asset  is  that  it  can  shorten  develop¬ 
ment  time  for  embedded  systems.  Pric¬ 
ing  begins  at  $5,000.  Reader  service 
no.  21. 

Applied  Microsystems  Corporation 

5020  148th  Ave.  NE 

P.O.  Box  97002 

Redmond,  WA  98073-9702 

206-882-2000 

Stony  Brook  Software  has  announced 
Version  2.1  of  their  Modula-2  Profes¬ 
sional  system  and  QuickMod  compil¬ 
ers.  Additional  code  optimization  in¬ 
cludes  loop  rewriting,  register  parame¬ 
ter  passing,  and  automatic  inline  expan¬ 
sion  of  procedures.  Also  new  is  Pres¬ 
entation  Manager  support,  enhanced 
MS  Windows  support,  an  integrated 
execution  profiler,  and  an  integrated 
object  librarian.  All  components  are  in¬ 
tegrated  under  a  single  environment.The 
Professional  system  includes  the  Stony 
Brook  environment,  the  QuickMod  and 
Optimizing  compilers,  the  debugger, 
and  the  run-time  library.  The  price  is 
$295.  Reader  service  no.  22. 

Stony  Brook  Software 
187  E.  Wilbur  Rd.,  Ste.  9 
Thousand  Oaks,  CA  91360 
805-496-5837 

Programmers  who  like  the  structure  of 
Modula-2  and  need  the  processing 
power  transputers  offer  now  have  the 
option  of  using  Modula-2  instead  of  C 
or  Occam.  Computer  System  Archi¬ 
tects  has  developed  a  Modula-2  pack¬ 
age  based  on  the  third  edition  of  Wirth’s 
Programming  in  Modula-2.  DDJ  spoke 
with  Richard  Ohran,  who  ported  the 
compiler  to  the  transputer  and  who 
worked  with  Wirth  on  the  original  im¬ 


plementation  on  the  Lilith  at  the  Swiss 
Federal  Institute  of  Technology.  He  said 
that  “our  version  of  Modula  has  fea¬ 
tures  that  facilitate  using  more  than 
one  processor.  It  is  set  up  to  replicate 
a  copy  of  itself  into  another  transputer.” 
The  full  symbolic  network  debugger 
identifies  deadlocks  and  run-time  er¬ 
rors,  and  can  display  the  state  of  every 
process  in  the  net  regardless  of  dis¬ 
tance  from  the  host  processor. 

Graphical  user  interface  routines  sup¬ 
port  overlapping  windows,  menus, 
down-loadable  fonts,  and  mouse-driven 
cursor  inputs.  The  compiler  operates 
in  two  passes  and  generates  binary  ob¬ 
ject  code  with  optimized  relative  ad¬ 
dressing  offsets.  Extensions  allow  gen¬ 
eration  of  all  transputer  parallel  pro¬ 
cessing  constructs. 

The  transputer  library  is  a  collection 
of  precompiled  Modula-2  procedures 
that  can  be  imported  into  your  pro¬ 
grams.  The  transputer  network  debug¬ 
ger  can  thread  its  way  into  a  dead¬ 
locked  net  of  transputers  and  display 
the  state  of  each  task  within  each  pro¬ 
cessor  until  it  finds  the  cause.  It  then 
displays  the  symbolic  notation  and 
shows  the  position  and  names,  types, 
and  contents  of  all  data  structures.  The 
system  sells  for  $995,  and  the  source 
code  to  the  Medos  system  kernel  (which 
allows  programs  to  call  other  programs 
as  overlays  that  link  dynamically  to  resi¬ 
dent  modules  and  so  inherit  character¬ 
istics  from  the  program  environment 
they  are  called  into)  and  the  library 
modules  is  another  $1,000.  Discounts 
available  to  educational  institutions. 
Reader  service  no.  23. 

Computer  System  Architects 
950  N.  University  Ave. 

Provo,  UT  84604-3422 
801-374-2300 

Coleman  Softlabs  has  released  Over¬ 
lay  Designer,  which  is  “computer-aided 
design”  for  programmers  using  Plink86 
and  RTLink  to  design  overlay  struc¬ 
tures.  If  you  are  building  a  product 
with  more  than  50  overlays,  Overlay 
Designer  can  apparently  save  you  a  lot 
of  time.  Mike  Milsner  of  Symantec  told 
DDJ  that  it  “saved  me  hours  and  days 
of  work.  I  like  it  a  lot.  We  use  Plink, 
and  have  an  overlay  structure  that  grew 
and  grew  —  to  more  than  170  mod¬ 
ules.  Instead  of  mapping  the  structure 
by  hand  I  used  Overlay  Designer  and 
it  automatically  prints  it  out  and  lets 
me  know  if  two  things  are  in  memory 
at  the  same  time.  It  helps  to  determine 
what  goes  into  the  root  and  which 
small  pieces  can  be  overlayed  on  disk, 
so  the  user  can  ping-pong  between, 
say,  a  spreadsheet  and  a  graph  and  not 
(continued  on  page  166) 
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(continued  from,  page  161) 
have  the  system  crash.” 

Overlay  Designer  reads  the  MAP  file 
output  by  the  linker  to  get  the  informa¬ 
tion  necessary  to  build  its  database. 
Overlay  Designer’s  graphic,  algorithmic, 
and  tabulation  tools  help  you  refine 
the  overlay  structure.  The  on-screen 
interaction  includes  a  report  that  shows 
direct  “equal  level  overlay"  conflicting 
calls,  35  dynamic  tables  to  cross-refer¬ 
ence  public  symbol  usage,  ability  to 
move  code  between  overlays  and  in¬ 
stantaneously  compute  the  result,  and 
tables  to  show  program  sizes  by  file, 
module,  and  overlay.  Price:  $595- 
Reader  service  no.  24. 

Coleman  Softlabs,  Inc. 

296  Bay  Rd. 

Atherton,  CA  94027 
415-322-9006 

A  full  standard  Common  Lisp  for  Unix 
System  V  and  X-Window-based  multi¬ 
processing  systems  is  available  from 
Top  Level.  TopCL  Version  2.0  includes 
a  foreign  function  interface  for  calling 
C  and  Fortran  code,  requires  minimal 
recoding  of  existing  algorithms  and  li¬ 
braries,  and  provides  debugging  tools 
not  available  with  strictly  serial  pro¬ 
gramming  languages.  The  company 
claims  that  TopCL  provides  near-lin¬ 
ear,  linear,  and  better  than  linear  per¬ 
formance  speedup,  that  synchronization 
is  handled  implicitly,  and  that  applications 
written  in  TopCL  can  run  as  fast  as  the 
multiprocessors  and  memory  bus  hard¬ 
ware  will  allow.  TopCL  is  ANSI-com¬ 
patible.  Reader  service  no.  25. 

Top  Level,  Inc. 

196  N.  Pleasant  St. 

Amherst,  MA  01002 
413-256-6405 

Version  4  of  the  source  code  analysis 
tool  for  C,  PC-lint,  has  been- released  by 
Gimpel  Software.  PC-lint  runs  under 
MS-DOS  or  OS/2,  and  analyzes  C  pro¬ 
grams  for  bugs  and  inconsistencies.  PC- 
lint  looks  across  multiple  modules  and 
helps  make  programs  more  maintain¬ 
able.  It  is  also  useful  for  porting  pro¬ 
grams  to  new  machines,  operating  sys¬ 
tems,  compilers,  and  memory  models. 

Kathy  Bell  of  Softcraft  told  DDJ  that 
“we  use  it  all  the  time  and  like  it  very 
much.  We  have  a  large  project  (125 
source  files,  2.5  Mbytes  of  code,  65 
header  files)  and  have  been  able  to  lint 
all  of  our  source  files  at  one  time.  The 
atest  version  is  the  best  so  far.  It  tells 
us  which  header  files  we  don’t  need 
and  which  functions  aren't  being  called. 
With  projects  this  large,  you  forget  what 
you  worked  on  a  year  ago,  and  with 
several  people  working  on  a  project,  it 
is  very  helpful  to  know  these  things.” 


New  diagnostics  include  checks  for 
compile -time  objects  such  as  macros, 
typedefs,  and  declarations;  PC-lint  re¬ 
ports  if  they  are  not  used  locally  and 
globally.  A  lint  object  module  captures 
in  binary  form  all  the  external  informa¬ 
tion  of  a  module,  allowing  for  incre¬ 
mental  linting  via  a  make  file.  New 
options  customize  message  suppres¬ 
sion,  Unix-style  options  are  supported, 
and  error  messages  give  detailed  infor¬ 
mation  regarding  files,  type  differences, 
precision  loss,  and  so  on.  And  you  can 
be  alerted  to  silent  conversions  caused 
by  prototypes.  PC-lint  requires  a  mini¬ 
mum  of  196  Kbytes  of  memory,  and 
will  use  all  available  memory.  It  sells 
for  $139.  Reader  service  no.  29. 

Gimpel  Software 
3207  Hogarth  Ln. 

Collegeville,  PA  19426 
215-584-4261 

Multitasking  for  C  programs  is  possible 
with  the  DIVVY  software  package  from 
Drumlin  Inc.,  which  provides  a  way 
to  divide  up  processor  time.  DIVVY 
allows  control  operations  to  be  pro¬ 
grammed  separately,  and  causes  the 
CPU  to  continually  switch  between  tasks 
at  run  time,  effectively  running  all  tasks 
simultaneously.  DOS  is  inherently  single¬ 
tasking;  DIVW  allows  a  multitasking 
application  to  be  self-contained,  avoid¬ 
ing  the  need  to  upgrade  to  OS/2  or 
Unix  to  achieve  multitasking.  Structured 
as  a  library  of  routines  that  can  be 
linked  into  programs  written  in  MS  C 
or  Turbo  C,  DIVVY  can  support  an 
unlimited  number  of  tasks,  flags,  and 
queues.  Standard  libraries  and  DOS  calls 
are  usable  through  the  scheduler  sys¬ 
tem,  which  operates  on  a  priority-based, 
non-preemptive  basis.  The  package  sells 
for  $229.  Reader  service  no.  26. 
Drumlin,  Inc. 

1011  Grand  Central  Ave. 

Glendale,  CA  91201 
818-244-4600 

FreeForm,  a  C,  symbolic,  source-level 
debugger  for  ROMable  68000-based  ap¬ 
plications,  is  new  from  Software  De¬ 
velopment  Systems.  The  company 
claims  this  product  will  deliver  the  high¬ 
est  level  of  symbolic  debugging  with¬ 
out  the  use  of  windows  or  an  in-circuit 
emulator.  FreeForm  is  command-lan¬ 
guage  driven,  allowing  you  to  choose 
precisely  which  code  and  data  are  be¬ 
ing  displayed  at  any  given  moment. 
You  can  plant  breakpoints  at  C-level 
source  statements,  inspect  and  modify 
C  symbols,  and  view  special  objects 
such  as  stacks  or  symbol  sets.  If  an 
object  is  too  big  to  fit  on  a  screen,  it  can 
be  redirected  to  a  file  and  edited.  Ar¬ 
rays,  enumerations,  and  structures  can 


be  displayed  in  full  symbolic  form,  and 
complex  data  structures  such  as  linked 
lists  and  trees  can  be  displayed  auto¬ 
matically  —  the  debugger  assumes  that 
the  entire  screen  is  available  for  dis¬ 
play. 

FreeForm  controls  the  target  applica¬ 
tion  through  available  serial  or  I/O  ports 
by  communicating  with  a  target  moni¬ 
tor  program  that  can  be  configured  to 
operate  on  virtually  all  68000-family 
targets.  Prices  range  from  $1,795  to 
$3,595,  depending  on  the  host  machine. 
Reader  service  no.  27. 

Software  Development  Systems,  Inc. 
4248  Belle  Aire  Ln. 

Downers  Grove,  IL  60515 
800-448-7733 

Watcom  has  announced  both  their  For¬ 
tran  77/386  and  C/386  Optimizing  Com¬ 
pilers  and  Tools  Version  8.0.  F77/386 
V8.0  supports  the  development  of  For¬ 
tran  programs  that  run  in  32-bit  pro¬ 
tected  mode  on  the  386,  typically  with 
a  DOS  extender.  F77/386  and  Watcom 
C8. 0/386  share  code  optimization  tech¬ 
nology  and  support  tools  such  as  the 
debugger,  linker,  profiler,  and  object 
librarian.  Both  are  run-time  compat¬ 
ible,  allowing  inter-language  function 
calls.  List  price  for  F77/386  V8.0  is 
$1,295;  the  Professional  Edition  of  C8.0/ 
386  is  $1,295,  Standard  Edition  is  $895. 
Reader  service  no.  30. 

Watcom 
415  Phillip  St. 

Waterloo,  Ontario 
Canada  N2L  3X2 
519-886-3700 

Lahey  Computer  Systems  announces 
Version  3-0  of  F77L-EM/32,  their  32-bit 
DOS  Fortran  compiler,  which  combined 
with  the  Ergo  OS/386  DOS  extender 
lets  users  exceed  the  DOS  640K  barrier 
and  use  extended  memory.  You  must 
purchase  the  Ergo  OS/386  extender 
($395)  in  order  to  use  the  Lahey  com¬ 
piler.  Virtual  memory  and  run-time  li¬ 
censes  are  included  in  the  $395.  The 
compiler  is  compatible  with  DESQview, 
so  you  can  multitask  applications  and 
run  other  applications  while  compiling 
in  the  background.  Version  3.0  includes 
a  new  editor  and  make  utility.  If  you 
use  a  386,  you  need  an  Intel  or  Weitek 
math  coprocessor,  1  Mbyte  of  extended 
memory,  and  DOS  3  x  or  greater.  You 
can  also  use  it  on  a  486.  The  compiler 
retails  for  $895.  Reader  service  no.  31. 
Lahey  Computer  Systems 
P.O.  Box  6091 
Incline  Village,  NV  89450 
702-831-2500 
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Thoughts  on  the  Reviewing  of  Software 

I  think  that  the  practice  of  sending  out  “reviewer’s  guidelines”  along  with  review  copies  of  a 
complex  product  is  a  good  one.  Of  course  such  guidelines  are  biased  —  slanted  toward  the 
features  of  the  product  that  the  vendor  thinks  are  most  likely  to  impress  the  reviewer,  engineered 
to  draw  the  reviewer’s  attention  away  from  the  aspects  of  which  the  vendor  isn’t  so  proud.  But  I 
believe  that  they  also  serve  two  commendable  purposes. 

First,  they  tell  the  reviewer  what  the  vendor  had  in  mind  in  developing  the  product.  This  is 
sometimes  far  from  clear.  Reviewer’s  guidelines  say,  in  effect,  “Here’s  what  we  think  we’ve 
accomplished;  here  are  the  features  on  which  we  want  to  be  judged.”  With  some  products,  it  really 
does  help  a  reviewer  to  know  what  the  company  had  in  mind;  consider,  for  example,  B&E 
Software’s  RagTime,  an  integrated  software  package  for  the  Macintosh. 

B&E  is  now  marketing  the  third  version  of  RagTime  in  the  U.S.  The  European  company  faces  the 
negative  impression  created  by  two  less-than-impressive  attempts  to  sell  the  product  here  through 
intermediaries.  It  faces  the  challenge  of  selling  an  integrated  do-all  application  for  the  Macintosh 
at  a  time  when  Apple  is  pushing  the  idea  of  small,  tool-like  applications  that  share  functionality. 
And  it  faces  the  problem  of  any  integrated  package:  None  of  its  included  applications  is  the  best 
in  its  class.  If  RagTime  gets  reviewed  on  the  basis  of  past  perceptions,  or  of  Apple’s  vision  of  the 
future,  or  of  its  components,  it  will  not  fare  well.  Reviewer’s  guidelines  would  let  B&E  define  the 
terms  on  which  it  wants  RagTime  to  be  evaluated. 

The  other  virtue  of  reviewer’s  guidelines  is  that  they  virtually  force  marketing  and  engineering 
to  communicate.  As  we  have  all  seen  demonstrated,  a  press  release  or  advertisement  can  be  written 
with  almost  no  knowledge  of  the  product.  Not  so  with  reviewer’s  guidelines.  Before  you  start 
suggesting  to  reviewers  what  sort  of  benchmarks  are  appropriate  in  your  product’s  category,  you’d 
better  know  something  about  the  product’s  performance. 

I  used  the  term  “functionality”  above  with  some  reservations.  When  I  was  at  InfoWorld  in  1981, 
we  argued  at  some  length  about  whether  or  not  there  was  such  a  word.  We  were  not  alone  in 
disliking  the  word:  Ted  Nelson  fumes  about  it  in  Computer  Lib.  But  the  word  does  exist  and  is  used, 
because  it’s  needed.  It’s  ugly,  but  it’s  right. 

I  wonder,  though,  if  software  reviews  today  are  using  all  the  right  words.  In  1974,  features  and 
performance  were  preeminent.  Design  and  depth  are  arguably  more  important  today,  but  those 
words  don’t  often  appear  as  subheads  in  reviews. 

Trip  Hawkins  of  Electronic  Arts  has  spoken  eloquently  about  the  need  for  software  to  be  deep: 
Capable  of  being  used  for  years,  with  new  folds  to  discover,  and  thus  a  long  shelf  life.  Naive  users 
have  different  needs  from  experienced  users,  and  a  software  product  ought  to  have  value  for  both 
groups.  HyperCard  is  an  extraordinary  case  study  in  depth:  All  the  way  from  cut-and-paste 
application  generation  to  the  brink  of  writing  utilities  in  C.  No,  HyperCard  doesn’t  teach  C,  but 
everyone  who  gets  deeply  into  HyperCard  is  strongly  tempted  to  write  an  external  command,  and 
HyperCard’s  external  command  interface  takes  away  a  lot  of  the  pain  of  learning  to  program 
the  Mac. 

Perhaps  reviewers  ought  to  give  more  attention  to  such  subjective  issues  as  depth  and  design, 
and  less  to  those  gargantuan  tables  of  features  and  benchmark  results. 

Then  again,  objectivity  is  safer  than  subjectivity. 

On  June  21  of  this  year,  the  Supreme  Court  removed  the  opinion  defense  in  libel  suits.  Writers 
of  newspaper  or  magazine  opinion  columns  or  of  letters  to  the  editor,  cartoonists,  restaurant  and 
software  reviewers,  can  all  be  sued  for  libel  if  the  opinions  they  express  cause  damage  to  someone. 
Negative  software  reviews,  it  goes  without  saying,  cause  damage  to  the  company  whose  product 
is  reviewed.  The  plaintiff  has  to  prove  that  the  damaging  statement  was  not  true,  but  legal  experts 
predict  that  a  lot  of  suits  that  would  never  before  have  been  considered  will  now  not  only  be  filed, 
but  will  actually  go  to  trial. 

The  same  legal  experts  predict  that  this  decision  will  cause  commentators  and  reviewers  to  be 
much  less  outspoken  in  their  views.  The  software  reviewers  of  my  acquaintance  do  not  seem  to 
be  modifying  their  behavior  in  response  to  the  ruling.  They  may  be  sorry. 

Under  the  circumstances,  I  think  I’ll  reserve  my  opinion  of  the  present  Supreme  Court  justices.  I 
don’t  think  we  could  print  it  anyway. 


ytflcJLuJ 


Michael  Swaine 
editor-at-large 
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SOURCE  CODE  AVAILABILITY 

As  a  service  to  our  readers,  all  source  code 
is  available  on  a  single  disk  and  online.  To 
order  the  disk,  send  $14.95  (Calif,  residents 
add  sales  tax)  to  Dr.  Dobb's Journal,  501 
Galveston  Dr.,  Redwood  City,  CA  94063, 
or  call  800-356-2002  (inside  Calif.)  or  800- 
533-4372  (outside  Calif.).  Specify  issue  num¬ 
ber  and  disk  format.  Code  is  also  available 
through  the  DDJ  Forum  on  CompuServe 
(type  GO  DDJ)  and  through  M&T’s  Telepath 
Conferencing  system. 


HEX!  ISSUE . 

November  brings  our  annual  object-ori¬ 
ented  programming  issue,  where  we’ll  ex¬ 
amine  programming  problems  —  and  pre¬ 
sent  practical  solutions  —  in  a  variety  of 
OOP  languages. 
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E  D  1  T  0  R  I 

Courting 

Trouble 
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In  the  most  recent  cat  fight  between  Intel  and  Advanced  Micro  Devices  (AMD),  lawyers  for  both 
sides  claimed  victory,  at  least  for  the  time  being.  In  his  preliminary  injunction,  Judge  William 
Ingram  said  AMD  could  continue  to  use  a  product  numbering  system  that  mirrors  Intel’s  product 
line,  but  backed  off  from  permitting  AMD  use  of  the  name  “Intel”  in  its  advertisements. 

This  case  revolves  around  a  copyright  infringement  lawsuit  launched  by  Intel  over  a  supposedly 
Intel-compatible  80287  math  coprocessor  AMD  began  selling  in  April.  The  judge  says  AMD  can’t 
boast  anymore  that  its  80287  is  the  100  percent  equivalent  of  Intel’s  although,  as  an  AMD  spokesman 
said,  the  AMD  chip  is  “a  reverse-engineered  coprocessor  that  incorporates  Intel  microcode,” 
microcode  AMD  received  from  Intel  in  a  1976  patent  exchange  agreement. 

But  what’s  at  stake  here  isn’t  just  the  “80287”  label  —  that  fish  isn’t  big  enough  to  fry.  The  big 
perch  in  the  pond  is  the  80386,  potentially  one  of  the  most  profitable  chips  around.  What’s  going 
on  is  that  Intel  is  setting  the  stage  to  protect  the  name  “80386”  against  chip  cloning  by  AMD  and 
other  manufacturers.  While  Intel  has  apparently  conceded  its  right  to  names  like  “8086,”  “80286,” 
and  “80287,”  the  company  is  claiming  ownership  of  and  protection  for  the  name  “80386”  (and 
“80486,”  etc.).  As  you  can  expect,  that  doesn’t  set  well  with  chip  manufacturers  who’d  like  to  cash 
in  with  compatible  chips.  AMD’s  response  is  that  the  “8(b86”  family  name  has  become  generic, 
somewhat  like  the  term  “PC,”  I  guess. 

By  the  time  you’re  reading  this,  the  situation  might  have  taken  another  faltering  step  towards 
settlement  because  of  a  September  ruling  on  the  other  Intel/AMD  rhubarb,  the  “second  source” 
dispute.  To  briefly  recap  that  story:  When  IBM  decided  on  Intel’s  80^86  architecture  as  the  CPU  for 
its  microcomputers,  Big  Blue  stipulated  that  Intel  had  to  provide  a  second  manufacturing  source 
for  the  chips.  Consequently,  Intel  licensed  the  80^86  architecture  to  other  chip  vendors,  usually  by 
means  of  technology  exchange  agreements.  After  that  it  was  business  as  usual,  until  the  80386. 
Intel,  recognizing  a  golden  goose  when  it  saw  one,  refused  to  allow  AMD  to  manufacture  the  chip. 
Since  the  original  agreement  between  the  two  companies  said  that  disputes  would  be  settled  by 
arbitration,  not  legal  action,  AMD  tried  to  get  Intel  to  a  mediator.  Intel  refused.  AMD  then  went  to 
court  just  to  get  to  arbitration. 

Who’s  right?  It  depends  on  which  court  case  you’re  talking  about.  As  for  the  microcode  copyright 
ruling,  I  don’t  question  Intel’s  right  to  protect  products  it  produces  and  the  names  it  uses  to  identify 
them.  However,  it  also  seems  there  may  be  some  First  Amendment  questions  involving  AMD’s  right 
to  say  in  advertisements  (or  otherwise)  whether  or  not  their  products  are  “Intel  compatible.”  The 
whole  question  of  second  sourcing,  on  the  other  hand,  will  likely  drag  on  and  I  expect  the  windup 
will  hinge  on  the  exact  wording  of  the  agreements  and  whether  or  not  those  agreements  are  valid 
and  binding.  In  any  event,  it  will  be  the  judge  (or  judges)  who  eventually  decides,  not  you  or  me. 

What  I  do  know  is  that  I  first  wrote  about  these  legal  calisthenics  several  years  ago.  Not  only 
have  the  issues  not  been  resolved,  but  new  lawsuits  keep  getting  pushed  onto  the  stack: 
Look-and-feel,  patents,  copyright,  and  on  and  on. 

To  keep  all  this  in  perspective,  however,  note  that  when  it  comes  to  litigious  propensities,  the 
computer  industry  doesn’t  stand  alone.  A  case  in  point:  Kellogg’s,  those  folks  who  put  breakfast 
cereal  on  your  table  every  morning,  have  launched  a  legal  salvo  at  arch  rival  Nabisco  over,  of  all 
things,  shredded  wheat.  Each  company  claims  “nutritional  superiority”  and  says  the  other  company 
is  copying  the  other’s  product  features  and  marketing  strategy.  Sound  familiar?  At  least  some  good 
could  come  out  of  the  Kellogg/Nabisco  suit  —  we  might  get  more  better  fiber. 

Better  yet,  maybe  we  all  should  join  the  League  for  Programming  Freedom  for  a  few  bars  of  the 
“Hexadecimal  Chant”  (loosely  sung  to  the  tune  of  Country  Joe  MacDonald’s  “Vietnam  Rag”): 
1-2-3-4,  Kick  that  lawsuit  out  the  door, 

5-6-7-8,  Innovate,  don’t  litigate, 

9-A-B-C,  Interfaces  should  be  free, 

D-E-F-0,  Look-and-feel  has  got  to  go. 

The  Official  DDJ  Bookmark 

Finally,  in  our  never  ending  quest  to  bring  you  practical  tools  for  everyday  use,  we’re  including 
this  month  the  official  DDJ bookmark.  You’ll  find  it  attached  to  a  tear-on-the-dotted-line  card 
accompanying  the  “Programmer’s  Bookshelf’  column  on  page  145.  Counter  to  the  prevailing  legal 
winds,  this  bookmark  is  provided  license-free;  copy  it  and  pass  it  around  to  your  friends.  As  you 
might  expect,  technical  support  is  minimal.  If  you  have  any  questions,  call  my  lawyer. 


Jonathan  Erickson 
editor-in-chief 
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Still  Going  in  Circles 

Dear  DDJ, 

As  usual,  the  July  1990  issue  proved  to 
me  that  my  DDJ  subscription  is  worth 
ev  ery  penny.  I  enjoyed  all  the  articles, 
including  Mr.  Paterson’s  on  drawing 
circles,  but  I'd  like  to  add  my  two  cents 
on  the  subject,  nonetheless. 

Mr.  Paterson’s  analysis  of  the  circle 
drawing  problem  using  calculus  was 
interesting,  but  there  are  some  simplifi¬ 
cations  overlooked  which  can  be  found 
if  one  applies  some  algebra  and  a  little 
elbow  grease.  Allow  me  to  borrow  from 
Mr.  Zigon,  Mr.  Lee,  and  Mr.  Paterson, 
and  state  the  problem  as  follows.  Given 
a  point  (x,y)  known  to  be  near  the 
circle,  find  the  next  contiguous  point. 
Furthermore,  we  will  confine  ourselves 
to  points  in  the  octant  defined  by  x  >= 
0,  y  <=  r,  x<=y. 

Since  we  are  only  considering  points 
on  the  octant  from  (0,  r)  traveling  clock¬ 
wise,  the  next  point  will  either  be  (x+1, 
y)  or  (x+1,  y- 7).  The  problem  then 
becomes  to  find  which  is  closer  to  a 
perfect  circle.  We  know  that  if  (x,y)  is 
on  the  circle,  (x+l,y)  is  above  or  on  the 
circle  and  ( x+l,y-l )  is  below  or  on  the 
circle.  I  won’t  prove  this,  but  a  drawing 
should  be  convincing  enough.  If  the 
distance  from  the  circle  to  ( x+l,y )  is 
greater  than  the  distance  from  ( x+l,y - 
7)  to  the  circle,  then  we  will  choose 
(x+l,y-l),  otherwise  we  will  choose 
(x+l,y)  as  the  next  point.  If  the  two 
distances  are  identical,  we’ll  arbitrarily 
choose  0+7  jD  as  the  next  point. 

Let  e(x,y)  be  the  error  function,  which 
is  the  distance  from  a  perfect  circle  of 
radius  r  centered  on  the  origin  to  the 
point  (x,y).  e(x,y)  is  expressed  as  e(x,y) 
=  x2  +  y2  -  r2. 

e(  )  can  be  easily  derived  by  using 
the  definition  of  a  circle  and  Pythago¬ 
ras’  Theorem.  At  this  point,  the  circle 
drawing  algorithm  looks  like  Example 
1 .  The  goal  now  is  to  reduce  the  amount 
of  computation  needed  in  the  loop. 
Most  of  it  is  being  performed  in  the  if 
statement.  The  problem  is  the  inequal¬ 
ity  which  computes  e( )  twice: 


e(x+l,y)  >  -  e(x+l,y+l) 

Algebra  to  the  rescue.  First,  expand  the 
right-hand  side,  and  substitute  using 
the  definition  of  e( ). 

e(x+l,  y  -1)  =  (x  +1)2  +  (y  -  l)2  -  r2 
e(x+l,y  -1)  =  (x+1)2  +  y2  -  2y+l  -  r2 
e(x+l,y  -1)  =  e(x+l,y)  -  2y+l 

Substitute  into  the  original  inequality: 

e(x+l,y)  >  -  e(x+l,y)+2y  -1 
Add  e(x+l,y)  -  2y+l  to  both  sides: 

2e(x  +  1,  y)  -  2y  +  1 

Divide  by  2: 

e(x+l,y)  -  y>0 

Note  that  the  1/2  drops  out,  since 
we  are  performing  an  integer  compari¬ 
son.  Now  e( )  is  computed  only  once 
instead  of  twice  each  time  through  the 
loop.  The  algorithm  now  looks  like 
Example  2. 

Now,  to  get  rid  of  the  remaining  e( ). 
The  above  expressions  showed  that 
e(x+l,y-l )  can  be  expressed  in  terms 
of  e(x+l,y).  If  e(x+  l,y)  can  be  expressed 
in  terms  of  e(x,y),  the  calculation  of 
e( )  can  be  written  in  an  iterative  form 
(each  new  value  of  e( )  computed  by 
modifying  the  previous  e( )),  which  is 
(hopefully)  easier  to  compute. 

e(x+l,y)  =  (x+1)2  +  y2  -  r2 
e(x+l,y)  =  x2  +2x+l+y2  -  r2 
e(x+l,y)  =  e(x,y)+2x+l 


Adding  a  variable,  e,  to  accumulate 
e()-y  and  changing  the  multiplication 
by  2  to  a  left  shift  by  1  yields  the  final 


version  shown  in  Example  3- 

There’s  my  version  of  the  circle  plot¬ 
ting  algorithms.  Plotting  a  circle  of  ra¬ 
dius  1,000,000  took  3-81  seconds  for 
Mr.  Paterson’s  algorithm  versus  1.51 
seconds  for  mine.  To  generate  an  el¬ 
lipse,  the  plot( )  routine  may  be  modi¬ 
fied  as  Mr.  Paterson  suggests. 

Michael  P.  Lindner 
Basking  Ridge,  New  Jersey 

Pointers:  Far  vs.  Huge  vs.  Based 

Dear  DDJ , 

On  page  85  in  the  August  1990  DDJ, 
Bruce  Schatzman  gives  a  useful  de¬ 
scription  of  the  new  based  pointer  tech¬ 
nique  available  under  MS  C  6.0.  Unfor¬ 
tunately,  he  makes  some  incorrect  state¬ 
ments  regarding  far  pointers. 

The  discussion  claims  that  far  point¬ 
ers  are  the  only  solution  available  for 
data  arrays  larger  than  64K.  This  is  sim¬ 
ply  not  true,  as  far,  near ;  and  based 
pointers  all  suffer  from  the  64K  limi- 
taion  on  contiguous  data  size.  The  only 
available  solution  to  this  limitation  is 
the  huge  pointer. 

Technically,  near,  far,  and  based 
pointers  are  represented  using  variations 
of  segmented  notation,  near  pointers 
assume  an  implied  segment  called 
DGROUP  and  only  require  a  2-byte 
offset,  far  pointers,  on  the  other  hand, 
make  no  assumptions  about  the  seg¬ 
ment.  They  require  4  bytes;  the  high 
word  holds  the  segment,  while  the  low 
word  holds  the  offset,  based  pointers 
represent  a  middle  ground  between 
near  and  far.  The  segment  and  offset 
are  split  into  two  variables;  one  vari¬ 
able  holds  the  segment,  while  the  other 
holds  the  offset.  This  leads  to  improved 
efficiency  where  numerous  references 
to  pointers  of  a  common  segment  are 
made. 

In  contrast,  huge  pointers  are  repre¬ 
sented  using  4-byte  absolute  notation. 
The  use  of  absolute  notation  supports 
contiguous  blocks  of  data  which  are 
larger  than  64K,  however,  additional 
code  overhead  is  incurred  to  transform 
the  absolute  notation  into  segmented 
notation  at  runtime. 

Hope  this  untangles  a  few  pointers 
and  thanks  for  a  great  magazine. 

Kent  Funk 
Manhattan,  Kansas 

Bruce  responds:  Kent  is  correct.  Both 
far  pointers  and  based  pointers  suffer 
from  the  64K  addressing  limitation, 
which  is  the  size  of  the  offset  (16  bits). 
The  reference  to  far  pointers  in  the  last 
paragraph  of  the  article  should  have 
been  a  reference  to  huge  pointers.  My 
apologies  and  thanks  to  Kent  for  the 
correction. 

(continued  on  page  12) 
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(continued  from  page  8) 

DOS  +  386  =  4  Gigabytes 

Dear  DDJ, 

In  my  article  “DOS  +  386  =  4  Giga¬ 
bytes!”  {DDJ,  July  1990)  there  is  a  com¬ 
patibility  problem  with  some  386  ma¬ 
chines.  To  correct  this,  you  must  re¬ 
place  the  a20( )  routine  in  Listing  Three, 
page  110.  The  correct  routine  is: 

/*  This  code  is  the  same  V 
void  a20(int  flag) 

( 

if  (inboard)  ( 

outp(INBA20,flag?INBA200FF); 

1 

/*  changes  start  here  V 
else 
( 

keywait(  ); 
outp(0x64,0xDl); 
keywait(  ); 

outp(0x60,flag?0xDF:0XDD); 
keywait(  ); 
outp(0x64,0xFF); 
keywaitC  ); 


The  code  in  the  article  works  on 
some  386  machines,  but  fails  on  Com¬ 
paq  and  Dell  computers.  The  code 
above  works  on  all  machines  I  tested, 
including  Everex,  Dell,  Compaq,  and 
CompuAdd. 

My  apologies  for  any  inconvenience 
this  has  caused.  I’d  like  to  thank  John 
Hamilton  of  Quad-S  for  providing  sev¬ 
eral  of  the  test  machines. 

A1  Williams 

League  City,  Texas 

Dear  DDJ, 

In  reviewing  the  code  supplied  with 
“DOS  +  386  =  4  Gigabytes!”  by  Al  Wil¬ 
liams  {DDJ,  July  1990),  I  have  identi¬ 
fied  some  potentially  dangerous  prac¬ 
tices  that  are  avoidable. 

The  first  is  that  the  state  of  the  IRQ 
intermpt  flag  (IF)  is  cleared  and  then 
forcibly  set  at  the  end  of  the  routine 
“protsetup.”  In  case  this  routine  is  called 
while  interrupts  are  disabled,  it  will 
reenable  them.  A  safer  method  is  to 
PUSHF,  CLI,  and  then  POPF  (POPF 
should  be  avoided  on  code  that  may 
run  on  an  80286,  but  this  is  80386  or 
above,  only). 

Generally,  interrupts  really  are  en¬ 
abled  in  such  context,  so  programmers 
tend  to  be  lax,  but  it  should  not  be  left 
up  to  chance.  At  least  the  fact  that 
interrupts  will  be  enabled  on  exit  should 
be  explicitly  documented. 

Secondly,  after  changes  to  the  pro¬ 
tection-enabled  (PE)  flag,  a  short  jump 
is  performed  to  flush  the  prefetch  queue. 
While  this  is  recommended  by  the 
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80386  Programmer’s  Reference  Man- 
ual (Ahern- Wahlstrom,  1986)  when  go¬ 
ing  into  protected  mode,  section  14.5 
dearly  states  that  a  far  jump  is  required 
to  put  “appropriate  values  in  the  ac¬ 
cess  rights  of  the  CS  register  [sic].” 

In  fact,  it  is  desirable  to  do  far  jumps 
on  both  entry  and  exit  of  protected 
mode.  This  assures  the  kind  of  coher¬ 
ency  that  greatly  simplifies  the  tran¬ 
sition  and  facilitates  the  use  of  an  In 
Circuit  Emulator  (ICE)  or  software  de¬ 
bugger.  If  one  is  single-stepping  through 
such  code,  the  dumps  and  restores  of 
invalid  CS  values  could  disrupt  the  or¬ 
derly  execution  of  instructions. 

The  lack  of  explicit  CS  descriptor 
loading  should  not  actually  cause  the 
code  to  fail  because  no  far  transitions 
are  performed  while  in  protected  mode. 
This  assures  the  cached  descriptor  in¬ 
formation  will  remain  valid.  On  the 
other  hand,  this  introduces  an  unnec¬ 
essary  architectural  dependence  that  may 
interfere  with  operation  on  yet-to-be- 
released  80386  compatible  processors. 

I  hope  these  recommendations  help 
you  and  Mr.  Williams  to  produce  and 
distribute  code  that  is  as  robust  and 
widely  compatible  as  possible. 

Thomas  Roden 

Irvine,  California 

Al  responds:  I  want  to  thank  Thomas 
for  his  interest  in  “DOS  +  386  =  4 
Gigabytes!”  I’m  glad  he  took  the  time 
to  explore  it  in  such  detail.  I’d  like  to 
address  his  issues  one  at  a  time. 

His  comments  about  reloading  the 
CS  register  for  protected  mode  are  cer¬ 
tainly  true —  true,  that  is,  if  you  are 
writing  a  protected-mode  application. 
In  this  case,  however,  the  same  cach¬ 
ing  that  allows  us  to  use  the  4-gigabyte 
segments  allows  us  to  use  this  handy 
technique.  Of  course,  if  the  code  ran 
with  interrupts  enabled,  or  made  any 
long  calls  or  jumps,  we  would  have  to 
force  the  CS  register  to  reload.  This  would 
have  required  another  GDT entry,  and 
was  deemed  unnecessary.  Also,  if  you 
look  at  the  code  for  my  DOS  extender 
(Part  I  in  this  issue),  the  CS  register  is, 
in  fact,  loaded  as  you  suggest.  Thanks 
again  and  I  hope  I  have  answered  any 
concerns. 

[Editor’s  note:  Thomas  is  the  author 
of  “Four  Gigabytes  in  Real  Mode,  "pub¬ 
lished  in  Programmer’s  Journal  (No¬ 
vember/December  1989)J 

Zortech  Heard  From 

Dear  DDJ, 

It  was  with  considerable  interest  that  I 
read  the  article  titled  “Collections  in 
Turbo  C++”  by  Bruce  Eckel  in  your 
August  1990  issue. 

The  article  seems  to  suggest  that  fac¬ 


tors  such  as  compilation  speed,  code 
size  and  speed,  and  support  for  devel¬ 
opment  of  Microsoft  Windows  3.0  and 
OS/2  are  irrelevant  or  certainly  not  worth 
his  mention.  For  those  interested  in 
such  features,  Zortech  C++  remains  the 
platform  of  choice.  Our  benchmarks 
clearly  show  Turbo  C++  compiles 
slower,  and  generates  bigger,  slower 
code.  Additionally,  Turbo  C++  currently 
has  no  support  for  the  Windows  and 
OS/2  operating  environments. 

Surprisingly,  a  big  deal  was  made  of 
Zortech  not  supporting  the  C++  lan¬ 
guage  feature  pointers  to  members.  As 
of  July  1,  Zortech  introduced  this  fea¬ 
ture  in  its  version  2.1  release.  It’s  par¬ 
ticularly  surprising,  since  at  the  time 
the  article  was  submitted,  Bruce  Eckel 
and  DDJ  had  beta  copies  in  their  pos¬ 
session  that  clearly  implemented  this 
feature. 

Perhaps  of  greatest  concern  was  that 
Bruce  Eckel’s  business  relationship  with 
Borland  International  was  not  made 
clear  on  the  front  of  the  article  in  the 
traditional  fashion.  It  is  standard  jour¬ 
nalistic  practice  to  reveal  to  readers  any 
conflicts  of  interest  at  the  time  of  publi¬ 
cation. 

Paul  Leathers 

President,  Zortech  Inc. 

DDJ  responds:  First  of  all,  the  article 
was  about  collections  in  Turbo  C++, 
not  collections  in  Zortech  C++.  No  com¬ 
parisons  were  made  or  intended  so  there 
was  no  reason  to  discuss  Zortech ’s  fea¬ 
tures,  admirable  as  they  may  be.  As 
you  said,  when  the  article  was  written, 
Zortech  C++  2. 1  was  still  in  beta.  DDJ 
covers  software  only  when  readers  can 
buy  it  off  the  shelf. 

There  was  no  tie  between  Bruce  and 
Borland  when  Bruce  wrote  the  article. 
After  the  magazine  was  available  on 
newsstands,  Bruce  began  teaching  an 
“Introduction  to  C++  ’’  seminar  as  part 
of  Borland’s  roving  OOP  educational 
program.  You  ’re  right-on  about  maga¬ 
zines  publishing  at  the  front  of  the 
article  any  of  the  author’s  interests 
that  might  suggest  possible  bias.  Hap¬ 
pily,  DDJ  is  one  of  the  few  magazines 
to  adhere  to  this  practice. 

Editor  Update 

Dear  DDJ, 

I  have  to  take  exception  to  the  sidebar 
“Regular  Expressions”  in  the  article 
“Awk  as  a  C  Code  Generator,”  by 
Wahhab  Baldwin  (August  1990).  The 
Microsoft  Editor  (M)  does  indeed  sup¬ 
port  parentheses  and  +  in  regular  ex¬ 
pressions.  In  fact,  it  supports  two  fla¬ 
vors  of  each. 

Parentheses  may  be  used  for  simple 
(continued  on  page  14) 
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(continued  from  page  12) 
grouping,  as  is  typical.  In  addition,  braces 
provide  grouping  and  retain  the  matched 
substring  for  use  in  a  replacement  ex¬ 
pression.  This  is  done  by  specifying  $1, 
$2,  etc.,  in  the  replacement  expression 
to  indicate  what  matched  the  first  pair 
of  braces,  the  second  pair,  etc. 

The  simple  plus  sign  is  supported, 
and  is  defined  to  match  the  shortest 
string  that  gives  a  successful  match  for 
the  regular  expression  as  a  whole.  Also, 
the  hash  sign  is  also  used  to  mean  one 
or  more  occurances  of  the  previous  subex¬ 
pression,  but  in  this  case  it  is  defined 
to  match  the  maximum  number  of  oc¬ 
curences  that  gives  a  match  for  the 
expression  as  a  whole.  The  difference 
between  these  two  forms  is  only  of 
significance  in  search  and  replace  op¬ 
erations.  For  example,  replacing 
foo(bar)+  with  spam  in  the  text  foobar- 
bar  will  give  spambar.  On  the  other 
hand,  replacing  foo(bar)#  with  spam 
in  the  text  foobarbar  will  give  spam. 

Paul  J.  Ste.  Marie 

CIS  72200,1324 

Guess  Who’s  Coming  to  Dinner? 

Dear  DDJ 

Shocking  but  true.  In  the  August  1990 
DDJ,  both  Douglas  N.  Franklin  and  Mi¬ 
chael  Swaine  are  right  in  their  asser¬ 
tions  about  the  “Dining  Philosophers” 


problem.  Mr.  Franklin  suggests  it  can 
be  solved  and  Michael  suggests  it  can¬ 
not.  The  key  is  that  they  are  talking 
about  different  forms  of  the  same  prob¬ 
lem.  The  problem  solved  by  Mr.  Frank¬ 
lin  is  not  that  same  problem  proved 
unsolvable  by  deterministic  algorithms 
in  Algorithmics  by  David  Harel  (Addison- 
Wesley,  1987).  To  quote  the  problem 
from  Mr.  Harel  on  page  288: 

Can  the  dining  philosophers  prob¬ 
lem  be  solved  without  a  doorman 
[Mr.  Franklin’s  first  solution],  and 
without  resorting  to  shared  memory 
[Mr.  Franklin’s  second  solution]  or 
its  equivalents?  In  other  words,  is 
there  a  fully  distributed,  fully  sym¬ 
metric  solution  to  the  problem  that 
does  not  employ  any  additional  pro¬ 
cessors?  Here  “fully  distributed” 
means  that  there  is  no  central  shared 
memory  and  the  protocols  may  use 
only  distributed  variables  ....  “Fully 
symmetric”  means  that  the  proto¬ 
cols  for  all  philosophers  are  essen¬ 
tially  identical  [ruling  out  Mr.  Frank¬ 
lin’s  third  solution], 

Mr.  Harel  goes  on  to  prove  that  this 
highly  restricted  form  of  the  dining  phi¬ 
losophers  problem  can’t  be  solved  with 
deterministic  algorithms.  Mr.  Harel  pro¬ 
vides  the  following  algorithm,  page  304: 


1 

do  the  following  again  and 
again  forever: 

1.1 

carry  out  private  activities  un¬ 
til  hungry; 

1.2 

toss  coin  to  choose  a  direc¬ 
tion,  left  or  right,  at  random; 

1.3 

wait  until  fork  lying  in  cho¬ 
sen  direction  is  available,  and 
then  lift  it; 

1.4 

if  other  fork  is  not  available 
do  the  following: 

1.4.1 

put  down  fork  that  was  lifted; 

1.4.2 

go  to  1.2; 

1.5 

otherwise  (i.e.  other  fork  is 
available)  lift  other  fork; 

1.6 

critical  section:  eat  to  your 
heart’s  content; 

1.7 

put  down  both  forks  (and 
back  to  1.1); 

and  then 

proves  that  it  solves  the  re- 

stricted  form  of  the  problem.  Note  that 
this  algorithm  depends  on  randomness, 
the  point  of  Mr.  Swaine  using  the  refer¬ 
ence  in  his  article. 

It  is  unfortunate  Mr.  Swaine  did  not 
make  it  clear  that  Mr.  Harel  was  refer¬ 
ring  to  this  highly  restricted  form  of  the 
problem,  not  the  classic  form  solved 
by  Mr.  Franklin.  But,  Mr.  Franklin  should 
have  given  Mr.  Swaine  the  benefit  of 
the  doubt  and  looked  up  Algorithmics 
in  his  local  library,  which  I  consider 
Mr.  Franklin’s  homework,  before  ac¬ 
cusing  Mr.  Swaine  of  not  doing  his.  I 
suggest  Mr.  Franklin,  or  anyone  else 
even  marginally  interested  in  the  the¬ 
ory  of  algorithms,  pick  up  a  copy  of 
Algorithmics.  It  is  an  excellent  book. 

Charles  P.  Jazdzewski 

Watsonville,  California 


Errata:  Correction  for  Example  1, 
“Dining  Philosophers”  problem, 
August  1990  “Letters.” 

fdefine  N  5 

#define  take_fork (num)  down(s[num]) 

#define  put_fork (num)  up (s [num]) 

typedef  int  semaphore; 

semaphore  s[N]; 

philosopher (i) 

int  i; 

1  while  (TRUE)  ( 
think  () ; 
take_fork(i) ; 
take_fork ( (i+l)  i  N)  ; 
eat ( ) ; 

put_fork (i) ; 
put_fork ( (i+l)  %  N) ; 

} 

) _ 

DDJ 

We  welcome  your  comments  (and  sug¬ 
gestions).  Mail  your  letters  (include  disk 
if  your  letter  is  lengthy  or  contains  code) 
to  DDJ,  501  Galveston  Dr.,  Redwood 
City,  CA  94063,  or  send  them  electroni¬ 
cally  to  CompuServe  76704,50  or  via 
MCI  Mail,  c/o  DDJ.  Please  include  your 
name,  city,  and  state.  We  reserve  the 
right  to  edit  letters. 
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Roll  Your  Own 

DOS  Extender:  Part  I 


Develop  your  own  386  protected-mode  applications 


Al  Williams 


The  80386  is  chock-full  of  advanced  features  that 
support  modern  applications  and  make  program¬ 
ming  easier.  Unfortunately,  DOS  programmers  can’t 
take  advantage  of  many  of  these  features  because 
DOS  is  unable  to  use  the  386’s  special  protected 
mode.  So  what  can  you  do  when  you  need  to  write  PC 
programs  that  require  large  amounts  of  memory,  multi¬ 
tasking,  or  other  sophisticated  features? 

One  solution  is  to  move  to  a  protected-mode  operating 
system  such  as  Xenix  386  or  OS/2.  Another  approach, 
however,  is  to  turn  to  a  DOS  extender  that  provides  some 
mechanism  for  interrupt-driven  I/O  and  for  making  DOS 
and  BIOS  calls  in  a  protected-mode  program.  Some  DOS 
extenders  switch  between  real  and  protected  mode  to  han¬ 
dle  interrupts  and  make  DOS  calls,  but  the  preferred  method 
runs  DOS  in  virtual-86  mode,  which  causes  the  80386  to 
emulate  an  8086.  (See  the  accompanying  text  box  entitled 
“Protected  Mode  Operations  on  a  PC”  for  more  details.) 

Actually,  running  protected-mode  programs  on  a  386  is 
not  very  difficult  if  you  don’t  need  to  access  the  system  calls 
or  perform  any  interrupt-driven  I/O.  In  fact,  two  articles 
previously  published  in  DDJ did  just  that  (see  the  references 
at  the  end  of  this  article).  However,  your  programs  will  often 
need  to  do  disk  and  keyboard  I/O,  as  well  as  make  calls  to 
DOS  and  the  BIOS. 

In  this  two-part  article,  I  present  a  DOS  extender,  PROT, 
that  deals  with  interrupt-driven  I/O  along  with  most  DOS 
and  BIOS  calls  in  protected  mode  using  virtual-86  mode.  In 
this  first  installment,  I’ll  discuss  protected  mode  in  general 
and  the  basics  of  PROT  in  particular.  In  next  month’s  issue, 
I’ll  cover  debugging  issues  and  80386  exceptions  and  take 
you  under  the  DOS  extender’s  hood. 

Alisa  systems  engineer  on  the  space  station  Freedom  project 
for  Jackson  and  Associates.  Look  for  an  expanded  version 
of  PROT  in  his  book  DOS:  A  Developer’s  Guide,  which  will 
be  available  from  M&T  Books  early  in  1991.  Al  can  be 
reached  at  310  Ivy  Glen  Ct.,  League  City,  TX  77573,  or  via 
CompuServe  at  72010,3574. 
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To  implement  this  system,  you’ll  need  Microsoft’s  MASM 
5.1  or  Borland’s  TASM  and  an  AT-style  computer  with  an 
80386,  80486,  or  80386SX  CPU,  or  an  Intel  Inboard  386/PC. 
While  all  of  the  source  code  listings  (more  than  2000  lines) 
that  accompany  this  two-part  article  will  be  available  online 
with  this  issue,  I’ll  cover  Listings  One  through  Three  in  part 
one  and  Listings  Four  through  Seven  in  part  two. 

About  PROT 

PROT.ASM  (see  Listing  One,  page  81)  and  its  associated 
include  files  make  up  a  true,  32-bit  DOS  extender.  This 
extender  allows  you  to  write  assembly  language  programs 
that  use  32-bit  addressing  and  access  all  of  the  80386’s 
special  features.  In  addition,  PROT  allows  you  to  do  I/O 
using  the  ROM  BIOS  or  DOS.  PROT  also  has  provisions  for 
direct  access  to  the  PC  hardware  (for  instance,  to  write 
directly  to  the  screen). 

PROT  doesn’t  allow  you  to  call  interrupts  that  terminate 
your  program  (such  as  INT  20H  or  INT  21H  function  4CH); 
instead,  PROT  provides  its  own  calls  for  program  termina¬ 
tion.  Obviously,  the  two  BIOS  calls  that  switch  the  processor 
into  protected  mode  (INT  15H  functions  87H  and  89H) 
won’t  operate  properly.  (Their  functions  are  superfluous 
under  PROT  anyway.)  Since  PROT  doesn’t  allow  program 
termination  calls,  it  cannot  deal  with  spawning  DOS  subpro¬ 
cesses  using  INT  21 H  function  4BH,  nor  does  it  allow  the 
undocumented  DOS  command  processor  “backdoor”  in¬ 
terrupt  (INT  2EH).  Of  course,  if  you  must  spawn  a  subpro¬ 
cess,  you  can  always  return  to  real  mode  temporarily. 


PROT  does  include  macros  to  assemble  some  32-bit  in¬ 
structions  since  the  linker  that  comes  with  MASM  doesn’t 
handle  certain  32-bit  references  properly.  These  macros  are 
particularly  useful  when  the  assembler  generates  a  negative 
32-bit  relative  number.  In  that  case,  the  linker  only  fills  in 
the  bottom  16  bits  of  the  number,  which  changes  the  nega¬ 
tive  relative  jump  into  a  positive  jump.  The  supplied  macros 
overcome  this  difficulty. 

The  Segments 

Any  program  written  with  PROT  starts  with  23  segments 
that  are  defined  in  the  GDT  (although  you  can  define  more 
in  your  program).  PROT  does  not  set  up  an  LDT,  but  your 
code  can  easily  set  one  up  if  you  require  it.  The  segments 
your  programs  will  use  are  shown  in  Table  1 . 

When  your  program  runs,  the  segment  registers  are  in¬ 
itialized  to  the  values  shown  in  Table  2.  GDT.INC  (Listing 
Two,  page  86)  contains  the  names  of  all  of  the  predefined 
segment  descriptors.  Your  program  will  begin  as  a  privilege 
level  0  task. 

PROT’s  other  components  include  EQUMAC.INC  (Listing 
Three,  page  86),  discussed  in  detail  below;  STACKS. INC 
(Listing  Four),  which  contains  the  stack  segments;  INT386.INC 
(Listing  Five)  for  386  interrupt  handling;  TSS.INC  (Listing 
Six),  which  contains  the  task  state  segment  definitions;  and 
CODE16.INC  (Listing  Seven),  which  is  the  16-bit  DOS  entry/ 
exit  code.  I’ll  cover  the  last  four  in  next  month’s  installment. 

Writing  a  Program 

Your  program  goes  into  a  file  with  a  .PM  (protected  mode) 
extension.  It  should  consist  of  the  two  user  segments 
SELJJDATA  and  SEL_UCODE.  Execution  begins  with  the 
USER  procedure. 

Example  1  shows  the  simplest  possible  PROT  program; 
it  does  nothing  except  return  to  DOS.  The  NODATA  macro 
declares  an  empty  data  segment,  since  the  program  uses 
no  data.  The  line  BACK2DOS  is  equivalent  to  JMPABS32 
SEL_CODEl6,BACKl6,  which  returns  to  DOS.  If  you  load  a 
value  in  the  AL  register  before  making  this  jump,  DOS 
receives  that  value  as  the  return  code.  The  BACK2DOS 
macro  accepts  an  optional  argument,  which  the  macro  loads 
into  AL  for  you.  PROT  will  also  return  to  DOS  if  a  breakpoint 
or  an  unexpected  interrupt  occurs.  In  this  case,  DOS  re¬ 
ceives  a  return  code  of  7FH. 

The  PROT_CODE  and  PRO T__ CODE_END  statements  are 
actually  macros  defined  in  EQUMAC.INC  (Listing  Three). 
Use  these  macros  to  define  your  main  code  segment,  as 
shown  in  Example  1.  The  corresponding  PROT_DATA  and 
PROT_DATA_END  macros  allow  you  to  define  your  main 
data  segment  if  needed. 

Most  programs  will  make  calls  to  DOS  or  the  BIOS.  In 
PROT,  the  call86  routine  makes  this  possible.  This  routine 
takes  a  pointer  (in  ES:EBX)  to  a  parameter  block  (see  Figure 
1).  A  macro,  VM86CALL,  performs  the  far  call  to  call86. 

Example  2  shows  a  short  DOS  program  that  prints  a 
message  using  DOS  function  9  and  the  corresponding  pro¬ 
gram  written  with  PROT.  The  statement  PROT_STARTUP 
(again,  a  macro  in  EQUMAC.INC)  sets  the  default  parameter 
block’s  data  segment  and  stack.  You  can  override  these 
defaults  when  you  call  PROTJSTARTUP. 

When  calling  call86,  all  registers  except  the  segment 
registers,  EFLAGS,  EBX,  and  EBP  are  passed  to  the  VM86 
interrupt  unchanged.  EBX,  EBP,  EFLAGS,  and  the  segment 
registers  receive  their  values  from  the  parameter  block.  If 
you  want  the  segment  registers  returned  in  the  parameter 
block,  set  the  first  word  in  the  block  to  a  non-zero  value. 
Otherwise,  the  parameter  block  remains  unchanged.  Upon 
return,  all  non-segment  registers  will  contain  the  values 
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returned  by  the  VM86 call. 

The  SEL_DATA  segment  defines  a  default  parameter  block 
(pintframe) .  You  may  use  this  for  all  of  your  DOS  calls,  or 
for  better  performance  you  can  define  multiple  blocks  by 
using  the  vm,86blk  structure  in  EQUMAC.INC.  For  instance, 
you  might  define  three  different  blocks:  one  for  disk  reads, 
one  for  BIOS  screen  writes,  and  another  for  other  BIOS 
calls.  Do  not  use  the  other  parameter  blocks  defined  in 
SEL_DATA  ( hintframe  and  cintframe)  in  your  programs. 
These  parameter  blocks  handle  hardware  interrupts  and 
critical  errors  exclusively. 

Whenever  you  pass  addresses  to  DOS  and  BIOS  routines, 


Segment 

Function 

SEL_DATA0 

4-gigabyte  data  segment  starting  at  location 

0.  With  this  segment,  you  can  address  any 
memory  location  you  please.  Be  careful. 

SEL_GDT 

Alias  for  the  GDT.  You  may  need  this  to  add 
more  segments  or  find  information  about  the 
predefined  segments. 

SEL_VIDEO 

4K-data  segment  at  video  page  0.  PROT 
determines  your  video  adapter  type,  sets  the 
page  to  0,  and  sets  SEL_VIDEO  to  the  proper 
address. 

SELDATA 

Contains  PROT’s  system  data  area.  Several 
useful  variables  reside  in  this  segment. 

SELJDT 

Alias  for  the  protected-mode  interrupt  vector 
table.  You  may  wish  to  modify  this  segment 
so  you  can  add  interrupts  to  the  system. 

SELJJCODE 

Your  program’s  default  code  segment. 

SELJJDATA 

Your  program’s  default  data  segment. 

SEL_PSP 

256-byte  long  data  segment  that  contains 
your  program’s  DOS  PSP.  You  can  use  this 
segment  to  access  the  command  line  and 
other  MS-DOS  specific  data. 

SEL_ENV 

Contains  your  program’s  DOS  environment 
block. 

SEL_FREE 

Starts  at  the  first  free  location  of  DOS  mem¬ 
ory  and  goes  to  the  end  of  DOS  RAM  (640K 
or  less). 

SEL_EFREE 

Similar  to  SEL_FREE,  but  begins  at  the  start 
of  extended  memory  and  continues  to  the 
end  of  extended  memory  as  reported  by  INT 

I5H,  function  88H.  If  no  extended  memory 
exists,  SEL_EFREE  will  have  a  limit  of  0. 

Table  1:  Segments  used  by  a  PROT program 


DS=SEL_UDATA 

ES=SEL_DATA 

FS=SEL_DATAO 

GS=SEL_ViDEO 


Table  2:  Initial  segment  register  values 


File: 

USER. INC 

;  SET 

UP 

EMPTY  DATA  SEGMENT 

NODATA 

;  SET 

UP 

CODE  SEGMENT  -  PROGRAM  RETURNS  TO  DOS 

PROT  CODE 

USER 

PROC  NEAR 

BACK2D0S 

USER 

ENDP 

PROT  CODE  END 

Example  1:  A  simple  PROT program 


you  must  ensure  that  they  point  somewhere  in  the  first 
megabyte  of  memory.  If  you  are  using  a  lot  of  extended 
memory  areas  for  storage,  it  might  be  wise  to  allocate  one 
or  two  temporary  storage  areas  in  low  memory  just  to 
handle  DOS  calls. 

By  default,  PROT  ignores  Ctrl-C  interrupts.  Your  program 
can  test  the  flag  breakkey  in  the  SELJDATA  segment  to  see 
if  a  break  event  occurred.  You  can  set  the  locations  break_seg 
and  break_off  to  the  address  of  your  own  protected-mode 
break  handler  if  you  wish.  The  routine  pointed  to  will 
execute  after  calling  a  DOS  or  BIOS  routine  with  call86  if  a 
break  has  occured.  PROT  also  ignores  the  Ctrl-Alt-Del  key¬ 
stroke  that  normally  reboots  the  computer,  since  rebooting 
in  protected  mode  will  cause  the  system  to  crash. 

PROT  provides  a  default  critical  error  handler  similar  to 
the  one  found  in  DOS.  By  setting  crit_seg  to  0  you  can 


Address 

Member  name 

BLOCK+O 

Segment  register  flag  (see  text) 

VMSEGFLAG 

BLOCK+4 

Interrupt  number 

VMINT 

BLOCK+8 

EFLAGS 

VMFLAGS 

BLOCK+12 

ESP 

VMESP 

BLOCK+16 

SS 

VMSS 

BLOCK+20 

ES 

VMES 

BLOCK+24 

DS 

VMDS 

BLOCK+28 

FS 

VMFS 

BLOCK+32 

GS 

VMGS 

BLOCK+36 

EBP 

VMEBP 

BLOCK+40 

EBX 

VMEBX 

Figure  1:  Parameter  block  for  ca!186  routine 


Real  Mode  Program 

REALPGM 

PROC 

MOV  AX, SEG  STACKAREA 

MOV  SS, AX 

MOV  SP, OFFSET  STACKAREA 
MOV  AX, SEG  DAT SEG 

;  SET  UP  STACK 

MOV  DS, AX 

;  SET  UP  DATA  SEGMENT 

MOV  DX, OFFSET  MESSAGE 

;  LOAD  POINTER  TO 

MESSAGE 

MOV  AH, 9 

INT  21H 

MOV  AH, 4CH 

;  PRINT  MESSAGE 

INT  21H 

;  RETURN  TO  DOS 

REALPGM 

ENDP 

PROT  Equivalent 

USER 

PROC 

PROT  STARTUP 

;  SET  UP  STACK/DS 

MOV  AX, 21H 

MOV  PINTFRAME. VMINT, EAX 
MOV  EDX, OFFSET  MESSAGE 

MOV  AH, 9 

MOV  EBX, OFFSET  PINTFRAME 

/LOAD  POINTER  TO 

MESSAGE 

VM86CALL 

;  PRINT  MESSAGE 

BACK2DOS 

/RETURN  TO  DOS 

USER 

ENDP 

Example  2:  DOS  and  PROT  code  fragments  to  print  a 
message  using  DOS  service  9 
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(continued  from  page  18) 

completely  disable  critical  error  handling  and  PROT  will 
ignore  critical  errors.  You  can  set  crit_seg  and  crit_offto  the 
segment  and  offset  of  your  own  critical  error  handler.  A 
protected-mode  critical  error  handler  is  very  similar  to  a 
normal  real-mode  error  handler.  A  real-mode  handler  gets 
status  information  in  AX,  DI,  BP,  and  SI.  For  protected-mode 
handlers,  the  AX  value  is  in  critax;  the  DI,  BP,  and  SI  values 
are  in  critdi,  critbp,  and  critsi ,  respectively.  Your  error 
handler  must  return  a  value  in  AL  that  determines  the  action 
to  take.  If  AL  is  0,  PROT  will  fail  the  error.  If  it  is  1,  PROT 
retries  the  error.  And  if  AL  is  equal  to  2,  PROT  will  abort  to 
DOS.  If  you  choose  to  abort  the  program  due  to  a  critical 
error,  PROT  returns  a  7FH  to  DOS. 

Two  DOS  interrupts,  INT  25H  and  26H,  do  not  properly 
return  to  their  callers.  They  normally  leave  the  caller’s  flags 
on  the  stack  when  returning.  When  programming  with 
PROT  in  protected  mode,  these  flags  do  not  remain  on  the 
stack.  The  same  effect  can  be  obtained  with  the  code  shown 


in  Example  3-  Flowever,  this  is  not  a  problem  when  running 
programs  in  virtual-86  mode,  but  only  in  protected  mode. 
Of  course,  if  you  don’t  need  the  old  flags,  and  you  usually 
won’t,  you  don’t  need  to  worry. 

PROT  uses  several  routines  that  may  also  be  useful  to  the 
applications  programmer,  as  shown  in  Table  3.  Your  pro¬ 
grams  can  call  these  routines  via  a  far  call  (the  CALL32F 
macro). 

Putting  It  Together 

After  creating  a  source  file  and  setting  any  equates  that  you 
want  to  change  at  the  top  of  EQUMAC.INC,  you  can  compile 
a  PROT  application  by  using  the  batch  file  shown  in  Figure 
2.  The  resulting  EXE  file  will  execute  from  the  DOS  prompt. 
If  PROT  does  not  find  a  386  or  486,  it  will  exit  with  an  error 
message  and  return  80H  to  DOS.  PROT  will  also  exit  with 
an  80H  to  DOS  if  another  program  already  has  the  computer 
in  protected  mode. 

(continued  on  page  24) 


Protected-Mode  Operations  on  a  PC 


If  protected  mode  is  so  great,  why  isn’t  it  used  more  often 
on  386  PCs?  There  are  a  host  of  difficulties  in  trying  to  get 
a  DOS-based  PC  to  do  anything  useful  in  protected  mode. 
The  primary  difficulty  is  DOS  itself;  DOS  expects  to  run  in 
real  mode.  The  same  goes  for  the  ROM  BIOS  (except  in 
the  PS/2-type  computers).  To  remain  compatible  with  the 
old  8088-based  PCs,  all  386  PCs  have  one  of  their  address 
lines  switched  off  to  prevent  accessing  memory  above  1 
Mbyte.  Finally,  some  of  the  hardware  interaipts  used  by 
the  PC  conflict  with  the  interrupts  the  80386  uses  for  error 
handling  in  protected  mode. 

With  all  of  these  obstacles,  tire  prospect  of  running  protected- 
mode  programs  on  a  DOS-based  PC  seems  bleak.  How¬ 
ever,  the  PC’s  address  lines  and  interrupt  controllers  are 
reprogrammable.  Better  still,  the  80386  has  a  special  mode 
(virtual-86  or  VM86  mode)  that  allows  old-style  8086  pro¬ 
grams  (like  DOS  or  the  BIOS)  to  operate  in  protected  mode. 

According  to  the  Intel  documentation,  running  8086 
code  in  VM86  mode  is  fairly  straightforward.  However, 
attempting  to  implement  Intel’s  strategy  fails  when  it  comes 
to  the  PC’s  BIOS  and  DOS.  Intel  assumes  that  your  8086 
code  will  always  call  intermpts  with  an  //VTinstruction  and 
return  with  an  IRET  instruction.  However,  this  seems  to 
be  the  exception  rather  than  the  rule  with  the  PC’s  system 
code.  Some  DOS  extenders  deal  with  this  problem  by 
returning  to  real  mode  for  each  system  call,  then  switching 
back  to  protected  mode  upon  completion.  While  this  is 
fairly  easy  to  implement,  it  causes  problems  if  your  pro¬ 
grams  are  written  to  take  advantage  of  the  80386’s  multi¬ 
tasking  capabilities. 

To  run  the  BIOS  and  DOS  in  VM86  mode,  you  have  to 
provide  the  386  with  a  VM86  task.  You  have  to  emulate 
certain  instructions,  most  notably  interrupts.  You  also  have 
to  reprogram  the  hardware  interrupt  controllers  and  redi¬ 
rect  their  interrupts  to  the  proper  routines. 

A  VM86  task  requires  emulation  for  the  CLI,  STI,  LOCK, 
PUSHF,  POPF,  INT,  and  IRET  instructions.  This  is  to  pre¬ 
vent  the  VM86  task  from  disrupting  other  tasks  that  might 
be  running  under  protected  mode.  PROT  emulates  all  of 
these  instructions  except  LOCK,  which  isn’t  really  an  instruc¬ 
tion  but  a  prefix.  Only  multiprocessor  systems  use  LOCK, 
so  PC  software  runs  fine  without  it. 


In  theory,  emulating  INT  and  IRET  is  fairly  straightfor¬ 
ward.  The  execution  of  an  INT  or  IRET  in  VM86  mode 
causes  a  general  protection  exception  (INT  13)  When  you 
detect  an  INT  instruction,  simply  determine  the  required 
interrupt  vector  address,  simulate  the  interrupt,  catch  the 
corresponding  IRET,  and  return  to  the  calling  program.  In 
practice,  the  PC  BIOS  and  DOS  do  not  always  have  a 
one-to-one  correspondence  between  /ATS  and  IRETs  (a 
problem  we  will  explore  in  detail  next  month).  Only  the 
normal  INT/IRET  sequence  provides  the  INT  13  required  to 
emulate  these  instructions. 

Some  DOS  extenders  take  different  approaches.  Some 
actually  switch  the  processor  back  to  real  mode  for  each 
call  to  DOS  or  the  BIOS.  Other  VM86  programs  (such  as 
EMS  memory  simulators)  let  real-mode  calls  run  unpro¬ 
tected,  which  shuts  you  off  from  many  of  the  80386’s  special 
features  and  only  allows  DOS  calls  from  VM86  mode. 
PROT  actually  runs  DOS  and  the  BIOS  as  a  VM86  task. 

Note  that  some  of  the  protected-mode  features  that  are 
also  available  in  real  mode  are  unavailable  in  VM86  mode. 
For  example,  a  VM86  task  can’t  switch  the  processor  into 
protected  mode  in  the  same  way  a  real-mode  program 
can.  This  means  some  386-specific  software  may  not  run 
with  PROT.  Also,  some  very  specific  BIOS  routines  that 
deal  with  extended  memory  and  protected  mode  may  not 
work.  However,  with  protected-mode  programming,  you 
won’t  need  BIOS  services  to  manage  extended  memory 
or  switch  modes. 

PROT  provides  facilities  to  handle  Control-C  interrupts 
and  critical  device  errors  in  protected  mode.  By  default, 
PROT  ignores  Control-C  interrupts  and  has  a  critical  error 
handler  similar  to  the  one  provided  by  DOS.  PROT  also 
catches  and  ignores  the  Ctrl-Alt-Del  keystroke  that  nor¬ 
mally  resets  the  computer  since  the  PC’s  BIOS  won’t  re¬ 
boot  in  protected  mode. 

PROT  reprograms  the  interrupt  controllers  so  that  hard¬ 
ware  interrupts  can  coexist  with  80386  exceptions.  When 
PROT  detects  a  hardware  interrupt,  PROT  automatically 
redirects  it  to  the  proper  BIOS  or  DOS  interrupt  handler. 

— -A.W. 
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(continued  from  page  20) 

I’ve  included  two  short  sample  programs  to  illustrate 
PROT  programming  and  a  protected-mode  file  browser, 
FBROWSE.PM.  Due  to  space  limitations,  however,  these 
programs  are  not  included  in  the  listings  section,  but  are 
available  directly  through  DDJ. 

That’s  it  for  this  issue.  Next  month  I'll  dive  into  debug¬ 
ging,  386  exceptions,  and  take  a  more  in-depth  look  at 
PROT  itself. 
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MOV  EAX,25H 

MOV  PINTFRAME . VMINT, EAX 

PUSHF 

;  (Or  PUSHFD) 

VM8 6 CALL 

;  Call  XNT  25  or  26 

Example  J:  Maintaining  the  caller’s  flags  on  the  stack 
when  returning  in  protected  mode 


Routine 

Purpose 

CLS 

Clears  page  0  of  the  video  display  directly. 

OUCH 

Prints  the  character  in  AL  to  page  0  of  the 
video  display  using  direct  video  access. 

CRLF 

Perform  a  carriage  return/line  feed  using  the 
OUCH  routine. 

MESSOUT 

Prints  the  zero-terminated  string  pointed  to 
by  DS:EDX  using  OUCH.  Modifies  EBX. 

HEXOUT 

Outputs  the  byte  in  AL  in  hex  using  OUCH. 

HEXOUT2 

Outputs  the  word  in  AX  in  hex  using  OUCH. 

HEXOUT4 

Outputs  the  double  word  in  EAX  in  hex  using 
OUCH. 

MAKE_GATE 

Makes  a  task  gate,  trap  gate,  interrupt  gate, 
or  call  gate.  Call  this  routine  with  ES:EDX 
pointing  to  the  table’s  (GDT,  LDT,  or  IDT) 
base  address  (as  a  read/write  segment).  Set 

CX  to  the  target  descriptor,  EBX  to  the  target 
offset  (if  applicable),  SI  to  the  selector  for  the 
gate,  AH  to  one  of  the  access  right  bytes 
(ARB)  defined  in  EQUMAC  INC  (Listing  Two), 
and  AL  to  the  word  count  (for  call  gates  only). 

MAKE_SEG 

Makes  a  segment  descriptor.  Call  this  rou¬ 
tine  with  ES:EDX  pointing  to  the  GDT  or  LDT 
table  base  address  (as  a  read/write  data 
segment).  EBX  is  the  base  address  of  the 
segment,  ECX  is  the  limit  (in  bytes),  AL  is  0 
for  a  1 6-bit  segment  or  1  for  a  32-bit  seg¬ 
ment,  and  AH  is  one  of  the  access  rights 
bytes  (ARB)  defined  in  EQUMAC. INC. 

Table  J:  PROT’s programmer  callable  routines 


echo  off 

if  X%1==X  goto  :errexit 
if  NOT  X%2==X  goto  :errexit 

masm  /DPROGRAM=%1  PROT.ASM,%1  ,OBJ,%1  .LST; 

if  ERRORLEVEL  1  goto  :exit 

link  %1 ; 

goto  :exit 

:errexit 

echo  PMASM  -  An  MASM  driver  for  the  PROT  386  DOS  Extender 
echo  usage:  PMASM  progname 

echo  Assembles  the  file  progname. pm  into  progname.exe 
echo  The  PROT  system  is  copyright  (C),  1 989  by  Al 
echo  Williams. 

echo  Please  see  the  file  "PROT.ASM”  for  more  details. 

:exit 


Figure  2:  Batch  file  used  to  compile  a  PROT program  with 
MASM 

Source  Code  Availability 

As  a  service  to  our  readers,  all  source  code  is  available  on  a 
single  disk  and  on  line.  To  order  the  disk,  send  $14.95  (Calif, 
residents  add  sales  tax)  to  Dr.  Dobb’s  Journal,  501  Galveston 
Drive,  Redwood  City,  CA  94063,  or  call  800-356-2002  (inside 
Calif.)  or  800-533-4372  (outside  Calif.).  Specify  issue  num¬ 
ber  and  disk  format.  Code  is  also  available  through  M&T’s 
Telepath  online  service  (via  TYMNET)  and  through  the  DDJ 
Forum  on  CompuServe  (type  GO  DDJ). 

DDJ 

(Listings  begin  on  page  81.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  1. 


24 


Dr.  Dobb’s  Journal,  October  1990 

899 


Opening  OS/2’s 
Backdoor 

DEVHLP.SYS  provides  low-level  services 


Andrew  Schulman 


»|p  -y  nlike  real-mode  MS-DOS, 
|  which  gives  the  programmer 
total  access  to  its  1-Mbyte  sand- 
I  box,  the  protected-mode  OS/2 
Vw"'  operating  system  takes  strict 
control  over  its  vastly  larger  address 
space  (up  to  16  Mbytes  of  physical 
memory  mapped  into  up  to  1  gigabyte 
of  virtual  memory).  Strict  control  over 
memory  is  necessary  not  only  because 
there  is  so  much  more  of  it  in  OS/2, 
but  also  because  OS/2  supports  multi¬ 
tasking  (again  in  contrast  to  MS-DOS, 
which  only  allows  multitasking  via  in¬ 
terrupt  handlers). 

However,  “there  ain’t  no  such  thing 
as  a  free  lunch.”  OS/2’s  tight  manage¬ 
ment  of  memory  means  that  an  appli¬ 
cation  can’t  freely  peek  and  poke  arbi¬ 
trary  locations  in  memory.  While  this 
is  good  because  it  prevents  tasks  from 
bashing  the  operating  system  (or  each 
other),  it  does  make  it  nearly  impossi¬ 
ble  for  applications  to  perform  memory- 
mapped  I/O  or  access  memory  on 
adapter  cards. 

It  also  makes  it  difficult  to  write  OS/2 
diagnostic  tools.  For  example,  prob¬ 
ably  every  PC  programmer  has  a  utility 
such  as  CORELOOK,  MAPMEM,  RAM- 
SCAN,  or  XRAY  in  his  or  her  \BIN 
directory.  How  would  you  port  such  a 


Andrew  is  an  engineer/writer  at  Phar 
Lap  Software  in  Cambridge,  Mass.  He 
is  a  contributing  editor  for  Dr.  Dobb’s 
Journal.  Andrew  can  be  reached  by 
phone  at  61 7-876-2102  or  on  Compu¬ 
Serve  at  76320,302. 


utility  to  OS/2?  Or  how  would  you 
write  a  program  that  displays  all  named 
semaphores  in  the  system?  (Hint:  Walk 
through  memory,  looking  for  strings 
that  begin  with  the  pattern  “\SEM\”. 
The  real  puzzle,  of  course,  is  how  to 
walk  through  all  of  memory.) 

The  OS/2  application  program  inter¬ 
face  (API)  does  have  one  function  that 
seems  to  help  with  this  task:  Vio- 
GetPhysBuf( ).  You  pass  in  a  32-bit 
absolute  physical  address,  presumably 
corresponding  to  a  video  adapter’s  dis¬ 
play  buffer,  and  VioGetPhysBufC )  re¬ 
turns  a  selector  that  can  be  used  to 
manipulate  the  buffer  directly.  There’s 


nothing  to  prevent  us  from  using  this 
to  manipulate  memory  not  on  a  video 
adapter. 

The  VIOPHYSBUF  structure  that  Vio¬ 
GetPhysBufC  )  takes  has  one  crucial  re¬ 
striction,  however:  The  physical  address 
must  be  in  the  range  AOOOOh  through 
BFFFFh.  This  makes  some  sense  be¬ 
cause,  without  restrictions,  the  single 
VioGetPhysBufC )  entry  point  could  be 
used  as  a  Trojan  horse  to  defeat  OS/2 
memory  protection.  But  then  we’re  stuck 
with  the  riddle  of  how  to  examine  physi¬ 
cal  memory  locations  outside  the  range 
AOOOO-BFFFF. 

With  mounting  irritation,  we  comb 
through  IBM’s  OS/2  documentation  look¬ 
ing  for  some  function  that  will  do  the 
trick  (in  API-rich  environments  such 
as  OS/2  or  Windows,  programming 
seems  to  have  been  reduced  to  the 
ability  to  search  through  a  parts  cata¬ 
log).  Finally,  in  the  section  on  device 
drivers,  we  find  something  that  sounds 
like  what  we’re  looking  for: 

PhysToUVirt 

Map  Physical  To  User  Virtual  Address 

IBM’s  documentation  says  that  this 
“converts  a  32-bit  physical  address  to 
a  valid  selector  offset  pair  addressable 
out  of  the  current  LDT.”  This  is,  in  fact, 
exactly  what’s  needed  to  do  memory- 
mapped  I/O:  Bang  on  adapter  cards 
and  walk  through  physical  memory. 

PhysToUVirt  is  a  DevHlp,  one  of  about 
55  helper  routines  OS/2  provides  for 
device  drivers.  In  his  indispensable  book 
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(continued  from  page  28) 

Inside  OS/2  (Microsoft  Press,  1988),  Gor¬ 
don  Letwin  refers  to  the  DevHlps  as 
OS/2’s  “backdoor.”  Many  of  the  device 
helpers  have  capabilities  found  nowhere 
else  in  OS/2.  A  few  examples: 
ABIOSCommonEntry  and  ABIOSCall 
(call  the  PS/2  ROM  BIOS),  Alloc- 
Phys (allocates  physical  memory),  Lock 
(lock  virtual  memory  against  reloca¬ 
tion  or  swap),  RealToProt  (switch  from 
real  to  protected  mode),  SetIRQ  (attach 
an  interrupt  handler  to  an  IRQ  level), 
and  VirtToPhys  (convert  locked  virtual 
address  to  physical  address). 

There’s  one  hitch:  Only  device  driv¬ 
ers  can  call  the  DevHlps.  Unlike  the 
rest  of  the  OS/2  API,  device  helpers 
use  a  register-based,  parameter-pass¬ 
ing  mechanism  much  like  the  “old” 


(but  by  no  means  defunct)  MS-DOS 
INT 21  interface.  All  device  helpers  share 
a  common  entry  point,  whose  address 
is  made  known  to  the  driver  only  at 
initialization  time.  Individual  functions 
(such  as  PhysToUVirl)  are  specified  with 
a  number  in  the  DL  register. 

Figure  1  shows  a  sample  invocation 
of  the  PbysToUVirt  device  helper.  A 
moment’s  consideration  should  con¬ 
vince  you  that  this  facility  to  map  physi¬ 
cal  addresses  into  a  user’s  address  space 
is  all  that  is  required  to  circumvent  any 
inconveniences  of  protected  mode.  Com¬ 
bined  with  the  Intel  SGDT  instruction, 
the  PbysToUVirt  DevHlp  could  be  used 
to  control  the  protected-mode  environ¬ 
ment.  OS/2’s  designers  probably  made 
a  wise  choice  in  allowing  this  function 
to  be  called  only  from  a  device  driver. 


Now,  you  could  get  the  company’s 
device-driver  guru  to  write  a  separate 
OS/2  device  driver  to  accompany  each 
application  that  you  wish  could  call  a 
DevHlp.  For  example,  to  use  PhysTo- 
UVirt ,  write  a  device  driver  that  maps 
access  to  physical  memory  onto  the 
read  and  write  operations.  This  would 
resemble  the  Unix  /dev/mem  device:  A 
memory  fetch  is  a  read,  and  a  store  is 
a  write;  memory  is  just  another  stream 
of  bytes. 

This  is  a  good  idea,  but  the  resulting 
driver  only  supports  the  PbysToUVirt 
DevHlp.  When  you  realize  that  you  also 
need  the  VirtToPhys  DevHlp,  you’re  out 
of  luck.  Isn’t  there  any  way  for  a  “nor¬ 
mal”  OS/2  Ring  3  application  to  call 
any  device  helper? 

There  is.  Using  the  function  DosDev- 


Walking  the  OS/2  Device  Chain 

Arthur  Rothstein 


DRVRLIST.EXE  is  a  DEVHLP  appli¬ 
cation  that  lists  the  device  drivers  in 
OS/2.  The  design  considerations  are 
similar  to  those  of  the  analogous 
DOS  program.  Descriptive  informa¬ 
tion  about  a  driver  is  contained  in  its 
device  control  block  (DCB),  and  the 
DCBs  are  linked  via  a  double-word 
pointer  at  offset  0.  The  last  DCB  in  the 
chain  has  a  pointer  with  offset  OFFFFH. 
The  challenge  is  to  find  the  first  in  the 
chain. 

The  first  two  DCBs  are  NUL  and 
CON,  and  both  are  in  OS/2’s  global 
data  segment.  This  segment  is  mapped 
by  a  bimodal  selector,  one  that  de¬ 
scribes  the  same  physical  memory 
whether  the  CPU  is  in  real  or  pro¬ 
tected  mode.  The  bimodal  selector 
varies  with  the  maintenance  level  of 
the  kernel.  The  segment  is  also 
mapped  by  selector  50H,  which  does 
not  vary  with  the  kernel  maintenance 
level  (it  even  works  with  IBM  SE  1.2). 
The  program,  source  code  for  which 
appears  in  DRVRLIST.C  in  Listing  Two 
(page  96),  and  which  uses  the  header 
file  DEVHLP.  H  in  Listing  Three  (page 
97),  searches  for  the  first  occurrence 
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of  the  driver  name,  “NUL”  followed 
by  five  blanks,  then  backs  up  10  bytes. 
When  displaying  the  driver  address, 
the  program  uses  the  bimodal  selec¬ 
tor  instead  of  50H.  Here  is  sample 
output  from  DRVRLIST  under  OS/2 
1.1: 

Address  Name 
9C0:03EE  NUL 
9C0:O4OA  CON 
798:0000  COM1 
748:0000  SINGLEQ$ 

730:0000  MOUSE$ 

720:0000  POINTERS 

6DO:0000  devhlpxx 

390:0000  Block  device,  3  logical  units 

380:0000  PRN 

380:001A  LPT1 

380:0034  LPT2 

380:004E  LPT3 

360:0000  KBDS 

350:0000  SCREENS 

340:0000  CLOCKS 

The  DCBs  are  mapped  by  GDT  se¬ 
lectors,  which  the  program,  running 
at  privilege  Level  3,  cannot  access. 
Given  a  GDT  selector,  the  program 
uses  the  VirtToPhys  device  helper  to 
get  the  physical  address  mapped  by 
the  selector,  then  the  PbysToUVirt  de¬ 
vice  helper  to  get  an  LDT  selector  to 
the  same  physical  memory.  These  two 
calls  in  sequence  constitute  function 
MakeSeK ).  The  LDT  selector  acquired 


by  MakeSel( )  maps  a  full  64K  byte 
starting  at  the  physical  address,  usu¬ 
ally  more  than  the  GDT  selector  maps. 
The  program  uses  this  LDT  selector 
to  access  a  DCB.  After  the  program 
finishes  using  a  given  selector,  it  again 
calls  the  PbysToUVirt  device  helper, 
this  time  to  release  the  selector.  The 
release  is  performed  in  function  Re- 
leaseSel(  ). 

The  global  data  segment  and  the 
DCBs  are  fixed  in  memory.  Their  GDT 
selectors  and  the  physical  addresses 
to  which  these  selectors  map  remain 
unchanged  at  least  until  the  system 
is  rebooted.  In  general  the  reverse  is 
true.  Selectors  come  and  go,  and  those 
that  are  unchanged  may  map  to  vari¬ 
ous  physical  addresses  during  the  life 
of  the  system.  An  example  of  the  first 
is  the  process  control  block,  which  is 
assigned  to  a  unique  GDT  selector 
during  the  life  of  a  process.  An  exam¬ 
ple  of  the  second  is  selector  28H, 
which  maps  the  LDT  of  the  active 
thread.  When  the  selectors  —  or  their 
physical  memory  —  are  not  fixed,  an 
application  must  lock  the  memory  with 
the  Lock  device  helper,  before  calling 
VirtToPhys  or  PbysToUVirt  to  ensure 
valid  results.  Even  then  you  must  ex¬ 
ercise  caution.  We  don’t  know,  for 
example,  how  OS/2  reacts  when  it 
attempts  to  kill  a  process  whose  pro¬ 
cess  control  block  has  been  locked 
by  another  application. 
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(continued  from  page  30) 

IOCtl( )  (equivalent  to  ioctl( )  in  Unix 
and  INT  21h  AH  =  44h  in  MS-DOS), 
any  OS/2  application  can  call  a  device 
driver,  and  the  device  driver  can  then 
call  the  device  helper  on  the  applica¬ 
tion’s  behalf.  Because  DosDevIOCtl( ) 
allows  a  program  to  issue  any  device¬ 
specific  commands  that  are  not  sup¬ 
ported  by  other  OS/2  API  functions, 
now  all  we  need  is  a  device  driver  that 

0S/2’s  tight 
management  of 
memory  means  that  an 
application  can’t  freely 
peek  and  poke  arbitrary 
locations  in  memory 


acts  as  a  DevHlp  “server,”  accepting 
DevHlp  requests  sent  to  it  via  ioctl 
packets. 

I  have  written  such  a  driver,  called 
DEVHLP.SYS.  It  is  a  totally  generic  de¬ 
vice  driver,  whose  sole  purpose  is  to 
call  device  helpers  on  behalf  of  “nor¬ 
mal”  Ring  3  applications.  In  one  sense, 
it  is  a  “fake”  device  driver  that  solely 
provides  an  ioctl  interface  without  ac¬ 
tually  controlling  a  device;  it  doesn’t 
even  support  the  read  and  write  func¬ 
tions.  In  another  sense,  though,  you 
could  say  that  DEVHLP.SYS  provides 
access  to  the  DEVHLP  device.  The  two 
hundred  lines  of  assembler  source 
(DEVHLPASM)  appear  in  Listing  One 
(page  94). 

In  addition  to  being  used  for  con¬ 
trolling  devices  without  having  to  write 


an  assembly  language  device  driver  (for 
example,  DEVHLP.SYS  is  being  used 
to  interface  with  an  image  scanner  from 
a  Modula-2  program),  DEVHLP.SYS  has 
been  used  in  several  OS/2  diagnostic 
utilities.  In  the  accompanying  text  box 
(“Walking  the  OS/2  Device  Chain”), 
Art  Rothstein  describes  his  program 
DRVRLIST.  In  a  future  DDJ  article,  I 
will  use  DEVHLP.SYS  to  write  a  pro¬ 
gram  for  browsing  the  OS/2  global  de¬ 
scriptor  table  (GDT). 

DEVHLP.SYS  works  in  OS/2,  Ver¬ 
sions  1.0, 1.1,  and  1.2  (both  Microsoft’s 
standard  and  IBM’s  extended  editions). 
It  will  definitely  have  to  be  changed  for 
32-bit  OS/2  2.0.  Note,  however,  that 
we  have  here  a  general  principle:  In 
any  operating  system  in  which  device 
drivers  are  allowed  operations  to  which 
regular  applications  are  denied  access, 
just  map  the  device  driver  operations 
onto  application  ioctl  requests  to  the 
device  driver. 

How  to  Use  DEVHLP.SYS 

Because  DEVHLP.SYS  is  a  device  driver 
it  must  be  loaded  at  system  boot  time 
by  adding  the  following  line  to  your 
OS/2  CONFIG.SYS:  device  =  devhlp.sys. 

An  application  calls  DEVHLP.SYS  us¬ 
ing  the  OS/2  function  DosDevIOCtK ), 
whose  parameters  are  shown  in  Figure 
2.  Note  that  DosDevIOCtl( )  requires  a 
handle  to  a  device;  an  application  can 
get  this  handle  by  opening  the  file 
named  “DEVHLPXX,”  using  either  the 
OS/2  function  DosOpenC )  or  a  func¬ 
tion  such  as  open( )  in  C. 

Applications  ask  for  ioctl  services  us¬ 
ing  a  category  number  and  a  function 
code;  DEVHLP.SYS  currently  provides 
only  one  service:  The  DEVHLP  service, 
whose  category  number  is  128  (the  first 
available  user-defined  category)  and 
whose  function  code  has  been  more-or- 
less  arbitrarily  set  to  60h. 

The  two  remaining  DosDevIOCtl( ) 


MOV  AX,  address  high 

;  top  of  32-bit  physical  absolute  address 

MOV  BX,  address  low 

;  bottom  of  32-bit  physical  absolute  address 

MOV  CX,  length 

;  count  of  bytes  to  map  (0=64k) 

MOV  DH,  request  type 

;  0=code,  1=data,  2=cancel 

MOV  DL,  DevHlp  PhysToUVirt 

;  17h 

CALL  DWORD  PTR  [DevHlp] 

JNC  ok 

;  carry  set=error,  clear=ok 

;  AX  contains  error  code 

ok: ;  ES:BX  contains  virtual  address 

Figure  1:  Invoking  the  PhysToUVirt  DevHlp 

USHORT  DosDevlOCtl(pvData,  pvParms,  usFunction,  usCategory,  hDevice) 

PVOID  pvData; 

/*  far  pointer  to  data  packet  —  >driver  7 

PVOID  pvParms; 

/*  far  pointer  to  parameter  packet  < — driver  7 

USHORT  usFunction; 

/*  two-byte  device  function  7 

USHORT  usCategory; 

/*  two-byte  device  category  7 

HFILE  hDevice; 

/*  two-byte  device  handle  7 

Figure  2:  Parameters  for  calling  DosDevIOCtK  ) 
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(continued  from  page  32) 
parameters  point  to  the  actual  request 
packet  passed  to  the  driver,  and  to  a 
data  packet  into  which  the  driver  should 
place  return  values.  The  two  pointers 
can  be  identical. 

In  the  case  of  DEVHLP.SYS  (because 
we  simply  want  applications  to  be  able 
to  make  DevHlp  calls,  and  because  the 
DevHlps  expect  their  parameters  in  the 
CPU  registers)  the  request  packet  ex¬ 


pected  by  DEVHLP.SYS  is  simply  an 
image  of  the  registers.  The  values  an 
application  puts  in  the  REGS  data  struc¬ 
ture  should  correspond  exactly  to  what 
an  OS/2  device  driver  would  put  in  the 
real  CPU  registers.  DEVHLP.SYS  will 
load  the  real  registers  from  these  fields 
of  the  parameter  packet,  and  will  call 
[DevHlp],  Upon  return  from  DevHlp, 
DEVHLP.SYS  will  store  the  contents  of 
the  registers  back  into  the  data  packet. 


This  is  basically  a  form  of  “remote  pro¬ 
cedure  call.” 

The  C  REGS  structure  shown  in  Fig¬ 
ure  3,  used  both  for  the  request  packet 
passed  to  the  driver  and  for  the  data 
packet  passed  back  by  the  driver,  closely 
resembles  the  union  REGS  used  in  the 
function  int86( )  provided  by  most  MS- 
DOS  C  compilers.  Of  course,  the  same 
structure  can  be  created  in  any  pro¬ 
gramming  language  for  which  there  is 
an  OS/2  version. 

DEVHLP.SYS  was 
designed  to  provide  the 
absolute  minimum 
necessary  for 
application  access  to 
DevHlps 


typedef  struct  { 

USHORT  ax,  bx,  cx,  dx,  si,  di,  ds,  es,  flags; 
}  REGS; 


Figure  3-'  The  DEVHLP  parameter/data  packet 


Now  it  is  simple  to  write  a  version 
of  a  DevHlp  to  be  called  by  a  Ring  3 
application.  For  example,  Figure  4 
shows  a  C  version  of  PhysToUVirt] ), 
which  uses  the  OS/2-supplied  macros 
HIUSHORT(  ),  LOUSHORTC  ),  MAKEU- 
SHORTC  ),  and  MAKEPC  ).  This  version 
opens  and  closes  the  DEVHLPXX  han¬ 
dle  inside  the  function;  if  you  expect 
to  make  a  lot  of  calls  to  PhysToUVirt( ) 
you  could,  of  course,  open  DEVHLPXX 
during  program  initialization.  Figure  4 
also  shows  a  C  enumeration  for  the 
three  requests  handled  by  PhysToUVirt: 
Creating  read-only  executable  ad¬ 
dresses,  creating  read/write  addresses, 
and  releasing  addresses. 

Calling  PhysToUVirt ( )  is  also  sim¬ 
ple.  For  example,  to  examine  100  bytes 
at  absolute  location  FE008h,  refer  to 
Figure  5(a)  and  Figure  5(b)  to  cancel 
the  selector. 

To  walk  through  all  of  physical  mem¬ 
ory,  just  call  PhysToUVirt ( )  in  a  loop 
that  increments  the  physical  address 
each  time  by  64K.  To  map  an  entire 
64K  into  your  address  space  at  one 
time,  pass  PhysToUVirt]  )  a  size  pa¬ 
rameter  of  zero.  Break  out  of  the  loop 
if  PhysToUVirt ( )  fails.  And  remember 
to  cancel  your  selectors  each  time 
through  the  loop:  Selectors  are  a  pre¬ 
cious  resource  in  OS/2! 

Device-Driver  Documentation 

In  order  to  use  DEVHLP.SYS  effectively, 
you  must  know  about  the  DevHlps. 
The  best  documentation  I  have  seen  is 
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(continued  from  page  34) 

IBM’s  OS/2  Technical  Reference  1.1: 
I/O  Subsystems  and  Device  Drivers. 
Volume  1  contains  thorough  descrip¬ 
tions  of  device  driver  functions,  DevHlps , 
and  numerous  DosDevIOCtl  calls.  Vol¬ 
ume  2  describes  Presentation  Manager 
(PM)  “presentation  drivers.” 

Ray  Duncan’s  Advanced  OS/2  Pro¬ 
gramming  (Microsoft  Press,  1989)  con¬ 
tains  an  excellent  70-page  chapter  on 
device  drivers,  with  an  additional  40  pages 
of  reference  material  on  the  DevHlps. 

Raymond  Westwater’s  Writing  OS/2 
Device  Drivers  (Addison-Wesley,  1989) 
contains  a  great  deal  of  useful  informa¬ 
tion  (Ray  gives  a  course  in  OS/2  de¬ 
vice  drivers  for  “Microsoft  University”) 
but  I  wish  it  were  better  organized. 
The  author  sells  a  useful  $50  toolkit 
for  writing  OS/2  device  drivers  in  C 
(contact  Future  Ware,  842  State  Rd., 
Princeton,  NJ  08540,  201-343-2033). 
Unfortunately,  the  material  on  writing 
OS/2  device  drivers  in  C  is  not  in¬ 
cluded  in  Ray’s  book.  Also,  the  book 
is  already  a  little  out  of  date,  missing 
such  DevHlps  as  ABIOSCommonEntry, 
ABIOSCall ,  and  GetLIDEntry ,  all  im¬ 
portant  for  communicating  with  the  OS/ 
2-compatible  Micro  Channel  ABIOS  on 


Figure  4:  PhysToUVirt(  )  in  C 


Figure  5:  Calling  PhysToUVirt(  ) 


IBM  PS/2  machines. 

Speaking  of  ABIOS,  the  key  docu¬ 
mentation  for  this  crucial  topic  is  Phoe¬ 
nix  Technologies’  ABIOS  for  IBM  PS/2 
Computers  and  Compatibles:  The  Com¬ 
plete  Guide  to  ROM-Based  System  Soft¬ 
ware  for  OS/2  (Addison-Wesley,  1989). 
The  Phoenix  book  documents  calling 
the  ABIOSCommonEntry  and  ABIOS- 
Call  DevHlps  from  an  OS/2  device 
driver. 

Finally,  as  this  article  was  going  to 
press,  IBM  has  released  a  program  some¬ 
what  like  DEVHLP,  which  reveals  just 
about  everything  there  is  to  know  about 
OS/2  1.x  memory  utilization.  The  pro¬ 
gram  is  available  in  the  PCMagnet  fo¬ 
rum  on  CompuServe  as  THESEU.ZIP 
(no  source  code  is  available,  however). 

Debugging 

OS/2  device  drivers  can  be  a  pain  to 
debug.  One  of  the  reasons  I  wrote  the 
generic  device  driver  DEVHLP.SYS  was 
to  avoid  having  to  debug  any  device 
driver  other  than  DEVHLP.SYS  itself. 
However,  if  you  are  writing  OS/2  de¬ 
vice  drivers,  in  addition  to  the  debug¬ 
ger  that  comes  with  Ray  Westwater’s 
package  mentioned  earlier,  there  is  also 
the  Universal  Device  Drive  Debugger  for 


#define  DevHlp_PhysToUVirt  0x17 
typedef  enum  { 

UVirt_Exec=0,  UVirt_ReadWrite,  UVirt_Release 
}  UVIRTJYPE; 

//turn  physical  address  into  virtual  address 

void  far  *PhysToUVirt(ULONG  addr,  USHORT  size,  UVIRT  JYPE  type) 

{ 

REGS  r; 

USHORT  sel,  ret=1 ; 

HFILE  devhlp; 
r.ax  =  HIUSHORT(addr); 
r.bx  =  LOUSHORT(addr); 
r.cx  =  size; 

r.si  =  r.di  =  r.ds  =  r.es  =  0;  //  not  used 

r.dx  =  MAKEUSHORT(DevHlp_PhysToUVirt,  type); 

if  ((devhlp  =  openfDEVHLPXX",  0))  !=  -1 ) 

{ 

ret  =  DosDevlOCtl(&r,  &r,  0x60,  128,  devhlp); 
close(devhlp); 

} 

//if  DosDevIOCtl  failed  OR  if  DevHIp  set  carry  flag  . . . 
if  (ret  ||  (r.flags  &  1)) 
return  NULL; 

else 

return  MAKEP(r.es,  r.bx); 

} 


(a)  char  far ‘copyright ; 

copyrights  PhysToUVirt(0xFE008L,  100,  UVirt_ReadWrite); 

(b)  #define  Cancel(pv)  \ 

PhysToUVirt((ULONG)  pv,  0,  UVirt_Release) 
Cancel(copyright); 
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OS/2,  ($249  from  OS  TECHnologies, 
532  Longley  Rd.,  Groton,  MA  01450, 
508-448-9653). 

One  important  feature  of  this  debug¬ 
ger  is  its  ability  to  operate  in  real,  as 
well  as  protected  mode.  Recall  that 
OS/2  device  drivers  can  be  bimodal. 
Few  debuggers  can  handle  bimodal 
applications  (try  using  Microsoft  Code¬ 
View  on  a  DOS  program  that  switches 
from  real  into  protected  mode  using 
DPMI,  for  example),  much  less  bimo¬ 
dal  device  drivers.  The  OSTECHnolo- 
gies  debugger  works  in  the  real  mode 
as  well  as  the  protected-mode  portion 
of  an  OS/2  device  driver. 

This  brings  up  an  important  point: 
Device  drivers  are  the  only  place  in 
OS/2  where  you  can  switch  between 
real  and  protected  mode!  Microsoft  and 
IBM  seem  to  have  designed  OS/2  with 
the  assumption  that  real  mode  was  sim¬ 
ply  going  to  disappear  by  imperial  edict. 
Why  did  they  think  that? 

Design  Principles 

DEVHLP.SYS  was  designed  to  provide 
the  absolute  minimum  necessary  for 
application  access  to  DevHlps.  No  seat 
belts  are  provided!  Using  DEVHLP.SYS, 
it  is  trivial  to  crash  OS/2. 

There  is  another  aspect  to  the  driver’s 
minimal  design:  Ironically,  DEVHLP.SYS 
knows  practically  nothing  about  the 
DevHlps'.  The  only  DevHlp  it  specifi¬ 
cally  knows  about  is  VerifyAccess,  which 
it  uses  to  ensure  that  the  addresses  for 
your  parameter  and  data  packets  are 
valid,  and  that  the  DS  and  ES  register 
values  you  pass  in  are  legal.  Other  than 
that,  DEVHLP.SYS  just  blindly  loads  reg¬ 
isters  from  the  parameter  packet,  in¬ 
vokes  [DevHlp],  and  stores  the  registers 
into  the  data  packet. 

This  “ignorant”  design  is  greatly  pref¬ 
erable  to  a  seemingly  more  intelligent 
design  that  would  provide  separate 
PhysToUVirt ,  Lock,  ABIOSCommonEn- 
try,  and  so  on,  ioctl  functions.  The  prob¬ 
lem  with  such  an  approach  is  not  only 
that  it  makes  the  driver  larger,  but  also 
that  it  fails  to  support  future  DevHlps. 
The  “ignorant”  design  of  DEVHLP.SYS 
is  precisely  what  should  enable  it  to 
work  even  with  new  DevHlps.  Such 
extensibility  is  usually  given  the  glori¬ 
fied  title  “object-oriented  programming” 
(see  any  discussion  of  virtual  functions 
in  C++)  but  really  it’s  just  common 
sense  that  the  more  ignorant  a  tool  is 
of  any  specific  protocol,  the  more  likely 
it  is  to  work  with  future  protocols! 
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Closing  DOS’s 
Backdoor 

Gaining  access  to  DOS  without  going  through  INT21 


John  Switzer 


Although  totally  protecting  any 
IBM  PC  or  compatible  from  in¬ 
trusion  is  impossible,  MS-DOS 
complicates  matters  by  having 
two  “backdoors”  that  allow  ac¬ 
cess  to  the  DOS  function  handler  INT 
21h.  These  backdoors  are  poorly  docu¬ 
mented  but  still  present  a  huge  gap  in 
a  PC’s  security.  To  have  a  secure  sys¬ 
tem,  it  is  essential  to  close  and  lock 
these  backdoors. 

These  backdoors  allow  access  to  INT 
21h  through  two  far  pointers  that  are 
easily  accessible  by  any  program.  The 
first  of  these  pointers  is  in  low  mem¬ 
ory,  at  the  address  reserved  for  inter¬ 
rupts  30h  and  31h  (0:00C0  through 
0:00C7).  Normally  an  entry  in  the  in¬ 
terrupt  vector  table  contains  a  dword 
pointer  to  the  interrupt’s  handler;  how¬ 
ever,  INT30  and  INT31  are  in  the  form 
of  a  JMP  FAR  instruction  that  points  to 
the  alternative  DOS  function  dispatcher 
(in  my  version  of  DOS  3-30:  JMP  FAR 
0274:1446).  This  allows  direct  access 
to  DOS  without  having  to  go  through 
INT21. 

This  alternative  DOS  handler,  how¬ 
ever,  has  different  entry  requirements 
than  a  normal  INT21  call.  Its  use  re¬ 
quires  some  special  handling  and  an 
understanding  of  the  functions  that  it 
allows.  Example  1  shows  the  alterna¬ 
tive  entry  point  as  it  exists  in  MS-DOS 
3.30,  with  some  changes  for  clarity. 


John  is  a  technical  writer  for  Commu¬ 
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First,  the  handler  expects  the  return 
address  to  be  on  the  stack  in  an  un¬ 
usual  order.  Normally,  when  an  inter¬ 
rupt  occurs,  the  CPU  pushes  the  flags 
onto  the  stack  first,  followed  by  the 
segment  and  offset  of  the  caller’s  return 
address.  However,  this  entry  point  ap¬ 
parently  expects  the  flags  to  be  pushed 
last,  after  the  offset  and  segment  of  the 
return  address.  Because  this  routine 
eventually  transfers  control  to  the  nor¬ 
mal  INT21h  handler,  the  handler’s  first 
job  is  to  translate  the  stack  into  an 
acceptable  form  for  the  eventual  IRET. 
Second,  this  handler  allows  only  func¬ 
tions  0  through  24h  to  be  executed. 
Also,  since  the  AX  register  is  destroyed 


immediately  upon  entry,  the  function 
number  is  passed  through  CL  and  not 
through  AH.  Function  OCh  (CLEAR  KEY¬ 
BOARD  BUFFER  AND  GET  STDIN)  is 
thus  unavailable,  as  it  uses  AL  for  a 
subfunction  value.  These  limitations 
may  be  familiar  to  former  CP/M  pro¬ 
grammers  —  they  result  from  the  origi¬ 
nal  MS-DOS  designers’  desire  for  CP/M 
compatibility. 

To  use  this  call,  therefore,  the  caller 
must  manually  set  up  the  stack  with  the 
flags  and  a  proper  far  return  address. 
With  the  function  number  in  CL,  a  far 
jump  to  0:00C0  executes  the  call.  After 
completion,  the  INT21  dispatcher  then 
does  an  IRET  to  the  return  address  on 
the  stack  as  normal.  Example  2  demon¬ 
strates  this  technique. 

CP/M  programmers,  however,  used 
a  near  CALL  to  execute  their  DOS  func¬ 
tion  calls.  The  second  backdoor  into 
MS-DOS  exists  precisely  to  duplicate 
this  procedure:  At  offset  5  in  every 
program’s  PSP  (program  segment  pre¬ 
fix)  is  a  far  call  instruction  that  theo¬ 
retically  allows  access  to  DOS  by  doing 
a  CALL  0005,  as  CP/M  allowed.  How¬ 
ever,  this  offset  usually  shows  an  in¬ 
struction  similar  to:  CALL  FAR  F5C2:A496. 

This  appears  to  reference  a  location 
in  what  seems  to  be  either  the  BIOS  or 
an  impossibly  high  RAM  memory  area, 
and  the  code  at  this  address  is  usually 
garbage.  So,  though  this  pointer  in  the 
PSP  has  been  documented  since  the 
beginnings  of  MS-DOS,  most  program¬ 
mers  have  ignored  it. 

The  problem  is  that  the  address 
shown  in  the  PSP  is  usually  not  accu- 
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(continued  from  page  42) 
rate  and  before  use  should  be  rounded 
up  to  the  nearest  paragraph.  Using  the 
previous  example,  this  results  in:  CALL 
FAR  F5C2:A4A0. 

Looking  at  the  code  at  this  address 
reveals  the  same  instruction  seen  at  the 
INT30  vector  0MP  FAR  0274:1446).  Both 
backdoors,  therefore,  jump  to  the  alter¬ 
nate  DOS  function  dispatcher.  By  setting 
up  the  stack  and  registers  as  described 

Closing  MS-DOS’s 
backdoors  removes  one 
of  the  more  obscure 
dangers  to  your 
computer  and  its  data 


for  the  first  backdoor,  the  corrected  dword 
pointer  can  be  inserted  into  the  pro¬ 
gram’s  data  area.  A  JMP  FAR  instruction 
can  then  be  used  to  execute  a  limited 
number  of  DOS  functions. 

By  modifying  the  pointer  in  the  PSP, 
however,  the  simpler  CP/M  approach 
could  also  be  used  to  access  DOS  func¬ 
tions.  First,  the  PSP  is  modified  (if  nec¬ 
essary)  to  round  the  pointer  up  to  the 
nearest  paragraph.  The  caller  can  then 
use  a  CALL  0005  instruction  to  execute 
the  DOS  function,  as  it  was  done  in 
CP/M.  This  pushes  the  caller’s  correct 
return  address  onto  the  stack  and  exe¬ 
cutes  the  far  CALL  in  the  PSP.  The  far 
CALL  pushes  the  program’s  code  seg¬ 
ment  onto  the  stack,  as  well  as  another 
return  address;  however,  the  second 
return  address  is  pointing  to  offset  OAh 
in  the  PSP.  This  is  not  a  problem,  be¬ 
cause  the  first  thing  the  DOS  dispatcher 
does  is  eliminate  the  second  return  ad¬ 
dress  with  a  POP  AX  instruction  (see 
Example  1).  It  then  rebuilds  the  stack 
so  that  the  IRET  correctly  returns  to  the 
caller’s  program.  So,  with  some  work, 
the  original  designer’s  goal  of  CP/M 
compatibility  is  achieved,  for  whatever 
it  is  worth. 

Now  that  the  alternative  DOS  han¬ 
dler  is  understood,  its  use  must  be  pre¬ 
vented.  Most  security  programs  do  an 
admirable  job  of  closing  the  door  to 
normal  DOS  calls  using  INT  21h,  but 
many  ignore  these  alternative  entry 
points  into  DOS.  A  secure  system  must 
close  these  backdoors.  For  the  back¬ 
door  at  0:00C0,  this  is  trivial.  Simply 
replace  the  JMP  FAR  instruction  at 
0:00C0  with  a  pointer  to  a  new  handler 
(continued  on  page  47) 
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(continued  from  page  44) 

that  can  refuse  or  execute  the  function 

as  appropriate. 

The  second  backdoor,  however, 
seems  to  be  more  difficult.  Because 


IBM  processors:  Offset  A4A0  =  seg¬ 
ment  0A4A,  so  segment  F5C2  plus  seg¬ 
ment  A4A  =  segment  1000C.  Segment 
1000C  wraps  around  to  segment  000C 
which  translates  into  address  0:00C0. 


any  number  of  PSPs  can  exist  in  mem¬ 
ory  at  one  time,  patching  each  one 
with  a  new  vector  could  be  difficult. 
Fortunately,  this  is  not  necessary.  Do¬ 
ing  some  calculations  on  the  modified 
address  given  in  the  PSP  (F5C2:A4A0, 
for  example)  shows  that  it  translates 
into  0:OOCO  because  of  the  quirks  of 


Thus,  changing  the  PSP  pointers  is  un¬ 
necessary,  since  both  backdoors  are 
different  pointers  to  the  same  memory 
location.  Changing  the  vector  at  0:00C0 
adequately  protects  against  both. 

Both  of  these  backdoors  have  ex¬ 
isted  in  PC-DOS  since  version  1.0  and 
in  most  versions  of  MS-DOS.  Given 


the  “wrap-around”  memory  address-  that  they  have  existed  for  almost  nine 
ing  found  in  the  real-mode  of  the  Intel  years  without  causing  any  apparent  prob- 


ALT  DOS  ENTRY: 

POP  AX 

;  get  rid  of  flags 

POP  AX 

;  save  caller's  segment 

POP  CS:TEMP 

;  save  caller's  offset 

PUSHF 

;  save  flags 

CLI 

;  kill  interrupts 

PUSH  AX 

;  save  caller's  segment 

PUSH  CS:TEMP 

;  save  caller's  offset 

CMP  CL, 24h 

;  is  CL  <  max  #? 

JA  REFUSE  RQST 

;  no,  so  invalid 

MOV  AH, CL 

;  yes,  AH=function  # 

JMP  CONT  INT21 

;  and  continue  INT21 

Exatnple  1:  An  alternative  entry  point  into  MS-DOS  3  30. 


MOV  AX, offset  RETURN 

get  return  address'  offset 

PUSH  AX 

push  flags  and  return  address 

PUSH  CS 

onto  stack  in  reverse  order 

PUSHF 

save  flags  for  IRET 

MOV  CL, 9 

display  DOS  string 

MOV  DX, offset  MSG 

PUSH  CS 

this  is  the  message 

POP  DS 

verify  that  DS  =  local  code 

JMP  dword  ptr  ALT  DOS  PTR 

and  execute  the  function 

RETURN: 

MOV  AH, 4Ch 

terminate  a  process 

INT  2ih 

via  DOS 

ALT  DOS 

PTR  DW  OOCOh, 0000 

entry  point  for  alternative 

DOS  handler  (0: OOCOh) 

MSG 

DB  ODh, OAh, "Example  of 

backdoor  MS-DOS  " 

DB  "function  call.", ODh, 

OAh, 7, "$" 

Example  2:  A  far  jump  executes  the  call  and  the  dispatcher  returns  to  the 
stack. 


MOV  AX, offset  RETURN 

get  return  address'  offset 

PUSH  AX 

push  flags  and  return  address 

PUSH  CS 

onto  stack  in  reverse  order 

PUSHF 

MOV  CL, 13h  ; 

DELETE  FCB  function 

MOV  DX, offset  FCB  ; 

this  is  the  special  FCB 

PUSH  CS 

POP  DS 

verify  that  DS  =  local  code 

JMP  dword  ptr  ALT  DOS  PTR; 

and  execute  the  function 

RETURN: 

MOV  AH,  4Ch 

terminate  the  process 

INT  2ih 

via  DOS 

ALT  DOS 

PTR  DW  OOCOh, 0000 

entry  point  for  alternative 

DOS  handler  (0: OOCOh) 

FCB 

DB  OFFh 

extended  FCB 

DB  5  dup ( 0 )  ; 

reserved  bytes 

DB  Uii 

ail  attribute  bits  set 

DB  0 

default  drive  ID 

DB  "??????????'?"  ; 

match  all  files 

DB  19h  dup{0) 

rest  of  FCB 

Example  3-  An  FCB  function  can  delete  files.  Calling  this  function  while  at  the 
root  directory  will  obliterate  all files  on  the  disk,  requiring  tedious  work  with  your 
favorite  disk  editor  to  restore  them. 
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lems,  and  that  the  alternative  DOS  han¬ 
dler  is  limited  in  its  scope,  how  serious 
a  danger  do  these  backdoors  present? 
Only  the  standard  input/output  and 
FCB  functions  are  allowed,  and  although 
FCBs  can  delete  and  rewrite  files,  they 
can  be  used  only  on  files  in  the  current 
directory.  Although  a  Trojan  Florse  pro¬ 
gram  could  use  these  backdoor  ap¬ 
proaches  to  do  some  damage,  it  would 
not  seem  to  pose  a  major  problem. 

This  would  be  true,  except  that  one 
FCB  call,  function  13h  (DELETE  AN 
FCB),  has  a  special  case  that  could 
destroy  all  files  on  a  hard  disk.  The 
special  case  requires  that  an  extended 
FCB  use  a  filename  of  “???????????”  and 
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an  attribute  of  lFh.  Seeing  this  specific 
combination,  function  13h  deletes  all 
files  in  the  current  directory,  including 
files  marked  with  the  read-only,  vol¬ 
ume,  and  subdirectory  attributes.  To 
make  matters  worse,  this  function  re¬ 
places  the  first  character  of  the  deleted 
filenames  with  a  0,  not  the  usual  0E5h. 
This  prevents  most  “undelete”  utilities 
from  being  able  to  undo  this  call’s  se¬ 
vere  damage. 

Consider  the  potential  damage  of  this 
call.  If  executed  at  the  root  directory, 
it  effectively  deletes  all  files  on  the 
disk.  As  subdirectories  are  only  special 
files  that  contain  directory  information, 
these  are  also  deleted.  This  therefore 


prevents  any  access  to  the  files  that 
were  in  those  subdirectories,  including 
any  deeper  subdirectories.  Note  that 
the  files  in  the  subdirectories  are  not 
deleted,  and  their  space  remains  allo¬ 
cated;  only  the  directory  information 
about  them  has  been  erased.  CHKDSK 
will  therefore  report  these  orphaned 
files  as  being  unallocated  clusters.  It  is 
possible  to  recover  these  files  and  the 
original  tree  structure,  but  only  with 
painstaking  work  with  a  disk  editor. 

This  behavior  of  MS-DOS  is  truly 
bizarre.  Normally,  only  MS-DOS’s  in¬ 
ternal  routines  can  update  or  delete  the 
files  marked  with  the  subdirectory  at¬ 
tribute.  That  an  FCB  function  is  allowed 
to  delete  these  files  is  an  unbelievable 
quirk  of  MS-DOS.  Example  3  shows 
the  use  of  this  special  case,  using  the 
first  DOS  backdoor.  Warning!  If  you 
experiment  with  this  call,  please  do  so 
only  on  a  floppy  disk  and  not  on  a  hard 
disk.  Calling  this  function  while  at  the 
root  directory  will  obliterate  all  files 
on  the  disk,  requiring  tedious  work 
with  your  favorite  disk  editor  to  restore 
them.  (This  warning,  by  the  way,  is 
from  my  own  personal  experience!) 

This  dangerous  call,  therefore,  pro¬ 
vides  the  answer  to  the  question  asked 
above:  MS-DOS’s  backdoors  present  a 
severe  threat  to  an  unsecured  system. 
Even  though  an  anti-viral  program  may 
filter  INT21h  calls,  if  it  doesn’t  change 
the  vector  at  0:00C0,  it  is  easy  to  de¬ 
stroy  all  files  on  a  hard  disk. 

Listing  One,  page  98,  shows  one  ap¬ 
proach  with  a  device  driver  called  BACK- 
DOOR.SYS.  By  installing  the  device 
driver  in  the  first  line  of  your  CON¬ 
FIG.SYS  file  (DEVICE=BACKDOOR 
.SYS),  you  ensure  that  it  is  installed 
before  any  other  programs  can  run. 
BACKDOOR.  SYS  simply  replaces  the 
vector  at  0:00C0h  with  a  pointer  to  a 
new  handler  and  then  installs  itself  as 
a  character  device.  The  new  handler 
refuses  any  requests  for  DOS  services 
through  the  alternative  DOS  function 
dispatcher.  This  effectively  closes  both 
of  MS-DOS’s  backdoors.  It  also  filters 
INT21h  to  specifically  look  for  the  spe¬ 
cial  function  13h  call  and  rejects  the 
function  request  if  it  occurs. 

No  IBM  PC  or  compatible  running 
in  real  mode  can  be  completely  safe 
from  destructive  programs,  whether  in¬ 
tentional  or  not.  However,  it  makes  no 
sense  to  allow  known  dangers  to  con¬ 
tinue  to  exist.  Closing  DOS’s  backdoors 
removes  one  of  the  more  obscure  dan¬ 
gers  to  your  computer  and  its  data. 

DDJ 

(Listing  begins  on  page  98.) 
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isk  operations  are  generally 
slow  and  expensive  compared 
to  other  operating  system  func¬ 
tions.  In  Unix,  performance 
-  is  boosted  by  caching  the  most 

recently  used  disk  blocks  within  a  pool 
of  RAM  buffers. 

This  pool,  called  the  “buffer  cache,” 
utilizes  cache  hits  to  complete  disk  re¬ 
quests  without  having  to  access  the 
disk.  Unfortunately,  the  buffer  cache 
is  static  in  size,  and  eventually  some 
buffers  must  be  written  out  to  disk 
before  they  can  be  reused  for  another 
disk  block. 

In  some  respects,  the  Unix  buffer 
cache  is  a  RAM  disk.  The  difference  is 
that  the  buffer  cache  manages  the  reuse 
of  disk  blocks,  while  the  RAM  disk 
simply  reports  the  file  system  as  full 
when  all  buffers  have  been  allocated. 

This  article  describes  the  implemen¬ 
tation  of  a  RAM  disk  driver  for  Unix.  A 
386  system  with  four  megabytes  of  RAM 
running  Unix  System  V/386  Release  3.2 
was  used  throughout  to  develop  the 
driver. 

The  Driver  Implementation 

The  RAM  disk  driver  differs  from  tradi¬ 
tional  Unix  disk  drivers  in  several  ways. 
The  first,  of  course,  is  the  hardware.  In 
reading  or  writing  to  a  physical  disk, 
the  driver  must  first  position  the  read/ 
write  head,  then  transfer  the  data  blocks. 
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When  all  is  done,  typically  many  milli¬ 
seconds  later,  the  hard  disk  presents 
an  interrupt  to  Unix  and  the  request 
can  be  completed.  In  contrast,  RAM 
disks  do  not  experience  the  position¬ 
ing  delays  associated  with  mechanical 
hardware,  which  eliminates  the  need 
for  interrupts. 

The  RAM  disk  driver  developed  for 
this  article  (see  Listing  One,  page  100) 
supports  both  a  block-mode  and  a  char¬ 
acter-mode  interface.  Block  mode  is 
used  by  the  kernel  to  read  and  write 
mounted  Unix  file  systems.  Character 
mode  provides  a  raw  interface  to  the 
disk,  allowing  the  application  to  by¬ 


pass  the  Unix  buffer  cache  and  ma¬ 
nipulate  the  disk  directly.  Eight  entry 
points  to  the  driver  are  provided:  rdinit, 
rdopen,  rdclose,  rdstrategy,  rdread, 
rdwrite ,  rdintr ,  rdioctl,  and  rdprint. 

During  the  Unix  boot,  the  kernel 
calls  rdinit,  which  determines  whether 
a  RAM  disk  has  been  defined,  and,  if  it 
has,  allocates  the  memory  required  to 
represent  the  disk.  The  sptalloc  func¬ 
tion  is  used  to  allocate  this  memory. 
Using  sptalloc,  memory  is  allocated  in 
page-size  units  (4096  bytes  in  386  Unix), 
and  if  successful  at  obtaining  the  num¬ 
ber  of  pages  requested,  sptalloc  returns 
a  kernel  virtual  address  referencing  this 
memory.  All  page  table  manipulation 
is  handled  by  sptalloc,  including  page 
linkage  and  the  locking  down  of  pages 
as  directed  by  the  PG_P  parameter 
passed  to  sptalloc.  Notice  the  DONT_ 
SLEEP  parameter  in  the  sptalloc  call. 
Initialization  routines  in  Unix  are  not 
permitted  to  sleep  because  they  can 
prevent  the  system  from  successfully 
booting. 

After  space  has  been  carved  out  for 
the  RAM  disk,  rdinit  fills  in  rd_cfg,  the 
configuration  structure  which  represents 
the  state,  virtual  address,  and  size  of 
the  RAM  disk.  Of  these,  only  the  size 
field  must  be  defined  during  driver  com¬ 
pile  time. 

The  driver  supports  three  states:  RD_UN- 
DEFINED,  RD_CONFIGURED ,  and  RD_ 
OPEN.  RD_UNDEFINED  is  the  initial 
state.  It  indicates  the  RAM  disk  has  not 
been  set  up.  RD_CONFIGURED  is  set 
by  rdinit  after  a  successful  call  to  sptal- 
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(continued  from  page  50) 
loc.  RD_OPEN  is  logically  ORed  to  the 
state  field  each  time  the  disk  is  opened. 
RD_OPEN  could  be  used  at  a  later  time 
to  implement  a  critical  region  lock  for 
the  RAM  disk,  allowing  only  one  open 
at  a  time. 

rdopen  is  either  called  when  a  mount 
is  being  performed  or  when  an  appli¬ 
cation  attempts  an  open  on  the  device 
node  associated  with  the  RAM  disk. 

This  RAM  disk  driver 
supports  both  block  and 
character  mode 
interfaces 


Application  programs  use  the  8  bits  of 
the  minor  number  to  inform  the  driver 
which  disk  should  service  the  request. 
In  this  implementation,  rdopen  recog¬ 
nizes  only  one  RAM  disk,  and  rejects 
the  request  if  it  specifies  any  disk  other 
than  zero.  Rejected  requests  are  han¬ 
dled  by  updating  the  error  field  in  the 
current  u  area  (defined  in  “sys/user.h”) 
and  returning  to  the  caller.  An  error  is 
returned  in  the  same  fashion  if  the  state 
maintained  by  the  configuration  struc¬ 
ture  rd_cfg  indicates  the  disk  has  not 
been  initialized.  With  request  verifica¬ 
tion  out  of  the  way,  rdopen  turns  on 
the  RD_OPEN  state  bit. 

rdclose  is  simple  since  there  is  no 
mechanical  hardware  associated  with 
a  RAM  disk,  rdclose  simply  turns  off  the 
RD_OPEN  state  bit.  You  may  think  this 
is  an  error  because  we  are  turning  off 
the  open  bit  even  though  multiple  opens 
may  have  been  performed  on  the  de¬ 
vice.  Not  to  worry;  if  a  file  has  been 
opened  multiple  times  in  Unix  and  a 
close  request  is  then  made  by  one  in¬ 
stance,  Unix  simply  decrements  in  in¬ 
ternal  file  open  count.  When  that  count 
reaches  zero,  the  close  function  is  called. 

rdstrategy  is  the  driver  function  that 
actually  services  the  read/write  requests. 
A  Unix  buffer  header  (described  in  sys/ 
buf.h)  is  passed  as  a  parameter  con¬ 
taining  all  necessary  information  to  ser¬ 
vice  the  request.  Pertinent  information 
such  as  the  requested  block,  number 
of  bytes  to  transfer,  direction  of  trans¬ 
fer,  and  the  target  device  are  filled  in 
by  the  kernel  prior  to  calling  rdstrategy. 

Rather  than  trusting  all  information 
presented  by  the  buffer  header,  rd¬ 
strategy  performs  some  simple  error 
checking;  without  error  checking,  a  sim¬ 


ple  request  exceeding  its  limits  could 
crash  the  system,  rdstrategy  begins  by 
converting  the  requested  block  num¬ 
ber  into  a  byte  offset  which  is  used  to 
reference  the  start  of  the  request.  The 
number  of  bytes  requested  is  then  added 
to  this  start  location  to  determine  if  the 
request  will  go  off  the  end  of  the  disk. 
If  the  operation  is  a  read  request,  this 
behavior  is  tolerated  so  end  of  file  (EOF) 
can  be  detected  by  the  application. 
The  request  is  adjusted  so  all  data  up 
to  and  including  the  last  block  is  read. 
However,  write  requests  are  rejected 
immediately. 

Now  that  the  error  checking  is  out 
of  the  way,  rdstrategy  can  transfer  the 
data  into  or  out  of  the  RAM  disk.  Since 
this  is  nothing  more  than  a  copy  opera¬ 
tion,  bcopy,  which  is  supplied  by  the 
kernel,  can  be  used,  bcopy  is  used  to 
copy  a  specified  number  of  bytes  from 
one  location  of  kernel  memory  to  an¬ 
other. 

Upon  completion  of  the  copy,  the 
residual  count  and  error  fields  of  the 
buffer  header  are  updated  to  indicate 
the  request  has  been  serviced  success¬ 
fully.  iodone  is  then  called  to  return  the 
buffer  to  the  process  responsible  for 
initiating  the  request. 

An  application  or  system  administra¬ 
tion  utility  references  the  character  in¬ 
terface  through  rdread  and  rdwrite. 
These  routines  are  virtually  identical 
except  for  the  direction  of  the  data 
transfer. 

Unix  provides  two  support  routines, 
physck  and  physio,  which  are  used  to 
transform  the  request  into  a  buffer 
header  suitable  for  rdstrategy.  In  a  man¬ 
ner  similar  to  rdstrategy ,  physck  veri¬ 
fies  that  the  submitted  request  is  within 
bounds  of  the  RAM  disk.  If  the  request 
is  a  write  and  it  exceeds  the  bounds  of 
the  disk,  physck  returns  an  error.  How¬ 
ever,  in  order  to  handle  EOF  correctly, 
read  operations  must  be  trimmed  back 
and  the  transfer  count  adjusted  so  the 
request  will  not  exceed  the  last  valid 
disk  block.  The  physio  function  per¬ 
forms  all  housekeeping  chores  such 
as  extracting  information  from  the  user 
area  to  build  a  buffer  header,  prevent¬ 
ing  user  buffers  from  being  paged  out, 
and  finally  calling  rdstrategy  to  get  the 
request  serviced. 

The  ioctl  Unix  interface  is  a  reposi¬ 
tory  for  miscellaneous  driver  functions. 
The  RAM  disk  driver  supports  only  one 
ioctl  function,  which  returns  informa¬ 
tion  about  the  size  of  the  specified 
RAM  disk.  The  size  information  is  taken 
out  of  the  rd_cfg  structure  and  returned 
to  the  process  initiating  the  request. 
The  buffer  location  passed  into  rdioctl 
is  not  in  the  same  memory  map  as  the 
rd_cfg  structure.  To  get  around  this 
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(continued  from  page  52) 
problem,  Unix  provides  the  copyout 
function,  copyout  allows  a  driver  to 
copy  data  out  of  kernel  space  and  into 
data  structures  residing  in  user  space. 
Example  1  illustrates  how  an  applica¬ 
tion  program  would  query  the  RAM 
disk  about  its  size. 

An  interrupt  handler  is  not  required 
for  the  RAM  disk,  but  one  is  supplied 
(rdintr)  just  in  case  some  spurious  in¬ 
terrupt  is  dispatched  to  the  RAM  disk. 
In  that  case,  a  warning  message  report¬ 
ing  the  spurious  interrupt  is  sent  to  the 
console  via  cmn_err. 

Information  or  messages  that  refer 
to  the  RAM  disk  are  dealt  with  by 
rdprint.  For  example,  if  the  RAM  disk 
has  no  free  blocks  left  to  allocate  and 
a  request  for  RAM  disk  blocks  arrives 
at  the  file  system,  it  calls  rdprint ,  pass¬ 
ing  along  a  text  string  stating  that  the 
RAM  disk  is  out  of  space. 

Adding  file  RAM  Disk  to  Unix 

After  the  driver  has  been  compiled, 
copy  the  object  file  to  /etc/conf/pack.d/ 
r d/Driver,  o.  The  kernel  must  now  be 
rebuilt  in  order  to  pull  in  support  for 
the  RAM  disk  driver.  There  are  numer¬ 
ous  ways  to  rebuild  a  kernel  and  com¬ 
plete  necessary  installation  procedures. 
The  method  described  here  utilizes  the 


Installable  Driver  Package  (IDP),  which 
is  used  on  most  Unix  System  V/386 
Release  3.2  systems.  Throughout  the 
build  process,  rd  is  the  prefix  used  to 
uniquely  identify  the  RAM  disk  driver. 

To  begin,  a  system  device  file  must 
be  created  that  describes  what  hard¬ 
ware  resources  the  RAM  disk  requires. 
Example  2(a)  shows  the  file  used  for 
this  article. 

Because  hardware  resources  are  not 


required  for  this  driver,  the  interrupt 
level,  interrupt  vector,  I/O  address,  and 
memory  address  fields  all  contain  a 
zero.  The  first  three  fields  tell  the  build 
process  the  name  of  the  driver,  confirm 
that  the  driver  is  to  be  linked  into  the 
kernel,  and  report  the  number  of  de¬ 
vices  supported,  respectively.  Copy  this 
file  to  /etc/conf/sdevice.d/rd  prior  to 
relinking  the  kernel. 

Next,  an  entry  must  be  added  to  the 


♦include  "sys/types.h" 

main  () 

{ 

int  fd; 

struct  rd_size  { 

daddr_t  sector_count; 
long  b_count; 

)  ram_disk_size; 

if  (  (fd  =  open  ("/dev/rdsk/rdO",  0_RD0NLY) )  <  0) 

( 

printf  ("Could  not  open  RAM  disk  to  do  ioctl.Xn"); 
exit  ( 1 )  ; 

) 

if  (  ioctl  (fd,  RD_GETSIZE,  &ram_disk_size)  <  0) 

I 

printf  ("Could  not  determine  size  of  RAM  disk.\n"); 
exit  (2)  ; 

} 

printf  ("The  RAM  disk  consists  of  %d  sectors  occupying  %d  bytes. \n”, 
ram_disk_size . sector_count ,  ram_disk_size.b_count) ; 

1 


Example  1:  How  an  application  queries  the  RAM  disk’s  size 
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master  device  file  that  describes  the 
driver  interface.  This  is  shown  in  Ex¬ 
ample  2(b). 

The  first  field  says  this  description 
applies  to  the  RAM  disk  driver.  Next, 
“ocrwil”  indicates  the  RAM  disk  sup¬ 
ports  an  open,  close,  read,  write,  ioctl, 
and  init  interface.  The  third  field  de¬ 
scribes  the  driver  as  installable,  capa¬ 
ble  of  supporting  character  and  block 
devices,  and  containing  only  one  entry 


in  the  system  device  file  described  pre¬ 
viously.  The  fourth  field  is  the  handler 
prefix  used  to  distinguish  the  interface 
entry  points.  Fields  five  and  six  are  for 
block  and  character  major  numbers. 
Setting  these  fields  to  zero  lets  the  build 
process  assign  these  numbers  dynami¬ 
cally.  Fields  seven  and  eight  specify 
the  minimum  and  maximum  number 
of  units  that  can  be  declared  in  the 
system  device  file.  The  last  field  is  for 


Direct  Memory  Access  (DMA),  and, 
since  this  device  doesn’t  use  any,  this 
field  is  assigned  -1. 

I’ve  found  the  easiest  way  to  add  this 
information  to  the  master  device  file  is 
to  create  a  file  in  your  local  directory 
called  “Master,”  containing  the  line  in 
Example  2(b).  Then  use  the  idinstall 
command  listed  in  Example  2(c)  to  ap¬ 
pend  the  description  to  the  master  de¬ 
vice  file. 

The  command  line  informs  idinstall 
that  the  description  in  file  Master  is  to 
be  added  to  the  master  device  file; 
upon  completion,  do  not  delete  file 
Master. 

After  running  idinstall,  the  major  num¬ 
bers  assigned  by  idinstall  can  be  ex¬ 
tracted  from  the  master  device  file  in 
/ etc/conf/cf.d/mdevice  and  used  to  con¬ 
firm  the  major  numbers  assigned  to  the 
block  and  character  device  files  by 
idmknode  during  the  next  system  boot. 

To  have  the  boot  process  automati¬ 
cally  generate  the  RAM  disk  device 
nodes,  a  node  file  is  needed.  Example 
2(d)  describes  two  nodes,  one  for  the 
block  and  one  for  the  character  device. 

Given  the  configuration  in  Example 
2(d),  the  block  device  will  be  addressed 
as  / dev/dsk/rdO  with  minor  number  0, 
while  the  character  device  is  referenced 
as  /dev/rdsk/rdO  using  min  r  number 


Example  2 (a) : 

rd  Y10000000 

Example  2  (b)  : 

rd  ocrwil  icbo  rd  0  0  1  2  -1 

Example  2 (c) : 

/etc/conf/bin/idinstall  -a  -m  -k  rd 

Example  2 (d) : 

rd  rdsk/rdO  c  0 
rd  dsk/rdO  b  0 

Example  2  (e)  : 

cd  / 

#  Make  a  filesystem  on  the  RAM  disk, 
/etc/mkfs  /dev/dsk/rdO  2048:150 
/etc/mountall  /etc/fstab 

Example  2:  Examples  for  developing  Unix  RAM  disk 
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(continued  from  page  55) 

0.  Modifying  the  driver  to  support  mul¬ 
tiple  RAM  disks  would  require  addi¬ 
tional  entries  in  Example  2(d)  as  well 
as  unique  minor  numbers.  To  com¬ 
plete  the  node  setup,  copy  the  file  de¬ 
scribed  in  Example  2(d)  to  /etc/conf/ 
node. d/rd. 

Before  proceeding,  it  makes  sense 
to  make  a  backup  copy  of  the  kernel 
just  in  case  the  new  driver  has  intro¬ 
duced  a  bug  and  prevents  the  system 
from  booting.  Then,  if  there  are  prob¬ 
lems,  the  old  kernel  can  be  used. 

At  this  point,  all  support  files  are  in 
place  and  the  kernel  can  be  rebuilt  by 
issuing  /etc/conf/bin/idbuild.  If  all  goes 
well  (meaning  all  external  references 
were  resolved)  the  current  kernel  can 
be  shut  down  and  the  new  one  brought 
up  for  driver  testing. 

Automating  the  Installation 

RAM  disks  represent  a  form  of  volatile 
storage.  Because  everything  written  to 
the  disk  is  lost  during  a  system  shut¬ 
down,  the  disk  must  be  initialized  ev¬ 
ery  time  the  system  is  restarted.  Rather 
than  manually  issuing  the  proper  com¬ 
mands  each  time,  a  system  administra¬ 
tor  could  automate  the  procedure  by 
adding  special  commands  to  the  Unix 
startup  scripts. 

To  begin  with,  a  mount  point  must 
be  established  so  the  user  community 
can  reference  the  RAM  disk.  To  create 
/ramdisk  as  the  mount  point  use  the 
following  mkdir  command:  mkdir/ram- 
disk. 

The  mount  point  needs  to  be  created 
only  once  as  long  as  you  don’t  delete 
it  after  unmounting  the  file  system.  Next, 
append  the  following  line  to  /etc/fstab: 
/dev/dsk/rdO  /ramdisk. 

The  fstabiile  contains  all  file  systems 
to  be  mounted  during  the  Unix  boot. 
The  last  step  involves  building  the  file 
system  on  the  RAM  disk  so  the  boot 
procedure  can  find  something  to  mount. 
The  file  system  can  be  created  by  add¬ 
ing  a  mkfs  command  to  /etc/rc2.d/ 
SOIMOUNTFSYS.  Example  2(e)  illus¬ 
trates  a  modified  SOIMOUNTFSYS  file. 

It’s  important  to  note  that  the  mkfs 
command  is  executed  before  directing 
/etc/mountall  to  read  and  mount  all  file 
systems  listed  in  /etc/fstab.  In  Example 
2(e),  the  mkfs  command  is  instructed 
to  build  a  file  system  on  the  RAM  disk 
using  2048  sectors  (each  sector  is  512 
bytes  in  size)  and  allow  a  maximum 
allocation  of  150  files.  Overhead  re¬ 
quired  by  the  file  system  is  minimal. 
However,  the  actual  number  of  inodes 
and  filesystem  blocks  will  be  reduced 
to  144  and  2024,  respectively. 

Although  the  procedure  above  will 
automate  the  installation  of  the  RAM 


disk,  it  should  be  noted  that  this  is  a 
static  configuration.  For  example,  re¬ 
configuring  the  RAM  disk  to  increase 
its  size  from  one  megabyte  to  two  re¬ 
quires  the  mkfs  command  buried  in 
/etc/rc2 .d/S01MOUNTFSYS  to  be  modi¬ 
fied  so  the  additional  space  provided 
can  be  utilized. 

Improving  the  Performance  of  Unix 

The  RAM  disk  has  several  practical  uses 
in  Unix.  For  example,  many  programs 
rely  on  temporary  files  and  tend  to 
create  them  in  /tmp.  Instead  of  using 
part  of  the  root  file  system  for  /tmp,  try 
mounting  the  RAM  disk  on  /tmp.  This 
can  be  done  by  simply  editing  the  /etc/ 
fstab  and  replacing  the  /ramdisk  mount 
point  with  /tmp. 

Another  possibility  is  to  reduce  over¬ 
head  associated  with  loading  files.  This 
is  a  matter  of  identifying  popular  files 
and  copying  them  to  the  RAM  disk. 
Make  sure  the  PATH  environment  vari¬ 
ables  are  updated  so  the  RAM  disk  is 
searched  for  the  file  first. 

If  your  system  allows  for  more  than 
one  swap  device,  a  significant  perfor¬ 
mance  gain  can  be  had  by  making  the 
RAM  disk  a  primary  swap  device.  The 
swap  device  is  the  area  of  disk  used 
by  the  buffer  cache  when  it  becomes 
necessary  to  page  out  buffers.  In  a  heav¬ 
ily  loaded  system,  the  RAM  disk  could 
keep  the  system  from  thrashing  itself 
to  death  because  the  swap  area  no 
longer  has  to  wait  for  a  slow  disk. 

Conclusion 

Writing  a  RAM  disk  driver  is  a  great 
way  to  get  your  feet  wet  in  Unix  device 
drivers.  The  driver  developed  here  sup¬ 
ports  only  one  RAM  disk,  one  mega¬ 
byte  in  size.  It’s  a  trivial  exercise  left  to 
the  reader  to  change  the  size  of  the 
RAM  disk  or  extend  the  driver  so  it  may 
support  additional  disks.  This  driver 
should  port  to  other  flavors  of  Unix 
with  minimal  effort. 

Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
online.  To  order  the  disk,  send  $14.95 
(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  M&T’s  Telepath  online  service 
(via  TYMNET)  and  through  the  DDJ  Fo¬ 
rum  on  CompuServe  (type  GO  DDJ). 

DDJ 
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Find  min  and  max  the  best  possible  way 
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xtents  are  often  used  in  com- 
I  5  puter  graphics  and  constructive 
v  ■  solid  geometry  where  the  edges 
of  the  smallest,  axes-aligned  rec- 
tangle  enclosing  an  object  are 
the  extents  of  that  object.  In  two-di¬ 
mensional  space,  this  is  also  called  “box¬ 
ing”  and  in  three-dimensional  it  is  a 
“three-dimensional  (3-D)  rectangle”  — 
a  parallelpiped. 

Graphical  objects  are  often  defined 
by  a  set  of  vertices  (points)  in  three 
dimensions.  Finding  extents  of  an  ob¬ 
ject  defined  by  a  set  of  points  is  a 
simple  process  once  you  realize  that 
the  extents  are  the  minimum  and  the 
maximum  of  the  object  in  every  dimen¬ 
sion.  To  find  the  minimum  (or  maxi¬ 
mum)  X  coordinate,  you  must  search 
the  vertex  list  that  defines  the  object. 
The  well-known  algorithms  find_min 
and  find_max  are  used  to  accomplish 
this  (see  Listing  One,  page  102).  The 
procedure  is  then  repeated  for  Y  and 
Z  dimensions. 

If  an  object  is  defined  by  N  vertices, 
this  approach  takes  (N  -1)  compari¬ 
sons  to  find  the  Xmin,  (N  -1)  compari¬ 
sons  to  find  the  Xmax,  and  so  on,  for  a 
total  of  6  (N  — 1)  comparisons  for  a  3-D 
object.  However,  is  this  the  minimal 
number  of  comparisons?  It’s  been 
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shown  that  (N  -1)  comparisons  are 
necessary  to  determine  the  minimum 
(or  the  maximum)  of  N  items.1  In  other 
words,  the  algorithms  find_min  and 
find_max  in  Listing  One  are  optimal 
and  it  is  not  possible  to  do  any  better 
by  comparison  of  items!  If  you  were  to 
perform  fewer  than  (N  — 1)  compari¬ 
sons,  an  incorrect  answer  would  result 
for  the  same  input.  Yet,  it  is  possible 
to  perform  fewer  comparisons  if  both 
the  minimum  and  maximum  are  needed, 
as  is  the  case  with  object  extents. 

When  minimizing  the  amount  of 
work  done  by  two  separate  opera¬ 
tions  —  searching  for  minimum  and 
maximum  in  our  case  —  the  usual  tech¬ 


nique  is  to  look  for  any  work  or  inter¬ 
mediate  results  that  can  be  shared.  In 
this  case  there  does  not  seem  to  be  any 
shared  work;  the  find_max  procedure 
compares  all  of  the  points  to  max  and 
the  find_min  procedure  compares  all  of 
the  points  to  min.  In  many  cases  it  may 
be  beneficial  to  sort  the  list  of  items, 
or  a  sublist  of  items.  Sorting  the  whole 
list  makes  things  worse,  because  sort¬ 
ing  is  a  slower  order  operation,  CXNlogN), 
than  finding  a  minimum  or  a  maxi¬ 
mum,  OfN).1  However,  sorting  two  items 
helps  minimize  the  work  since  this  takes 
only  a  single  comparison. 

The  strategy  used  to  find  the  extents 
is  as  follows  (see  the  find_min_max 
procedure  in  Listing  Two,  page  102): 

1.  Compare  the  first  two  items  to 
each  other.  Place  the  larger  in  max  and 
the  smaller  in  min. 

2.  Take  the  next  two  items  and  com¬ 
pare  them  to  each  other.  Then  com¬ 
pare  the  larger  item  to  max  and  the 
smaller  item  to  min.  If  the  larger  item 
is  larger  than  max  place  it  in  max.  If 
the  smaller  item  is  smaller  than  min 
place  it  in  min. 

3.  Take  care  of  the  last  item  if  the 
number  of  items  is  odd.  If  this  item  is 
greater  than  max  it  can  not  be  smaller 
than  min,  so  there  is  no  need  to  com¬ 
pare  to  min. 

This  procedure  is  slightly  more  com¬ 
plex,  but  the  gains  are  dramatic.  In  fact, 
to  find  the  minimum  vertex  and  the 
maximum  vertex  in  the  X  dimension 
for  an  object  with  N  vertices  (3N/2  -2) 
comparisons  will  be  performed  by 
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Machine 

MIN/MAX 

MIN  &  MAX 

Speed  up 

PC/AT  8  MHz 
600,000  items 

34.82  sec. 

48.20  sec. 

27.8% 

VaxStation2000 
1,200,000  items 

13.70  sec. 

18.70  sec 

26.7% 

DEC  3100 
24,000,000  items 

17.30  sec. 

32.70  sec. 

47.1% 

Sun  SparcStation 
24,000,000  items 

50.70  sec. 

66.60  sec. 

23.9% 

Cray  Y-MP 
60,000,000  items 

30.21  sec. 

43.97  sec. 

31.3% 

Table  1:  Results  of  MIN/MAX  algorithm 
(continued  from  page  58) 
find_min_max  if  N  is  even,  and  (3N/2 
-3/2)  comparisons  if  N  is  odd.  In  con¬ 
trast,  2(N  -1)  comparisons  will  be  done 
by  find_min  and  find_max.  This 
amounts  to  a  savings  of  approximately 
25  percent.  What  is  most  important 
about  this  result  is  that  it  has  been 
shown  to  be  optimal!1  In  other  words, 
it  is  not  possible  to  make  any  fewer 
comparisons  of  items!  What’s  more,  the 
find_min_max  procedure  is  general  pur¬ 
pose  and  can  be  used  in  many  other 
applications. 

Application 

As  one  example  of  computational  sav¬ 
ings,  let’s  apply  the  find_ m  in_  max  pro- 
cedure  to  a  polygon  clipping  test.  As¬ 
sume  that  100,000,  4-vertex  polygons 
need  to  be  displayed  per  second.1 2 3  Each 
of  the  polygons  must  be  tested  to  see 
if  it  falls  completely  inside  of  the  dis¬ 
play  window’s  boundaries  which  are 
3-D  boundaries.  Each  polygon  must 
be  handled  separately  since  no  rela¬ 
tionship  can  be  assumed  between  poly¬ 
gons  in  general.  There  are  three  possi¬ 
ble  ways  to  handle  this: 

1 .  The  vertices  of  each  polygon  could 
be  tested  to  see  if  all  of  them  fall  within 
the  3-D  display  window.  This  implies 
that  400,000  vertices  must  be  checked 
against  two  boundaries  in  each  dimen¬ 
sion  (for  example,  window_x_ m in  and 
window_x_max) ,  or  six  comparisons 
per  vertex.  In  other  words,  this  requires 
2,400,000  comparisons  per  second,  or 
2.4  Mflops.2 

2.  Extents  ( min  and  max)  of  each 
polygon  could  be  found  and  compared 
to  the  window  boundaries.  This  im¬ 
plies  2(4  -1)  comparisons  per  dimen¬ 
sion,  plus  a  comparison  of  min  to  the 
window  minimum  and  of  max  to  the 
window  maximum  —  a  total  of  eight 
comparisons  per  dimension.  Therefore, 
24  comparisons  per  polygon  would 
have  to  be  made,  or  2.4  Mflops  (as 
before). 

3.  Perform  (3*4/2 -2)  or  four  compari¬ 


sons  per  dimension  plus  the  two  com¬ 
parisons  to  the  window  boundaries, 
for  a  total  of  six  comparisons  per  di¬ 
mension.  Therefore,  18  comparisons 
would  be  made  per  polygon,  or  1.8 
Mflops.  This  is  a  savings  of  0.6  Mflops, 
or  25  percent  of  2.4  Mflops. 

This  example  demonstrates  that  valu¬ 
able  computing  resources  are  being 
wasted  by  performing  redundant  work 
using  the  first  two  methods. 

Benchmarks 

The  MIN/MAX  algorithm  was  bench- 
marked  on  several  computer  systems 
using  lists  of  floating-point  numbers 
of  various  lengths.  The  results  are  sum¬ 
marized  in  Table  1.  Note  that  the  MIN/ 
MAX  algorithm  delivers  more  than  the 
promised  25  percent  speedup,  on  the 
majority  of  the  systems  tested.  Since 
the  algorithm  performs  fewer  compari¬ 
sons,  it  performs  fewer  stores  (writes) 
of  items  to  min  and  max.  In  fact,  the 
number  of  writes  is  potentially  reduced 
in  half,  as  each  item  is  compared  to 
either  min  or  max,  but  never  both,  in 
the  MIN/MAX  algorithm.  This  may  re¬ 
duce  bus  traffic  in  some  systems. 

The  method  described  is  applicable 
to  computational  environments  where 
a  comparison  is  a  binary  operation. 
Most  of  today’s  sequential  software  en¬ 
vironments  satisfy  this  condition.  How¬ 
ever,  it  is  possible  to  build  hardware 
to  find  the  min  and  the  max  of  a  fixed 
number  of  items  in  a  single  step. 
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Optimizing  compilers  can  be 
both  a  blessing  and  a  curse. 
Certainly,  we  are  all  happy 
to  have  our  code  automati¬ 
cally  transformed  into  smaller, 
faster  packages:  We  spend  less  time 
sifting  through  long  source  listings  to 
uncover  inefficiencies,  we  can  write 
code  in  more  readable  form,  and  we 
don’t  need  to  resort  to  assembly  lan¬ 
guage  for  optimum  speed  as  often. 

However,  automated  code  transfor¬ 
mation  has  its  drawbacks,  including 
the  tendency  to  decrease  diligence  on 
the  part  of  some  programmers.  There 
is  a  temptation  to  get  sloppy  because 
“the  compiler  will  take  care  of  it.”  The 
compiler  does,  indeed,  handle  many 
inefficiencies,  but  not  all  of  them.  Un¬ 
derstanding  exactly  what  a  compiler  will 
do  to  your  code  (and  what  it  will  not 
do)  is  an  important  step  toward  pro¬ 
ducing  software  that  displays  both  speed 
and  readability.  In  short,  optimizing 
compilers  are  a  supplement  to  hand 
optimization,  not  a  substitute  for  it. 

This  article  focuses  on  both  the  prac¬ 
tical  and  theoretical  aspects  of  code 
optimization,  using  Microsoft’s  recently 
introduced  C  Version  6.0  compiler  (C6) 
as  the  tool. 

You  usually  have  several  goals  in 
mind  when  adopting  an  optimizing  com¬ 
piler.  Among  them  may  be  to: 
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•  Decrease  the  number  of  processor 
cycles  required  by  the  program. 

•  Decrease  the  number  of  address  cal¬ 
culations  performed. 

•  Minimize  the  number  of  memory 
fetches. 

•  Minimize  the  size  of  the  object  code. 

In  all  optimizing  compilers,  most  of 
these  goals  are  achieved  primarily 
through  “local”  optimizations.  Local  op¬ 
timizations  are  improvements  to  small, 
mostly  self-contained  blocks  of  code 
such  as  loops,  switches,  and  if-else  con¬ 
structs.  Despite  all  the  hype  from  com¬ 
piler  vendors  on  “global  optimization,” 
most  code  transformations  are  still  per¬ 
formed  at  the  local  level.  Typical  local 
optimizations  include  elimination  of  com¬ 
mon  subexpressions  and  dead  variables, 
movement  of  loop-invariant  computa¬ 
tions,  and  folding  of  constants  into  a 


single  value. 

In  general,  local  optimizations  are 
fairly  easy  to  perform,  mostly  because 
they  are  easy  to  detect  and  implement. 
Compilers  have  little  trouble  fixing  such 
local  inefficiencies  because  they  are 
reasonably  independent  of  the  pro¬ 
gram’s  flow  of  control  on  a  macro¬ 
scopic  level.  The  behavior  of  variables 
and  expressions  within  small  blocks  is, 
for  the  most  part,  predictable;  the  num¬ 
ber  of  possible  values  taken  by  these 
items,  as  well  as  how  they  fit  within  the 
flow  of  control,  can  be  understood. 

However,  programs  contain  more 
than  just  a  series  of  isolated  blocks, 
and  until  recently,  commercial  compil¬ 
ers  made  almost  no  effort  to  optimize 
across  entire  routines.  In  an  attempt  to 
produce  still  more  efficient  code,  com¬ 
pilers  are  now  appearing  on  the  mar- 
( continued  on  page  66) 
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385.3 

234.2 

279.3 

215.7 

239.9 

189.3 
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312.7 

228.0 
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208.0 
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167.8 
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149.0 

145.4 
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279.3 

234.2 
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259.9 
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181.9 
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Three 
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140.4 
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167.8 
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215.8 
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1 80.1 

180.1 

234.2 
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208.1 

179.5 

175.3 

181.9 

181.9 

228.1 
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164.8 

145.4 

138.0 

140.4 

140.4 

167.9 

Switch 
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Listing 

One 

258.3 

177.2 

Two 

259.9 

180.8 

Three 

203.6 

144.0 

Table  1:  The  “switch”  table 
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(continued  from  page  62) 
ket  with  the  ability  to  perform  “global” 
optimizations.  This  type  of  optimiza¬ 
tion  looks  at  code  on  a  broader  scale, 
seeking  inefficiencies  that  affect  multi¬ 
ple  blocks.  This  task  is  much  more 
difficult  to  achieve  because  of  the  more 
complex  data  flow  analysis  that  must 
be  performed  by  the  compiler. 

Strategies  for  Using  C6  Optimizations 

Although  somewhat  of  a  simplification, 
the  “90/10”  program  execution  rule  is 
generally  true.  That  is,  90  percent  of  a 
program’s  execution  time  is  spent  in 
about  10  percent  of  its  code.  Optimiz¬ 
ing  a  routine  to  achieve  a  50  percent 
speed  increase  sounds  impressive,  but 
if  your  program  spends  an  average  of 
110  microseconds  in  that  routine  for 
every  minute  of  execution  time,  the 
results  are  hardly  noticeable  or  worth 
the  time  to  achieve.  Simply  turning  on 
a  variety  of  optimizing  switches  (such 
as  with  /Ox)  at  compile  time  is  likely 
to  yield  only  modest  improvements  in 
speed.  A  small  amount  of  extra  work 
can  give  you  much  better  results.  These 
results  can  be  achieved,  following  the 
90/10  rule,  by  implementing  an  optimi¬ 
zation  strategy  that  focuses  only  on 
critical  sections  of  code  that  represent 
the  greatest  amount  of  “execution  drag.” 
Uncovering  these  critical  portions  of 
code  can  be  done  with  a  good  profil¬ 
ing  tool.  Unfortunately,  C6  does  not 
provide  such  a  tool.  For  this  article,  I 
used  Inside!  profiler  (Paradigm  Systems, 
Endwell,  N.Y.)  to  produce  a  number 
of  useful  execution  statistics. 

Paradigm’s  profiler  is  available  in  a 
number  of  versions  that  are  compatible 
with  debug  information  and  map  files 
generated  by  C6/QuickC,  Turbo  C, 
Zortech  C++,  and  other  non-C  compil¬ 
ers.  This  tool  has  several  strengths,  in¬ 
cluding  the  ability  to  provide  timing 
statistics  at  the  function,  block,  and 
source-line  levels.  Some  profilers  can 
identify  which  functions  are  consum¬ 
ing  the  most  cycles,  but  will  provide 
no  insight  into  which  elements  within 
a  function  represent  candidates  for  op¬ 
timization.  Block-  and  line-level  analy¬ 
sis  enables  the  programmer  to  identify 
exactly  where  cycles  are  being  con¬ 
sumed  within  a  function,  eliminating 
guesswork  and  saving  time. 

Inside!  also  has  the  ability  to  isolate 
time  spent  during  DOS  calls,  enabling 
you  to  measure  the  impact  of  servicing 
various  DOS  interrupts.  It  is  often  the 
case  that  DOS  I/O  represents  the  larg¬ 
est  percentage  of  execution  time  within 
a  function.  For  example,  if  a  loop  pro¬ 
cesses  100  strings  and  writes  each  to  a 
file  using  fputs( )  on  every  loop  itera¬ 
tion,  there  is  no  question  that  this  con- 
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sumes  an  enormous  amount  of  cycles. 
A  much  better  strategy  would  be  to 
buffer  all  100  strings  in  memory  during 
the  loop  and  write  them  as  a  block 
using  a  single  fputs( )  function  after  the 
loop  completes.  Optimizations  such  as 
this  can  yield  execution  times  that  are 
orders  of  magnitude  faster.  Profilers 
make  optimizations  such  as  this  more 
obvious. 

For  maximum  performance,  the  fol¬ 
lowing  strategy  is  recommended,  as¬ 
suming  your  code  is  already  in  a  rea¬ 
sonably  stable  state: 

1.  Disable  all  optimizations  on  your 
compiler  (/ Od )  and  produce  an  execut¬ 
able. 

2.  Use  a  profiler  to  determine  which 
functions  consume  the  majority  of  cy¬ 
cles.  Most  profilers  provide  a  “percent¬ 
age  of  total  runtime”  value  for  each 
function.  Record  all  statistics  in  a  file. 

3.  Recode  the  major  algorithms  in  these 
functions  (if  possible)  for  more  effi¬ 
ciency,  and  make  local  and  global  op¬ 
timizations  (such  as  elimination  of  re¬ 
dundant  subexpressions  and  unfolded 
constants)  by  hand. 

4.  Declare  all  major  functions  with  the 
_Jastcall keyword,  and  use  based  point¬ 
ers  for  access  to  far  code  and  data. 
Elimination  of  aliasing,  if  possible,  will 
enable  more  aggressive  compiler  opti¬ 
mization  when  you  get  to  that  stage. 

5.  Produce  another  executable,  again 
with  compiler  optimization  disabled, 
and  run  your  profiler.  Compare  the 
new  statistics  to  your  previous  values 
to  measure  progress. 

6.  Compiler  optimizations  can  now  be 
used.  Place  pragma-level  switches  in 
those  files  containing  the  cycle-hungry 
functions,  and/or  use  option  file-level 
switches  where  appropriate. 

7.  Run  the  program  several  more  times 
under  control  of  the  profiler  using  dif¬ 
ferent  combinations  of  pragmas  and/ 
or  switches  to  determine  which  yield 
the  best  results.  Save  all  profiler  statis¬ 
tics,  and  compare  these  with  the  origi¬ 
nal  statistics  to  ensure  that  the  compiler 
is  helping,  not  hurting.  A  “switch  ta¬ 
ble”  (see  Table  1)  will  help  you  record 
your  times. 

8.  Optimize  all  of  the  minor  routines 
of  the  program  using  only  file-level 
switches  or  pragmas.  Hand-optimiza¬ 
tion  of  these  minor  routines  will  prob¬ 
ably  not  be  worth  the  effort. 

Although  this  approach  may  seem 
Overly  thorough,  it  usually  yields  the 
best  results.  Step  3  might  seem  to  de¬ 
feat  the  purpose  of  an  optimizing  com¬ 
piler,  but  there  is  no  amount  of  com¬ 
piler  optimization  that  can  compensate 
for  a  poorly  designed  algorithm.  Typi- 
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cally,  the  best  that  can  be  expected 
from  an  optimizing  compiler  is  a  10  - 
50  percent  improvement  in  speed  for 
well-written  code.  Recoding  an  algo¬ 
rithm  may  boost  performance  many 
times  this  amount. 

The  Role  of  Aliasing  in  Optimization 

Most  compilers  have  trouble  dealing 
with  aliased  variables.  Using  aliases  will 
inhibit  most  of  the  optimizations  that 
could  potentially  be  performed  —  and 
there  are  many.  The  /Oa  switch  is  one 
of  the  most  effective  optimizations  be¬ 
cause  it  enables  many  local  code  im¬ 
provements  that  otherwise  could  not 
be  done. 

Consider  the  code  in  Example  1.  In 
this  example,  *p  is  an  alias  of  the  vari¬ 
able  x.  In  MS  C5.1,  if  the  /Oa  option  is 
used  during  compilation,  the  compiler 


void  main (void) 

{ 

int  x,  y,  *p; 

P  =  &x; 

7.  =  1;  y  =  2;  z  =  6 

for (k  =  1;  k  <=  100.;  k++)  ( 

k  +=  x  +  y  +  z; 
*p  =  k; 

i 

) 


Example  1:  *p  is  an  alias  of  the  variable  x. 


will  assume  that  no  variables  have  been 
aliased  (which  is  not  true).  The  expres¬ 
sion  x+y+z  will  be  seen  by  the  com¬ 
piler  as  being  constant  (or  “loop-in- 
variant”)  for  the  duration  of  the  loop. 
There  is  thus  (apparently)  no  need  to 
compute  x+y+z  100  times,  and  it  will 
be  hoisted  out  of  the  loop  and  re¬ 
placed  with  its  assumed  constant  value. 


However,  the  assignment  of  k  to  *p 
(which  is  really  x),  means  that  x+y+z 
is  not  constant,  and  the  program’s  re¬ 
sults  will  be  incorrect  when  executed. 
This  problem  would  not  have  happened 
if  aliasing  had  been  declared  (/Oa  is 
not  specified),  because  subexpressions 
are  not  factored  (hoisted)  from  loops 
in  this  case. 


Types  of  Optimizations  Provided  by  C6 


Among  the  more  important  optimiza¬ 
tion  features  in  Microsoft  C  6.0  are 
pragma-level  optimization,  global  op¬ 
timization,  new  peep-hole  optimiza¬ 
tions,  based  pointers,  and  in-register 
parameter  passing  (_  Jastcall) .  With  the 
exception  of  based  pointers  (which 
are  described  in  DDJ,  August  1990, 
page  85),  I’ll  briefly  discuss  each  of 
them. 

Pragma-Level  Optimization 

In  C  5.1,  some  optimizations  had  to 
be  disabled  because  the  behavior  of 
the  optimized  code  could  be  unpre¬ 
dictable.  For  example,  imagine  a  pro¬ 
gram  file  that  consists  of  three  func¬ 
tions,  the  first  of  which  uses  aliased 
variables.  In  this  case,  you  must  dis¬ 
able  alias-sensitive  optimizations 
across  all  three  functions,  and  the  abil¬ 
ity  to  optimize  the  two  functions  which 
do  not  use  aliasing  is  lost. 

In  C6,  you  can  fully  optimize  the 
two  non-aliased  functions  while  still 
preventing  alias-sensitive  optimiza¬ 
tions  within  the  first  function.  This  is 
accomplished  by  placing  new 
“pragma”  statements  within  the  pro¬ 
gram  module. 

Pragmas  are  not  optimizations  per 
se,  but  are  control  directives  parsed 
by  the  compiler.  With  pragmas,  virtu¬ 
ally  all  optimizing  switches  can  be 
toggled  on  or  off  at  the  function  level. 
You  can  also  use  these  constructs  to 
toggle  combinations  of  switches  such 
as  #pragma  optimize/ “lee”,  off),  which 
will  turn  off  loop  optimization,  global 


register  allocation,  and  reduction  of 
common  subexpressions. 

Of  the  many  new  optimization- 
related  enhancements  offered  by  C6, 
pragmas  could  have  the  greatest  over¬ 
all  impact  on  program  performance. 
They  allow  a  finer  level  of  control 
over  the  compiler  than  was  possible 
in  C5.1,  and  take  greater  advantage 
of  the  programmer’s  own  knowledge 
of  the  code. 

Global  Optimization 

With  C6,  programmers  can  use  the 
/Oe  switch,  which  tells  the  compiler 
to  manage  register  variables  on  a  func¬ 
tion-wide  basis.  When  this  switch  is 
specified  on  the  command  line  (or  in 
a  pragma),  the  frequently  used  regis¬ 
ter  keyword  is  ignored,  and  the  com¬ 
piler  takes  over.  Although  it  is  a  good 
bet  that  this  switch  will  result  in  speed 
improvements,  it  is  a  mistake  to  as¬ 
sume  that  the  compiler  can  always 
do  a  better  job  of  register-variable 
allocation  than  you  can.  For  func¬ 
tions  that  already  declare  register  vari¬ 
ables,  use  a  good  profiling  tool  to 
measure  the  program’s  performance 
both  with  and  without  the  /Oe  switch 
in  order  to  verify  that  performance 
really  does  improve.  The  same  advice 
applies  to  any  optimizing  operations  — 
verify  to  be  sure.  Another  C6  global 
optimization  factors  common  subex¬ 
pressions  across  entire  functions.  The 
corresponding  switch  is  /Og,  which 
differs  from  its  predecessor  (/Oc)  by 
searching  for  such  subexpressions 


across  entire  functions.  Consider  this 
line  of  code:  x  =  y[k]  +  (c  *  d  +  100  * 
e);  If  the  subexpression  (c  *  d  +  100 
* e )  is  found  to  exist  within  two  loops, 
three  if-else  constructs,  and  two  switch- 
case  blocks,  it  will  not  be  factored  2 
+  3  +  2  =  7  times,  but  just  once.  This, 
of  course,  is  if  the  subexpression  is 
completely  invariant.  If  it  is  variant,  it 
will  be  factored  by  the  number  of 
variances  encountered. 

Peephole  Optimizations 

In  the  world  of  compilers,  a  peephole 
optimization  is  simply  a  specialized 
improvement  on  a  small  (but  poten¬ 
tially  important)  piece  of  code,  typi¬ 
cally  just  a  few  instructions.  This  is 
where  assembly  language  expertise 
pays  large  dividends.  Peephole  opti¬ 
mization  is  performed  by  looking  for 
special  code  patterns  that  may  be  re¬ 
placed  with  more  efficient  equivalents. 
A  simple  example  is  “constant  fold¬ 
ing”  which  can  be  illustrated  with  this 
line  of  code:  a:  =  12*(y  +  25)  -  zfy  + 
r+  9  +  20)  +  10: 

The  three  computations  which  can 
be  performed  by  the  compiler  before 
the  program  is  actually  run  are:  12  * 
25  =  300,  9  +  20  =  29,  and  300  +  10 
=  310.  A  good  compiler  will  replace 
this  code  with  its  more  efficient  equiva¬ 
lent:  x  =  12*y  +  310-  zfy  +r  +  29}, 
This  optimization  saves  one  multiply 
and  two  adds.  In  a  loop  of  100  itera¬ 
tions,  this  amounts  to  100  multiplies 
and  200  adds,  not  to  mention  the 
associated  register  operations.  C6  in- 
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C6  does  a  much  better  job  of  han¬ 
dling  aliased  variables.  In  the  code  sam¬ 
ple,  even  if  the  programmer  specifies 
/Oa  at  compile  time,  the  C6  preproces¬ 
sor  will  notice  that  the  address  of  xhas 
been  taken  and  will  assume  that  its 
value  might  not  be  constant  within  the 
loop.  Because  y  and  rr  have  not  had 
their  address  taken,  the  compiler  as¬ 
sumes  that  these  variables  are  constant, 
and  will  remove  them  while  leaving  x 
correctly  within  the  loop.  C6  therefore 
makes  the  /Oa  option  safer  than  its 
former  implementation  in  C5.1. 

In  some  cases,  aliasing  can  occur 
without  the  explicit  declaration  of  the 
address  operator  (such  as  when  two 
pointers  are  equated),  and  the  prepro¬ 
cessor  will  not  detect  it.  However,  if 
an  option  is  selected  that  invokes  the 
global  optimizer  (such  as  /Oe,  /Og,  or 


eludes  bit-shifting  and  switch  opera¬ 
tions.  Code  blocks  having  these  two  j 
types  of  statements  should  run  faster 
in  C6  than  in  C5.1. 

In-Register  Parameter  Passing 

To  minimize  the  large  amount  of  mem¬ 
ory  I/O  incurred  by  a  function  call, 
C6  includes  the  Jastcall  convention 
which  generates  faster  code  by  pass¬ 
ing  selected  arguments  through  regis¬ 
ters,  rather  than  pushing  and  pop¬ 
ping  from  the  stack.  Jastcall  is  a 
“strongly  typed”  calling  convention, 
meaning  that  the  register  selected  for 
a  particular  variable  is  related  to  the 
variable’s  data  type  (which  defines  its 
size). 

Jastcall  produces  different  results 
depending  on  the  function.  Functions 
passing  only  a  few  characters  and/or 
integers  will  probably  see  the  greatest 
speed  increases  because  all  parame¬ 
ters  can  be  passed  via  registers.  You 
control  which  functions  should  use 
the  Jastcall  convention  by  placing 
the  keyword  in  the  function  declara¬ 
tion.  For  example:  int Jastcall 
func/int,  long,  long,  int,  long);  This 
feature  can  also  be  implemented  on 
a  file-wide  basis  with  the  /Gr  option, 
which  converts  each  function  in  your 
file  to  the  Jastcall  convention.  It 
should  be  noted  that  Jastcall  cannot 
be  used  with  functions  having  variable- 
length  argument  lists,  nor  can  it  be 
used  with  functions  containing  _asm 
blocks.  —  B.D.S. 
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/Ol),  the  optimizer  itself  will  perform  a 
data  flow  analysis  that  can  detect  ali¬ 
ases  which  occur  without  the  address 
operator.  Thus,  switch  combinations 
such  as  /Oae  and  /Oal  represent  an 
additional  layer  of  safety  above  /Oa. 

It  should  be  mentioned  that  the  “a” 
and  “z”  options  have  been  eliminated 
from  /Ox  in  C6.  Microsoft  explains  that 
this  step  was  taken  to  increase  the  safety 
of  /Ox.  For  some  code,  /Ox  might  actu¬ 
ally  produce  slower  execution  times 
in  C6  than  in  C5.1.  However,  /Ox  will 
also  invoke  the  new  global  optimizer, 
meaning  that  execution  times  may  still 
be  faster  in  C6,  even  with  the  elimina¬ 
tion  of  “a”  and  “z.”  Simply  specifying 
/Oxaz  will  include  these  two  switches 
during  compilation. 
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Another  step  Microsoft  has  taken  to 
deal  with  the  aliasing  problem  is  the 
new  /Ow  switch,  which  tells  the  com¬ 
piler  to  assume  no  aliasing  except  when 
calling  functions  (which  typically  pass 
pointers).  This  switch  flushes  all  vari¬ 
ables  held  in  temporary  locations  (such 
as  registers)  back  to  memory  before 
each  function  call,  producing  only  one 
instance  of  a  variable  that  can  be  modi¬ 
fied  by  a  function.  This  prevents  the 
assignment  of  two  different  values  to 
the  same  variable  —  one  in  memory 
and  one  in  a  register. 

The  Effectiveness  of  Compiler  Switch 
Combinations 

Considering  the  wide  variety  of  switches 
and  options  in  today’s  compilers,  how 


do  you  know  which  switches  are  ap¬ 
propriate  for  a  particular  program?  Some 
may  yield  good  results,  while  others 
are  disappointing.  Because  of  the  infi¬ 
nite  variety  of  programs,  there  is  no 
chart  that  indicates  which  combination 
of  switches  should  be  optimal  for  your 
software.  However,  there  are  a  number 
of  rough  guidelines  that  can  be  fol¬ 
lowed.  Some  sample  code  will  help 
illustrate  the  process. 

Consider  Listings  One  through  Three 
(page  104).  These  are  all  different  forms 
of  a  program  that  approximates  the 
definite  integral  of  three  functions  and 
prints  the  results.  The  three  functions 
are: 

y(x)  =  2x2  +  46x  +10 
y(x)  =  3x  +  54 
y(x)  =  x3  —  72x2  +  14 


The  definite  integral  may  be  thought 
of  as  the  area  between  the  curve  of  the 
function  (as  plotted  in  the  xy  plane) 
and  the  x-  axis.  This  particular  program 
measures  the  area  for  the  interval  be¬ 
tween  x  =  0  and  x  =  100.  The  area  is 
approximately  equal  to  the  sum  of  100 
rectangles,  each  of  length  1  and  height 
y(x),  where  x  is  the  midpoint  of  the 
base  of  each  rectangle. 

Listing  One  was  designed  to  test  sev¬ 
eral  optimization  features.  The  bulk  of 
the  test  is  provided  by  the  com- 
pute_areas  function,  which  contains  the 
following  challenges: 

•  There  are  more  register  variable  can¬ 
didates  than  there  are  registers. 

•  There  are  several  subexpressions 
(such  as  a*b )  that  are  both  locally  and 
globally  redundant. 

•  Several  constant  expressions  (such 
as  a*b+c+d)  are  not  folded  into  a 
single  value. 

•  The  program  is  loop  oriented,  and 
some  of  the  inefficiencies  center 
around  these  loops. 

Notice  that  none  of  the  variables  in 
this  listing  have  been  explicitly  declared 
as  “register.”  The  algorithm  itself  is  also 
inefficient.  Three  of  the  loops  can  re¬ 
ally  be  combined  into  one,  and  there 
is  no  need  to  sort  the  array  elements 
in  order  to  compute  an  integral  ap¬ 
proximation.  In  addition,  two  of  the 
loops  are  repeated  100  times  in  order 
to  provide  more  significant  digits  in  the 
output  from  the  profiler.  They  are  not 
meant  to  test  the  compiler. 

Listing  Two  is  an  attempt  to  antici¬ 
pate  compiler  optimizations  and  per¬ 
form  them  by  hand.  None  of  the  algo¬ 
rithmic  inefficiencies  are  fixed.  Listing 
Three  combines  the  improvements 
made  in  Listing  Two,  and  makes  one 
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algorithmic  enhancement  — two  of  the 
loops  are  combined  into  one. 

Table  1  lists  the  execution  times  for 
different  combinations  of  switches  on 
each  code  listing.  The  test  was  per¬ 
formed  on  a  Compaq  386/20  with  no 
floating-point  hardware  (which  would 
not  have  been  used  anyway  on  this 
integer-based  code).  Test  results  are  in 
milliseconds,  and  the  accuracy  of  the 
profiler  is  within  10  microseconds  (+/— 
.01  millisecond).  The  last  digit  was 
rounded  to  the  nearest  hundredth  of  a 
millisecond. 

In  most  cases,  the  test  results  were 
predictable,  but  there  are  some  sur¬ 
prises.  The  predictable  results  are  as 
follows: 

•  On  the  average,  the  optimizations  per¬ 
formed  by  hand  in  Listing  Two  did  not 
help  much  when  it  came  to  execution 
time.  At  least  this  proved  that  the  com¬ 
piler  did  its  job  well  in  Listing  One,  and 
that  certain  hand  optimizations  are  a 
waste  of  time. 

•  Loop  optimization  (/ 01 )  almost  never 
improved  performance  when  used  in 
tandem  with  g  or  c.  Because  the  major 
problem  with  this  program’s  loops  is 
redundant  subexpressions,  loop  optimi¬ 
zations  are  effectively  equivalent  to  re¬ 
duction  of  common  subexpressions. 

•  Specifying  /G2(  use  80286  instruction 
set)  did  not  improve  performance.  I 
suspect  that  this  was  because  the  gen¬ 
erated  code  was  fairly  simple  and  han¬ 
dled  equally  well  by  the  8086  instruc¬ 
tion  set. 

•  The  /Og  switch  (global  subexpres¬ 
sion  reduction)  was  much  more  effec¬ 
tive  than  /Oc  (local  subexpression  re¬ 
duction).  For  this  code,  c  optimizations 
were  a  subset  of  g  optimizations. 

The  surprises  were  as  follows: 

•  It  is  not  surprising  that  the  so-called 
“maximum  optimizations”  such  as  /Ox 
and  /Oaxz  /G2  did  not  produce  the 
fastest  times.  The  surprise  is  that  they 
were  beaten  slightly  by  /Oleg  and 
/Oaleg.  (I  am  unable  to  explain  this 
because  /Ox  supposedly  includes  the 
/Oleg  optimizations.  It  may  be  useful 
to  try  /Oleg  on  loop-intensive  routines 
to  see  if  it  outperforms  other  optimiza¬ 
tions.)  Although  only  two  to  four  per¬ 
cent  better  than  the  maximum,  this  ex¬ 
tra  performance  may  be  critical  in  some 
applications  such  as  animation,  where 
every  millisecond  is  important. 

•  Although  not  shown  in  the  matrix,  I 
declared  all  integer  variables  as  “regis¬ 
ter”  in  all  three  listings  and  ran  the 
tests.  Performance  was  equal  to  or  worse 
than  the  times  shown  in  the  matrix  for 
all  switches.  I  am  unable  to  explain  this. 
«  The  /Oe  option  (global  register  allo¬ 


cation)  was  extremely  effective.  Speci¬ 
fying  only  /Oe  produced  very  fast  times. 
Generally,  any  combination  of  switches 
that  included  option  e  outperformed 
any  other  combination  of  switches  with¬ 
out  option  e. 

These  code  listings  are  isolated  exam¬ 
ples.  Although  this  was  not  a  bench¬ 
mark,  C 6  performed  admirably,  provid¬ 
ing  up  to  a  54  percent  increase  in  per¬ 
formance  over  unoptimized  code.  Dif¬ 
ferent  code  will  undoubtedly  give  dif¬ 
ferent  results,  and  experimentation  is 
important. 

Conclusion 

C6  is  much  more  than  just  a  code  gen¬ 
erator.  It  is  a  powerful  tool  that  re¬ 


quires  a  certain  amount  of  skill  to  use 
effectively.  The  popular  technique 
among  C5.1  programmers  of  consis¬ 
tently  using  the  /Ox  option  (which  en¬ 
ables  many  optimizations  at  once)  has 
less  merit  in  C6.  The  point  is  that  opti¬ 
mization  is  the  responsibility  of  both 
the  compiler  and  the  programmer.  Pro¬ 
grammers  who  understand  that  com¬ 
pilers  are  really  a  supplement  to  hand 
optimization,  rather  than  a  substitute 
for  it,  will  benefit  the  most.  Experimen¬ 
tation  with  these  new  optimizing  fea¬ 
tures  may  be  time  consuming,  but  in  the 
end,  it  is  very  much  worth  the  effort. 

DDJ 

(Listings  begin  on  page  104.) 
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Kermit  for 
Part  II 

Wrapping  up  the  port 


Brian  R.  Anderson 


Last  month,  I  began  a  trek  that 
would  lead  us  from  the  comfort¬ 
able  world  of  DOS  to  the  magi¬ 
cal  land  of  OS/2.  At  our  side  was 
a  familiar  friend,  Kermit,  whose 
job  it  is  to  communicate  between  dif¬ 
ferent  machines  whether  they  be  main¬ 
frame  or  PC.  In  Part  I,  I  presented  the 
PCKermit  and  Shell  modules  (Listings 
One  through  Nine)  and  the  basics  of 
programming  under  Presentation  Man¬ 
ager.  Part  II  provides  Listings  Ten 
through  Nineteen,  covers  some  of  the 
problems  encountered  when  porting 
PCKermit  from  DOS  to  OS/2,  then  ex¬ 
amines  the  communications  capabilities 
of  OS/2  as  well  as  the  low-level  screen 
and  video  I/O.  Finally,  I  discuss  the 
implement  of  TVI950  terminal  emulation. 

I  would  like  to  mention  that,  be¬ 
cause  of  space  considerations,  not  all 
listings  to  PCKermit  are  provided  in  the 
magazine.  The  complete  set  of  listings 
is  available  directly  from  DDJ (see  “Avail¬ 
ability”  on  page  3  for  details). 

Also  note  that  Stony  Brook  has  re¬ 
leased  Version  2.1  of  their  Modula-2 
since  this  article  was  written.  This  new 
version  is  the  first  to  “officially”  sup¬ 
port  Presentation  Manager.  While  func¬ 
tionally  equivalent  to  the  listings  pre¬ 
sented  here,  the  source  code  mentioned 
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tems  technology  at  the  British  Colum¬ 
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Burnaby,  B.C.,  Canada  V5G  3H2. 


above  reflects  changes  introduced  by 
the  new  Modula-2  version. 

Unexpected  Problems 

It  is  not  possible  to  write  to  the  AVio 
presentation  space  while  you  are  exe¬ 
cuting  within  a  thread  unless  you  cre¬ 
ate  a  separate  message  queue  for  the 
thread  —  accessing  AVio  (or  Gpi)  with¬ 
out  a  separate  message  queue  is  one 
of  the  few  activities  that  will  bring  OS/2 
to  its  knees. 

I  found  that  I  could  do  anything  else 
that  I  wanted  to  within  a  thread  (such 
as  open  a  file,  read  from  the  file,  send 
to  the  COM  port,  receive  from  the  COM 
port,  or  write  to  a  file)  without  trouble. 
As  soon  as  I  tried  to  output  to  the  AVio 
presentation  space,  the  system  (except 
for  the  mouse  pointer)  froze.  When  the 
mouse  pointer  was  moved  to  the  area 
on  the  screen  where  the  writing  should 
have  occurred,  the  pointer  disappeared; 
move  the  mouse  away,  and  the  pointer 
reappeared.  I  found  this  particularly 
odd,  as  writing  to  AVio  actually  con¬ 
sists  of  sending  the  data  to  a  buffer  — 
the  contents  of  the  buffer  are  not  actu¬ 
ally  displayed  until  a  WMJPA1NT  mes¬ 
sage  is  detected  within  the  main  thread 
back  in  the  window  procedure. 

My  solution  (rather  than  adding  a 
second  message  queue)  was  to  write 
to  AVio  only  while  executing  in  the 
main  thread.  For  other  threads  to  dis¬ 
play  information,  they  had  to  post  mes¬ 
sages  to  the  main  thread.  The  main 
thread  then  output  to  the  AVio  presen¬ 


tation  space  for  them. 

One  severe  limitation  of  OS/2  is  that 
the  buffers  for  the  serial  ports  are  fixed 
size.  In  other  words,  there  is  no  way 
that  an  applications  programmer  can 
specify  a  larger  buffer.  I  found  that 
while  in  terminal  emulation  mode  (on 
an  IBM  PS/2,  Model  70),  PM  is  unable 
to  keep  the  screen  updated  when  char¬ 
acters  from  the  serial  port  are  arriving 
at  960  per  second  (9600  bps).  I  assume 
PM  message-passing  overhead  causes 
this,  as  no  such  problem  exists  while 
running  a  similar,  but  character-based. 
OS/2  program. 

At  9600  bps,  the  host  sends  a  com¬ 
plete  screenful  (up  to  2000  characters) 
in  about  two  seconds.  However,  be¬ 
cause  the  window  procedure  is  ad¬ 
vised  of  each  character  via  a  message 
(similar  to  a  WM_CHAR  message),  it 
takes  PM  about  six  seconds  to  update 
the  screen  (again,  this  is  for  an  IBM 
PS/2,  Model  70).  With  the  fixed  serial 
buffer  (currently  IK,  but  Microsoft 
doesn’t  promise  not  to  change  that  later), 
a  buffer  overflow  can  easily  result.  And 
that  means  lost  data  and  a  scrambled 
screen.  As  I  mentioned  in  the  begin¬ 
ning  under  the  module  descriptions.  I 
added  one  layer  of  variable  size  buffer¬ 
ing  to  the  Stony  Brook  serial  port  mod¬ 
ule.  When  I  specified  a  buffer  of  -tK. 
the  overflow  problem  was  eliminated. 

The  standard  OS/2  serial  port  isn't 
the  only  buffer  that  can  overflow  in  the 
situation  just  described  —  the  default 
message  queue  size  is  ten  (fine  for 
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(continued  from  page  72) 
messages  generated  by  user  interac¬ 
tion,  but  inadequate  when  the  serial 
port  is  causing  the  generation  of  960 
messages  per  second).  Even  worse  than 
the  low  default,  there  “seems”  to  be 
an  upper  limit  on  message  queue  size 
of  1024  —  above  this,  much  of  the  key¬ 
board  interface  (including  keyboard  ac¬ 
celerators)  simply  quits  working.  Nev¬ 
ertheless,  by  maintaining  a  very  large 
buffer  (4K)  for  incoming  characters,  I 
found  that  there  were  never  problems 
like  those  just  described  with  the  file 
transfer  threads;  the  PAD  and  DataLink 
modules  post  only  one  message  for 


each  packet  received  or  sent.  Even  at 
the  highest  transmission  speed,  this  re¬ 
sults  in  only  about  20  messages  every 
second  —  well  within  the  ability  of  the 
system  to  handle. 

PCKermit  can  transfer  files  between 
my  386-AT  clone  and  my  Atari  ST  at 
up  to  19200  bps.  Although  OS/2  sup¬ 
ports  19200  bps,  IBM  PS/2  hardware 
does  not  —  the  Model  70  will  not  work 
at  19200  bps  (with  this  or  any  other 
communications  program  that  I  have 
tried).  PCKermit  is  able  to  transfer  files 
between  the  IBM  PS/2,  Model  70  and 
the  IBM  3083  mainframe  at  up  to  9600 
bps. 


Terminal  Emulation 

TERM.MOD  (Listing  Ten,  page  108)  pro¬ 
vides  TVI950  terminal  emulation.  TERM- 
.DEF  is  included  in  the  listings  in  Part 
I  of  this  article,  as  are  all  the  definition 
files  for  the  modules  discussed  later. 
Terminal  emulation  consists  of  inter¬ 
cepting  keyboard  entries  and  converting 

PCKermit  can  transfer 
files  between  my 
386-AT  clone  and  my 
Atari  ST  at  up  to 
19200  bps 


them  to  match  what  the  host  expects 
(for  example,  the  Insert  code  from  the 
IBM  PC  keyboard  is  not  the  same  as  the 
Insert  code  for  the  TV1950  — the  soft¬ 
ware  must  make  the  appropriate  trans¬ 
lation).  Control  codes  coming  from  the 
host  must  be  recognized  and  the  ap¬ 
propriate  action  taken  (for  example, 
for  TVI950  emulation,  receipt  of  an 
ESC*  must  result  in  the  video  screen 
being  cleared).  Term  makes  calls  to 
Screen,  the  module  which  contains  the 
actual  functions  for  doing  such  things 
as  clearing  the  screen,  positioning  the 
cursor,  and  so  on.  Also  in  the  Term 
module  is  Dir ,  the  function  that  accepts 
a  path  from  the  user,  changes  to  the 
specified  drive  and  directory,  and  then 
displays  the  requested  directory. 

The  thread  used  for  terminal  emula¬ 
tion  (that  is,  Connect  mode)  is  Term- 
ThrProc  (line  1545).  As  long  as  the 
thread  is  active,  this  procedure  sits  in 
a  loop,  getting  characters  and  posting 
WM_TERM messages  (line  1554).  If  no 
character  has  been  received,  a  call  to 
DosSleep  returns  the  balance  of  this 
thread’s  time  slice  to  the  system  (no 
busy  waiting  loops  in  OS/2!). 

When  the  window  procedure  detects 
the  WM_TERM  message,  it  calls  Put- 
PortChar  (line  1566)  with  the  character 
obtained  from  the  LOWORD  of  the  mpl, 
the  message’s  first  parameter.  The  Put- 
PortChar  procedure  performs  half  of 
TVI950  terminal  emulation:  It  recog¬ 
nizes  the  TVI950  codes  and  takes  ap¬ 
propriate  action  (clears  screen,  posi¬ 
tions  the  cursor,  or  displays  a  charac¬ 
ter).  Several  other  procedures  help  with 
this  task:  Escape ,  line  1604,  handles  the 
escape  sequences;  Cursor ;  line  1620, 
positions  the  cursor;  InsertMsg  and 
MsgOn,  lines  1636  and  1654,  respec¬ 
tively,  place  status  messages  from  the 
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host  in  reverse  video  at  the  bottom  of 
the  screen. 

When  the  window  procedure  detects 
a  WM_CHAR  message,  it  calls 
PutKbdChar  ( line  1457).  This  and  sev¬ 
eral  other  functions  perform  the  bal¬ 
ance  of  TVI950  terminal  emulation:  They 
convert  various  keystrokes  (for  exam¬ 
ple,  function  keys  and  cursor  keys) 
into  the  correct  TVI950  codes.  All  of 
these  special  codes  are  actually  han¬ 
dled  by  Function  (line  1484). 

Also  contained  in  the  Term  module, 
but  not  related  to  terminal  emulation, 
is  the  Dir  procedure  (line  1375).  Be¬ 
sides  displaying  a  directory,  this  func¬ 
tion  allows  the  user  to  log  on  to  a 
different  drive,  or  to  change  to  a  differ¬ 
ent  directory  (both  by  simply  specify¬ 
ing  a  complete  path  while  requesting 
a  directory).  This  feature  is  necessary 
in  a  Kermit  program,  as  only  a  file 
name  must  be  specified  when  sending 
(for  example,  you  cannot  send  a  file 
based  upon  a  complete  path).  This  is 
done  because  not  all  computers  that 
use  PCKermit  recognize  Unix-style  path 
specifications.  The  Dir  procedure  con¬ 
sists  mostly  of  code  for  parsing  the 
path  to  separate  out  the  drive,  the  sub¬ 
directory,  and  the  file  specification. 

The  Screen  Module 

SCREEN. MOD  (Listing  Eleven,  page  110) 
uses  the  OS/2  Vio  functions  to  control 
the  display.  Vio  allows  for  various  at¬ 
tributes  (in  either  monochrome  or 
color).  Constants  defined  starting  on 
line  1694  and  variables  defined  starting 
on  line  1712  control  the  attributes.  The 
only  video  attributes  that  PCKermit  emu¬ 
lates  are  NORMAL,  HIGHLIGHT,  and 
REVERSE  (that  is  all  that  is  needed  for 
interaction  with  the  mainframe  host). 
These  three  attributes  can  be  assigned 
various  colors:  PCKermit  provides  five 
color  combinations.  On  line  1837,  the 
ClrEol  procedure  uses  VioScrollUp  to 
clear  to  end-of-line  by  scrolling  up  a 
portion  of  screen  (filling  it  with  a  blank, 
NORMAL  attribute  character  cell).  On 
line  1961,  Write Att  uses  VioWrtNCell  to 
write  a  character  cell  with  the  current 
attribute  at  the  present  cursor  location. 

SCREEN. MOD  uses  AVio  to  provide 
several  video  functions  including: 
ClrScr,  ClrEol,  GetXY,  GotoXY,  and 
WriteAtt  (which  writes  a  character  plus 
attribute  at  the  current  cursor  position). 
Charles  Petzold  refers  to  AVio  as  “the 
easy  way  out,”  but  says  these  functions 
are  “too  good  to  give  up  entirely.”  I 
agree  on  both  counts:  AVio  is  certainly 
easier  to  use  than  Gpi,  but  it  has  every¬ 
thing  that  is  needed  to  provide  the 
screen  output  for  emulating  a  standard 
VDT.  I  make  no  apology  for  taking  the 
easy  way  out! 


Working  with  CommPort 

COMMPORT.MOD  (Listing  Twelve,  page 
114)  is  a  module  that  was  supplied  by 
Stony  Brook.  Its  purpose  is  to  transmit 
a  byte  at  a  time  to  the  communications 
ports  (COM1  or  COM2).  The  DataLink 
module  (see  Listing  Seventeen,  page 
119)  calls  this  module  repeatedly.  The 
original  module  had  a  couple  of  prob¬ 
lems,  the  most  serious  of  which  was 
that  for  receive,  it  would  wait  until  a 
character  was  available  rather  than  re¬ 
turning  immediately  with  status  set  to 
“no  character”  (this  causes  the  system 
to  hang  in  many  situations).  I  have 
modified  the  module  extensively  to  cor¬ 
rect  this  and  a  few  other  problems,  and 


to  add  a  more  flexible  buffering  scheme. 
(See  earlier  under  “Unexpected  Prob¬ 
lems”  for  further  details.)  The  fix  in¬ 
volved  using  DosDevIOCtl  to  check  the 
status  of  the  serial  port  in  several  cases, 
and  return  proper  status  information 
to  the  caller.  In  addition,  there  was  a 
small  problem  with  setting  up  stop  bits. 

I  further  enhanced  CommPort  by  add¬ 
ing  dynamically  allocated  buffers.  In 
the  original  version,  calling  GetChar 
resulted  in  just  a  single  character  being 
fetched  from  the  serial  port.  If  GetChar 
is  not  called  often  enough,  the  OS/2 
buffer  will  eventually  overrun.  In  my 
enhanced  version,  each  call  to  GetChar 
transfers  all  of  the  characters  from 
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Original  Stony  Brook  Modula-2  (very  similar  to  Microsoft  C) 

WinPostMsg  (ChildFrameWindow,  WM_PAD, 

MPFROM2 SHORT  (PAD_ReceivedPacket ,  0 
HPFROM2SHORT  (PktNbr,  rSeq) ) ; 

Stony  Brook  Modula-2  v2.1 

VAR 

MP1,  HP 2  :  MPARAM;  (*  New  variables  required  *) 

MP1.W1  :  =  PAD_ReceivedPacket ;  MP1.W2  :=  0; 

MP2.W1  :=  PktNbr;  MP2.W2  :=  rSeq; 

WinPostMsg  (ChildFrameWindow,  WM_PAD,  MP1,  MP2); 


Example  1:  Code  fragments  showing  how  the  new  version  of  Stony  Brook 
Modula-2  handles  MPARAM. 


OS/2’s  buffer  into  a  local  buffer  (which 
can  be  any  size).  Although  each  call  to 
GetChar  returns  only  a  single  charac¬ 
ter,  it  also  results  in  OS/2’s  (too  small) 
buffer  getting  transferred  to  a  local  buffer 
(the  size  of  which  can  be  specified  by 
the  programmer). 

Stony  Brook  v2.1  should  be  ship¬ 
ping  by  the  time  you  read  this,  and  will 
have  many  improvements  (including  a 
fixed  CommPort  module).  Unfortu¬ 
nately,  Stony  Brook  has  changed  the 
use  of  the  OS/2-PM  message  parame¬ 
ter,  MPARAM.  According  to  the  Micro¬ 
soft  documentation,  and  the  earlier  ver¬ 
sions  of  the  Stony  Brook  documenta¬ 
tion,  MPARAM  is  a  32-bit  address.  Stony 
Brook  v2.1  has  changed  the  represen¬ 
tation  of  MPARAM  to  a  variant  record. 
Figure  1  shows  the  record  definition. 

MPARAM  (a  32-bit  address  used  as 
a  parameter  during  message  passing) 
is  often  made  up  of  an  unsigned  short 
or  a  char.  Microsoft  provides  various 
macros,  such  as  MPFROM2SHORT, 
which  make  the  necessary  conversions. 
The  original  version  of  Stony  Brook 
provided  similar  macros.  The  new  ver¬ 
sion,  however,  does  not  use  the  mac¬ 
ros,  but  instead  fills  in  the  variant  re¬ 
cords  with  information  before  passing 
the  parameters.  Example  1  provides  a 
code  fragment  that  demonstrates  this. 


Other  Modules 

FILES. MOD  (Listing  Thirteen,  page  1 16) 
provides  access  to  disk  files:  opens, 
reads,  writes,  and  closes.  FILES  is  essen¬ 
tially  unchanged  from  the  DOS  version 
except  that  file  name  clashes  now  re¬ 
sult  in  automatic  renaming  of  the  file, 
rather  than  asking  the  user  whether  or 
not  to  overwrite  (for  example,  if  a  du¬ 
plicate  file  name  of  FILENAME.TYP  is 
received,  it  is  renamed  to  FILE- 
NAME.KO). 

KH.DEF  (Listing  Fourteen,  page  118), 
KH.MOD  (Listing  Fifteen,  page  118), 
and  PCKERMIT.H  (Listing  Sixteen,  page 
118)  contain  definitions  of  constants 
(e.g.,  IDM_KERMIT)  that  are  used  by 
the  resources.  Each  menu  item,  radio 
button,  icon,  and  so  on,  has  its  own 
unique  identifier.  The  Modula-2  pro¬ 
gram  gets  this  information  from  KH.DEF 
(KH.MOD  is  empty).  The  resources  them¬ 
selves  get  the  information  from  PC- 


TYPE 

MPARAM 

=  RECORD 

CASE 

:  INTEGER  OF 

1 

:  B1,  B2,  B3,  B4  :  BYTE; 

2 

:  W1,  W2  :  WORD; 

3 

:  L  :  LONG  1  NT; 

END; 

END; 

Figure  1:  Record  type  definition  for 
MPARAM. 
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KERMIT.H.  In  a  C  program,  both  the  Conclusion  functions,  and  I  suspect  that  will  in¬ 
program  and  the  resources  would  get  While  it  is  a  steep  learning  curve  to  volve  another  steep  climb  up  a  slip- 

the  information  from  the  (.H)  header  become  familiar  with  the  OS/2  Kernel  pery  slope.  Again,  I  feel  the  view  will 

file;  but  because  the  Modula-2  com-  API  and  the  OS/2  Presentation  Man-  be  worth  the  climb  —  learning  to  use 

piler  cannot  read  .H  files,  the  informa-  ager  API,  it  is  well  worth  the  climb,  the  PM  functions  is  certainly  easier  than 

tion  must  be  duplicated  in  a  .DEF  file.  Once  you  have  a  working  skeleton,  writing  similar  functionality  into  your 

PAD. MOD  is  the  packet  assembler/  adding  the  menus,  keyboard  accelera-  own  code, 
disassembler.  Because  of  its  length,  the  tors,  message  boxes,  and  dialog  boxes  Finally,  I  would  like  to  mention  that 

PAD. MOD  listing  is  not  included  in  this  is  really  quite  easy.  Having  these  things  since  this  article  was  written  I  have 

article  (but  it  is  available  directly  from  out  of  the  way  allows  you  to  concen-  continued  to  enhance  PCKermit.  The 

DDJ).  Except  for  the  screen  output  (via  trate  upon  the  application  itself.  Except  enhanced  version  is  available  directly 

message  passing)  to  keep  the  user  in-  for  console  I/O,  which  is  heavily  influ-  from  me  at  the  address  given  at  the 
formed,  and  multiple  file  sending,  this  enced  by  the  Presentation  Manager,  beginning  of  this  article, 

module  is  essentially  unchanged  from  much  of  any  OS/2-PM  application  is  DDj 

the  original  DOS  version  (see  “Kermit  the  same  as  in  a  more  traditional  envi-  (Listings  begin  on  page  108.) 
Meets  Modula-2,”  DDJ,  May  1989).  Dur-  ronment.  Vote  for  your  favorite  feature/article, 

ing  Kermit  file  transfer,  PAD  assembles  This  article  does  not  address  the  Gpi  Circle  Reader  Service  No.  7. 

the  data  into  packets  and  passes  the  - 

packets  on  to  the  DataLink  module. 

The  changes  involve  the  OS/2-PM 
message  passing  facility,  WinPOst- 
Msg( )  —  which  replaces  the  ordinary 
terminal  output  for  progress  messages, 
and  collecting  all  of  the  output  routines 
into  a  single  function.  This  rather  strange 
organization  is  necessary  because  most 
of  the  PAD  module  runs  in  a  non¬ 
message-queue  thread,  which  cannot 
perform  I/O.  The  function  that  collects 
the  output  routines  is  called  from  the 
main  thread,  which  has  a  message 
queue. 

DATALINK. MOD  gets  the  packets 
from  PAD,  adds  SOH  and  Checksum, 
and  transmits  them  (as  well  as  the  re¬ 
verse).  Again,  this  module  is  virtually 
unchanged  from  the  DOS  version. 

PCKERMIT.RC  (Listing  Eighteen,  page 
119)  is  the  resource  file  that  contains 
all  resources  except  bitmaps.  These  re¬ 
sources  include  menus,  dialog  boxes, 
and  keyboard  accelerators.  Bitmaps, 
which  include  icons,  fonts,  and  graph¬ 
ics  bit  images,  are  in  separate  files.  A 
bit-image  file  called  PCKERMIT.ICO  (see 
“Availability”  on  page  3)  contains  the 
icon  (a  picture  of  Kermit  the  Frog)  that 
is  displayed  when  the  program  is  mini¬ 
mized.  Icons  are  created  interactively 
using  a  program  called  ICONEDIT, 
which  is  essentially  a  drawing  program. 

Although  I  created  all  of  the  dialog 
boxes  using  the  Microsoft’s  DLGBOX 
program  to  separately  create  the  re¬ 
sources  for  the  dialog  boxes,  I  then 
merged  all  of  the  code  together  into 
PCKERMIT.RC.  I  added  the  menus  and 
accelerator  tables  manually.  The  re¬ 
source  compiler  converts  the  .RC  file 
into  a  .RES  file,  which  is  then  linked 
into  the  .EXE  -file. 

PCKERMIT.EDF  (Listing  Nineteen, 
page  121)  is  the  .EXE  definition  file;  it 
contains  information  for  the  linker(e.g., 
stack  size,  window  procedures  ex¬ 
ported,  procedures  imported  via  DLLs, 
and  mode).  In  a  C  project,  this  file 
would  be  called  PCKERMIT.  DEF. 
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Listing  One  (Text  begins  on  page  16.) 


PROT  -  A  386  protected  mode  DOS  extender 
Copyright  (C)  1989,  by  A1  Williams  All  rights  reserved. 
Permission  is  granted  for  non-commercial  use  of  this  software. 
You  are  expressly  prohibited  from  selling  this  software, 
distributing  it  with  another  product,  or  removing  this  notice. 
If  you  distribute  this  software  to  others  in  any  form,  you  must 
distribute  all  of  the  files  that  are  listed  below: 

PROT. ASM  -  The  main  routines  and  protected  mode  support. 
EQUMAC.INC  -  Equates  and  macros. 

STACKS. INC  -  Stack  segments. 

GDT.INC  -  Global  descriptor  table. 

INT386.INC  -  Protected  mode  interrupt  handlers. 

PMDEMO.PM  -  Example  user  code. 

PMPWD.PM  -  Alternate  example  code. 

FBROWSE.PM  -  Complete  sample  application. 

TSS.INC  -  Task  state  segments. 

C0DE16.INC  -  16  bit  DOS  code  (entry/exit). 

PMASM.BAT  -  MASM  driver  for  assembling  PROT  programs. 

PTASM.BAT  -  TASM  driver  for  assembling  PROT  programs. 

To  assemble:  MASM  /DPROGRAM=pname  PROT. ASM, , PROT. LST; 

To  link:  LINK  PROT; 

pname  is  the  program  name  (code  in  pname.PM) 
if  pname  is  ommited,  USER. PM  is  used 
The  resulting  .EXE  file  is  executable  from  the  DOS  prompt. 

This  file  is:  PROT. ASM,  the  main  protected  mode  code. 


.XLIST 

.LALL 


;  Name  program  if  PROGRAM  is  defined 
IFDEF  PROGRAM 


CRIT_OFF 
CRIT  SEG 


DD 

DW 


OFFSET  DEF_CRIT 
SEL  CODE 3 2 


;  Message  for  default  critical  error  handler 
CRITMSG  DB  'A  critical  error  has  occured.' 

DB  ' <A>bort,  <R>etry,  <F>ail?  $' 

;  here  is  where  vm86  int's  stack  up  plO  esp's 
INTSP  DD  $+PVSTACK+4 

DB  PVSTACK  DUP  (0) 

;  Default  VM86CALL  parameter  block 
PINTFRAME  VM86BLK  <> 

;  interface  block  for  critical  error  handler 
CINTFRAME  VM86BLK  <> 

;  hardware  interrupt  vm86  block 
HINTFRAME  VM86BLK  <> 

;  storage  for  the  original  PIC  interrupt  mask  registers 


13,10 


INTMASK 

INTMASKAT 


DAT32END 
DAT  3  2 


DB 


EQU 

ENDS 


Begin  32  bit  code  segment 


PCODE 

SEG32BEG 


SEGMENT 

ASSUME 

PROC 

EQU 


PARA  PUBLIC  ' CODE32'  USE32 
CS:SEG32,  DS:DAT32 


Start  of  protected  mode  code.  We  jump  here  from  inside  CODE16.INC 


MOV 

MOV 


AX, SEL_DATA 
DS,  AX 


1st  order  of  business: 
load  up  segment  registers 


VTITLE 

MACRO 

PNAME 

;  temporary  macro  to  title  program 

LSS 

ESP,  FWORD  PTR  SLOAD 

TITLE 

PNAME 

MOV 

AX, SEL  VIDEO 

ENDM 

MOV 

ES,  AX 

VTITLE 

% PROGRAM 

MOV 

AX, SEL  DATAO 

PURGE 

VTITLE 

;  delete  macro 

MOV 

FS,  AX 

;  equates 

and  macros 

MOV 

AX, SEL  GDT 

INCLUDE 

EQUMAC . INC 

MOV 

GS,  AX 

;  set  up  IDT 

;  stack  segments 

CALL32S 

MAKIDT 

INCLUDE 

STACKS . INC 

;  reprogram  pic(s) 

IN 

AL,  21H 

;  Global 

descriptor  table  definitons 

MOV 

INTMASK, AL 

INCLUDE 

GDT.INC 

IF  ATCLASS 

IN 

AL,  0A1H 

;  interrupt  code 

MOV 

INTMASKAT, AL 

INCLUDE 

INT386. INC 

MOV 

AL, 11H 

OUT 

0A0H, AL 

;  this  is 

required  to 

find  out  how  large  PROT  is 

OUT 

20H, AL 

ZZZGROUP 

GROUP 

ZZZSEG 

I DELAY 

MOV 

AL, 28H 

********* 

************ 

************* 

*********************************** 

OUT 

0A1H, AL 

;  32  bit 

data  segment 

MOV 

AL,  20H 

DAT  3  2 

SEGMENT 

PARA  PUBLIC  1 

'  DATA32'  USE32 

OUT 

21H, AL 

DAT32BEG 

EQU 

$ 

IDELAY 

MOV 

AL,  2 

;  32  bit 

stack  values 

OUT 

0A1H,  AL 

SLOAD 

DD 

OFFSET  SSEG321-1 

MOV 

AL,  4 

SSLD 

DW 

SEL_STACK 

OUT 

21H, AL 

IDELAY 

;  This  location  will  1 

hold  the  address  for  the  PMODE  IDT 

MOV 

AL,  1 

NEWIDT 

EQU 

THIS  FWORD 

OUT 

0A1H,  AL 

DW 

(IDTEND-IDTBEG)-l 

OUT 

21H,  AL 

IDTB 

DD 

0 

;  filled  in  at  runtime 

IDELAY 

MOV 

AL, INTMASKAT 

;  PSP  segment  address 

OUT 

0A1H, AL 

_PSP 

DW 

0 

MOV 

AL, INTMASK 

OUT 

21H,  AL 

;  video  variables  for 

the  OUCH  and 

related  routines 

ELSE 

CURSOR 

DD 

0 

;  cursor  location 

;  INBOARD  PC  Code 

COLOR 

DB 

7 

;  display  cursor 

MOV 

AL, 13H 

OUT 

20H,  AL 

;  temp  vars  for  some  i 

non  reentrant 

interrupt  routines 

MOV 

AL, 20H 

ST01 

DD 

0 

OUT 

21H,  AL 

ST02 

DD 

0 

MOV 

AL,  9 

ST03 

DD 

0 

OUT 

21H, AL 

ST04 

DD 

0 

MOV 

AL, INTMASK 

SAV  DS 

DD 

0 

OUT 

21H, AL 

SAV  ES 

DD 

0 

END  IF 

SAV  GS 

DD 

0 

STI 

;  enable  interrupts 

SAV_FS 

DD 

0 

;  ***  Start  user  code 

with  TSS  (req'd  for  vm86  op's  etc.) 

BPON 

DB 

0 

;  Enables  conditional  breakpoints 

MOV 

AX, TSSO 

LTR 

AX 

;  Debug  Dump  variables 

JMPABS32 

TSS1, 0 

DUMP  SEG 

DW 

0 

;  if  zero  don't  dump  memory 

PCODE  ENDP 

DUMP  OFF 

DD 

0 

;  Offset  to  start  at 

DUMP_CNT 

DD 

0 

;  #  of  bytes  to  dump 

;***  32  bit  support  routines 

;  This  routine  creates  the  required  IDT.  This  is  only  a  subroutine  to  keep 

;  Break  & 

critical  error  handler  variables 

;  from  cluttering  up 

the  main  code,  since  you  aren't  likely  to  call  it  again. 

BREAKKEY 

DB 

0 

;  break  key  occurred 

;  Assumes  that  all  ISR  routines  are  of  fixed  length  and  in  sequence.  After 

CRITICAL 

DB 

0 

;  critical  error  occured 

;  makidt  has  built  the  table,  you  can  still  replace  individual  INT  gates  with 

CRITAX 

DW 

0 

;  critical  error  ax 

;  your  own  gates  (see 

make  gate) 

CRITDI 

DW 

0 

;  critical  error  di 

MAKIDT  PROC 

NEAR 

CRITBP 

DW 

0 

;  critical  error  bp 

PUSH 

ES 

CRITSI 

DW 

0 

;  critical  error  si 

MOV 

AX, IDTABLE 

MOVZX 

EAX, AX 

;  Address 

of  user's  break  handler 

SHL 

EAX,  4 

BREAK  HANDLE  EQU 

THIS  FWORD 

ADD 

EAX, OFFSET  IDTBEG 

BRK  OFF 

DD 

0 

MOV 

IDTB, EAX 

BRK_SEG 

DW 

0 

MOV 

AX, SEL  IDT 

MOV 

ES,  AX 

;  Address 

of  user's  critical  error 

handler 

XOR 

AL,  AL 

CRIT_HANDLE  EQU 

THIS  FWORD 

(continued  on  page  82) 
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Listing 

One  (Listing  continued,  text  begins  on  page  16.) 

;  Make  all 

interrupt 

gates  DPL=3 

MOV 

AH, INTR  GATE  OR  DPL3 

MOV 

CX, SEL  ICODE 

MOV 

EDX, OFFSET  IDTBEG 

XOR 

SI,  SI 

MOV 

EBX, OFFSET  INTO 

IDTLOOP : 

CALL32F 

SEL  CODE32 ,MAKE  GATE 

ADD 

EBX, INT1-INT0 

ADD 

SI,  8 

;  loop  form  max  #  of 

interrupts 

CMP 

SI, (TOPINT+1 ) *8 

JB 

SHORT  IDTLOOP 

LIDT 

NEWIDT 

POP 

ES 

RET 

MAKIDT 

ENDP 

;  This  routine  is  just  like  the  real  mode  make  desc 

;  EBX=base 

ECX=limit 

AH=ARB  AL=0  or  1  for  16  or  32  bit 

;  SI=selector  (TI&RPL 

ignored)  and  ES:EDX  is  the  table  base  address 

MAKE  SEG 

PROC 

FAR 

PUSH 

ESI 

PUSH 

EAX 

PUSH 

ECX 

MOVZX 

ESI, SI 

SHR 

SI, 3  ;  adjust  to  slot  # 

SHL 

AL,6  ;  shift  size  to  right  bit  position 

CMP 

ECX,OFFFFFH  ;  see  if  you  need  to  set  G  bit 

JLE 

OKLIM 

SHR 

ECX, 12  ;  div  by  4096 

OR 

AL,80H  ;  set  G  bit 

OKLIM: 

MOV 

ES: [EDX+ESI*8] , CX 

SHR 

ECX, 16 

OR 

CL,  AL 

MOV 

ES: [EDX+ESI*8+6] , CL 

MOV 

ES: [EDX+ESI*8+2] , BX 

SHR 

EBX,  16 

MOV 

ES: [EDX+ESI*8+4 ) , BL 

MOV 

ES: [EDX+ESI*8+5] ,  AH 

MOV 

ES: [EDX+ESI*8+7] , BH 

POP 

ECX 

POP 

EAX 

POP 

ESI 

RET 

MAKE_SEG 

ENDP 

;  This  routine  make  gates  —  AL=WC  if  applicable  —  AH=ARB  —  EBX=offset 

;  CX=selector  --  ES: 

SDX=table  base  —  SI=  selector  (TI&RPL  ignored) 

MAKE  GATE 

PROC 

FAR 

PUSH 

ESI 

PUSH 

EBX 

SHR 

SI, 3 

MOVZX 

ESI, SI 

MOV 

ES: [EDX+ESI*8] ,  BX 

MOV 

ES: [EDX+ESI*8+2] ,  CX 

MOV 

ES: [EDX+ESI*8+4 ] ,  AX 

SHR 

EBX, 16 

MOV 

ES: [EDX+ESI*8+6] , BX 

POP 

EBX 

POP 

ESI 

RET 

MAKE_GATE 

ENDP 

;  Routine  to  call  BIOS/DOS.  NOT  REENTRANT  (but  so  what?  DOS  isn't  either) 

CALL86 

PROC 

FAR 

PUSH 

DS 

PUSH 

GS 

PUSH 

FS 

RETRY86 : 

PUSHAD 

PUSHFD 

PUSH 

ES: [EBX+40]  ;  save  new  ebx 

PUSH 

EBX 

PUSH 

ES 

INT 

3 OH  ;  call  PROT 

PUSH 

SEL  DATA 

POP 

DS 

POP 

ES 

XCHG 

EBX, [ESP] 

POP 

ES: [EBX+40] 

PUSHFD 

CMP 

BREAKKEY, 0  ;  see  if  break  occured 

JZ 

SHORT  NOBRKCHECK 

CMP 

BRK  SEG,0  ;  see  if  user  has  brk  handler 

JZ 

SHORT  NOBRKCHECK 

;  call  user's  break  handler 

MOV 

BREAKKEY, 0 

CALL 

FWORD  PTR  BREAK  HANDLE 

NOBRKCHECK 

CMP 

CRITICAL, 0  ;  see  if  critical  error 

JZ 

SHORT  NOCRITCK 

CMP 

CRIT  SEG,0  ;  see  if  critical  error  handler 

JZ 

SHORT  NOCRITCK 

;  call  critical  error  handler 

PUSH 

EAX 

XOR 

AL,  AL 

MOV 

CRITICAL,  AL 

CALL 

FWORD  PTR  CRIT  HANDLE 

OR 

AL, AL  ;  AL=0?  FAIL 

JNZ 

SHORT  RETRY? 

POP 

EAX 

POPFD 

STC 

PUSHFD 

;  make  sure  carry  is  set 

JMP 

SHORT  NOCRITCK 

RETRY?: 

DEC 

AL  ;  AL=1?  RETRY 

JNZ 

SHORT  C ABORT 

( continued  on  page  84) 
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;  To  retry 

an  error. 

we  set  up  everything  the  way  it  was  and 

;  redo  the 

interrupt . 

This  is  cheating  (a  little) ,  and  may  not 

;  work  in  every  possible  case,  but  it  seems  to  work  in  all  the  cases  tried. 

POP 

EAX 

POPFD 

POP 

ES:  [EBX+40] 

POPFD 

POPAD 

JMP 

SHORT  RETRY 8 6 

CABORT: 

POP 

EAX  ;  ABORT 

POPFD 

LEA 

ESP, [ESP+40]  ;  balance  stack 

MOV 

AL, 7FH  ;  DOS  error=7FH 

BACK2DOS 

NOCRITCK: 

POPFD 

LEA 

ESP, [ESP+40]  ;  balance  stack 

PUSHFD 

;  see  if  segment  save 

requested 

CMP 

BYTE  PTR  ES: [EBX],0 

JZ 

NOSEGS 

;  load  parameter  block  from  static  save  area 

PUSH 

EAX 

MOV 

EAX, SAV  FS 

MOV 

ES: [EBX+28] , EAX 

MOV 

EAX, SAV  DS 

MOV 

ES: [EBX+24] , EAX 

MOV 

EAX, SAV  ES 

MOV 

ES: [EBX+20] , EAX 

MOV 

EAX, SAV  GS 

MOV 

ES: [EBX+32] , EAX 

POP 

EAX 

NOSEGS: 

POPFD 

POP 

FS 

POP 

GS 

POP 

DS 

MOV 

EBX, ES: [EBX+40] 

RET 

CALL86 

ENDP 

;  Directly  clear  page 

0  of  the  screen 

CLS 

PROC 

FAR 

PUSHFD 

PUSH 

DS 

PUSH 

ES 

PUSH 

EDI 

PUSH 

ECX 

PUSH 

EAX 

MOV 

CX, SEL  VIDEO 

MOV 

ES,CX 

MOV 

CX, SEL  DATA 

MOV 

DS,CX 

CLD 

MOV 

EDI,  0 

MOV 

ECX, 2000 

MOV 

AX, 0720H 

REP 

STOSW 

XOR 

ECX, ECX 

MOV 

CURSOR, ECX 

POP 

EAX 

POP 

ECX 

POP 

EDI 

POP 

ES 

POP 

DS 

POPFD 

RET 

CLS 

ENDP 

;  Outputs  message  to  : 

3creen  —  ASCIIZ  pointer  in  ds:ebx  -  modifies  ebx 

MESSOUT 

PROC 

FAR 

PUSH 

EAX 

NXT: 

MOV 

AL, [EBX] 

INC 

EBX 

OR 

AL,  AL 

JNZ 

SHORT  SKIP 

POP 

EAX 

RET 

SKIP: 

CALL32F 

SEL  CODE32,  OUCH 

JMP 

SHORT  NXT 

MESSOUT 

ENDP 

;  Performs 

CR/LF  sequence  to  screen  using  OUCH 

CRLF 

PROC 

FAR 

PUSH 

EAX 

MOV 

AL,  13 

CALL32F 

SEL  CODE32, OUCH 

MOV 

AL,  10 

CALL32F 

SEL  CODE32, OUCH 

POP 

EAX 

RET 

CRLF 

ENDP 

;  Character 

and  digit 

output  routines 

;  hexout4  - 

print  longword  in  EAX  in  hex 

;  hexout2  - 

print  word  in  AX  in  hex 

;  hexout  - 

print  byte  in  AL  in  hex 

;  ouch 

print  ASCII  character  in  AL 

OUTPUT 

PROC 

FAR 

;  print  longword  in  eax 

HEXOUT4 

LABEL 

FAR 

PUSH 

EAX 

SHR 

EAX, 16 

CALL32F 

SEL  CODE 3 2, HEXOUT 2 

POP 

EAX 

;  print  word  in  ax 

HEX0UT2 

LABEL 

FAR 

PUSH 

EAX 

MOV 

AL,  AH 

CALL32F 

SEL  CODE32,  HEXOUT 

POP 

EAX 

;  print  a 

hex  byte  in 

al 

HEXOUT 

LABEL 

FAR 

MOV 

BL,  AL 

AND 

AX, 0F0H 

SHL 

AX,  4 

MOV 

AL,  BL 

AND 

AL, OFH 

ADD 

AX, '00' 

MOV 

BL,  AL 

MOV 

AL,  AH 

CALL32F 

SEL  CODE32,  HEX1DIG 

MOV 

AL,  BL 

HEX1DIG: 

CMP 

AL, ' 9' 

JBE 

SHORT  H1DIG 

H1DIG: 

ADD 

AL, ' A' O' -0AH 

OUCH 

LABEL 

FAR 

PUSH 

EDI 

PUSH 

EAX 

PUSH 

DS 

PUSH 

ES 

PUSH 

ECX 

MOV 

CX, SEL  VIDEO 

MOV 

ES,  CX 

MOV 

CX, SEL  DATA 

MOV 

DS,  CX 

POP 

ECX 

MOV 

AH, COLOR 

MOV 

EDI, CURSOR 

CMP 

EDI, 2000  ;  rolli 

JB 

NOSCROLL 

rolling  off  the  screen? 


scroll  screen  if  required 


PUSH 

DS 

PUSH 

ES 

POP 

DS 

PUSH 

ESI 

PUSH 

ECX 

PUSH 

EDI 

CLD 

MOV 

ECX, 960 

XOR 

EDI, EDI 

MOV 

ESI, 160 

REP 

MOVSD 

POP 

EDI 

SUB 

EDI, 80 

POP 

ECX 

POP 

ESI 

POP 

DS 

CMP 

AL, 0DH 

JZ 

SHORT  CR 

CMP 

AL, 0AH 

JZ 

SHORT  LF 

:reen 

MOV 

ES: [EDI *2 ] , AX 

INC 

EDI 

JMP 

SHORT  OUCHD 

PUSH 

EDX 

PUSH 

ECX 

MOV 

EAX, EDI 

XOR 

EDX, EDX 

MOV 

ECX, 80 

DIV 

ECX 

SUB 

EDI, EDX 

POP 

ECX 

POP 

EDX 

JMP 

SHORT  OUCHD 

ADD 

EDI, 50H 

MOV 

CURSOR, EDI  i 

POP 

ES 

POP 

DS 

POP 

EAX 

POP 

EDI 

RET 

ENDP 

LF: 

OUCHD : 


OUTPUT 

;  Default  critical  error  handler 


update  cursor 


PROC 

PUSH 

PUSH 

PUSH 

MOV 

MOV 

ASSUME 


FAR 
ES 
EBX 
EDX 

BX, SEL_DATA 
ES,  BX 

DS: NOTHING,  ES:DAT32 


load  critical  error  handler's  private  stack 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
PUSH 

VM86CALL 

POP 

CLOOP: 

MOV 

PUSH 

VM86CALL 

POP 

;  ignore  function  keys 
OR 
JZ 


BX, CSTACK 
CINTFRAME . VMSS, EBX 
EBX, OFFSET  CSTACK 
CINTFRAME .VMESP, EBX 
BX, DAT 3 2 

CINTFRAME .VMDS, EBX 
BX, 21H 

CINTFRAME. VMINT, EBX 
EBX,  OFFSET  CINTFRAME 
EDX, OFFSET  CRITMSG 
AH,  9 
EBX 


AH,  7 
EBX 


print  message 


get  keystroke 


MOV 


AL,  AL 

SHORT  CRITFNKEY 
AH,  AL 


AL, 20H 
AL,  'a' 


convert  to  lower  case 


(continued  on  page  86) 
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CMP 

MOV 

JNZ 

MOV 

MOV 

PUSH 

PUSH 

VM86CALL 

POP 

MOV 

MOV 

PUSH 

VM86CALL 

POP 

MOV 

MOV 

VM86CALL 

POP 


MOV  i 

PUSH  1 

VM86CALL 
POP  1 

MOV  I 

MOV  i 

PUSH  1 

VM86CALL 
POP  1 

jmp  : 

ENDP 


SHORT  CFAIL? 
AL,  2 

SHORT  CREXIT 
AL, 'f' 

SHORT  CRETRY? 
AL,  AL 

SHORT  CREXIT 

AL,  'r' 

AL,  1 

SHORT  CRITBAD 
DL, AH  ; 


echo  letter  +  CRLF 


EBX 

SHORT  CLOOP 


ignore  fn  key/alt-key 


unknown  input  -  ring  bell 


SEG32END 

SEG32 


user  program  -  PROT  includes  the  file  defined  by  the  variable  PROGRAM, 
convoluted  method  to  make  MASM  take  a  string  equate  for  an  include  filename 


;  ;  temporary  macro 


TEMP INCLUDE  MACRO  FN 

INCLUDE  &FN&.PM 
ENDM 

TEMPINCLUDE  % PROGRAM 


;  task  state  segments 
INCLUDE  TSS.INC 

;  16  bit  code  (DOS  entry/exit) 

INCLUDE  CODE 16. INC 

;  Segment  to  determine-  the  last  memory  address 

ZZZSEG  SEGMENT  PARA  PUBLIC  'ZZZ'  USE16 

ZZZSEG  ENDS 

ELSE 

IF2 

%0UT  You  must  specify  a  program  title 

%0UT  use:  MASM  /DPROGRAM=PNAME  PROT. ASM. 

END  IF 

.ERR 

END  IF 

END  ENTRY 


DESC 

SEL  VIDEO 

VIDEO  MEMORY 

DESC 

SEL  DATA 

32  BIT  DATA 

DESC 

SEL  IDT 

IDT  ALIAS 

DESC 

SEL  ICODE 

ISR  SEGMENT 

DESC 

SEL  TSSO 

DUMMY  TASK  BLOCK 

DESC 

TSSO 

SAME  (MUST  FOLLOW 

SEL_ 

TSSO) 

DESC 

SEL  TSS1 

MAIN  TASK  BLOCK 

DESC 

TSS1 

SAME  (MUST  FOLLOW 

SEL_ 

TSS1) 

DESC 

SEL  UCODE 

USER  CODE 

DESC 

SEL  UDATA 

USER  DATA 

DESC 

SEL  PSP 

DOS  PSP 

DESC 

SEL  FREE 

FREE  DOS  MEMORY 

DESC 

SEL  EXT 

EXTENDED  MEMORY 

DESC 

SEL  ENV 
e 

ENVIROMENT 

ENDS 

y 

End  Listing  Two 


Listing  Three 


PROT  -  A  386  protected  mode  DOS  extender 
Copyright  (C)  1989,  by  A1  Williams  —  All  rights  reserved. 
Permission  is  granted  for  non-commercial  use  of  this  software 
subject  to  certain  conditions  (see  PROT. ASM) . 

This  file  is:  EQUMAC.INC,  assorted  macros  and  equates. 


.********* 

******** 

******************* 

****************** *************1 

;  EQUates 

the  user 

may  wish  to  change 

ATCLASS 

EQU 

1 

l=AT/386  0=INBOARD  386/PC 

DOSSTACK 

EQU 

200H 

stack  size  for  DOS  startup 

VM86STACK 

EQU 

200H 

stack  size  for  VM86  int  calls 

CRITSTACK 

EQU 

3  OH 

stack  size  for  crit  err  handler 

PMSTACK 

EQU 

1000H 

stack  size  for  p-mode  stack 

PVSTACK 

EQU 

260 

pl0/vm86  psuedo  stack  size 

;  Maximum  protected  mode  interrupt  # 

defined 

TOPINT  EQU  30H 

;  The  critical  error  handler  works  different  for  DOS  2.X  than  for  other  DOS 
;  versions.  In  99%  of  the  cases  it  won't  make  any  difference  if  you  compile 

;  with  DOS=2 _  major  dos  version  number  (2,  3  or  4) 

DOS  EQU  3 

;  parameter  block  to  interface  for  int  30H  (call86  &  VM86CALL) 


End  Listing  One 


VM86BLK 

STRUC 

VMSEGFLAG 

DD 

0 

restore  se 

VMINT 

DD 

0 

interrupt 

VMFLAGS 

DD 

0 

EFLAGS 

VMESP 

DD 

0 

ESP 

VMSS 

DD 

0 

SS 

VMES 

DD 

0 

ES 

VMDS 

DD 

0 

DS 

VMFS 

DD 

0 

FS 

VMGS 

DD 

0 

GS 

VMEBP 

DD 

0 

EBP 

VMEBX 

DD 

0 

EBX 

VM86BLK 

ENDS 

;  Access  rights  equates.  Use  these 

fith  make_de 

RO  DATA 

EQU 

90H 

r/o  data 

RW  DATA 

EQU 

92H 

r/w  data 

RO  STK 

EQU 

94H 

r/o  stack 

RW  STK 

EQU 

96H 

r/w  stack 

EX  CODE 

EQU 

98H 

exec  only 

ER  CODE 

EQU 

9AH 

read/exec 

CN  CODE 

EQU 

9CH 

exec  only 

CR  CODE 

EQU 

9EH 

read/exec 

LDT  DESC 

EQU 

82H 

LDT  entry 

TSS_DESC 

EQU 

89H 

TSS  entry 

;  use  these 

with  make 

gate 

CALL  GATE 

EQU 

"8CH 

call  gate 

TRAP  GATE 

EQU 

8FH 

trap  gate 

INTR  GATE 

EQU 

8EH 

int  gate 

TASK  GATE 

EQU 

85H 

task  gate 

;  dpi  equates 

DPLO 

EQU 

0 

DPL1 

EQU 

20H 

DPL2 

EQU 

40H 

DPL3 

EQU 

60H 

macro  definitons 


Listing  Two 


PROT  -  A  386  protected  mode  DOS  extender 
Copyright  (C)  1989,  by  A1  Williams  —  All  rights  reserved. 
Permission  is  granted  for  non-commercial  use  of  this  software 
subject  to  certain  conditions  (see  PROT. ASM) . 

This  file  is:  GDT.INC,  the  Global  Descriptor  Table  definitions. 


;  See  EQUMAC.INC  for  an  explanation  of  the  DESC  macro 
GDTSEG  SEGMENT  PARA  PUBLIC  'CODE32'  USE32 

GDT  EQU  $  ;  GDT  space 

DESC  SEL_NULL  ;  DUMMY  NULL  SELECTOR 

DESC  SEL_C0DE16  ;  16  BIT  CODE  SEGMENT 

DESC  SEL_DATA0  ;  4GB  SEGMENT 

DESC  SEL_CODE32  ;  32  BIT  CODE  SEGMENT 

DESC  SEL_STACK  ;  32  BIT  STACK 

DESC  SEL_RDATA  ;  REAL  MODE  LIKE  DATA  SEG 

DESC  SEL  GDT  ;  GDT  ALIAS 


;  other  macros  use  this  to  error  check  parameters 
;  Give  an  error  if  last  is  blank  or  toomany  is  not  blank 
ERRCHK  MACRO  LAST, TOOMANY 

IFNB  < TOOMANY > 

IF2 

%OUT  Too  many  parameters 


Not  enough  parameters 


;  Perform  absolute  16  bit  jump  (in  a  16  bit  segment) 

JMPABS  MACRO  A, B, ERRCK 

ERRCHK  B, ERRCK 
DB  OEAH  ;  ;  absoulte  16  bit  jump 

DW  OFFSET  B 


(continued  on  page  88) 
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DW 

A 

DB  8FH 

ENDM 

ELSEIFIDNI 

<CONDX>,  <GE> 

DB  8DH 

;  Peform  absolute  32 

bit  jump  (in  a  32  bit  segment) 

ELSEIFIDNI 

<CONDX>,  <L> 

JMPABS32 

MACRO 

A, B, ERRCK 

DB  8CH 

ERRCHK 

B, ERRCK 

ELSEIFIDNI 

<CONDX>,  <LE> 

DB 

OEAH  ;  ;  absolute  32  bit  jump 

DB  8EH 

DD 

OFFSET  B 

ELSEIFIDNI 

<CONDX>,  <NA> 

DW 

A 

DB  86H 

ENDM 

ELSEIFIDNI 

<CONDX>,  <NB> 

;  this  generates  a  correct  32  bit  offset  for  a  proc  call 

DB  83H 

;  since  MASM 

doesn't 

sign  extend  32  bit  relative  items 

ELSEIFIDNI 

<CONDX>,  <NC> 

CALL32S 

MACRO 

LBL, ERRCK  ;  ;  short  call 

DB  83H 

ERRCHK 

LBL, ERRCK 

ELSEIFIDNI 

<CONDX>,  <NGE> 

DB 

0E8H 

DB  8CH 

DD 

LBL- ($+4) 

ELSEIFIDNI 

<CONDX> ,  <NL> 

ENDM 

DB  8DH 

ELSEIFIDNI 

<CONDX>,  <NO> 

CALL32F 

MACRO 

SG, LBL, ERRCK  ;  ;  far  call 

DB  81H 

ERRCHK 

LBL, ERRCK 

ELSEIFIDNI 

<CONDX>,  <NP> 

DB 

9AH 

DB  8BH 

DD 

OFFSET  LBL 

ELSEIFIDNI 

<CONDX>,  <NS> 

DW 

SG 

DB  89H 

ENDM 

ELSEIFIDNI 

<CONDX>,  <NZ> 

DB  85H 

JMP32S 

MACRO 

LBL, ERRCK  ;  ;  short  jump 

ELSEIFIDNI 

<CONDX>,  <0> 

ERRCHK 

LBL, ERRCK 

DB  80H 

DB 

0E9H 

ELSEIFIDNI 

<CONDX>,  <P> 

DD 

LBL- ($+4) 

DB  8  AH 

ENDM 

ELSEIFIDNI 

<CONDX>,  <PE> 

;  conditional  jump  macro 

DB  8AH 

;  jcc32  uses 

condition  codes  used  in  Intel  literature 

ELSEIFIDNI 

<CONDX>,  <PO> 

JCC32 

MACRO 

CONDX, LBL, ERRCK 

DB  8BH 

ERRCHK 

LBL, ERRCK 

ELSEIFIDNI 

<CONDX>,  <S> 

DB 

OFH 

DB  88H 

IFIDNI 

<CONDX>, 

<A> 

ELSE 

DB 

87H 

%OUT  JCC32 :  Unknown 

ELSEIFIDNI 

<CONDX>, <NBE>  l 

.ERR 

DB 

87H 

END  IF 

ELSEIFIDNI 

<CONDX>, 

<AE> 

DD  LBL- ($+4) 

DB 

83H 

ENDM 

ELSEIFIDNI 

<CONDX>, 

<C> 

DB 

82H 

;  Override 

default  operand  size 

ELSEIFIDNI 

<CONDX>, 

<NAE> 

OPSIZ 

MACRO  NOPARM 

DB 

82H 

ERRCHK  X, NOPARM 

ELSEIFIDNI 

<CONDX>, 

<B> 

DB  66H 

DB 

82H 

ENDM 

ELSEIFIDNI 

<CONDX>, 

<BE> 

;  Override 

default  address  size 

DB 

86H 

ADSIZ 

MACRO  NOPARM 

ELSEIFIDNI 

<CONDX>, 

<E> 

ERRCHK  X, NOPARM 

DB 

84H 

<CONDX>, 

DB 

<CONDX>, 


<Z> 

84H 

<G> 


op  size  overide 


;  address  size  overide 


(continued  on  page  90) 
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DB 

67H 

ENDM 

;  delay  macro  for  interrupt  controller  access 

IDELAY 

MACRO 

NOPARM 

LOCAL 

DELAY1,DELAY2 

ERRCHK 

X, NOPARM 

JMP 

SHORT  DELAY1 

DELAY1 : 

JMP 

SHORT  DELAY2 

DELAY2 : 

ENDM 

;  BREAKPOINT  MACROS 

;  MACRO  to 

turn  on  NBREAKPOINTS .  If  used  with  no  arguments  (or  a  1) ,  this 

;  macro  makes  NBREAKPOINT  active  if  used  with  an  argument  >  1,  NBREAKPOINT 

;  will  break  after  that  many  passes 

BREAKON 

MACRO 

ARG, ERRCK 

ERRCHK 

X, ERRCK 

PUSH 

DS 

PUSH 

SEL  DATA 

POP 

DS 

PUSH 

EAX 

IFB 

<ARG> 

MOV 

AL,  1 

ELSE 

MOV 

AL, &ARG 

END  IF 

MOV 

BPON, AL 

POP 

EAX 

POP 

DS 

ENDM 

;  Turns  off 

NBREAKPOINT 

BREAKOFF 

MACRO 

NOPARAM 

ERRCHK 

X, NOPARAM 

PUSH 

DS 

PUSH 

SEL  DATA 

POP 

DS 

PUSH 

EAX 

XOR 

AL,  AL 

MOV 

BPON, AL 

POP 

EAX 

POP 

DS 

ENDM 

BREAKPOINT 

MACRO 

NOPARM 

ERRCHK 

X, NOPARM 

INT 

3 

ENDM 

;  Counter  breakpoint 

-  use  BREAKON  to  set  count  control 

;  BREAKPOINT  with  memory  dump. 

;  usage:  BREAKDUMP  seg  selector,  offset,  number  of  words 

BREAKDUMP 

MACRO 

SEG, OFF, CNT, ERRCK 

ERRCHK 

CNT, ERRCK 

PUSH 

EAX 

PUSH 

DS 

MOV 

AX, SEL  DATA 

MOV 

DS,  AX 

MOV 

AX, & SEG 

MOV 

DUMP  SEG, AX 

MOV 

EAX, OFFSET  &OFF 

MOV 

DUMP  OFF, EAX 

MOV 

EAX, &CNT 

MOV 

DUMP  CNT, EAX 

POP 

DS 

POP 

EAX 

BREAKPOINT 

ENDM 

NBREAKDUMP 

MACRO 

SEG, OFF, CNT, ERRCK 

ERRCHK 

CNT, ERRCK 

LOCAL 

NONBP 

PUSH 

DS 

PUSH 

SEL  DATA 

POP 

DS 

PUSHFD 

OR 

BPON,  0 

JZ 

NONBP 

DEC 

BPON 

JNZ 

NONBP 

POPFD 

POP 

DS 

BREAKDUMP  SEG, OFF, CNT 

NONBP : 

POPFD 

POP 

DS 

ENDM 

;  determine 

linear  address  of  first  free  byte  of  memory  (to  nearest  paragraph) 

LOADFREE 

MACRO 

REG, ERRCK 

ERRCHK 

REG, ERRCK 

XOR 

E&REG, E&REG 

MOV 

&REG, SEG  ZZZGROUP 

SHL 

E&REG,  4 

ENDM 

;  Set  up  PINTFRAME  (uses  eax) .  Loads  vmstack  &  vmdata  to  the  ss:esp  and 

;  ds  slots  in  pintframe  —  default  ss:esp=ssintl  —  default  ds=userdata 

PROT  STARTUP 

MACRO 

VMSTACK, VMDATA,  ERRCK 

ERRCHK 

X, ERRCK 

IFB 

<VMSTACK> 

MOV 

AX, SEG  SSINT1 

ELSE 

MOV 

AX, SEG  VMSTACK 

END  IF 

MOV 

PINTFRAME . VMSS ,  EAX 

IFB 

<VMSTACK> 

MOV 

EAX,  OFFSET  SSINT1 

ELSE 

MOV 

EAX,  OFFSET  VMSTACK 

(continued  on  page  92) 
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END  IF 

MOV 

P INTFRAME . VMESP , EAX 

IFB 

<VMDATA> 

MOV 

AX, SEG  USERDATA 

ELSE 

MOV 

AX, SEG  VMDATA 

END  IF 

MOV 

P INTFRAME .  VMDS ,  EAX 

ENDM 

;  start  PROT  user  segments 

PROT  CODE 

MACRO 

NOPARM 

ERRCHK 

X, NOP ARM 

USERCODE 

SEGMENT 

PARA  PUBLIC  '  CODE32'  USE32 

USERCODEBEG 

EQU 

$ 

ASSUME 

CS: USERCODE,  DS: USERDATA,  ES:DAT32 

ENDM 

PROT  DATA 

MACRO 

NOPARM 

ERRCHK 

X, NOPARM 

USERDATA 

SEGMENT 

PARA  PUBLIC  ' DATA32'  USE32 

USERDATABEG 

EQU 

$ 

ENDM 

PROT  CODE  END  MACRO 

NOPARM 

ERRCHK 

X, NOPARM 

USERCODEEND 

EQU 

$ 

USERCODE 

ENDS 

ENDM 

PROT  DATA  END  MACRO 

NOPARM 

ERRCHK 

X, NOPARM 

USERDATAEND 

EQU 

$ 

USERDATA 

ENDS 

ENDM 

;  Simplfy  programs  with  no  data  segment 

NODATA 

MACRO 

NOPARM 

ERRCHK 

X, NOPARM 

PROT  DATA 

PROT  DATA  END 

ENDM 

;  Mnemonic 

for  call86 

call 

VM86CALL 

MACRO 

NOPARM 

ERRCHK 

X,  NOPARM 

CALL32F 

SEL  CODE32, CALL86 

ENDM 

;  Mnemonic 

for  dos  return 

BACK2DOS 

MACRO 

RC, ERRCK 

ERRCHK 

X,  ERRCK 

IFNB 

<RC> 

MOV 

AL,  RC 

END  IF 

JMPABS32 

SEL  CODE16, BACK16 

ENDM 

;  Variables 

and  macro 

to  create  GDT/ LDT/ IDT  entries 

C  GDT 

= 

0 

C  LDT 

= 

0 

C  IDT 

= 

0 

;  create  "next"  descriptor  with  name  in  table.  If  no  table 

specified,  use  GDT 

DESC 

MACRO 

NAME, TABLE,  ERRCK 

DQ 

0 

IFB 

<TABLE> 

NAME 

=  C  GDT 

C  GDT 

= 

C  GDT+8 

ELSE 

IFIDNI 

<TABLE>, 

<LDT> 

;  For  LDT  selectors, 

set  the  TI  bit  to  one 

NAME 

=  C  STABLE  OR  4 

ELSE 

NAME 

=  C  STABLE 

END  IF 

C  STABLE 

= 

C  STABLE+8 

END  IF 

ENDM 

End  Listings 

92 


Dr.  Dobb’s  Journal,  October  1990 

935 


OS/2  BACKDOOR 


Listing  One  (Text  begins  on  page  28.) 

;  verify  user's  access: 

;  VerifyAccess  will  shut  down  user's  app  in  the  event  of  error 

;  DEVHLP . ASM 

mov  ax,  word  ptr  es:[bx+17]  ;  selector  of  parameter  block 

;  to  produce  DEVHLP. SYS  ("OS/2  Device  Driver  in  a  Can") 

mov  di,  word  ptr  es:[bx+15]  ;  offset 

;  Andrew  Schulman,  32  Andrew 

St.,  Cambridge  MA  02139 

mov  cx,  regs  size  ;  length  to  be  read 

;  with 

revisions  by  Art  Rothstein,  Morgan  Labs,  San  Francisco,  CA 

mov  dx,  VerifyAccess  ;  read 

call  DevHlp 

;  DEF 

file: 

jne  okl 

;  LIBRARY  DEVHLP 

ret 

;  DESCRIPTION  'DEVHLP. SYS  (c)  Andrew  Schulman  1990' 

;  PROTMODE 

okl : 

mov  ax,  word  ptr  es:[bx+21]  ;  selector  of  data  buffer 

mov  di,  word  ptr  es:[bx+19]  ;  offset 

;  masm 

devhlp;  &&  link  devhlp,devhlp.sys, , ,devhlp.def 

mov  cx,  regs  size  ;  length  to  be  written 

mov  dx,  (1  SHL  8)  +  VerifyAccess  ;  read/write 

;  put 

in  OS/2  config.sys: 

call  DevHlp 

;  device=devhlp.sys 

jne  ok2 

ret 

;  access  with  DosOpen  ("DEVHLPXX") ,  DosDevIOCTL  (category  128,  func  60h) 

ok2: 

push  ds  ?  see  if  we  should  verify  ds 

.  286p 

Ids  di,  es: [bx] .param 
mov  ax,  [dij.regs  ds 

;  the 

only  specific  DevHlp  that  DEVHLP. SYS  knows  about 

pop  ds 

VerifyAccess  equ  27h 

test  ax,  ax  ;  need  to  verify? 

je  nods  ;  skip  if  no 

ioctlpkt  struc 

xor  di,  di  ;  verify  seg:0  for  read,  1  byte 

db  13  dup  (?)  ;  header 

mov  cx,  1  ;  length 

cat  db  ? 

;  category 

mov  dx,  VerifyAccess  ;  read=0 

fun  db  ? 

;  function 

call  DevHlp 

pa  ram  dd  ? 

;  param  area 

jc  fini  ;  if  carry  flag  set 

dataptr  dd  ? 

;  data  area 

ioctlpkt  ends 

nods : 

push  ds  ;  see  if  we  should  verify  es 

Ids  di,  es: [bx] .param 

regs 

struc 

mov  ax,  [di].regs  es 

regs  ax  dw  ? 

pop  ds 

regs  bx  dw  ? 

test  ax,  ax  ;  need  to  verify? 

regs  cx  dw  ? 

je  noes  ;  skip  if  no 

regs  dx  dw  ? 

xor  di,  di  ;  verify  seg:0  for  read,  1  byte 

regs  si  dw  ? 

mov  cx,  1  ;  length 

regs  di  dw  ? 

mov  dx,  VerifyAccess  ;  read=0 

regs  ds  dw  ? 

call  DevHlp 

regs_es  dw  ? 

regs  flags  dw  ? 

jc  fini  ;  if  carry  flag  set 

regs 

ends 

noes: 

push  ds  ;  going  to  be  bashed! 

push  es 

regs_size  equ  size  regs 

push  bx 

dgroup 

group  DATA 

;  save  DevHlp  address  on  stack  so  we  can  change  ds 
push  word  ptr  DevHlp+2 

_DATA 

segment  word  public 

DATA' 

push  word  ptr  DevHlp 

header 

dd  -1 

;  get  the  parameters  for  DevHlp  from  regs 

dw  8880h 

Ids  di,  es: [bx] .param 

dw  Strat 

mov  ax,  [di] . regs  ax 

dw  0 

• 

mov  bx,  [dij.regs  bx 

db  'DEVHLPXX' 

mov  cx,  [di] . regs  cx 

db  8  dup  (0) 

mov  dx,  [dij.regs_dx 
mov  si,  [dij.regs  si 

DevHlp 

dd  0 

mov  es,  [di] . regs  es 
push  [dij.regs  ds 

dispch 

dw  Init 

0  —  Init 

mov  di,  [di j . regs  di 

dw  12  dup  (Error) 

1..12  —  not  supported 

pop  ds 

dw  DevOp 

13  —  DevOpen 

dw  DevOp 

14  —  DevClose 

;  here  it  is,  the  whole  point  of  this  exercise! 

dw  Error 

15  —  not  supported 

mov  bp,  sp 

dw  GenlOCtl 

16  —  DevIOCtl 

call  dword  ptr  [bp] 

dw  10  dup  (Error) 

17.. 26  —  not  supported 

pop  bp  ;  pull  DevHlp  address  off  stack 

pop  bp  ;  without  changing  carry  flag 

enddata  dw  0 

jc  fini 

DATA 

ends 

;  save  ES:BX  to  put  in  out-regs:  destroys  DX 

_TEXT 

segment  word  public 

CODE' 

mov  bp,  es 
mov  dx,  bx 

assume  cs:  TEXT,  ds: DGROUP,  es: NOTHING 

;  get  back  old  DS,  ES:BX 

Strat 

proc  far 

pop  bx 

mov  di,  es: [bx+2] 

pop  es 

and  di,  Offh 
cmp  di,  26 

;  max  #  of  commands 

pop  ds 

jle  Strati 

;  save  FLAGS,  SI,  DS  on  stack 

call  Error 

pushf 

jmp  short  Strat2 

push  si 

Strati 

add  di,  di 

push  ds 

call  word  ptr  [di+dispch] 

Strat2 

mov  word  ptr  es:[bx+3],  ax  ;  set  request  header  status 

;  set  up  regs  to  return  to  the  app 

ret 

Ids  si,  es: [bx] .dataptr 

Strat 

endp 

mov  [si]. regs  ax,  ax 
pop  [si j. regs  ds 

;  used  by  DevOpen  and  DevClose 

pop  [si]. regs  si 

DevOp 

proc  near 

pop  [si j. regs  flags 

mov  ax,  OlOOh 

mov  [si]. regs  cx,  cx 

ret 

mov  [si]. regs  bx,  dx 

DevOp 

endp 

mov  [ si j. regs  es,  bp 

mov  [si]. regs  di,  di 

GenlOCtl  proc  near 

clc 

push  es 

fini : 

ret 

push  bx 

Do  DevHlp  endp 

cmp  es : [bx] .cat,  128 
jne  bad 

Error 

proc  near 

cmp  es:[bx].fun,  60h 

mov  ax,  8103h 

jne  bad 

ret 

call  Do  DevHlp 

Error 

endp 

jc  bad 

mov  ax,  OlOOh 

;  no  error 

Init 

proc  near 

jmp  short  done 

mov  ax,  es:[bx+14] 

bad: 

mov  ax,  8101h 

;  error 

mov  word  ptr  DevHlp,  ax 

done: 

pop  bx 

mov  ax,  es : [bx+16] 

pop  es 
ret 

mov  word  ptr  DevHlp+2,  ax 

GenlOCtl  endp 

Do  DevHlp  proc  near 

(continued  on  page  96) 
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listing  One  (Listing  continued,  text  begins  on  page  28.) 

mov  word  ptr  es:[bx+14],  offset  _TEXT:Init  ;  end  of  code 

mov  word  ptr  es:[bx+16],  offset  DGROUP : enddata 
mov  ax,  OlOOh 
ret 

Init  endp 


_TEXT  ends 
end 


End  Listing  One 


Listing  Two 


/*  DRVRLIST.C 

list  the  device  drivers  in  OS/2 
Art  Rothstein,  1990 

we  assume  the  first  driver  in  the  chain  is  NUL  and  is  in  the  global  data 
segment,  and  that  the  second  driver  (CON)  is  the  same  segment. 

cl  -AL  drvrlist.c  (four-byte  data  pointers  required  for  memchr) 

*/ 

#define  INCL_DOSDEVICES 
#include  <os2.h> 

((include  <process.h> 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  "devhlp.h" 

USHORT  devhlp  ; 

SEL  MakeSel (  SEL  selValue) 

( 

extern  USHORT  devhlp  ; 

REGS  regs  ; 

USHORT  ret  ; 

regs.dx  =  DevHlp_VirtToPhys 
regs.ds  -  selValue  ; 
regs.es  -  0  ; 
regs. si  =  0  ; 

ret  =  DosDevIOCtl(  Sregs,  iregs, 


//  function  requested 
//  selector 
//  avoid  trap 
//  offset 
0x60,  128,  devhlp)  ; 


if  (  ret  !=  0  1!  regs. flags. carry  !-  0) 

return  0  ; 

//  physical  address  in  ax:bx 

regs.cx  =  0  ;  //  limit  65,535 

regs.dx  =  MAKEUSHORT (  DevHlp_PhysToUVirt,  UVirt_ReadWrite) ; 


regs.es  =  0  ;  //  avoid  trap 

ret  =  DosDevIOCtU  Sregs,  &regs,  0x60,  128,  devhlp)  ; 
if  (  ret  !=  0  !!  regs. flags. carry  !=  0)  //  if  error 

return  0  ; 

return  regs.es  ;  //  return  the  selector 

) 

BOOL  ReleaseSel (  SEL  selValue) 

{ 

extern  USHORT  devhlp  ; 

REGS  regs  ; 

USHORT  ret  ; 

regs. ax  =  selValue  ;  //  selector  to  free 

regs.dx  =  MAKEUSHORT (  DevHlp_PhysToUVirt,  UVirt_Release) ; 
regs.ds  =  0  ;  //  safety 

regs.es  =  0  ; 

ret  =  DosDevIOCtl(  Sregs,  &regs,  0x60,  128,  devhlp)  ; 
if  (  ret  !=  0  I!  regs. flags. carry  !=  0)  //  if  error 

return  FALSE  ; 

return  TRUE  ;  //  successful  return 

} 

void  main(  void) 

{ 

USHORT  usOffsetDriver 
,  usBytesLeft; 

PCH  pchGlobal  ; 

static  CHAR  szDriverName[ ]  =  "DEVHLPXX" 

,  szNullDriver []  =  "NUL 

typedef  struct  _DDHEADER  { 

Struct  _DDHEADER  *  pddNext  ; 

USHORT  fsAttribute  ; 

USHORT  usStrategyEntryOffset  ; 

USHORT  usIDCEntryOff set  ; 

CHAR  chName [  8]  ; 

USHORT  usIDCEntrySegmentProt  ; 

USHORT  usIDCDataSegmentProt  ; 

USHORT  usIDCEntrySegmentReal  ; 

USHORT  usIDCDataSegmentReal  ; 

}  DDHEADER  ; 

typedef  DDHEADER  *  PDDHEADER  ; 

PDDHEADER  pddCurrent 
,  pddNext; 

SEL  selDriver  ; 


//  in  search  for  NUL  device 
//  pointer  to  system  global  data 
//  device  helper  driver 
//  first  driver  in  system 

//  device  driver  header 
//  chain  to  next  driver 
//  driver  attributes 

//  inter  device  communication 
//  name  for  character  devices 


//  current  DCB 
//  next  DCB 
//  selector  of  DCB 


//  open  the  DEVHLP  device 
.if  ( (devhlp  =  open (szDriverName,  0)) 
puts (  "Can't  find  DEVHLP. SYS")  ; 
exit (  1)  ; 

} 

//  locate  the  first  driver 
selDriver  =  0x50  ; 
usOffsetDriver  =  0  ; 
usBytesLeft  =  32000  ;  //  should  be  large  enough 

pchGlobal  =  MAKEP (  MakeSel (  selDriver),  usOffsetDriver)  ; 
do  { 

PCH  pchMatch  ; 


-1)  ( 


//  global  data  segment 


pchMatch  =  memchr (  pchGlobal  +1,  'N' 
if  (  pchMatch  ==  NULL)  { 

ReleaseSel (  SELECTOROF (  pchGlobal)) 
puts(  "NUL  driver  not  found")  ; 
exit (  1)  ; 

)  //  if  no  match 

//  partial  match 
usBytesLeft  -=  pchMatch  -  pchGlobal  ; 
pchGlobal  =  pchMatch  ; 
while  (  memcmp(  pchGlobal 
,  szNullDriver 

,  sizeof  szNullDriver  -  1)  !=  0); 


usBytesLeft);  //look  for  first  char 
//  if  no  match 
;  //  release  the  selector 
//  and  give  up 


//  reduce  residual  count 
//  point  to  start  of  match 
//  break  out  if  name  matches 
//  exactly 


//  run  the  chain 

printf(  "  Address  Name\n")  ;  //  column  headings 

for  (  usOffsetDriver  =  OFFSETOF (  pchGlobal)  -  0x0a  //  back  up  to  DCB  start 
,  pddCurrent  =  (  PDDHEADER)  (  pchGlobal  -  0x0a) 

,  selDriver  =  SELECTOROF (  pddCurrent->pddNext)  //  selector  of  next  DCB 

;  ;  )  ( 

printf (  "%4X: %04X  ",  selDriver,  usOffsetDriver); 
if  (  (  pddCurrent->fsAttribute  &  0x8000)  ==  0) 
printf (  "Block  device,  %d  logical  units\n" 

,  pddCurrent->chName [  0]); 

else 

printf (  "%-8.8s\n",  pddCurrent->chName) ; 
selDriver  =  SELECTOROF (  pddCurrent->pddNext)  ; 
usOffsetDriver  =  OFFSETOF (  pddCurrent->pddNext) 
if  (  usOffsetDriver  ==  Oxffff) 
break  ; 

pddNext  =  MAKEP (  MakeSel (  selDriver), 

ReleaseSel (  SELECTOROF (  pddCurrent)) 
pddCurrent  =  pddNext  ; 

)  //  loop  once  for  each  device  driver 

//  release  the  last  selector 
ReleaseSel (  SELECTOROF (  pddCurrent))  ; 

exit (0)  ; 


//  if  block  driver 


//  number  of  units 
//if  character  driver 


//  point  to  next  DCB 


//  if  end  of  chain 
//we  are  done 
usOffsetDriver)  ; 

;  //  free  previous  DCB 

//  age  the  pointer 


End  Listing  Two 
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Listing  Three 

♦define  DevHlp  FreeLIDEntry 

0x35 

♦define  DevHlp_ABIOSCall 

0x36 

/*  DEVHLP.H  --  for  use  with  DosDevIOCtl  and  DEVHLP.SYS  */ 

♦define  DevHlp  ABIOSCommonEntry 

0x37 

♦define  DevHlp  RegisterStackUsage 

0x38 

♦define  DevHlp_SchedClockAddr 

0x00 

♦define  DevHlp_DevDone 

0x01 

♦define  UVirt  Exec 

C 

) 

♦define  DevHlp_Yield 

0x02 

♦define  UVirt  ReadWrite 

] 

. 

♦define  DevHlp_TCYield 

0x03 

♦define  UVirt_Release 

♦define  DevHlp_Block 

0x04 

♦define  DevHlp  Run 

0x05 

♦pragma  pack(l) 

♦define  DevHlp  SemRequest 

0x06 

♦define  DevHlp  SemClear 

0x07 

typedef  struct  { 

♦define  DevHlp_SemHandle 

0x08 

unsigned  int  carry 

1 

♦define  DevHlp_PushReqPacket 

0x09 

unsigned  int 

1 

♦define  DevHlp_PullReqPacket 

OxOA 

unsigned  int  parity 

1 

♦define  DevHlp  PullParticular 

OxOB 

unsigned  int 

1 

♦define  DevHlp_SortReqPacket 

OxOC 

unsigned  int  aux 

1 

♦define  DevHlp_AllocReqPacket 

OxOD 

unsigned  int 

1 

♦define  DevHlp_FreeReqPacket 

OxOE 

unsigned  int  zero 

1 

♦define  DevHlp_QueueInit 

OxOF 

unsigned  int  sign 

1 

♦define  DevHlp  QueueFlush 

0x10 

unsigned  int  trap 

1 

♦define  DevHlp_QueueWrite 

Oxll 

unsigned  int  int_en 

1 

♦define  DevHlp_QueueRead 

0x12 

unsigned  int  direction 

1 

♦define  DevHlp  JLock 

0x13 

unsigned  int  overflow 

1 

♦define  DevHlp_Unlock 

0x14 

unsigned  int  iopl 

2 

♦define  DevHlp  PhysToVirt 

0x15 

unsigned  int  nest  task 

1 

♦define  DevHlp_VirtToPhys 

0x16 

unsigned  int 

1 

♦define  DevHlp_PhysToUVirt 

0x17 

}  FLAGS/ 

♦define  DevHlp  AllocPhys 

0x18 

♦define  DevHlp_FreePhys 

0x19 

typedef  struct  { 

♦define  DevHlp_SetROMVector 

OxlA 

USHORT  ax/bXfCXfdxyS^di/dSjes; 

♦define  DevHlp  Set IRQ 

OxlB 

FLAGS  flags; 

♦define  DevHlp_UnSetIRQ 

OxlC 

}  REGS; 

♦define  DevHlp_SetTimer 

OxlD 

♦define  DevHlp  ResetTimer 

OxlE 

♦define  DevHlp_MonitorCreate 

OxlF 

♦define  DevHlp_Register 

0x20 

♦define  DevHlp_DeRegister 

0x21 

♦define  DevHlp_MonWrite 

0x22 

♦define  DevHlp_MonFlush 

0x23 

♦define  DevHlp_GetDosVar 

0x24 

♦define  DevHlp_SendEvent 

0x25 

♦define  DevHlp_ROMCritSection 

0x26 

♦define  DevHlp_VerifyAccess 

0x27 

♦define  DevHlp_SysTrace 

0x28 

♦define  DevHlp_AttachDD 

0x2A 

♦define  DevHlp_AllocGDTSelector 

0x2D 

♦define  DevHlp_PhysToGDTSelector 

0x2E 

♦define  DevHlp_RealToProt 

0x2F 

♦define  DevHlp_ProtToReal 

0x30 

♦define  DevHlp_EOI 

0x31 

♦define  DevHlp_UnPhysToVirt 

0x32 

♦define  DevHlp_TickCount 

0x33 

♦define  DevHlp_GetLIDEntry 

0x34 

End  Listings 
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Listing  One  (Text  begins  on  page  42.) 


TITLE  -  BACKDOOR. SYS 
PAGE  60,132 
.RADIX  16 


closes  DOS's  backdoors 


BACKDOOR. SYS  closes  two  "backdoors"  into  the  MS-DOS  INT  21h  function 
dispatcher  that  could  be  used  by  a  virus  or  trojan  horse  to  cause  damage. 
It  also  filters  INT  21h  directly  to  reject  a  special  case  of  function  13h 
which  could  destroy  all  data  on  a  disk. 

For  use  with  MASM  5.1 
MASM  BACKDOOR; 

LINK  BACKDOOR; 

EXE2BIN  BACKDOOR . EXE  BACKDOOR. SYS 


ASSUME  CS :CSEG,  DSrCSEG 
CSEG  SEGMENT  PARA  PUBLIC  'CODE' 
ORG  OOOOh 

DW  OFFFFh, OFFFFh 
DW  8000h 

DW  offset  DEV_STRAT_RTN 
DW  offset  DEV_INT_RTN 
DB  "B"+80h, "ACKDOOR" 

INSTALL  MSG  DB  0Dh,0Ah 


;  device  driver  starts  at  0 

;  far  pointer  to  next  device 
;  character  device  driver 
;  pointer  to  the  strategy  routine 
;  pointer  to  the  interrupt  routine 
;  device  name  with  high  bit  set  will 
;  avoid  any  filename  conflicts 


DB  "BACKDOOR  is  installed  at  $" 


DEV_HDR_BX 
DEV  HDR  ES 


DW  0000 
DW  0000 


ORIG_INT21_OFF  DW  0000 
ORIG  INT21  SEG  DW  0000 


DW  0000 


REFUSE_RQST  PROC  FAR 
POP  AX 
POP  AX 
POP  CS : TEMP 
PUSH  AX 
PUSH  CS : TEMP 
STC 

MOV  AX, OFFFFh 
RET 

REFUSE_RQST  ENDP 

NEW_INT21  PROC  NEAR 
PUSH  AX 
PUSH  BX 
CMP  AH, 13h 
JNZ  CONT_ORIG_INT2 1 
MOV  BX, DX 

CMP  byte  ptr  DS: [BX],0FFh 


pointer  for  ES:BX  for  device 
request  header 


used  for  temporary  storage 


get  rid  of  flags  on  stack 
get  the  return  segment 
and  save  offset 

save  the  return  address  in  proper 
order 

return  STC  for  error 
return  AX=-1 

and  do  FAR  RET  back  to  caller 


save  original  registers  first  thing 

is  this  the  DELETE  FCB  function? 
no,  so  continue  on 
point  BX  to  the  FCB 
got  an  extended  FCB? 


JNZ  CONT_ORIG_INT2 1 

CMP  byte  ptr  DS: [BX+6] , lFh 

JNZ  CONT_ORIG_INT2 1 

CMP  word  ptr  DS: [BX+8] , "?? 

JNZ  CONT_ORIG_INT2 1 

CMP  word  ptr  DS: [BX+OAh] , " 

JNZ  CONT_ORIG_INT2 1 

CMP  word  ptr  DS : [BX+OCh] , " 

JNZ  CONT_ORIG_INT21 

CMP  word  ptr  DS: [BX+OEh] , " 

JNZ  CONT_ORIG_INT2 1 

CMP  word  ptr  DS: [BX+lOh] , " 

JNZ  CONT_ORIG_INT2 1 

CMP  byte  ptr  DS: [BX+12h] , 

JNZ  CONT_ORIG_INT2 1 

POP  BX 

POP  AX 

MOV  AL, OFFh 

STC 

RETF  0002 

CONT_ORIG_INT21 : 

POP  BX 
POP  AX 

JMP  dword  ptr  CS:ORIG_INT21 
NEW_INT21  ENDP 

DEV_STRAT_RTN  PROC  FAR 

MOV  CS : DEV_HDR_BX, BX 
MOV  CS : DEV_HDR_ES, ES 
RET 

DEV  STRAT  RTN  ENDP 


DEV_INT_RTN  PROC  FAR 
PUSH  AX 
PUSH  BX 
PUSH  CX 
PUSH  DX 
PUSH  DS 
PUSH  ES 
PUSH  DI 
PUSH  SI 
PUSH  BP 
PUSH  CS 
POP  DS 

LES  D I, dword  ptr  DEV_HDR_BX; 
MOV  BL, ES : [DI+02] 

XOR  BH, BH 
CMP  BX, OOh 
JNZ  DEV_IGNORE 
CALL  INSTALL  BACKDOOR 


DEV_IGNORE: 

MOV  AX, OlOOh 
LDS  BX, dword  ptr  CS:DEV_HDR 
MOV  [BX+03] , AX 
POP  BP 
POP  SI 
POP  DI 
POP  ES 
POP  DS 
POP  DX 
POP  CX 
POP  BX 
POP  AX 
RET 

DEV_INT_RTN  ENDP 

INSTALL_BACKDOOR  PROC  NEAR 

CALL  CLOSE  BACK  DOOR 


CALL  HOOK_INT21 
MOV  AH, 09h 

MOV  DX, offset  INSTALL_MSG 
INT  21h 
MOV  AX, CS 

CALL  OUTPUT_AX_AS_HEX 

MOV  AL, 3Ah 

CALL  DISPLAY_TTY 

MOV  AX, offset  REFUSE_RQST 

CALL  OUTPUT_AX_AS_HEX 

CALL  DISPLAY_NEWLINE 

LES  D I, dword  ptr  DEV_HDR_BX; 

MOV  Word  Ptr  ES : [DI+OEh) , of f 

MOV  ES: [DI+10h],CS 

RET 

INSTALL  BACKDOOR  ENDP 


CLOSE_BACK_DOOR  PROC  NEAR 
PUSH  ES 
PUSH  AX 
PUSH  BX 
XOR  AX, AX 
MOV  ES, AX 
MOV  BX, OOClh 

MOV  AX, offset  REFUSE_RQST 

MOV  ES: [BX],AX 

MOV  AX, CS 

MOV  ES: [BX+02] , AX 

POP  BX 

POP  AX 

POP  ES 

RET 

CLOSE  BACK  DOOR  ENDP 


HOOK  INT21 


PROC  NEAR 
PUSH  AX 
PUSH  BX 
PUSH  ES 
MOV  AX, 3521h 
INT  21h 


no,  so  continue  on 
yes,  so  got  the  special  attribute? 
no,  so  continue  on 
yes,  so  filename  starts  with  "??"  ? 
no,  so  continue  on 

yes,  so  filename  =  "??"  ? 
no,  so  continue  on 

yes,  so  filename  =  "??"  ? 
no,  so  continue  on 

yes,  so  filename  =  "??"  ? 
no,  so  continue  on 

yes,  so  filename  =  "??"  ? 
no,  so  continue  on 
';  yes,  so  filename  ends  with  "??"  ? 
no,  so  continue  on 
yes,  so  reject  it  altogether 

return  match  not  found 
STC  just  for  the  heck  of  it 
and  IRET  with  new  flags 


restore  original  registers 

OFF;  continue  with  original  handler 


save  the  ES:BX  pointer  to  the 
device  request  header 


save  all  registers 


point  DS  to  local  code 
ES:DI=device  request  header 
get  the  command  code 
clear  out  high  byte 
doing  an  INSTALL? 
no,  so  just  ignore  the  call  then 
yes,  so  install  code  in  memory 


return  STATUS  of  DONE 
BX;  DS:BX=device  request  header 
'return  STATUS  in  the  header 
restore  original  registers 


and  RETF  to  DOS 


install  new  handler  to  close  back 
door 

and  hook  INT21  filter 
DOS  display  string 
show  installation  message 
via  DOS 

display  current  code  segment 
output  AX  as  two  HEX  digits 
now  output  a  colon 
to  the  screen 
show  new  handler's  offset 
output  AX  as  two  HEX  digits 
output  a  newline  to  finish  display 
ES:DI=device  request  header 
:set  INSTALL_BACKDOOR;  this  is  the 
end  of  resident  code 


save  original  registers 


point  ES  to  the  interrupt  vector 
table 

install  new  handler  at  INT30  +  1 
get  new  offset  for  the  handler 
save  it  in  interrupt  vector  table 
get  the  segment  for  the  handler 
and  save  it,  too 
restore  original  registers 


and  RET  to  caller 


get  current  INT21  vector 
via  DOS 
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save  the  offset 


MOV  CS : ORIG_INT2 1_0FF ,  BX 
MOV  BX, ES 

MOV  CS : ORIG_INT21_SEG, BX 
PUSH  CS 
POP  DS 

MOV  DX, offset  NEW_INT2 1 

MOV  AX, 2521h 

INT  21h 

POP  ES 

POP  BX 

POP  AX 

RET 

HOOK_INT21  ENDP 

OUTPUT_AX_AS_HEX  PROC  NEAR 
PUSH  AX 
PUSH  BX 
PUSH  CX 
PUSH  AX 
MOV  AL, AH 

CALL  OUTPUT_AL_AS_HEX 
POP  AX 

CALL  OUTPUT_AL_AS_HEX 

POP  CX 

POP  BX 

POP  AX 

RET 

OUTPUT_AX_AS_HEX  ENDP 

OUTP UT_AL_AS_HEX  PROC  NEAR 
PUSH  AX 
PUSH  BX 
PUSH  CX 

PUSH  AX 
MOV  CL, 04h 
SHR  AL,CL 
ADD  AL, 30h 
CMP  AL, 39h 

JBE  OUTPUT_FIRST_DIGIT 
ADD  AL, 07h 

OUTPUT_F I RS T_D I G I T : 

CALL  DISPLAY_TTY 
POP  AX 
AND  AL, OFh 
ADD  AL, 30h 
CMP  AL, 39h 

JBE  OUTPUT_SECOND_DIGIT 
ADD  AL, 07h 

OUTPUT_SECOND_DIGIT : 

CALL  DISPLAY_TTY 

POP  CX 

POP  BX 

POP  AX 

RET 

OUTPUT_AL_AS_HEX  ENDP 

DISPLAY_NEWLINE  PROC  NEAR 
PUSH  AX 
MOV  AL, ODh 
CALL  DISPLAY_TTY 
MOV  AL, OAh 
CALL  DISPLAY_TTY 
POP  AX 
RET 

DISPLAY  NEWLINE  ENDP 


;  and  the  segment 

;  make  sure  DS=local  code 
;  point  to  new  handler 
;  install  new  handler 
;  via  DOS 

;  and  restore  original  registers 


;  and  RET  to  caller 


save  original  registers 


save  number  for  output 
output  high  byte  first 
output  AL  as  two  HEX  digits 
output  low  byte  next 
output  AL  as  two  HEX  digits 
restore  original  registers 


and  RET  to  caller 


save  original  registers 


;  save  the  number  for  output  (in  AL) 
;  first  output  high  nibble 
;  get  digit  into  low  nibble 
;  convert  to  ASCII 
;  got  a  decimal  digit? 

;  yes,  so  continue 
;  no,  so  convert  to  HEX  ASCII 

;  output  it  via  BIOS 
;  get  number  back 
;  keep  only  low  digit  now 
;  convert  to  ASCII 
;  got  a  decimal  digit? 

;  yes,  so  continue 
;  no,  so  convert  to  HEX  ASCII 


output  it  via  BIOS 
restore  original  registers 


and  RET  to  caller 


;  save  original  AX 
;  first  do  CR 
;  output  it  via  the  BIOS 
;  do  LF  next 

;  output  it  via  the  BIOS 
;  restore  original  AX 
;  and  RET  to  caller 


DISPLAY  TTY 


DISPLAY  TTY 


PROC  NEAR 
PUSH  AX 
PUSH  BX 
MOV  AH, OEh 
MOV  BX, 0007h 
INT  lOh 
POP  BX 
POP  AX 
RET 
ENDP 


display  TTY 

on  page  0,  normal  attribute 
via  BIOS 


CSEG  ENDS 
END 


End  Listings 
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UNIX 


listing  One  (Text  begins  on  page  50.) 

/*  The  following  is  a  RAM  disk  driver  developed  for  Unix  Sys  V/386 
*  release  3.2.  —  Author:  Jeff  Reagen  05-02-90. 

*/ 

♦include  "sys/types .h" 

♦include  "sys/param.h" 

♦include  "sys/immu.h" 

♦include  "sys/fs/s5dir .h" 

♦include  "sys/signal.h" 

♦include  "sys/user .h" 

♦include  "sys/errno.h" 

♦include  "sys/cmn_err .h" 

♦include  "sys/buf.h" 


♦define  RD_SIZE_IN_PAGES  OxlOOL 
♦define  RD_MAX  1 

♦define  RAMDISK(x)  (int) (x&OxOF) 

♦define  DONT_SLEEP  1 


/*  256  4K  pages  =>  1  MB  */ 
/*  Max  RAM  Disks  */ 
/*  Ram  disk  number  from  dev  */ 
/*  sptalloc  parameter  */ 


/*  For  ioctl  routines. 

*/ 

♦define  RD_GETSIZE  1  /*  return  size  of  RAM  disk  */ 

struct  rd_getsize  {  /*  Structure  passed  to  rdioctl  */ 

daddr_t  sectors; 
long  in_bytes; 

}; 


/*  Valid  states  for  the  RAM  disk  driver 
*/ 

♦define  RDJJNDEFINED  0x0000 
♦define  RD_CONFIGURED  0x0001 
♦define  RD  OPEN  0x0002 


/*  Disk  has  not  been  setup  */ 

/*  Configured  disk  */ 

/*  Indicates  disk  has  been  opened  */ 


/*  The  RAM  disk  is  created  iff  the  size  field  has  been  defined.  Since 

*  sptalloc  only  allocates  pages,  make  sure  the  size  is 

*  some  multiple  of  page  size  (4096) . 

*/ 

struct  ram_config  { 

int  state;  /*  current  state  */ 

caddr_t  virt;  /*  virtual  address  of  RAM  disk  */ 

long  size;  /*  RAM  disk  size  in  units  of  4K  */ 


struct  ram_config  rd_cfg  =  (RD_UNDEFINED,  (caddr_t)0,  RD_SIZE_IN_PAGES) ; 

extern  caddr_t  sptalloc (); 

/*  rdinit  -  initialize  the  RAM  disk. 

V 

rdinit  (dev) 
dev_t  dev; 

{ 

/*  Has  a  RAM  disk  been  defined?  */ 
if  (rd  cfg.size  ==  0) 


{ 

/*  Just  return  silently  -  ram  disk  is  not  configured.  */ 
return  0; 

} 


/*  Last  parameter  1  in  sptalloc  calls  prevents  sleep  if  no  memory.  */ 
if  ((rd  cfg.virt  =  sptalloc  (rd_cfg.size,  PG_P, 0, DONT_SLEEP) )  ==  NULL) 

( 

cmn_err  (CE_WARN, "Could  not  allocate  enough  memory  for  RAM  disk.Nn"); 
return  0; 

) 

rd_cfg. state  1=  RD_CONF I GURED ; 
return; 


/*  rdopen 
*/ 

rdopen  (dev) 
dev_t  dev; 

{ 

int  rdisk; 

rdisk  =  RAMDISK (dev) ; 


if  (  rdisk  >=  RD_MAX ) 

{ 

/*  RAM  disk  specified  foes  not  exist.  */ 

u.u_error  =  ENODEV; 

return; 

) 

/*  Make  sure  ram  disk  has  been  configured.  */ 
if  (  (rd_cfg. state  &  RD_CONFIGURED)  !=  RD_CONFIGURED) 
( 

/*  disk  has  not  been  configured!  */ 

u.u_error  =  ENOMEM; 

return; 

) 

/*  RAM  disk  successfully  opened.  */ 
rd_cfg. state  !=  RD_OPEN; 

) 

/*  rdclose  -  close  the  RAM  disk. 

*/ 

rdclose  (dev) 
dev_t  dev; 

{ 

rd_cfg. state  &=  ~RD_OPEN; 
return; 


/*  rdstrategy  -  the  entire  synchronous  transfer  operation  happens  here. 

*/ 

rdstrategy  (bp) 

register  struct  buf  *bp; 

{ 

register  long  req_start;  /*  start  of  transfer  */ 

register  long  byte_size;  /*  Max  capacity  of  RAM  disk  in  bytes.  */ 

int  disk;  /*  RAM  disk  being  requested  for  service.  */ 


disk  =  RAMDISK ( bp- >b_dev ) ; 

/*  Validate  disk  number.  */ 
if  (disk  >=  RD_MAX) 

( 

/*  Disk  does  not  exist.  */ 
bp->b_flags  !=  B_ERROR; 
bp->b_error  =  ENODEV; 
iodone (bp) ; 
return; 

) 

/*  Validate  request  range.  Reads  can  be  trimmed  back...  */ 
byte_size  =  rd_cfg.size  *  NBPP; 
req_start  =  bp->b_blkno  *  NBPSCTR; 

bp->b_resid  =  0;  /*  Number  of  bytes  remaining  after  transfer  */ 


/*  Check  for  requests  exceeding  the  upper  bound  of  the  disk.  */ 
if  (req_start  +  bp->b_bcount  >  byte_size) 

( 

if  (bp->b_flags  &  B_READ) 

( 

/*  Read  */ 

/*  Adjust  residual  count.  */ 

bp->b_resid  =  req_start  +  bp->b_bcount  -  byte_size; 
bp->b_bcount  =  byte_size  -  req_start; 

1 

else 

( 

/*  Write  -  always  fails  */ 
bp->b_resid  =  bp->b_bcount; 
bp->b_flags  !=  B_ERROR; 
iodone  (bp) ; 
return; 

) 


/*  Service  the  request.  */ 
if  (bp->b_flags  &  B_READ) 

{ 

bcopy  (rd_cfg.virt  +  req_start,  bp->b_un.b_addr,  bp->b  bcount); 

) 

else 


bcopy  (bp->b_un.b_addr,  rd_cfg.virt  +  req_start,  bp->b  bcount); 

) 

bp->b_flags  &=  ~B_ERROR;  /*  Make  sure  an  error  is  NOT  reported.  */ 

iodone (bp) ; 

return; 
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/*  rdread  -  character  read  interface. 

*/ 

rdread  (dev) 
dev_t  dev; 

{ 

/*  Validate  request  based  on  number  of  512  bytes  sectors  supported.  */ 
if  (physck  ( (daddr_t) rd_cfg. size  «  DPPSHFT,  B  READ)) 

{ 

/*  Have  physio  allocate  the  buffer  header,  then  call  rdstrategy.  */ 
physio  (rdstrategy,  (struct  buf  *)NULL,  dev,  BREAD) ; 


/*  rdwrite  -  character  write  interface. 

*/ 

rdwrite  (dev) 
dev_t  dev; 

{ 

/*  Validate  request  based  on  number  of  512  bytes  sectors  supported.  */ 
if  (physck  ( (daddr_t) rd_cfg.size  «  DPPSHFT,  B  WRITE)) 

{ 

/*  Have  physio  allocate  the  buffer  header,  then  call  rdstrategy.  */ 
physio  (rdstrategy,  (struct  buf  *)NULL,  dev,  B  WRITE); 

} 


/*  rdioctl  -  returns  size  of  RAM  disk. 

*/ 

rdioctl  (dev,  command,  arg,  mode) 
dev_t  dev; 

int  command; 

int  *arg; 

int  mode; 

( 

struct  rd_getsize  sizes; 

if  (  RAMDISK (dev)  >  RD  MAX  I  I  ! (rd  cfg.state&RD  CONFIGURED)  ) 

{ 

u.u_error  =  ENODEV; 
return; 

} 

switch  (command)  { 
case  RD_GETSIZE : 

sizes. sectors  =  rd_cfg.size  «  DPPSHFT; 
sizes. in_bytes  =  rd_cfg.size  *  NBPP; 

/*  Now  transfer  the  request  to  user  space  */ 
if  (copyout  (&sizes,  arg,  sizeof  (sizes))  ) 

{ 

u.u_error  =  EFAULT; 

} 

break; 

default: 

/*  Error  -  do  not  recognize  command  submitted.  */ 

u.u_error  =  EINVAL; 

return; 

} 

} 

/*  rdintr  -  the  RAM  disk  does  not  generate  hardware  interrupts, 

*  so  this  routine  simply  prints  a  warning  message  and  returns. 

rdintr  () 

{ 

cmn_err  (CE_WARN,  "RAM  disk  took  a  spurious  hardware  interrupt . \n") ; 

} 

/*  rdprint  -  send  messages  concerning  the  RAM  disk  to  the  console. 

*/ 

rdprint  (dev,  str) 
dev_t  dev; 
char  *str; 

( 

cmn_err  (CE_NOTE,  "%s  on  Ram  Disk  %d.\n",  str,  RAMDISK  (dev)); 

} 


End  Listing 
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OBJECT  EXTENTS 


Listing  One  (Text  begins  on  page  58.) 

/*  min.c  —  Procedure  to  find  the  smallest  element  of  the  array. 

The  number  of  elements  in  the  array  must  be  >  0.  (  n  >  0  )  */ 

float  find_min(  array,  n  ) 

float  array[];  /*  input  array  */ 

int  n;  /*  number  of  elements  in  the  array  {  n  >  0  )  */ 

register  i;  float  min; 

min  =  array [0] ; 

for(  i  =  1;  i  <  n;  i++  ) 

if  (  min  >  arrayfi]  )  min  =  array [i]; 
return (  min  ) ; 

) 

/*  Procedure  to  find  the  largest  element  of  the  array. 

The  number  of  elements  in  the  array  must  be  >  0.  (  n  >  0  )  */ 

float  find_max(  array,  n  ) 

float  array!];  /*  input  array  */ 

int  n;  /*  number  of  elements  in  the  array  {  n  >  0  )  */ 

register  i;  float  max; 

max  =  array [0]; 

for(  i  =  1;  i  <  n;  i++  ) 

if  (  max  <  array [i]  )  max  =  array [i]; 
return (  max  ) ; 


End  Listing  One 


Listing  Two 

/*  min_max.c  —  Procedure  to  find  the  smallest  and  the  largest  element  of 
the  array.  The  number  of  elements  in  the  array  must  be  >  0.  (  n  >  0  )  */ 

void  f ind_min_max (  array,  n,  min,  max  ) 
float  array!];  /*  input  array  */ 

int  n;  /*  number  of  elements  in  the  array  (  n  >  0  )  */ 

float  *min,  *max;  /*  pointers  to  the  return  values  */ 

{ 

register  i; 

if  (  n  <=  1  ) 

*min  =  *max  =  array[0]; 
else  J 

if  (  array!0]  >  arrayfl]  )  (  /*  establish  the  basis  min  and  max  */ 

*max  =  array [0] ; 

*min  =  array [1] ; 

} 

else  ! 

*max  =  array [1]; 

*min  =  array [0 j; 

} 

for(  i  =  2;  (  i  +  2  )  <=  n;  i  +=  2  ) 
if  (  array!  i  ]  >  array!  i  +  1  ]  )  { 


if 

(  array!  i 

|  >  *max  ) 

*max  =  array! 

i 

1; 

if 

(  array!  i  +  1  ; 

|  <  *min  ) 

*min  =  array! 

i 

+  l  ]; 

else  { 

if 

(  array!  i  +  1  ! 

|  >  *max  ) 

*max  =  array! 

i 

+  l  ]; 

if 

(  array!  i 

I  <  *min  ) 

*min  =  array! 

i 

]; 

} 

if  (  i  <  n  )  /*  handle  the  odd/last  array  element  */ 

if  (  *max  <  array [i]  )  *max  =  array [i] ; 
else  if  (  *min  >  array [i]  )  *min  =  arrayfi]; 

} 

} 


End  listings 
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EXAMINING  ROOM 


Listing  One  (Text  begins  on  page  62.) 

♦include  <stdio.h> 

long  area [3]; 

void  compute_areas (void) ; 

main  ( ) 

{ 

int  i; 

extern  long  area [3]; 
compute_areas () ; 

for(i  =  0;  i  <=  2;  i++)  printfC'The  approximate  area  of  function  %d  is 


void  compute_areas (void) 

(  long  temp,  yO ( 100 ] ,  yl[100],  y2 ( 1 00 ] ; 

extern  long  area [3]; 
int  i,  k,  a,  b,  c,  d,  n,  m,  j; 

a  =  2;  b  =  5;  c  =  1;  d  =  3; 

area(0]  =  area[l]  =  area[2]  =  temp  =  0; 

/*  compute  100  initial  y  values  for  all  functions  and  approximate  area 
under  curves.  Do  this  100  times.  */ 
for  (i  =  0;  i  <=  99;  i++)  ( 

for  (j  =  0;  j  <=  99;  j++)  ( 
n  =  j-1; 
m  =  j+1; 

y0  [  j ]  =  a*j*n  +  48*  j  -  (c+d) ; 
yl [ j]  =  d* ( j+10)  +  a*b; 
y2 [ j]  =  c*j*m  +  7  3*  j  *  j  +  n; 

) 

> 

/*  add  a*b+c+d  to  all  y  values.  Do  this  100  times.  */ 
for  (i  =  0;  i  <=  99;  i++)  { 

for  (j  =  0;  j  <=  99;  j++)  { 
yO ( j ]  +=  a*b+c+d; 
yl  [  j)  +=  a*b+c+d; 
y2 [ jj  +=  a*b+c+d; 

} 

1 


/*  bubblesort  each  array  */ 

for  (i  =  0;  i  <=  99;  i++)  ( 

for  (k  =  99;  k  >=  1;  k  — )  ( 

if  (y0[k-l)  >  yO [k] )  { 
temp  =  y  0 [ k ] ; 
yO [ k )  =  y0[k-l] ; 
y0[k-l]  =  temp; 

) 

if  (y 1 ( k-1 ]  >  y 1 ( k ] )  { 
temp  =  yl [k] ; 
yl  [k]  =  yl [k-1 J ; 
yl [k— 1 ]  =  temp; 

) 

if  (y2 [k-1 ]  >  y2 [k] )  { 
temp  =  y2 [ k ] ; 
y2[k]  =  y2 [k-1] ; 
y2 [ k- 1 ]  =  temp; 


y2 [ j]  =  c* j* j*m  -  7  3  *  j  *  j ; 


/*  add  14  to  all  y  values.  Do  this  100  times.  */ 
for  (i  =  0;  i  <=  99;  i++)  ( 

for  (j  =  0;  j  <=  99;  j++)  ( 
yO [ j]  +=  14; 
yl t j]  +=  14; 
y2[ j]  +=  14; 

} 

} 

/*  bubblesort  each  array  */ 

for  (i  =  0;  i  <=  99;  i++)  { 

for  (k  =  99;  k  >=  1;  k--)  { 

if  (yO [k-1]  >  yO [k] )  { 
temp  =  y0[k); 
yO [k]  =  yO [k-1] ; 
yO [k-1 ]  =  temp; 

) 

if  (yl [k-1]  >  yl [k] )  { 
temp  =  yl [k] ; 
yl [k]  =  yl [k-1] ; 
yl [k— 1 ]  =  temp; 

) 

if  (y2[k-l)  >  y2 [k] )  { 
temp  =  y2 [ k ) ; 
y2[k]  =  y2 [k-1] ; 
y2 [ k— 1 ]  =  temp; 


/*  now  compute  areas  */ 
for  (j  =  0;  j  <=  99;  j++)  [ 
area [0]  +=  yO [ j ] ; 
area [ 1 ]  +=  yl [ j] ; 
area [2)  +=  y2[j); 


Listing  Three 

♦include  <stdio.h> 

long  area [3]; 

void  compute_areas (void) ; 

main () 

I 

int  i; 

extern  long  area [3]; 
compute_areas () ; 

for(i  =  0;  i  <=  2;  i++)  printfC'The  approximate 


•} 


/*  now  compute  areas  */ 
for  (j  =  0;  j  <=  99;  j++) 
area [0]  +=  yO [ j] ; 
area[l]  +=  yl [ j] ; 
area [2]  +=  y2 [ j ] ; 

[ 


void  compute_areas (void) 

[  long  temp,  yO [ 100 ) ,  y 1 [ 100 ] ,  y2 [100] ; 

extern  long  area [3]; 
int  i,  k,  j; 

area[0]  =  area[l)  =  area [2]  =  temp  =  0; 


End  Listing  One 


compute  100  initial  y  values  for  all  functions  and 
curves.  Do  this  100  times.  */  . 
for  (i  =  0;  i  <=  99;  i++)  { 

for  (j  =  0;  j  <=  99;  j++)  ( 

y0[ j]  =  2* j* j  -  50* j  +10; 

yl [ j]  =  3* j  +  54; 

y2[ j]  =  j* j* j  -  72* j  +  14; 


Listing  Two 

♦include  <stdio.h> 

long  area [3]; 

void  compute_areas (void) ; 

main  ( ) 

{ 

int  i; 

extern  long  area [3]; 
compute_areas () ; 

for(i  =  0;  i  <=  2;  i++)  printfC'The  approximate  area  of  function  %d  is 

%ld\n",  i,  area[i]); 

) 

void  compute_areas (void) 

(  long  temp,  yO [100 ) ,  yl [100 ] ,  y2 [ 100] ; 

extern  long  area [3); 
int  i,  k,  a,  b,  c,  d,  n,  m,  j; 

a  =  2;  b  =  5;  c  =  1;  d  =  3; 

area[0]  =  area[l)  =  area [2]  =  temp  =  0; 

/*  compute  100  initial  y  values  for  all  functions  and  approximate  area  under 
curves.  Do  this  100  times.  */ 
for  (i  =  0;  i  <=  99;  i++)  { 

for  (j  =  0;  j  <=  99;  j++)  { 
n  =  j-1; 
m  =  j  + 1  ; 

yO  [  j ]  =  a*j*n  +  4  8  *  j  -  4; 
yl  ( j 1  =  d*j  +  40; 


bubblesort  each  array  */ 

for  (i  =  0;  i  <=  99;  i++)  { 

for  (k  =  99;  k  >=  1;  k— )  { 

if  (yO [k-1]  >  yO [k] )  { 
temp  =  y  0 [ k ] ; 
y0[k]  =  yO [k-1] ; 
yO  [k-1 ]  =  temp; 

} 

if  (yl [k-1]  >  yl [k] )  { 
temp  =  yl [k] ; 
yl [k]  =  yl [k-1] ; 
yl [ k-1 ]  =  temp; 

1 

if  (y2 [k-1]  >  y2 [k] )  ( 
temp  =  y2 [k] ; 
y2[k]  =  y2 [k-1] ; 
y2[k-l]  =  temp; 


/*  now  compute  areas  */ 
for  (j  =  0;  j  <=  99;  j++)  { 
area [0]  +=  y0[ j] ; 
area [ 1 ]  +=  yl [ j ] ; 
area [2]  +=  y2 [ j ] ; 

} 


return; 


End  Listing  Two 


area  of  function  %d  is 
%ld\n",  i,  area[i]); 


approximate  area  under 


End  Listings 
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Listing  Ten  (Text  begins  on  page  72.) 

1399: 

gotFN  :=  TRUE; 

1400 : 

END; 

1290 : 

IMPLEMENTATION  MODULE  Term;  (*  TVI950  Terminal 

Emulation  for  Kermit  *) 

1401 : 

DEC  (i); 

1291 

1402! 

END; 

1292! 

FROM  Drives  IMPORT 

1403: 

IF  gotFN  THEN 

12931 

SetDrive; 

1404: 

j  :=  i  +  1; 

1294: 

14051 

k  :=  0; 

1295: 

FROM  Directories  IMPORT 

1406: 

WHILE  path [ j ]  #  0C  DO 

1296! 

FileAttributes,  AttributeSet,  DirectoryEntry, 

FindFirst,  FindNext; 

1407: 

filename [k]  :=  path[j]; 

1297! 

1408! 

INC  (k);  INC  (j); 

12981 

FROM  SYSTEM  IMPORT 

14091 

END; 

1299! 

ADR; 

i4io: 

filename [k]  :=  0C; 

1300 : 

i4ii : 

IF  (i  =  -1)  OR  ((i  =  0)  AND  (path[0] 

=  ' V ) )  THEN 

1301 

FROM  OS2DEF  IMPORT 

1412: 

INC  (i); 

1302! 

ULONG; 

1413: 

END; 

1303: 

1414: 

path[i]  :=  0C; 

1304: 

FROM  DosCalls 

IMPORT 

1415: 

END; 

1305! 

DosChDir,  DosSleep; 

1416: 

END; 

1306: 

1417! 

IF  Length  (path)  #  0  THEN 

1307! 

FROM  Screen  IMPORT 

1418: 

DosChDir  (ADR  (path) ,  0) ; 

1308! 

ClrScr,  ClrEol,  GotoXY,  GetXY, 

1419: 

END; 

13091 

Right,  Left 

Up,  Down,  WriteAtt,  WriteString, 

WriteLn,  Write, 

1420: 

IF  Length  (filename)  =  0  THEN 

1310 : 

attribute, 

FORMAL,  HIGHLIGHT,  REVERSE; 

1421 : 

filename  := 

i3ii : 

1422: 

END; 

1312! 

FROM  PMWIN  IMPORT 

1423: 

attr  :=  AttributeSet  (Readonly,  Directory, 

Archive) ; 

13131 

WinPostMsg, 

MPFROM2 SHORT; 

1424: 

i  :=  1;  (*  keep  track  of  position  on  line 

*) 

13141 

1425: 

1315! 

FROM  Shell  IMPORT 

1426: 

ClrScr; 

13161 

comport,  FrameWindow; 

1427: 

gotFN  :=  FindFirst  (filename,  attr,  ent); 

1317! 

1428: 

WHILE  gotFN  DO 

13181 

FROM  KH  IMPORT 

1429: 

WriteString  (ent. name); 

1319: 

COM  OFF; 

1430! 

j  :=  Length  (ent. name); 

1320! 

1431 : 

WHILE  j  <  12  DO  (*  12  is  max.  length  for 

"filename.typ"  *) 

1321! 

FROM  CommPort 

IMPORT 

1432: 

Write  ('  '); 

1322! 

CommStatus, 

GetChar,  SendChar; 

1433: 

INC  (j); 

13231 

1434: 

END; 

1324: 

FROM  Strings  IMPORT 

1435: 

INC  (i);  (*  next  position  on  this  line 

*) 

1325! 

Length,  Concat; 

1436: 

IF  i  >  5  THEN 

1326! 

1437: 

i  :=  1;  (*  start  again  on  new  line 

*) 

1327: 

IMPORT  ASCII; 

1438: 

WriteLn; 

13281 

1439: 

ELSE 

1329: 

1440: 

WriteString  ("  :  "); 

1330 : 

CONST 

1441 

END; 

1331! 

(*  Key  codes: 

Note:  FI  --  F12  are  actually  Shift-Fl 

—  Shift-F12  *) 

1442! 

gotFN  :=  FindNext  (ent); 

1332! 

FI  =  124C; 

1443: 

END; 

1333! 

F2  =  125C; 

1444: 

WriteLn; 

13341 

F3  =  126C; 

1445! 

END  Dir; 

1335! 

F4  =  127C; 

1446: 

133'6! 

F5  =  130C; 

1447: 

13371 

F6  =  13 1C; 

1448: 

PROCEDURE  InitTerm; 

13381 

F7  =  132C; 

1449: 

(*  Clear  Screen,  Home  Cursor,  Get  Ready  For  Terminal  Emulation  *) 

13391 

F8  =  133C; 

1450 

BEGIN 

1340: 

F9  =  1 3  4  C ; 

1451 

ClrScr; 

1341 

F10  =  135C; 

1452: 

Insert  :=  FALSE; 

13421 

Fll  =  207C; 

1453! 

attribute  :=  NORMAL; 

1343! 

F12  =  2 10C? 

1454: 

END  InitTerm; 

13441 

AF1  =  213C; 

(*  Alt-Fl  *) 

1455: 

1345! 

AF2  =  214C; 

(*  Alt-F2  *) 

1456: 

1346! 

INS  =  122C; 

1457: 

PROCEDURE  PutKbdChar  (chi,  ch2  :  CHAR); 

13471 

DEL  =  123C; 

1458: 

(*  Process  a  character  received  from  the  keyboard 

*) 

13481 

HOME  =  107C 

1459: 

BEGIN 

13491 

PGDN  =  121C 

(*  synonym  for  PF10  *) 

1460 

IF  chi  =  ASCII. enq  THEN  (*  Control-E  *) 

1350! 

PGUP  -111C 

(*  synonym  for  PF11  *) 

1461 

echo  :=  On; 

1351 : 

ENDD  =  117C 

(*  synonym  for  PF12  *) 

1462: 

ELSIF  chi  =  ASCII. ff  THEN  (*  Control-L  *) 

13521 

UPARROW  =  HOC; 

14631 

echo  :=  Local; 

1353: 

DOWNARROW  = 

120C; 

1464: 

ELSIF  chi  =  ASCII. dc4  THEN  (*  Control-T  * 

1354: 

LEFTARROW  = 

113C; 

1465: 

echo  :=  Off; 

1355: 

RIGHTARROW 

115C; 

1466! 

ELSIF  chi  =  ASCII. so  THEN  (*  Control-N  *) 

1356: 

CtrlX  =  30C 

1467: 

newline  :=  TRUE; 

1357! 

CtrlCaret  = 

36C; 

1468: 

ELSIF  chi  =  ASCI I. si  THEN  (*  Control-0  *) 

1358: 

CtrlZ  =  32C 

1469: 

newline  :=  FALSE; 

1359i 

CtrlL  =  14C 

1470! 

ELSIF  (chi  =  ASCII. can)  OR  (chi  =  ESC)  THEN 

1360 : 

CtrlH  =  10C 

1471 

attribute  :=  NORMAL; 

1361 

CtrlK  =  13C 

14721 

WinPostMsg  (FrameWindow,  WM  TERMQUIT,  0, 

0); 

1362! 

CtrlJ  =  12C 

14731 

ELSIF  Chl  =  0C  THEN 

1363! 

CtrlV  =  26C 

1474: 

Function  (ch2); 

1364! 

ESC  =  33C; 

14751 

ELSE 

1365! 

BUFSIZE  =  4096;  (*  character  buffer  used  by 

term  thread  *) 

1476: 

commStat  :=  SendChar  (comport  -  COM  OFF, 

chl,  FALSE); 

1366: 

14771 

IF  (echo  =  On)  OR  (echo  =  Local)  THEN 

13671 

1478: 

WriteAtt  (chl); 

1368: 

VAR 

1479: 

END; 

13691 

commStat  :  CommStatus; 

1480: 

END; 

1370! 

echo  :  (Off 

Local,  On); 

1481 

END  PutKbdChar; 

1371! 

newline:  BOOLEAN;  (*  translate  <cr>  to 

<cr><lf> 

*) 

1482: 

13721 

Insert  :  BOOLEAN; 

1483! 

13731 

14841 

PROCEDURE  Function  (ch  :  CHAR); 

1374: 

14851 

(*  handles  the  function  keys  —  including  PF1  -  PF12,  etc.  *) 

13751 

PROCEDURE  Dir  (path  :  ARRAY  OF  CHAR) ; 

I486: 

BEGIN 

13761 

(*  Change  drive 

&/or  directory;  display  directory 

(in 

wide  format)  *) 

1487! 

CASE  ch  OF 

13771 

14881 

FI  :  commStat  :=  SendChar  (comport  -  COM  OFF, 

ASCII .soh,  FALSE); 

13781 

VAR 

1489: 

commStat  :=  SendChar  (comport  -  COM  OFF, 

FALSE); 

1379: 

gotFN  :  BOOLEAN; 

1490 : 

commStat  :=  SendChar  (comport  -  COM  OFF, 

ASCII . cr,  FALSE); 

1380 : 

filename 

:  ARRAY  [0..20]  OF  CHAR; 

1491 : 

:  F2  :  commStat  :=  SendChar  (comport  -  COM  OFF, 

ASCI I. SOh,  FALSE); 

1381 

attr  :  AttributeSet; 

1492: 

commStat  :=  SendChar  (comport  -  COM  OFF, 

'A',  FALSE); 

1382! 

ent  :  DirectoryEntry; 

1493: 

commStat  :=  SendChar  (comport  -  COM  OFF, 

ASCII .cr,  FALSE); 

1383! 

i/  j,  k 

INTEGER; 

1494: 

:  F3  :  commStat  :=  SendChar  (comport  -  COM  OFF, 

ASCI I. soh,  FALSE); 

1384: 

1495: 

commStat  :=  SendChar  (comport  -  COM  OFF, 

'B',  FALSE); 

1385: 

BEGIN 

1496: 

commStat  :=  SendChar  (comport  -  COM  OFF, 

ASCII .cr,  FALSE); 

1386: 

filename 

:  =  ;  (*  in  case  no  directory  change  *) 

1497! 

:  F4  :  commStat  :=  SendChar  (comport  -  COM  OFF, 

ASCI I. soh,  FALSE); 

13871 

i  :=  Length  (path); 

1498,' 

commStat  :=  SendChar  (comport  -  COM  OFF, 

'C',  FALSE); 

1388: 

IF  (i  >  2)  AND  (path (1]  =  ':')  THEN 

(*  drive 

specifier  *) 

1499: 

commStat  :=  SendChar  (comport  -  COM  OFF, 

ASCII. cr,  FALSE); 

1389: 

DEC  (i,  2); 

1500: 

1  F5  :  commStat  :=  SendChar  (comport  -  COM  OFF, 

ASCI I. soh,  FALSE); 

1390 : 

SetDrive  (ORD  (CAP  (path[01))  -  ORC 

('A 

)); 

1501 : 

commStat  :=  SendChar  (comport  -  COM  OFF, 

'D',  FALSE); 

1391 : 

FOR  i 

:=  0  TO  i  DO  (*  strip  off  the  drive 

specifier  *) 

1502: 

commStat  :=  SendChar  (comport  -  COM  OFF, 

ASCII .cr,  FALSE); 

1392: 

1503: 

:  F6  :  commStat  :=  SendChar  (comport  -  COM  OFF, 

ASCI I. soh,  FALSE); 

1393: 

END; 

1504: 

commStat  :=  SendChar  (comport  -  COM  OFF, 

'E',  FALSE); 

1394; 

END; 

1505! 

commStat  :=  SendChar  (comport  -  COM  OFF, 

ASCII .cr,  FALSE); 

1395: 

IF  i  #  0 

THEN 

1506: 

:  F7  :  commStat  :=  SendChar  (comport  -  COM  OFF, 

ASCI I. soh,  FALSE); 

1396: 

gotFN 

:=  FALSE; 

1507: 

commStat  :=  SendChar  (comport  -  COM  OFF, 

'F',  FALSE); 

1397: 

WHILE 

(i  >=  0)  AND  (path ( i ]  #  '  \'  ) 

DO 

1398: 

IF 

path[i]  =  THEN 

(continued  on  page  110) 
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Listing  Ten  (Listing  continued,  text  begins  on  page  72.) 


1524 

1525 

1526 

1527 

1528 

1529 

1530 

1531 

1532 

1533 

1534 

1535 

1536 

1537 

1538 

1539 

1540 

1541 

1542 

1543 

1544 

1545 

1546 

1547 

1548 

1549 

1550 

1551 

1552 

1553 

1554 

1555 

1556 

1557 

1558 

1559 

1560 

1561 

1562 

1563 

1564 

1565 

1566 

1567 

1568 

1569 

1570 

1571 

1572 

1573 

1574 

1575 

1576 

1577 

1578 

1579 

1580 

1581 

1582 

1583 

1584 

1585 

1586 

1587 

1588 

1589 

1590 

1591 

1592 

1593 

1594 

1595 

1596 

1597 

1598 

1599 

1600 
1601 
1602 

1603 

1604 

1605 

1606 

1607 

1608 

1609 

1610 
1611 
1612 

1613 

1614 

1615 

1616 


1508: 

commStat 

= 

SendChar 

(comport 

-  COM 

OFF 

1509: 

:  F8  : 

commStat 

= 

SendChar 

(comport 

-  COM’ 

'OFF 

1510 : 

commStat 

= 

SendChar 

(comport 

-  COM’ 

"off 

i5ii : 

commStat 

= 

SendChar 

(comport 

-  COM’ 

’OFF 

1512: 

:  F9  : 

commStat 

= 

SendChar 

(comport 

-  COM' 

'OFF 

1513: 

commStat 

= 

SendChar 

(comport 

-  COM' 

'off 

1514: 

commStat 

= 

SendChar 

(comport 

-  COM] 

;off 

1515 : 

:  fio, 

1516: 

PGDN: 

commStat 

= 

SendChar 

(comport 

-  COM 

OFF 

15171 

commStat 

= 

SendChar 

(comport 

-  COM’ 

’OFF 

1518: 

commStat 

= 

SendChar 

(comport 

-  COM] 

;off 

15191 

1  Fll, 

15201 

AF1 , 

15211 

PGUP: 

commStat 

= 

SendChar 

(comport 

-  COM 

OFF 

15221 

commStat 

= 

SendChar 

(comport 

-  COM' 

'OFF 

15231 

commStat 

= 

SendChar 

(comport 

-  COM' 

'off 

FALSE) ; 
ASCII. SOh,  FALSE); 
'G' ,  FALSE); 

ASCII. cr,  FALSE); 
ASCI I. soh,  FALSE); 
'H' ,  FALSE); 

ASCII. cr,  FALSE); 

ASCII. soh,  FALSE); 
'I',  FALSE); 

ASCII .cr,  FALSE); 


ASCII. soh,  FALSE); 
' J' ,  FALSE); 

ASCII. cr,  FALSE); 


F12, 

AF2, 

ENDD:  commStat  :=  SendChar  (comport 
commStat  :=  SendChar  (comport 
INS  :  IF  NOT  Insert  THEN 

commStat  :=  SendChar  (comport 
commStat  :=  SendChar  (comport 
END; 

DEL  :  commStat  :: 

commStat 
commStat 


COM_OFF ,  ESC,  FALSE); 
COM_OFF,  'Q' ,  FALSE); 


COM_OFF ,  ESC,  FALSE); 
COM  OFF,  'E',  FALSE); 


:  HOME 
:  UPARROW 
:  DOWNARROW 
:  LEFTARROW  : 

1  RIGHTARROW 
ELSE 

(*  do  nothing 
END; 

END  Function; 


SendChar  (comport 
:=  SendChar  (comport 


COM_OFF ,  ESC,  FALSE) ; 

COM_OFF,  'R',  FALSE); 

SendChar  (comport  -  COM_OFF,  CtrlZ,  FALSE); 
commStat  :=  SendChar  (comport  -  COM_OFF,  CtrlK,  FALSE); 
commStat  :=  SendChar  (comport  -  COM_OFF,  CtrlV,  FALSE); 
commStat  :=  SendChar  (comport  -  COM_OFF,  CtrlH,  FALSE) ; 

:  commStat  :=  SendChar  (comport  -  COM_OFF,  CtrlL,  FALSE) ; 

*) 


PROCEDURE  TermThrProc; 

(*  Thread  to  get  characters  from  port,  put  into  buffer  *) 


ch  :  CHAR; 

BEGIN 

LOOP 

IF  GetChar  (comport  -  COM_OFF,  ch)  =  Success  THEN 
WinPostMsg  (FrameWindow,  WM_TERM,  MPFROM2 SHORT  (ORD  (ch) ,  0),  0) ; 
ELSE 

DosSleep  (0); 

END 

END; 

END  TermThrProc; 


EscState,  CurStatel,  CurState2  :  BOOLEAN; 
CurCharl  :  CHAR; 

PROCEDURE  PutPortChar  (ch  :  CHAR); 

(*  Process  a  character  received  from  the  port  *) 
BEGIN 

IF  EscState  THEN 

EscState  :=  FALSE; 

IF  ch  =  '='  THEN 

CurStatel  :=  TRUE; 

ELSE 

Escape  (ch) ; 

END; 

ELSIF  CurStatel  THEN 
CurStatel  :=  FALSE; 

CurCharl  :=  ch; 

CurState2  :=  TRUE; 

ELSIF  CurState2  THEN 
CurState2  :  =  FALSE; 

Cursor  (ch) ; 

ELSE 

CASE  ch  OF 

CtrlCaret,  CtrlZ  :  ClrScr; 

!  CtrlL  :  Right; 

CtrlH  :  Left; 

CtrlK  :  Up; 

CtrlJ  :  Down; 

ESC  :  EscState  :=  TRUE; 

ELSE 

WriteAtt  (ch) ; 

IF  newline  AND  (ch  =  ASCII. cr)  THEN 
WriteLn; 

END; 

END; 

END; 

IF  echo  =  On  THEN 

commStat  :=  SendChar  (comport  -  COM_OFF, 
END; 

END  PutPortChar; 


PROCEDURE  Escape  (ch  :  CHAR); 

(*  handles  escape  sequences  *) 

BEGIN 

CASE  ch  OF 

'*'  :  ClrScr; 

'T',  'R'  :  ClrEol; 

')'  :  attribute  :=  NORMAL; 

' ('  :  attribute  :=  HIGHLIGHT; 
'  t'  :  InsertMsg; 

'g'  :  InsertOn; 


ELSE 

(*  ignore 
END; 


16171  END  Escape; 

16181 

1619: 

1620:  PROCEDURE  Cursor  (ch  :  CHAR); 

1621 :  (*  handles  cursor  positioning  *) 

16221 

16231  VAR 

1624:  x,  y  :  CARDINAL; 

1625: 

1626:  BEGIN 

1627:  y  :=  ORD  (CurCharl)  -  20H; 

16281  x  :=  ORD  (ch)  -  20H; 

1629i  GotoXY  (x,  y) ;  (*  adjust  for  HOME  =  (1,  1)  *) 

1630 1  END  Cursor; 

1631! 

1632! 

1633!  VAR 

1634:  cx,  cy  :  CARDINAL; 

1635! 

1636:  PROCEDURE  InsertMsg; 

1637!  (*  get  ready  insert  mode;  place  message  at  bottom  of  the  screen  *) 

1638!  BEGIN 

1639:  IF  NOT  Insert  THEN 

1640:  GetXY  (cx,  cy) ;  (*  record  current  position  *) 

1641 :  GotoXY  (1,  24); 

1642!  ClrEol; 

1643!  attribute  :=  REVERSE; 

1644!  ELSE  (*  exit  Insert  mode  *) 

1645!  GetXY  (cx,  cy) ; 

1646:  GotoXY  (1,  24); 

1647:  ClrEol; 

16481  GotoXY  (cx,  cy) ; 

1649!  Insert  :=  FALSE; 

1650 :  END; 

1651!  END  InsertMsg; 

1652! 

16531 

1654:  PROCEDURE  InsertOn; 

1655!  (*  enter  insert  mode  —  after  INSERT  MODE  message  is  printed  *) 

16561  BEGIN 

1657,1  attribute  :=  NORMAL; 

1658:  GotoXY  (cx,  cy) ; 

1659:  Insert  :=  TRUE; 

1660!  END  InsertOn; 

1661 : 

1662i 

1663!  BEGIN  (*  module  initialization  *) 

1664:  echo  :=  Off; 

1665:  newline  :=  FALSE; 

1666:  Insert  :=  FALSE; 

1667:  EscState  :=  FALSE; 

1668:  CurStatel  :=  FALSE; 

1669!  CurState2  :=  FALSE; 

1670 :  END  Term. 

1671 : 


End  Listing  Ten 


Listing  Eleven 


1672 

1673 

1674 

1675 

1676 

1677 

1678 

1679 

1680 
1681 
1682 

1683 

1684 

1685 

1686 

1687 

1688 

1689 

1690 

1691 

1692 

1693 

1694 

1695 

1696 

1697 

1698 

1699 

1700 

1701 

1702 

1703 

1704 

1705 

1706 

1707 

1708 

1709 

1710 

1711 

1712 

1713 

1714 

1715 

1716 

1717 

1718 

1719 

1720 

1721 


IMPLEMENTATION  MODULE  Screen; 

(*  module  to  perform  "low  level"  screen  functions  (via  AVIO)  *) 

IMPORT  ASCII; 

FROM  SYSTEM  IMPORT 
ADR; 

FROM  Strings  IMPORT 
Length; 

FROM  Conversions  IMPORT 
IntToString; 

FROM  KH  IMPORT 
IDM_GREEN; 

FROM  Vio  IMPORT 

VioSetCurPos,  VioGetCurPos,  VioScrollUp, 

VioWrtNCell,  VioWrtTTY,  VioCell; 


CONST 

GREY  =  07H; 
WHITE  =  0FH; 
REV_GY  =  7 OH; 
GREEN  =  02H; 
LITE_GRN  =  0AH; 
REV_GRN  =  2 OH; 
AMBER  =  06H; 
LITE_AMB  =  0EH; 
REV_AMB  =  6 OH; 
RED  =  0CH; 

CY_BK  =  0B0H; 
CY_BL  =  0B9H; 
REV_RD  =  0CFH; 
REV_BL  =  9FH; 
MAGENTA  =  05H; 


(*  From  Definition  Module 
NORMAL  :  CARDINAL; 

HIGHLIGHT  :  CARDINAL; 

REVERSE  :  CARDINAL; 

attribute  :  CARDINAL; 
hvps  :  HVPS; 

*) 

x,  y  :  CARDINAL;  ,  .  ,  .  „ 

been  :  vioceii;  (continued  on  page  1 13) 
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1722! 

17231 

1724!  PROCEDURE  White; 

1725!  (*  Sets  up  colors:  Monochrome  White  *) 

17261  BEGIN 

17271  NORMAL  :=  GREY; 

1728:  HIGHLIGHT  :=  WHITE; 

17291  REVERSE  :=  REV_GY; 

1730!  attribute  :=  NORMAL; 

1731 1  END  White; 

17321 

17331 

1734:  PROCEDURE  Green; 

1735!  (*  Sets  up  colors:  Monochrome  Green  *) 

1736!  BEGIN 

1737!  NORMAL  :=  GREEN; 

17381  HIGHLIGHT  :=  LITE_GRN; 

17391  REVERSE  :=  REV_GRN; 

1740 :  attribute  :=  NORMAL; 

1741 1  END  Green; 

1742! 

17431 

1744:  PROCEDURE  Amber; 

17451  (*  Sets  up  colors:  Monochrome  Amber  *) 

1746:  BEGIN 

17471  NORMAL  :=  AMBER; 

17481  HIGHLIGHT  :=  LITE_AMB; 

1749:  REVERSE  :=  REV_AMB; 

1750!  attribute  :=  NORMAL; 

1751!  END  Amber; 

1752! 

17531 

.17541  PROCEDURE  Colorl; 

17551  (*  Sets  up  colors:  Blue,  Red,  Green  *) 

17561  BEGIN 

1757!  NORMAL  :=  GREEN; 

1758!  HIGHLIGHT  :=  RED; 

1759!  REVERSE  :=  REV_BL; 

1760 :  attribute  :=  NORMAL; 

1761 1  END  Colorl; 

1762! 

1763! 

17641  PROCEDURE  Color2; 

17651  (*  Sets  up  colors:  Cyan  Background;  Black,  Blue,  White-on-Red  *) 

17661  BEGIN 

1767!  NORMAL  :=  CY_BK; 

1768:  HIGHLIGHT  :=  CY_BL; 

17691  REVERSE  :=  REV_RD; 

1770!  attribute  :=  NORMAL; 

1771!  END  Color2; 

1772! 

1773! 

1774:  PROCEDURE  HexToString  (num  :  INTEGER; 


17751 
17761 
17771 
17781 
17791 
1780: 
1781 : 
1782: 
1783: 
1784: 
1785! 
1786: 
1787: 
1788: 
1789: 
1790: 

1791 : 

1792: 

1793: 

1794: 

1795: 

1796: 

1797: 

1798: 

1799: 

1800: 
1801 : 
1802: 
1803: 
1804: 
1805: 
1806: 
1807: 
1808! 
1809: 

i8io: 
1811 : 
1812: 
1813: 
1814: 
1815: 
1816: 
1817: 
1818: 
1819: 
1820: 
1821 : 
1822: 
1823: 
1824: 
1825: 
1826: 
1827! 


size  :  CARDINAL; 

VAR  buf  :  ARRAY  OF  CHAR; 

VAR  I  :  CARDINAL; 

VAR  Done  :  BOOLEAN) ; 

Local  Procedure  -  convert  number  to  string,  represented  in  HEX  *) 
CONST 

ZERO  =  3 OH;  (*  ASCII  code  *) 

A  =  41H; 


i  :  CARDINAL; 
h  :  CARDINAL; 

t  :  ARRAY  [0..10]  OF  CHAR; 

BEGIN 

i  :=  0; 

REPEAT 

h  :=  num  MOD  16; 

IF  h  <=  9  THEN 

t [i]  :=  CHR  (h  +  ZERO); 

ELSE 

t [i]  :=  CHR  (h  -  10  +  A); 

END; 

INC  (i); 

num  :=  num  DIV  16; 

UNTIL  num  =  0; 

IF  (size  >  HIGH  (buf))  OR  (i  >  HIGH  (buf))  THEN 
Done  :=  FALSE; 

RETURN; 

ELSE 

Done  :=  TRUE; 

END; 

WHILE  size  >  i  DO 

buf [ I ]  :=  'O';  (*  pad  with  zeros  *) 

DEC  (size) ; 

INC  (I); 

END; 

WHILE  i  >  0  DO 
DEC  (i); 
buf [I]  :=  t [i] ; 

INC  (I); 

END; 

buf [I]  :=  0C; 

END  HexToString; 


PROCEDURE  ClrScr; 

(*  Clear  the  screen, 


and  home  the  cursor  *) 
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listing  Eleven  (Listing  continued,  text  begins  on  page  72.) 

1828:  BEGIN 

1829!  bCell.ch  :=  '  (*  space  =  blank  screen  *) 

1830!  bCell.attr  :=  CHR  (NORMAL);  (*  Normal  Video  Attribute  *) 

1831!  VioScrollUp  (0,  0,  24,  79,  25,  bCell,  hvps); 

18321  GotoXY  (0,  0) ; 

18331  END  ClrScr; 


PROCEDURE  ClrEol; 

(*  clear  from  current  cursor  position  to  the  end  of  the  line  *) 
BEGIN 

GetXY  (x,  y) ;  (*  current  cursor  position  *) 

bCell.ch  (*  space  =  blank  *) 

bCell.attr  :=  CHR  (NORMAL);  (*  Normal  Video  Attribute  *) 
VioScrollUp  (y,  x,  y,  79,  1,  bCell,  hvps); 

END  ClrEol; 


PROCEDURE  Right; 

(*  move  cursor  to  the  right  *) 
BEGIN 

GetXY  (x,  y); 

INC  (x); 

GotoXY  (x,  y) ; 

END  Right; 


PROCEDURE  Left; 

(*  move  cursor  to  the  left  *) 
BEGIN 

1  GetXY  (x,  y); 

DEC  (x); 

GotoXY  (x,  y) ; 

END  Left; 


PROCEDURE  Up; 

(*  move  cursor  up  *) 
BEGIN 

GetXY  (x,  y); 
DEC  (y); 
GotoXY  (x,  y) ; 
END  Up; 


PROCEDURE  Down; 

(*  move  cursor  down  *) 
BEGIN 

GetXY  (x,  y); 

INC  (y); 

GotoXY  (x,  y); 
END  Down; 


PROCEDURE  GotoXY  (col,  row  :  CARDINAL); 

(*  position  cursor  at  column,  row  *) 

BEGIN 

IF  (col  <=  79)  AND  (row  <=  24)  THEN 
VioSetCurPos  (row,  col,  hvps)  ; 
END; 

END  GotoXY; 


PROCEDURE  GetXY  (VAR  col,  row  :  CARDINAL) ; 
(*  determine  current  cursor  position  *) 
BEGIN 

VioGetCurPos  (row,  col,  hvps); 

END  GetXY; 


PROCEDURE  Write  (c  :  CHAR) ; 
(*  Write  a  Character  *) 
BEGIN 

WriteAtt  (c) ; 

END  Write; 


PROCEDURE  WriteString  (str  :  ARRAY  OF  CHAR); 
(*  Write  String  *) 


i  :  CARDINAL; 
c  :  CHAR; 

BEGIN 
i  :=  0; 
c  :=  str [i] ; 
WHILE  c  #  0C  DO 
Write  (c) ; 
INC  (i); 
c  :=  str [i] ; 
END; 

END  WriteString; 


PROCEDURE  Writelnt  (n  :  INTEGER;  s  :  CARDINAL); 
(*  Write  Integer  *) 


i  :  CARDINAL; 
b  :  BOOLEAN; 

str  :  ARRAY  [0..6]  OF  CHAR; 
BEGIN 

i  :=  0; 

IntToString  (n,  s,  str,  i,  b) ; 
WriteString  (str); 

END  Writelnt; 


PROCEDURE  WriteHex  (n,  s  :  CARDINAL) ; 
(*  Write  a  Hexadecimal  Number  *) 


i  :  CARDINAL; 
b  :  BOOLEAN; 

str  ;  ARRAY  [0..6]  OF  CHAR; 


HexToString  (n,  s,  str,  i,  b) ; 
WriteString  (str); 

END  WriteHex; 


PROCEDURE  WriteLn; 

(*  Write  <cr>  <lf>  *) 
BEGIN 

Write  (ASCII .cr) ; 
END  WriteLn; 


Write  (ASCI I. If); 


PROCEDURE  WriteAtt  (c  :  CHAR) ; 

(*  write  character  and  attribute  at  cursor  position 


S  :  ARRAY  [0..1]  OF  CHAR; 

BEGIN 

GetXY  (x,  y); 

IF  (c  =  ASCII. ht)  THEN 
bCell.ch  :=  '  '; 
bCell.attr  :=  CHR  (attribute); 

REPEAT 

VioWrtNCell  (bCell,  1,  y,  x,  hvps); 
Right; 

UNTIL  (x  MOD  8)  =  0; 

ELSIF  (c  =  ASCII. cr)  OR  (c  *=  ASCII. If) 

OR  (c  =  ASCII. bel)  OR  (c  =  ASCII. bs)  THEN 
s [0]  :=  c;  s [1  ]  :=  0C; 

VioWrtTTY  (ADR  (s) ,  1,  hvps); 

IF  C  =  ASCII. If  THEN 
ClrEol; 

END; 

ELSE 

bCell.ch  :=  c; 

bCell.attr  :=  CHR  (attribute); 
VioWrtNCell  (bCell,  1,  y,  x,  hvps) ; 
Right; 

END; 

END  WriteAtt; 

BEGIN  (*  module  initialization  *) 

ColorSet  :=  IDM_GREEN; 

NORMAL  :=  GREEN; 

HIGHLIGHT  :=  LITE_GRN; 

REVERSE  :=  RE V_GRN ; 
attribute  :=  NORMAL; 

END  Screen. 


End  Listing  Eleven 


Listing  Twelve 


Copyright  (c)  1988,  1989 
by  Stony  Brook  Software 
and 

Copyright  (c)  1990 
by  Brian  R.  Anderson 
All  rights  reserved. 


IMPLEMENTATION  MODULE  CommPort  [7] ; 


FROM  SYSTEM  IMPORT 

ADR,  BYTE,  WORD,  ADDRESS; 


FROM  Storage  IMPORT 

ALLOCATE,  DEALLOCATE; 


FROM  DosCalls  IMPORT 

DosOpen,  AttributeSet,  DosDevIOCtl,  DosClose,  DosRead,  DosWrite; 


TYPE 

CP  =  POINTER  TO  CHAR; 


pn  :  CARDINAL; 

Handle  :  ARRAY  [0..3]  OF  CARDINAL; 

Bufln  :  ARRAY  [0..3]  OF  CP; 

BufOut  :  ARRAY  [0..3]  OF  CP; 

BufStart  :  ARRAY  [0..3]  OF  CP; 

Buf Limit  :  ARRAY  [0..3]  OF  CP; 

BufSize  :  ARRAY  [0..3]  OF  CARDINAL; 

Temp  :  ARRAY  [1..1024]  OF  CHAR;  (*  size  of  OS/2's  serial  queue  *) 


PROCEDURE  CheckPort  (portnum  :  CARDINAL)  :  BOOLEAN; 

{*  Check  for  valid  port  number  and  open  port  if  not  alredy  open  *) 

CONST 

PortName  :  ARRAY  [0..3]  OF  ARRAY  [0..4]  OF  CHAR  = 

( [ ' COM1 ' ,  0C],  ['COM2',  0C],  ['COM3',  0C] ,  ['COM4',  0C) ] ; 
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20431 

VAR 

2044! 

2045: 

Action  :  CARDINAL; 

2046: 

BEGIN 

2047! 

(*  check  the  port  number  *) 

2048: 

IF  portnum  >  3  THEN 

2049: 

RETURN  FALSE; 

2050! 

END; 

2051 : 
2052! 

(*  attempt  to  open  the  port  if  it  is  not  already  open 

*) 

2053! 

IF  Handle [portnum]  =  0  THEN 

2054! 

IF  DosOpen (ADR (PortName [portnum] ) ,  Handle [portnum] ,  Action,  0, 

2055! 

AttributeSetU,  1,  12H,  0)  #  0  THEN 

20561 

RETURN  FALSE; 

2057,' 

END; 

2058: 

END; 

20591 

RETURN  TRUE; 

2060! 
2061 : 
2062! 
2063: 

END  CheckPort; 

2064! 

PROCEDURE  InitPort  (portnum  :  CARDINAL;  speed  :  BaudRate;  data 

20651 

DataBits;  stop  :  StopBits;  check  :  Parity)  :  CommStatus; 

2066! 

2067! 

(*  Initialize  a  port  *) 

20681 

CONST 

20691 

Rate  :  ARRAY  BaudRate  OF  CARDINAL  = 

2070! 

[110,  150,  300,  600,  1200,  2400,  4800,  9600 

19200] ; 

2071! 

2072! 

TransParity  :  ARRAY  Parity  OF  BYTE  =  [2,  1,  0]; 

2073! 

TYPE 

20741 

LineChar  =  RECORD 

2075! 

bDataBits  :  BYTE; 

2076! 

bParity  :  BYTE; 

2077! 

bStopBits  :  BYTE; 

2078! 

END; 

20791 

2080: 

VAR 

2081 : 
2082: 

LC  :  LineChar; 

2083: 

BEGIN 

2084: 

(*  Check  the  port  number  *) 

2085: 

IF  NOT  CheckPort (portnum)  THEN 

2086: 

RETURN  InvalidPort; 

2087! 

20881 

END; 

20891 

(*  Set  the  baud  rate  *) 

2090! 

IF  DosDevIOCtl (0,  ADR (Rate [ speed] ) ,  41H,  1,  Handle [portnum] ) 

#  0  THEN 

2091! 

RETURN  InvalidParameter; 

2092! 

20931 

END; 

2094! 

(*  set  the  characteristics  *) 

20951 

LC. bDataBits  :=  BYTE (data); 

2096! 

IF  stop  =  1  THEN 

20971 

DEC  (stop);  (*  0x00  =  1  stop  bits;  0x02  =  2  stop  bits  *) 

20981 

END; 

2099: 

LC. bStopBits  :=  BYTE ( stop) ; 

2100! 

2101! 

LC. bParity  :=  TransParity [check] ; 

2102! 

IF  DosDevIOCtl (0,  ADR(LC) ,  42H,  1,  Handle [portnum] )  # 

0  THEN 

2103! 

RETURN  InvalidParameter; 

2104! 

2105! 

END; 

2106! 

RETURN  Success; 

21071 

21081 

21091 

END  InitPort; 

21101 

PROCEDURE  StartReceiving  (portnum,  bufsize  :  CARDINAL)  :  CommStatus; 

2111 : 

(*  Start  receiving  characters  on  a  port  *) 

21121 

BEGIN 

21131 

IF  NOT  CheckPort (portnum)  THEN 

2114! 

RETURN  InvalidPort; 

2115! 

END; 

21161 

IF  BufStart [portnum]  #  NIL  THEN 

2117! 

RETURN  AlreadyReceiving; 

2118! 

END; 

2119! 

ALLOCATE  (BufStart [portnum] ,  bufsize); 

2120! 

Bufln [portnum]  :=  BufStart [portnum] ; 

2121! 

BufOut [portnum]  :=  BufStart [portnum] ; 

2122! 

BufLimit [portnum]  :=  BufStart [portnum] ; 

21231 

INC  (BufLimit [portnum] : ADDRESS,  bufsize  -  1); 

21241 

BufSize [portnum]  :=  bufsize; 

21251 

RETURN  Success; 

2126! 

21271 

END  StartReceiving; 

21281 

2129! 

PROCEDURE  StopReceiving  (portnum  :  CARDINAL)  :  CommStatus; 

2130! 

(*  Stop  receiving  characters  on  a  port  *) 

21311 

BEGIN 

21321 

IF  NOT  CheckPort (portnum)  THEN 

21331 

RETURN  InvalidPort; 

21341 

END; 

21351 

IF  BufStart [portnum]  #  NIL  THEN 

21361 

DEALLOCATE  (BufStart [portnum] ,  BufSize [portnum] ) ; 

21371 

BufLimit [portnum]  :=  NIL; 

2138! 

Bufln [portnum]  :=  NIL; 

2139! 

BufOut [portnum]  :=  NIL; 

2140 : 

BufSize [portnum]  :=  0; 

2141! 

END; 

21421 

DosClose (Handle [portnum] ) ; 

21431 

Handle [portnum]  :=  0; 

21441 

RETURN  Success; 

21451 

21461 

21471 

END  StopReceiving; 

21481 

PROCEDURE  GetChar  (portnum  :  CARDINAL;  VAR  ch  :  CHAR)  :  CommStatus; 

21491 

21501 

(*  Get  a  character  from  the  comm  port  *) 

2151! 

VAR 

2152 

2153 

2154 

2155 

2156 

2157 

2158 

2159 

2160 
2161 
2162 

2163 

2164 

2165 

2166 

2167 

2168 

2169 

2170 

2171 

2172 

2173 

2174 

2175 

2176 

2177 

2178 

2179 

2180 
2181 
2182 

2183 

2184 

2185 

2186 

2187 

2188 

2189 

2190 

2191 

2192 

2193 

2194 

2195 

2196 

2197 

2198 

2199 

2200 
2201 
2202 

2203 

2204 

2205 

2206 

2207 

2208 

2209 

2210 
2211 
2212 

2213 

2214 

2215 

2216 

2217 

2218 

2219 

2220 
2221 
2222 

2223 

2224 

2225 

2226 

2227 

2228 

2229 

2230 

2231 

2232 

2233 

2234 

2235 

2236 
2237: 


status  :  CARDINAL; 
read  :  CARDINAL; 
que  :  RECORD 

ct  :  CARDINAL; 
sz  :  CARDINAL; 

END; 

i  :  CARDINAL; 

BEGIN 

IF  BufStart [portnum]  =  NIL  THEN 
RETURN  NotReceiving; 

END; 

IF  NOT  CheckPort (portnum)  THEN 
RETURN  InvalidPort; 

END; 

status  :=  DosDevIOCtl  (ADR  (que),  0,  68H,  1,  Handle [portnum] ) ; 
IF  (status  =  0)  AND  (que.ct  #  0)  THEN 

status  •:  =  DosRead  (Handle [portnum] ,  ADR  (Temp),  que.ct,  read); 
IF  (status  #  0)  OR  (read  =  0)  THEN 
RETURN  NotReceiving; 

END; 

FOR  i  :=  1  TO  read  DO 

Bufln [portnum] A  :=  Temp[i]; 

IF  Bufln [portnum]  =  BufLimit [portnum]  THEN 
Bufln [portnum]  :=  BufStart [portnum] ; 

ELSE 

INC  (Bufln [portnum] : ADDRESS) ; 

END; 

IF  Bufln [portnum]  =  BufOut [portnum]  THEN 
RETURN  BufferOverflow; 

END; 

END; 

END; 

IF  Bufln [portnum]  =  BufOut [portnum]  THEN 
RETURN  NoCharacter; 

END; 

ch  :=  BufOut [portnum] A; 

IF  BufOut [portnum]  =  BufLimit [portnum]  THEN 
BufOut [portnum]  :=  BufStart [portnum] ; 

ELSE 

INC  (BufOut [portnum] : ADDRESS) ; 

END; 

RETURN  Success; 

END  GetChar; 


PROCEDURE  SendChar  (portnum  :  CARDINAL;  ch  :  CHAR; 

modem  :  BOOLEAN)  :  CommStatus; 

(*  send  a  character  to  the  comm  port  *) 

VAR 

wrote  :  CARDINAL; 
status  :  CARDINAL; 
commSt  :  CHAR; 

BEGIN 

IF  NOT  CheckPort (portnum)  THEN 
RETURN  InvalidPort; 

END; 

status  ;=  DosDevIOCtl  (ADR  (commSt),  0,  64H,  1,  Handle [portnum] ) ; 
IF  (status  #  0)  OR  (commSt  #  0C)  THEN 
RETURN  TimeOut; 

ELSE 

status  :=  DosWrite (Handle [portnum] ,  ADR(ch),  1,  wrote); 

IF  (status  #  0)  OR  (wrote  #  1)  THEN 
RETURN  TimeOut; 

ELSE 

RETURN  Success; 

END; 

END; 

END  SendChar; 


BEGIN  (*  module  initialization  *) 

(*  nothing  open  yet  *) 

FOR  pn  :=  0  TO  3  DO 
Handle [pn]  :=  0; 

BufStart [pn]  :=  NIL; 

BufLimit [pn]  :=  NIL; 

Bufln [pn]  :=  NIL; 

BufOut [pn]  :=  NIL; 

BufSize[pn]  :=  0; 

END; 

END  CommPort. 

End  Listing  Twelve 


Listing  Thirteen 

IMPLEMENTATION  MODULE  Files;  (*  File  I/O  for  Kermit  *) 

FROM  FileSystem  IMPORT 

File,  Response,  Delete,  Lookup,  Close,  ReadNBytes,  WriteNBytes; 
FROM  Strings  IMPORT 
Append; 

FROM  Conversions  IMPORT 
CardToString; 

FROM  SYSTEM  IMPORT 
ADR,  SIZE; 

TYPE 

buffer  =  ARRAY  [1..512]  OF  CHAR; 

VAR 

ext  :  CARDINAL;  (*  new  file  extensions  to  avoid  name  conflict  *) 
inBuf,  outBuf  :  buffer; 

inP,  outP  :  CARDINAL;  (*  buffer  pointers  *) 

read,  written  :  CARDINAL;  (*  number  of  bytes  read  or  written  *) 
(*  by  ReadNBytes  or  WriteNBytes  *) 
PROCEDURE  Open  (VAR  f  :  File;  name  :  ARRAY  OF  CHAR)  :  Status; 

(*  opens  an  existing  file  for  reading,  returns  status  *) 
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BEGIN 

Lookup  (f ,  name,  FALSE) ; 

IF  f.res  =  done  THEN 

inP  :=  0;  read  :=  0; 

RETURN  Done; 

ELSE 

RETURN  Error; 

END; 

END  Open; 

PROCEDURE  Create  (VAR  f  :  File;  name  :  ARRAY  OF  CHAR)  :  Status; 

{*  creates  a  new  file  for  writing,  returns  status  *) 

VAR 

ch  :  CHAR; 

str  :  ARRAY  [0..3]  OF  CHAR; 
i  ;  CARDINAL; 
b  :  BOOLEAN; 

BEGIN 

LOOP 

Lookup  (f,  name,  FALSE);  (*  check  to  see  if  file  exists  *) 
IF  f.res  =  done  THEN 
Close  (f); 

(*  Filename  Clash:  Change  file  name  *) 

IF  ext  >  99  THEN  (*  out  of  new  names...  *) 

RETURN  Error; 

END; 

i  :=  0; 

WHILE  (name[i]  #  0C)  AND  (name[i]  #  '.')  DO 
INC  (i) ;  {*  scan  for  end  of  filename  *) 

END; 

name[i]  :=  name[i  +  1]  :=  'K';  name[i  +  2]  :=  0C; 

i  :=  0; 

CardToString  (ext,  1,  str,  i,  b) ; 

Append  (name,  str);  (*  append  new  extension  *) 

INC  (ext); 

ELSE 

EXIT; 

END; 

END; 

Lookup  (f,  name,  TRUE); 

IF  f.res  =  done  THEN 
outP  :=  0; 

RETURN  Done; 

ELSE 

RETURN  Error; 

END; 

END  Create; 

PROCEDURE  CloseFile  (VAR  f  :  File;  Which  :  FileType)  :  Status; 

(*  closes  a  file  after  reading  or  writing  *) 

BEGIN 

written  :=  outP; 

IF  (Which  =  Output)  AND  (outP  >  0)  THEN 
WriteNBytes  (f,  ADR  (outBuf),  outP); 
written  :=  f. count; 

END; 

Close  (f); 

IF  (written  =  outP)  AND  (f.res  =  done)  THEN 
RETURN  Done; 

ELSE 

RETURN  Error; 

END; 

END  CloseFile; 

PROCEDURE  Get  (VAR  f  :  File;  VAR  ch  :  CHAR)  :  Status; 

(*  Reads  one  character  from  the  file,  returns  status  *) 

BEGIN 

IF  inP  =  read  THEN 

ReadNBytes  (f,  ADR  (inBuf),  SIZE  (inBuf)); 
read  :=  f. count; 
inP  :=  0; 

END; 

IF  read  =  0  THEN 
RETURN  EOF; 

ELSE 

INC  (inP); 

ch  :=  inBuf [ inP ]; 

RETURN  Done; 

END; 

END  Get; 

PROCEDURE  Put  (ch  :  CHAR) ; 

(*  Writes  one  character  to  the  file  buffer  *) 

BEGIN 

INC  (outP); 
outBuf [outP]  :=  ch; 

END  Put; 

PROCEDURE  DoWrite  (VAR  f  :  File)  :  Status; 

(*  Writes  buffer  to  disk  only  if  nearly  full  *) 

BEGIN 

IF  outP  <  400  THEN  (*  still  room  in  buffer  *) 

RETURN  Done; 

ELSE 

WriteNBytes  (f,  ADR  (outBuf),  outP) ; 
written  :=  f. count; 

IF  (written  =  outP)  AND  (f.res  =  done)  THEN 
outP  :=  0; 

RETURN  Done; 

ELSE 

RETURN  Error; 

END; 

END; 

END  DoWrite; 

BEGIN  (*  module  initialization  *) 
ext  : =  0 ; 

END  Files. 


Listing  Fourteen 

DEFINITION  MODULE  KH; 
CONST 

ID  OK  -  25; 


End  Listing  Thirteen 


(continued  on  page  118) 
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Listing  Fourteen  (Listing  continued,  text  begins  on  page72.) 


PARITY  OFF 

= 

150. 

ID  NONE 

= 

152. 

ID  ODD 

= 

151. 

ID_EVEN 

= 

150, 

STOP  OFF 

= 

140. 

ID  STOP 2 

= 

142, 

ID_STOPl 

= 

141. 

DATA  OFF 

= 

130, 

ID  DATA8 

- 

138 

ID  DATA7 

= 

137, 

IDM_FILE  =  51; 

IDM_KERMIT  =  50; 

END  KH. 

End  Listing  Fourteen 


Listing  Fifteen 

IMPLEMENTATION  MODULE  KH; 
END  KH. 


#define  ID_B1200 
#define  ID_B2400 
♦define  ID_B4800 
♦define  ID_B9600 
#define  IDJ319K2 
♦define  ID_DATA7 
♦define  ID_DATA8 
♦define  ID_STOPl 
♦define  ID_STOP2 
♦define  ID_EVEN 
♦define  ID_ODD 
♦define  ID_NONE 


124 

125 

126 

127 

128 

137 

138 

141 

142 

150 

151 

152 


End  listing  Sixteen 


BAUD  OFF 

= 

120 

ID  B19K2 

= 

128 

ID  B9600 

= 

127 

ID  B4800 

= 

126 

ID  B2400 

= 

125 

ID  B1200 

= 

124 

ID  B600 

= 

123 

ID  B300 

= 

122 

ID  B150 

= 

121 

ID_B110 

= 

120 

COM  OFF 

= 

100 

ID  COM2 

= 

101 

ID_C0M1 

= 

100 

I DM  C2 

= 

24; 

I  DM  Cl 

= 

23; 

IDM  AMBER 

= 

22; 

I DM  GREEN 

= 

21; 

IDM  WHITE 

= 

20; 

IDM  COLORS 

= 

19; 

IDM  D I REND 

= 

18; 

ID  DIRPATH 

= 

17; 

ID  SENDFN 

= 

16; 

IDM  DIRPATH 

= 

15; 

IDM  SENDFN 

= 

14; 

IDM  TERMHELP 

= 

13; 

IDM  HELPMENU 

= 

12; 

IDM  ABOUT 

= 

11; 

IDM  PARITY 

= 

10; 

IDM  STOPBITS 

= 

9 

IDM  DATABITS 

= 

8 

IDM  BAUDRATE 

= 

7 

IDM  COMPORT 

= 

6 

IDM  QUIT 

= 

5 

IDM  REC 

= 

4 

IDM  SEND 

= 

3 

IDM  CONNECT 

= 

2 

IDM  DIR 

= 

1 

IDM  OPTIONS 

= 

52; 

End  Listing  Fifteen 


Listing  Sixteen 


Listing  Seventeen 

IMPLEMENTATION  MODULE  DataLink; 

FROM  ElapsedTime  IMPORT 
StartTime,  GetTime; 


(*  Sends  and  Receives  Packets  for  PCKermit  *) 


♦define 

IDM  KERMIT 

50 

FROM  Screen  IMPORT 

♦define 

IDM  FILE 

51 

ClrScr,  WriteString,  WriteLn; 

♦define 

IDM  OPTIONS 

52 

FROM  OS2DEF  IMPORT 

♦define 

IDM  HELP 

0 

HI WORD,  LOWORD; 

♦define 

IDM  DIR 

1 

FROM  PMWIN  IMPORT 

♦define 

IDM  CONNECT 

2 

MPARAM,  MPFROM2SHORT,  WinPostMsg; 

♦define 

IDM  SEND 

3 

FROM  Shell  IMPORT 

♦define 

IDM  REC 

4 

ChildFrameWindow,  comport; 

♦define 

IDM  QUIT 

5 

FROM  CommPort  IMPORT 

♦define 

IDM  COMPORT 

6 

CommStatus,  GetChar,  SendChar; 

♦define 

IDM  BAUDRATE 

7 

FROM  PAD  IMPORT 

♦define 

IDM  DATABITS 

8 

PacketType,  yourNPAD,  yourPADC, 

,  yourEOL; 

♦define 

IDM  STOPBITS 

9 

FROM  KH  IMPORT 

♦define 

IDM  PARITY 

10 

COM  OFF; 

♦define 

IDM  ABOUT 

11 

FROM  SYSTEM  IMPORT 

♦define 

IDM  HELPMENU 

12 

BYTE; 

♦define 

IDM  TERMHELP 

13 

IMPORT  ASCII; 

♦define 

IDM  SENDFN 

14 

CONST 

♦define 

IDM  DIRPATH 

15 

MAXtime  =100;  (*  hundredths 

of  a  second 

♦define 

ID  SENDFN 

16 

MAXsohtrys  =  100; 

♦define 

ID  DIRPATH 

17 

DL  BadCS  =  1; 

♦define 

IDM  DIREND 

18 

DL  NoSOH  =  2; 

♦define 

IDM  COLORS 

19 

TYPE 

♦define 

IDM  WHITE 

20 

SMALLSET  =  SET  OF  [0..7];  (* 

BYTE  *) 

♦define 

IDM  GREEN 

21 

VAR 

♦define 

IDM  AMBER 

22 

ch  :  CHAR; 

♦define 

IDM  Cl 

23 

status  :  CommStatus; 

♦define 

IDM  C2 

24 

PROCEDURE  Delay  (t  :  CARDINAL); 

♦define 

ID  OK 

25 

{*  delay  time  in  milliseconds  *) 

♦define 

ID  COM1 

100 

VAR 

♦define 

ID  COM2 

101 

tmp  :  LONGINT; 

♦define 

ID  B110 

120 

BEGIN 

♦define 

ID  B150 

121 

tmp  :=  t  DIV  10; 

♦define 

ID  B300 

122 

StartTime; 

♦define 

ID  B600 

123 

WHILE  GetTime ()  <  tmp  DO 

one  second  *) 
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END; 

END  Delay; 

PROCEDURE  ByteAnd  (a,  b  :  BYTE)  :  BYTE; 

BEGIN 

RETURN  BYTE  (SMALLSET  (a)  *  SMALLSET  (b) ) ; 

END  ByteAnd; 

PROCEDURE  Char  (c  :  INTEGER)  :  CHAR; 

(*  converts  a  number  0-95  into  a  printable  character  *) 

BEGIN 

RETURN  (CHR  (CARDINAL  (ABS  (c)  +  32))); 

END  Char; 

PROCEDURE  UnChar  (c  :  CHAR)  :  INTEGER; 

(*  converts  a  character  into  its  corresponding  number  *) 

BEGIN 

RETURN  (ABS  (INTEGER  (ORD  (c) )  -  32)); 

END  UnChar; 

PROCEDURE  FlushUART; 

(*  ensure  no  characters  left  in  UART  holding  registers  *) 

BEGIN 

Delay  (500); 

REPEAT 

status  :=  GetChar  (comport  -  COM_OFF,  ch) ; 

UNTIL  status  =  NoCharacter; 

END  FlushUART; 

PROCEDURE  SendPacket  (s  :  PacketType) ; 

(*  Adds  SOH  and  Checksum  to  packet  *) 

VAR 

i  :  CARDINAL; 
checksum  :  INTEGER; 

BEGIN 

Delay  (10);  (*  give  host  a  chance  to  catch  its  breath  *) 

FOR  i  :=  1  TO  yourNPAD  DO 

status  :=  SendChar  (comport  -  COM_OFF,  yourPADC,  FALSE); 

END; 

status  :=  SendChar  (comport  -  COM_OFF,  ASCII. soh,  FALSE); 
i  :=  1; 

checksum  :=  0; 

WHILE  s [i]  #  0C  DO 

INC  (checksum,  ORD  (s[i])); 

status  :=  SendChar  (comport  -  COM_OFF,  s[i],  FALSE); 

INC  (i); 

END; 

checksum  :=  checksum  +  (INTEGER  (BITSET  (checksum)  *  (7,  6))  DIV  64); 
checksum  :=  INTEGER  (BITSET  (checksum)  *  (5,  4,  3,  2,  1,  0 } )  ; 
status  :=  SendChar  (comport  -  COM_OFF,  Char  (checksum),  FALSE); 

IF  yourEOL  #  0C  THEN 

status  :=  SendChar  (comport  -  COM  OFF,  yourEOL,  FALSE); 

END; 

END  SendPacket; 

PROCEDURE  ReceivePacket  (VAR  r  :  PacketType)  :  BOOLEAN; 

(*  strips  SOH  and  checksum  —  returns  status:  TRUE  =  good  packet  *) 

(*  received;  FALSE  =  timed  out  waiting  for  packet  or  checksum  error  *) 

VAR 

sohtrys  :  INTEGER; 
i,  len  :  INTEGER; 
ch  :  CHAR; 
checksum  :  INTEGER; 
mycheck,  yourcheck  :  CHAR; 

BEGIN 

sohtrys  :=  MAXsohtrys; 

REPEAT 

StartTime; 

REPEAT 

status  :=  GetChar  (comport  -  COM_OFF,  ch) ; 

UNTIL  (status  =  Success)  OR  (GetTimeO  >  MAXtime); 
ch  :=  CHAR  (ByteAnd  (ch,  177C) ) ;  (*  mask  off  MSB  *) 

(*  skip  over  up  to  MAXsohtrys  padding  characters,  *) 

(*  but  allow  only  MAXsohtrys/10  timeouts  *) 

IF  status  =  Success  THEN 
DEC  (sohtrys); 

ELSE 

DEC  (sohtrys,  10); 

END; 

UNTIL  (ch  =  ASCII. soh)  OR  (sohtrys  <=  0); 

IF  ch  =  ASCI I. soh  THEN 

(*  receive  rest  of  packet  *) 

StartTime; 

REPEAT 

status  :=  GetChar  (comport  -  COM_OFF,  ch) ; 

UNTIL  (status  =  Success)  OR  (GetTimeO  >  MAXtime); 

ch  :=  CHAR  (ByteAnd  (ch,  177C) ) ; 

len  :=  UnChar  (ch); 

r [ 1 ]  :=  ch; 

checksum  :=  ORD  (ch) ; 

i  :=  2;  (*  on  to  second  character  in  packet  —  after  LEN  *) 

REPEAT 

StartTime; 

REPEAT 

status  :=  GetChar  (comport  -  COM_OFF,  ch) ; 

UNTIL  (status  =  Success)  OR  (GetTimeO  >  MAXtime); 
ch  :=  CHAR  (ByteAnd  (ch,  177C) ) ; 
r[i]  :=  ch;  INC  (i); 

INC  (checksum,  (ORD  (ch) ) ) ; 

UNTIL  (i  >  len); 

(*  get  checksum  character  *) 

StartTime; 

REPEAT 

status  :=  GetChar  (comport  -  COM_OFF,  ch) ; 

UNTIL  (status  =  Success)  OR  (GetTimeO  >  MAXtime); 
ch  :=  CHAR  (ByteAnd  (ch,  177C)); 
yourcheck  :=  ch; 
r [i]  :=  0C; 

checksum  :=  checksum  + 

(INTEGER  (BITSET  (checksum)  *  (7,  6))  DIV  64); 
checksum  :=  INTEGER  (BITSET  (checksum)  *  (5,  4,  3,  2,  1,  0 } ) ; 

mycheck  :=  Char  (checksum); 

IF  mycheck  =  yourcheck  THEN  (*  checksum  OK  *) 

RETURN  TRUE; 

ELSE  (*  ERROR!!!  *) 

WinPostMsg  (ChildFrameWindow,  WM_DL, 

MPFROM2 SHORT  (DL_BadCS,  0),  0) ; 


RETURN  FALSE; 

END; 

ELSE 

WinPostMsg  (ChildFrameWindow,  WM_DL, 

MPFROM2 SHORT  (DL_NoSOH,  0),  0) ; 
RETURN  FALSE; 

END; 

END  ReceivePacket; 

PROCEDURE  DoDLMsg  (mpl,  mp2  :  MPARAM) ; 

(*  Process  DataLink  Messages  *) 

BEGIN 

CASE  LOWORD  (mpl)  OF 
DL_BadCS : 

WriteString  ("Bad  Checksum") ;  WriteLn; 
!  DL_NoSOH : 

WriteString  ("No  SOH");  WriteLn; 

ELSE 

(*  Do  Nothing  *) 

END; 

END  DoDLMsg; 

END  DataLink. 


End  Listing  Seventeen 


Listing  Eighteen 

2238! 

finclude  <os2.h> 

22391 

finclude  "pckermit.h" 

2240 : 

2241! 

ICON  IDM_KERMIT  pckermit.ico 

22421 

2243: 

MENU  I DM  KERMIT 

2244: 

BEGIN 

22451 

SUBMENU  "“File",  I DM  FILE 

2246! 

BEGIN 

2247! 

MENUITEM  "“Directory. . . 

I DM  DIR 

2248: 

MENUITEM  "“Connect\tAC", 

I DM  CONNECT 

2249! 

MENUITEM  "“Send. . .\tAS", 

I DM  SEND 

2250! 

MENUITEM  "“Receive . . . \t AR" , 

IDM_REC 

2251! 

MENUITEM  SEPARATOR 

2252! 

MENUITEM  "E“xit\tAX" , 

I DM  QUIT 

22531 

MENUITEM  "A“bout  PCKermit... 

" ,  IDM_ABOUT 

2254! 

END 

2255! 

2256! 

SUBMENU  "“Options",  I DM  OPTIONS 

22571 

BEGIN 

22581 

MENUITEM  "“COM  port...", 

I DM  COMPORT 

22591 

MENUITEM  "“Baud  rate...", 

I DM  BAUDRATE 

2260! 

MENUITEM  "“Data  bits...", 

I DM  DATABITS 

2261 : 

MENUITEM  "“Stop  bits...", 

I DM  STOPBITS 

2262: 

MENUITEM  "“Parity  bits...", 

I DM  PARITY 

22631 

END 

( continued  on  page  120) 
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Listing  Eighteen  (Listing  continued,  text  begins  on  page  72.) 


22641 
2265! 
2266! 
22671 
22681 
22691 
2270: 
2271! 
2272! 
22731 
22741 
22751 
2276! 
22771 
2278! 
22791 
2280! 
2281 : 
2282! 
22831 
2284! 
22851 
22861 
22871 
22881 
22891 
2290! 
2291 : 
2292! 
22931 
22941 
2295! 
2296! 
2297! 
22981 
22991 
2300 : 
2301 : 
2302: 
2303: 
2304: 
2305: 
2306! 
2307: 
2308! 
2309: 
2310! 

2311 : 

2312: 
2313: 
2314: 
2315: 
2316: 
2317! 
23181 
23191 
2320 : 
2321 : 
23221 
23231 
23241 
23251 
23261 
23271 
23281 
23291 
2330! 
2331 : 
2332: 
23331 
23341 
23351 
2336! 
2337! 


SUBMENU  "'Colors",  IDM_COLORS 
BEGIN 

MENU ITEM  "'White  Mono", 
MENUITEM  "'Green  Mono", 
MENUITEM  "'Amber  Mono", 
MENUITEM  "Full  Color  ~1", 
MENUITEM  "Full  Color  ~2", 

END 

MENUITEM  "Fl-Help",  IDM_HELP, 


IDM_WHITE 
IDM_GREEN 
IDM_AMBER 
IDM_C1 
I  DM  C2 


MIS  HELP  :  MIS  BUTTONSEPARATOR 


ACCELTABLE  IDM_KERMIT 
BEGIN 

"AC",  IDM_CONNECT 
"AS",  IDM_SEND 
"AR",  IDM_REC 
"AX",  IDM_QUIT 


DLGTEMPLATE  IDM_COMPORT  LOADONCALL  MOVEABLE  DISCARDABLE 

BEGIN 

DIALOG  "",  IDM_COMPORT,  129,  91,  143,  54,  FS_NOBYTEALIGN  \ 

FS_DLGBORDER  !  WS_VISIBLE  I  WS_CLIPSIBLINGS  !  WS_SAVEBITS 

BEGIN 

CONTROL  "Select  COM  Port",  IDM_COMPORT,  10,  9,  83,  38, 
WC_STATIC,  SS_GROUPBOX  I  WS_VISIBLE 
CONTROL  "C0M1",  ID_COMl,  30,  25,  43,  10,  WC_BUTTON, 

BS_AUTORADIOBUTTON  \  WS_GROUP  \  WS_TABSTOP  I  WS_VISIBLE 
CONTROL  "COM2",  ID_COM2,  30,  15,  39,  10,  WCBUTTON, 
BS_AUTORADIOBUTTON  I  WS_TABSTOP  I  WS_VISIBLE 
CONTROL  "OK",  ID_OK,  101,  10,  38,  12,  WC_BUTTON, 

BS_PUSHBUTTON  !  BS_DEFAULT  I  WS_GROUP  I  WS_TABSTOP  I  WS_VISIBLE 

END 

END 

DLGTEMPLATE  IDM_BAUDRATE  LOADONCALL  MOVEABLE  DISCARDABLE 

BEGIN 

DIALOG  IDM_BAUDRATE,  131,  54,  142,  115,  FS_NOBYTEALIGN  ! 

FS_DLGBORDER  I  WS_VISIBLE  I  WS_CLIPSIBLINGS  I  WS_SAVEBITS 

BEGIN 

CONTROL  "Select  Baud  Rate",  IDM_BAUDRATE,  8,  6,  85,  107, 
WC_STATIC,  SS_GROUPBOX  !  WS_VISIBLE 
CONTROL  "110  Baud",  ID_B110,  20,  90,  62,  10,  WC_BUTTON, 

BS_AUTO RADIOBUTTON  !  WS_GROUP  WS_TABSTOP  \  WS_VISIBLE 
CONTROL  "150  Baud",  ID_B150,  20,  80,  57,  10,  WC_BUTTON, 
BS_AUTORADIOBUTTON  WS_TABSTOP  \  WS_VISIBLE 
CONTROL  "300  Baud",  ID_B300,  20,  70,  58,  10,  WC_BUTTON, 
BS_AUTORAD IOBUTTON  !  WS_TABSTOP  !  WS_VISIBLE 
CONTROL  "600  Baud",  ID_B600,  20,  60,  54,  10,  WC_BUTTON, 
BS_AUTORAD IOBUTTON  !  WS_TABSTOP  I  WS_VISIBLE 
CONTROL  "1200  Baud",  ID_B1200,  20,  50,  59,  10,  WC_BUTTON, 
BS_AUTORAD IOBUTTON  !  WS_TABSTOP  !  WS_VISIBLE 
CONTROL  "2400  Baud",  ID_B2400,  20,  40,  63,  10,  WC_BUTTON, 
BS_AUTORAD I OBUTTON  \  WS_TABSTOP  \  WS_VISIBLE 
CONTROL  "4800  Baud",  ID_B4800,  20,  30,  62,  10,  WC_BUTTON, 
BS_AUTORAD I OBUTTON  :  WS_TABSTOP  '  WS_VISIBLE 
CONTROL  "9600  Baud",  ID_B9600,  20,  20,  59,  10,  WC_BUTTON, 
BS_AUTORAD I OBUTTON  !  WSJTABSTOP  !  WS_VISIBLE 
CONTROL  "19,200  Baud",  ID_B19K2,  20,  10,  69,  10,  WC_BUTTON, 
BS_AUTORAD I OBUTTON  !  WSJTABSTOP  !  WS_VISIBLE 
CONTROL  "OK",  ID_OK,  100,  8,  38,  12,  WC_BUTTON,  BS_PUSHBUTTON  ! 
BS_DEFAULT  !  WS_GROUP  !  WS_TABSTOP  !  WS_VISIBLE 

END 

END 

DLGTEMPLATE  IDM_DATABITS  LOADONCALL  MOVEABLE  DISCARDABLE 

BEGIN 

DIALOG  "",  IDM_DATABITS,  137,  80,  140,  56,  FS_NOBYTEALIGN  I 
FS_DLGBORDER  I  WS_VISIBLE  !  WS_SAVEBITS 

BEGIN 

CONTROL  "Select  Data  Bits",  IDM_DATABITS,  8,  11,  80,  36, 

WC  STATIC,  SS  GROUPBOX  !  WS  VISIBLE 


23381  CONTROL  "7  Data  Bits",  ID_DATA7 ,  15,  25,  67,  10,  WC_BUTTON, 

23391  BS_AUTORAD I OBUTTON  I  WS_GROUP  I  WSJTABSTOP  I  WS_VISIBLE 

2340 1  CONTROL  "8  Data  Bits",  ID_DATA8,  15,  15,  64,  10,  WC_BUTTON, 

2341 1  BS_AUTORAD IOBUTTON  !  WS_TABSTOP  !  WS_VISIBLE 

2342:  CONTROL  "OK",  ID_OK,  96,  12,  38,  12,  WCJ3UTTON,  BS_PUSHBUTTON  ! 

23431  BS_DEFAULT  !  WS_GROUP  !  WS_TABSTOP  \  WS_VISIBLE 

23441  END 

23451  END 

23461 

23471  DLGTEMPLATE  IDM_STOPBITS  LOADONCALL  MOVEABLE  DISCARDABLE 
2348:  BEGIN 

23491  DIALOG  "",  IDM_STOPBITS,  139,  92,  140,  43,  FS_NOBYTEALIGN  ! 

2350 !  FS_DLGBORDER  !  WS_VISIBLE  !  WS_SAVEBITS 

2351 1  BEGIN 

23521  CONTROL  "Select  Stop  Bits",  IDM_STOPBITS,  9,  6,  80,  32, 

23531  WC_STATIC,  SS_GROUPBOX  !  WS_VISIBLE 

2354:  CONTROL  "1  Stop  Bit",  ID_STOPl,  20,  20,  57,  10,  WC_BUTTON, 

23551  BS_AUTORAD IOBUTTON  I  WS_GROUP  \  WS_TABSTOP  WS_VISIBLE 

23561  CONTROL  "2  Stop  Bits",  ID_STOP2,  20,  10,  60,  10,  WC_BUTTON, 

23571  BS_AUTORAD IOBUTTON  !  WS_TABSTOP  I  WS_VISIBLE 

23581  CONTROL  "OK",  ID_OK,  96,  8,  38,  12,  WC_BUTTON,  BS_PUSHBUTTON  ! 

23591  BS_DEFAULT  !  WS_GROUP  I  WS_TABSTOP  I  WS_VISIBLE 

2360 1  END 

2361 1  END 

23621 

23631  DLGTEMPLATE  IDM_PARITY  LOADONCALL  MOVEABLE  DISCARDABLE 
23641  BEGIN 

23651  DIALOG  IDM_PARITY,  138,  84,  134,  57,  FS_NOBYTEALIGN  ! 

2366:  FS_DLGBORDER  \  WS_VISIBLE  I  WS_SAVEBITS 

2367!  BEGIN 

23681  CONTROL  "Select  Parity",  IDM_PARITY,  12,  6,  64,  46,  WC_STATIC, 

2369!  SS_GROUPBOX  I  WS_VISIBLE 

2370 1  CONTROL  "Even",  ID_EVEN,  25,  30,  40,  10,  WC_BUTTON, 

2371 !  BS_AUTORAD I OBUTTON  !  WS_GROUP  !  WS_TABSTOP  !  WS_VISIBLE 

23721  CONTROL  "Odd",  ID_ODD,  25,  20,  38,  10,  WC_BUTTON, 
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2373 

BS  AUTORADIOBUTTON  I  WS  TABSTOP  1  WS  VISIBLE 

2484! 

CONTROL  "PCKermit  for  OS/2",  259,  59,  45,  82,  8,  WC  STATIC, 

2374 

CONTROL  "None",  ID  NONE,  25,  10,  40,  10,  WC  BUTTON, 

34851 

SS  TEXT  :  DT  LEFT  I  DT  TOP  !  WS  GROUP  !  WS  VISIBLE 

2375 

BS  AUTORADIOBUTTON  \  WS  TABSTOP  \  WS  VISIBLE 

2486: 

CONTROL  "OK",  260,  154,  36,  38,  12,  WC  BUTTON,  BS  PUSHBUTTON  ! 

2376 

CONTROL  "OK",  ID  OK,  88,  8,  38,  12,  WC  BUTTON,  BS  PUSHBUTTON  I 

24871 

WS  TABSTOP  :  WS  VISIBLE  \  BS  DEFAULT 

2377 

BS  DEFAULT  !  WS  GROUP  1  WS  TABSTOP  1  WS  VISIBLE 

2488: 

CONTROL  "",  ID  SENDFN,  89,  10,  98,  8,  WC  ENTRYFIELD,  ES  LEFT  ! 

2378 

END 

2489: 

ES  MARGIN  :  WS  TABSTOP  I  WS  VISIBLE 

2379 

END 

2490: 

END 

2380 

2491 : 

END 

2381 

24921 

2382 

DLGTEMPLATE  I DM  ABOUT  LOADONCALL  MOVEABLE  DISCARDABLE 

3493: 

DLGTEMPLATE  I DM  DIRPATH  LOADONCALL  MOVEABLE  DISCARDABLE 

2383 

BEGIN 

2494: 

BEGIN 

2384 

DIALOG  "",  I DM  ABOUT,  93,  74,  229,  88,  FS  NOBYTEALIGN  ! 

24951 

DIALOG  "\  I DM  DIRPATH,  83,  95,  242,  46,  FS  NOBYTEALIGN  \ 

2385 

FS  DLGBORDER  \  WS  VISIBLE  !  WS  SAVEBITS 

24961 

FS  DLGBORDER  !  WS  VISIBLE  I  WS  SAVEBITS 

2386 

BEGIN 

24971 

BEGIN 

2387 

ICON  I DM  KERMIT  -1,  12,  64,  22,  16 

2498! 

CONTROL  "Directory",  256,  7,  5,  227,  24,  WC  STATIC,  SS  GROUPBOX  ! 

2388 

CONTROL  "PCKermit  for  OS/2",  256,  67,  70,  82,  8,  WC  STATIC, 

2499: 

WS  GROUP  i  WS  VISIBLE 

2389 

SS  TEXT  I  DT  LEFT  !  DT  TOP  1  WS  GROUP  !  WS  VISIBLE 

2500: 

CONTROL  "Path:",  257,  28,  11,  26,  8,  WC  STATIC,  SS  TEXT  \ 

2390 

CONTROL  "Copyright  (c)  1990  by  Brian  R.  Anderson",  257,  27,  30,  172,  8, 

isoi : 

DT  LEFT  i  DT  TOP  I  WS  GROUP  I  WS  VISIBLE 

2391 

WC  STATIC,  SS  TEXT  !  DT  LEFT  !  DT  TOP  \  WS  GROUP  !  WS  VISIBLE 

2502: 

CONTROL  "OK",  258,  185,  31,  38,  12,  WC  BUTTON,  BS  PUSHBUTTON  I 

2392 

CONTROL  "Microcomputer  to  Mainframe  Communications",  259,  13,  50,  199,  8, 

2503: 

WS  TABSTOP  I  WS  VISIBLE  !  BS  DEFAULT 

2393 

WC  STATIC,  SS  TEXT  !  DT  LEFT  !  DT  TOP  !  WS  GROUP  !  WS  VISIBLE 

2504: 

CONTROL  ID  DIRPATH,  57,  11,  166,  8,  WC  ENTRYFIELD, 

2394 

CONTROL  "  OK  ",  258,  88,  10,  38,  12,  WC  BUTTON,  BS  PUSHBUTTON  ! 

2505: 

ES  LEFT  i  ES  AUTOSCROLL  !  ES  MARGIN  !  WS  TABSTOP  WS  VISIBLE 

2395 

BS  DEFAULT  I  WS  TABSTOP  !  WS  VISIBLE 

2506: 

END 

2396 

END 

2507: 

END 

2397 

END 

2508: 

2398 

2509: 

DLGTEMPLATE  I DM  DIREND  LOADONCALL  MOVEABLE  DISCARDABLE 

2399 

DLGTEMPLATE  I DM  HELPMENU  LOADONCALL  MOVEABLE  DISCARDABLE 

2510: 

BEGIN 

2400 

BEGIN 

2511: 

DIALOG  "",  I DM  DIREND,  149,  18,  101,  27,  FS  NOBYTEALIGN  I 

2401 

DIALOG  "",  I DM  HELPMENU,  83,  45,  224,  125,  FS  NOBYTEALIGN  \ 

(2512 : 

FS  DLGBORDER  !  WS  VISIBLE  I  WS  SAVEBITS 

2402 

FS  DLGBORDER  1  WS  VISIBLE  !  WS  CLIPSIBLINGS  1  WS  SAVEBITS 

2513: 

BEGIN 

2403 

BEGIN 

2514: 

CONTROL  "Cancel",  256,  30,  2,  38,  12,  WC  BUTTON,  BS  PUSHBUTTON  ! 

2404 

ICON  I DM  KERMIT  -1,  14,  99,  21,  16 

(2515! 

BS  DEFAULT  !  WS  TABSTOP  I  WS  VISIBLE 

2405 

CONTROL  "PCKermit  Help  Menu",  256,  64,  106,  91,  8,  WC  STATIC, 

I2516 : 

CONTROL  "Directory  Complete",  257,  9,  16,  84,  8,  WC  STATIC, 

2406 

SS  TEXT  ;  DT  LEFT  \  DT  TOP  \  WS  GROUP  1  WS  VISIBLE 

2517: 

SS  TEXT  :  DT  LEFT  I  DT  TOP  1  WS  GROUP  I  WS  VISIBLE 

2407 

CONTROL  "set  communications  Options  .  Alt,  O", 

2518: 

END 

2408 

258,  10,  80,  201,  8,  WC  STATIC,  SS  TEXT  1  DT  LEFT  1  DT  TOP  ! 

12519: 

END 

2409 

WS  GROUP  !  WS  VISIBLE 

2520 : 

2410 

CONTROL  "Connect  to  Host  .  Alt,  F;  C", 

2521: 

2411 

259,  10,  70,  204,  8,  WC  STATIC,  SS  TEXT  I  DT  LEFT  !  DT  TOP  I 

2412 

WS  GROUP  :  WS  VISIBLE 

2413 

CONTROL  "Directory  .  Alt,  F;  D", 

2414 

260,  10,  60,  207,  8,  WC  STATIC,  SS  TEXT  !  DT  LEFT  !  DT  TOP  ! 

2415 

2416 

WS  GROUP  l  WS  VISIBLE 

CONTROL  "Send  a  File  .  Alt,  F;  S", 

End  Listing  Eighteen 

2417 

261,  10,  50,  207,  8,  WC  STATIC,  SS  TEXT  !  DT  LEFT  \  DT  TOP  \ 

2418 

2419 

WS  GROUP  I  WS  VISIBLE 

CONTROL  "Receive  a  File  .  Alt,  F;  R"., 

Listing  Nineteen 

2420 

262,  10,  40,  209,  8,  WC  STATIC,  SS  TEXT  !  DT  LEFT  !  DT  TOP  ! 

2421 

WS  GROUP  I  WS  VISIBLE 

HEAPSIZE  16384 

2422 

CONTROL  "Exit  .  Alt,  F;  X", 

STACKSIZE  16384 

2423 

263,  10,  30,  205,  8,  WC  STATIC,  SS  TEXT  1  DT  LEFT  !  DT  TOP  1 

EXPORTS 

2424 

WS  GROUP  :  WS  VISIBLE 

WindowProc 

2425 

CONTROL  "OK",  264,  83,  9,  38,  12,  WC  BUTTON,  BS  PUSHBUTTON  ! 

ChildWindowProc 

2426 

WS  TABSTOP  1  WS  VISIBLE  !  BS  DEFAULT 

End  Listings 

2427 

END 

2428 

END 

2429 

2430 

DLGTEMPLATE  I DM  TERMHELP  LOADONCALL  MOVEABLE  DISCARDABLE 

2431 

BEGIN 

2432 

DIALOG  "",  I DM  TERMHELP,  81,  20,  238,  177,  FS  NOBYTEALIGN  : 

2433 

FS  DLGBORDER  I  WS  VISIBLE  \  WS  CLIPSIBLINGS  !  WS  SAVEBITS 

2434 

BEGIN 

2435 

CONTROL  "AE  =  Echo  mode",  256,  10,  160,  72,  8,  WC  STATIC, 

2436 

SS  TEXT  :  DT  LEFT  1  DT  TOP  1  WS  GROUP  I  WS  VISIBLE 

2437 

CONTROL  "AL  =  Local  echo  mode",  257,  10,  150,  97,  8,  WC  STATIC, 

2438 

SS  TEXT  ;  DT  LEFT  I  DT  TOP  1  WS  GROUP  1  WS  VISIBLE 

2439 

CONTROL  "AT  =  Terminal  Mode  (no  echo)",  258,  10,  140,  131,  8,  WC  STATIC, 

2440 

SS  TEXT  !  DT  LEFT  1  DT  TOP  1  WS  GROUP  1  WS  VISIBLE 

2441 

CONTROL  " AN  =  Newline  mode  (<cr>  — >  <crxlf>)",  259,  10,  130,  165,  8, 

2442 

WC  STATIC,  SS  TEXT  1  DT  LEFT  I  DT  TOP  !  WS  GROUP  I  WS  VISIBLE 

2443 

CONTROL  "A0  =  Newline  mode  OFF",  260,  10,  120,  109,  8,  WC  STATIC, 

2444 

SS  TEXT  I  DT  LEFT  1  DT  TOP  \  WS  GROUP  !  WS  VISIBLE 

2445 

CONTROL  "Televideo  TVI950/IBM  7171  Term.  Emul.",  261,  10,  100,  217,  8, 

2446 

WC  STATIC,  SS  TEXT  1  DT  LEFT  1  DT  TOP  I  WS  GROUP  1  WS  VISIBLE 

2447 

CONTROL  "Sh-Fl  -  Sh-F12  =  PF1  -  PF12",  262,  10,  90,  135,  8, 

2448 

WC  STATIC,  SS  TEXT  !  DT  LEFT  I  DT  TOP  I  WS  GROUP  I  WS  VISIBLE 

2449 

CONTROL  "Home  =  Clear",  263,  10,  80,  119,  8,  WC  STATIC, 

2450 

SS  TEXT  1  DT  LEFT  !  DT  TOP  !  WS  GROUP  !  WS  VISIBLE 

2451 

CONTROL  "PgDn  =  Page  Down  (as  used  in  PROFS)", 

2452 

264,  10,  70,  228,  8,  WC  STATIC,  SS  TEXT  I  DT  LEFT  !  DT  TOP  I 

2453 

WS  GROUP  :  WS  VISIBLE 

2454 

CONTROL  "PgUp  =  Page  Up  (as  used  in  PROFS)", 

2455 

265,  10,  60,  227,  8,  WC  STATIC,  SS  TEXT  :  DT  LEFT  1  DT  TOP  1 

2456 

WS  GROUP  :  WS  VISIBLE 

2457 

CONTROL  "Insert  =  Insert  (Enter  to  Clear)",  266,  10,  40,  221,  8, 

2458 

WC  STATIC,  SS  TEXT  \  DT  LEFT  1  DT  TOP  I  WS  GROUP  !  WS  VISIBLE 

2459 

CONTROL  "Delete  =  Delete",  267,  10,  30,  199,  8, 

2460 

WC  STATIC,  SS  TEXT  1  DT  LEFT  I  DT  TOP  I  WS  GROUP  1  WS  VISIBLE 

2461 

CONTROL  "Control-G  =  Reset  (rewrites  the  screen)",  268,  10,  20,  222,  8, 

2462 

WC  STATIC,  SS  TEXT  1  DT  LEFT  1  DT  TOP  !  WS  GROUP  !  WS  VISIBLE 

2463 

CONTROL  "Cursor  Keys  (i.e.,  Up,  Down,  Left,  Right)  all  work.", 

2464 

269,  10,  10,  229,  8,  WC  STATIC,  SS  TEXT  I  DT  LEFT  I  DT  TOP  I 

2465 

WS  GROUP  !  WS  VISIBLE 

2466 

CONTROL  "OK",  270,  193,  158,  38,  12,  WC  BUTTON,  BS  PUSHBUTTON  1 

2467 

BS  DEFAULT  I  WS  TABSTOP  :  WS  VISIBLE 

2468 

CONTROL  "End  =  End  (as  used  in  PROFS)",  271,  10,  50,  209,  8, 

2469 

WC  STATIC,  SS  TEXT  I  DT  LEFT  1  DT  TOP  1  WS  GROUP  I  WS  VISIBLE 

2470 

END 

2471 

END 

2472 

2473 

2474 

DLGTEMPLATE  I DM  SENDFN  LOADONCALL  MOVEABLE  DISCARDABLE 

2475 

BEGIN 

2476 

DIALOG  "",  I DM  SENDFN,  113,  90,  202,  60,  FS  NOBYTEALIGN  !  FS  DLGBORDER  \ 

2477 

WS  VISIBLE  I  WS  SAVEBITS 

2478 

BEGIN 

2479 

CONTROL  "Send  File",  256,  4,  4,  195,  24,  WC  STATIC,  SS  GROUPBOX  \ 

2480 

WS  GROUP  I  WS  VISIBLE 

2481 

CONTROL  "Enter  filename:",  257,  13,  11,  69,  8,  WC  STATIC,  SS  TEXT  I 

2482 

DT  LEFT  I  DT  TOP  1  WS  GROUP  1  WS  VISIBLE 

2483 

ICON  I DM  KERMIT  -1,  15,  38,  22,  16 
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The  Promise  of 
System  1 


At  MacWorld  Expo  in  Boston  this 
August,  System  7  was  not  to  be 
seen  on  the  exhibit  floors.  It 
wasn’t  shown  in  the  Apple  booth, 
and  third-party  developers  were  under 
an  embargo  preventing  them  from  show¬ 
ing  their  System-7-compatible  versions 
or  new  applications. 

This  was  no  great  loss,  because  the 
major  vendors  admitted  that  in  their 
first  System  7  releases  they  will  only 
be  concerned  with  compatibility  —  mak¬ 
ing  sure  their  products  run  under  Sys¬ 
tems  6  and  7.  They  will  initially  imple¬ 
ment  only  those  aspects  of  System  7 
that  come  free:  outline  fonts,  for  exam¬ 
ple.  Only  later  will  we  see  applications 
that  take  advantage  of  significant  Sys¬ 
tem  7  features,  such  as  interapplication 
communication. 

Attendees  did  get  a  look  at  System 
7,  though.  At  one  session,  Chris  Espi¬ 
nosa,  he  of  the  single-digit  Apple  em¬ 
ployee  number,  and  currently  the  mar¬ 
keting  manager  for  system  software  at 
Apple  USA,  presented  what  was  for 
most,  a  first  look  at  System  7.  Espinosa 


Michael  Swaine 


and  his  fellow  panelists  touched  on 
several  points  particularly  relevant  to 
developers  and  system  administrators; 
including  how  Apple  is  encouraging  a 
fast  move  to  System  7  of  its  whole  user 
base,  and  what  features  of  System  7 
will  support  new  categories  of  soft¬ 
ware.  I’ll  summarize  those  here,  filling 
in  some  details  that  the  panelists  glossed 
over. 


Espinosa  was  frank  about  the  Win¬ 
dows  threat,  acknowledging  that  very 
soon  there  will  be  as  many  Windows 
users  as  Macintosh  users  (and  implying 
that  soon  thereafter  there  will  be  a  lot 
more  of  the  former  than  of  the  latter). 
Apple  can’t  afford  to  fragment  its  mar¬ 
ket,  Espinosa  said;  it  must  deliver  a 
single  platform  for  all  Mac  software, 
and  a  single  package  of  fundamental 
functionality  for  all  users.  System  7  is 
supposed  to  become  essentially  the  only 
operating  system  version  for  the  Mac. 
(Although  it  won’t  go  in  the  box  with 
all  new  Macs  sold  until  late  next  year.) 
That  being  the  goal,  Apple  has  tried  to 
achieve  several  objectives  with  System 
7.  Apple  needs  to  stay  technologically 
ahead  of  the  competition  across  its 
whole  line,  and  needs  to  provide  a 
platform  for  a  new  generation  of  appli¬ 
cations,  firing  up  a  lethargic  market. 
And  since  System  7  is  the  intended 
vehicle  for  reaching  both  these  objec¬ 
tives,  Apple  needs  to  handle  the  intro¬ 
duction  of  System  7  very  well. 

Fear  of  System  Software  Upgrades 

The  handling  of  the  introduction  is  criti¬ 
cal,  because  Apple  needs  to  pick  up 
the  momentum  it  lost  when  Windows 
3  beat  System  7  out  the  door.  And  if  the 
introduction  doesn’t  encourage  people 
to  upgrade  right  away  (rather  than  wait¬ 
ing  for  7.0.1  or  7.0.2,  as  conventional 
wisdom  dictates),  the  point  at  which 
third-party  applications  arrive  that  re¬ 
ally  take  advantage  of  System  7’s  new 
features  will  be  pushed  further  off. 

“The  way  we  have  handled  system 
software  upgrades  in  the  past  has  not 


been  all  that  stellar,”  Espinosa  admit¬ 
ted.  But  he  claims  that  Apple  learned 
its  lesson  with  System  6.0.  “Our  fingers 
were  seriously  burned,”  he  told  one 
member  of  the  audience.  6.0  was  in¬ 
compatible  with  a  significant  number 
of  third-party  products  and  did  not  of¬ 
fer  enough  added  value  to  justify  the 
hassle  of  upgrading.  With  System  7,  Ap¬ 
ple  has  seeded  its  direct  sales  sites  and 
application  developers  early.  Develop¬ 
ers  will  have  had  the  product  for  nine 
months  rather  than  a  few  weeks.  The 
sales  staff  will  have  the  product  in  beta. 

Besides  having  learned  its  lesson  from 
the  6.0  release,  Apple  is  in  a  different 
position  regarding  this  release  than  has 
been  the  case  before.  Usually,  Apple 
system  software  upgrades  have  been 
tied  to  new  hardware  and  couldn’t  be 
discussed;  this  time,  Apple  can  talk  more 
freely,  and  is  doing  so. 

The  7.0  release  is  complex  enough 
to  need  more  in  the  way  of  documen¬ 
tation,  and  Apple  is  aware  of  this.  Sys¬ 
tem  7  will  be  documented  in  a  com¬ 
pletely  rewritten  system  software  man¬ 
ual,  in  a  delta  guide  listing  the  changes, 
and  in  various  quick  references  on  spe¬ 
cific  features.  It  will  go  out  to  system 
administrators  with  on-disk  documen¬ 
tation,  upgrade  tips  and  hints,  and  com¬ 
patibility  notes  directly  from  the  field. 
Perhaps  most  importantly,  Apple  is  mak¬ 
ing  every  effort  to  solve  compatibility 
problems  and  list  the  unsolved  ones 
so  that  most  software  will  run  with 
System  7.0  when  it’s  released  and  so 
that  you’ll  hear  about  software  that 
doesn’t  from  Apple  before  you  have 
to  learn  it  for  yourself. 
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The  remote-install  capability  should 
ease  the  installation  work  of  those  re¬ 
sponsible  for  more  than  one  Mac.  It 
allows  the  system  administrator  to  put 
the  installer  on  a  server  and  let  the 
users  install  the  new  system  on  their 
machines  over  the  network. 

But  a  smooth  introduction  alone 
won’t  make  everyone  upgrade.  Al¬ 
though  the  software  itself  will  be  dis- 

When  System  7  is 
released  around  the  end 
of  this  year,  the 
immediate  user  appeal 
will  be  better  type,  more 
memory,  and  more  ease 
of  use 


tributed  through  the  usual  channels  and 
perhaps  some  new  means  at  a  nominal 
cost,  upgrading  will  be  expensive  for 
some  users.  System  7  requires  a  Mac 
Plus,  SE,  SE/30,  Portable,  II,  IIx,  Ilex, 
Ilci,  or  Ilfx,  or  any  future  Mac;  a  mini¬ 
mum  of  2-Mbyte  memory;  and  a  hard 
disk  drive.  A  68030  CPU  or  a  PMMU  is 
necessary  for  virtual  memory,  but  ma¬ 
chines  without  a  68030  or  PMMU  will 
run  all  other  features  of  System  7.  Espi¬ 
nosa  says  that  the  goal  is  to  allow  the 
user  with  2  Mbyte  to  print  from  Hyper¬ 
Card  or  an  application  of  similar  size. 

Anyone  who  doesn’t  have  such  a 
system  will  have  to  buy  hardware  to 
upgrade  to  System  7,  and  that’s  a  seri¬ 
ous  consideration.  Even  more  critically, 
many  of  those  who  meet  the  minimum 
requirements  will  need  more  RAM  to 
do  serious  work,  and  Apple’s  policy 
on  RAM  pricing  has  a  history  of  being 
user-hostile.  This  will  have  to  change, 
and  Apple  will  have  to  give  users  some 
breaks  in  upgrading  to  System  7. 

This  is  tough  for  Apple;  it  represents 
a  shift  in  mindset,  and  those  of  us  who 
think  Apple  needs  to  get  a  lot  more 
competitive  in  pricing  should  continue 
to  encourage  this  transition.  The  rela¬ 
tively  generous  II-to-fx  upgrade  price 
is  encouraging,  and  the  new  low-cost 
Macs  to  be  announced  this  month 
should  be  further  evidence  that  Apple 
is  changing. 

The  other  thing  needed  to  make  peo¬ 
ple  upgrade  immediately  is  a  compel¬ 
ling  set  of  immediate  benefits.  7.0  has 
that. 
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(continued  from  page  124) 

Building  a  User  Base 

Espinosa  ran  through  a  demo,  empha¬ 
sizing  the  new  features  from  a  user 
viewpoint.  It’s  worth  examining  a  few 
of  these  immediately-available  user  fea¬ 
tures  with  this  question  in  mind:  Does 
this  feature  make  the  user  more  willing 

The  Mac  has  always 
been  a  model  of  user- 
interface  consistency, 
and  System  7  makes  the 
GUI  more  consistent 
and  more  powerful 


to  spend  the  money  and  take  the  per¬ 
ceived  risk  to  upgrade  immediately? 

Espinosa  started  by  saying  that  users 
at  Apple  often  start  using  another  per¬ 
son’s  Mac  without  realizing  they’re  work¬ 
ing  on  System  7.  At  first  this  sounds  like 
bad  news:  The  product  does  not  distin¬ 
guish  itself.  But  it’s  really  part  of  the 


best  user  feature  of  System  7:  consis¬ 
tency. 

The  Mac  has  always  been  a  model 
of  user  interface  consistency,  and  Sys¬ 
tem  7  makes  the  GUI  more  consistent 
at  the  same  time  it  is  becoming  more 
powerful. 

The  clearest  evidence  of  this  is  the 
tightening  of  the  definition  of  icon  be¬ 
havior.  Now,  more  than  ever  before, 
an  icon  is  an  icon.  When  you  double¬ 
click  on  it,  it  does  something.  As  be¬ 
fore,  applications  launch  and  contain¬ 
ers  open  when  double-clicked,  but  now 
desk  accessories  can  be  launched  by 
double-clicking,  too,  and  the  trash  acts 
like  any  other  container,  rather  than 
emptying  itself  whimsically  and  relo¬ 
cating  itself  on  the  desktop  when  you 
reboot. 

The  Apple  menu  is  now  associated 
with  a  folder  of  icons,  and  when  you 
put  an  icon  in  the  folder,  it  immediately 
becomes  available  in  the  Apple  menu. 
You  can  put  all  sorts  of  things  in  the 
menu  this  way,  including  applications 
and  AppleShare  volumes. 

The  System  file,  which  previously  gave 
an  error  message  when  double-clicked, 
now  opens  to  show  its  contents,  in¬ 
cluding  fonts.  Double-click  on  a  font 
and  you  see  an  example  of  the  font. 

(continued  on  page  129) 
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(continued  from  page  126) 

Another  improvement  in  consistency 
is  that  MultiFinder  is  always  on  under 
System  7.  It  will  always  be  possible  to 
access  the  Finder  or  other  open  appli¬ 
cations  via  the  icon  at  the  right  end  of 
the  menubar,  which  Apple  calls  a  “co¬ 
operative  multitasking  icon.”  Since  it 
presents  a  menu  of  processes,  I  offer 
Apple  the  infinitely  more  memorable 
“Process  Server.”  No  charge. 

The  balloon  help  system  is  another 
immediately-accessible  advantage  of  Sys¬ 
tem  7.  Click  on  the  help  icon  in  the 
menubar,  and  any  Finder  object  you 
point  at  displays  a  cartoon-style  word 
balloon  explaining  what  it  is  and  what 
it  does.  You  can  even  pull  down  menus 
and  inquire  about  individual  menu 
items.  Pointing  to  a  grayed  (disabled) 
menu  item  will  bring  up  a  balloon  tell¬ 
ing  that  the  item  is  grayed  because  it  is 
not  presently  available,  explaining  why 
it  is  not  available,  and  what  you  need 
to  do  to  make  it  available. 

Any  Macintosh  user  who  plays  with 
System  7  for  a  short  time  is  going  to 
walk  away  with  the  impression  that  it 
is  more  consistent,  more  coherent,  and 
more  elegant. 

Also  immediately  useful  to  the  user 
is  the  new  file  system,  built  around  the 
Alias  manager.  The  Finder  now  finds 
files.  And  users  can  use  aliases  to  cata¬ 
log  disks,  which  is  worth  the  price  of 
a  utility  alone  and  easier  than  any  such 
utility  could  possibly  be. 

Outline  fonts  will  benefit  users  im¬ 
mediately  in  one  way:  they’ll  get  single¬ 
point  font  increments  on  screen.  A  smart 
dealer  could  make  a  point  by  demon¬ 
strating  this  to  users,  since  it  distin¬ 
guishes  the  Mac  interface  from  Win¬ 
dows.  Otherwise,  the  immediate  effect 
of  outline  fonts  is  likely  to  be  negative 
unless  Apple  can  minimize  confusion 
and  incompatibility  in  the  use  of  differ¬ 
ent  font  types.  Espinosa  described  see¬ 
ing  documents  with  three  kinds  of  fonts 
(Adobe,  bitmapped,  TrueType)  mixed 
together.  Apple  is  at  least  aware  of  the 
potential  for  confusion  and  incompati¬ 
bility,  and  has  had  a  lot  of  time  to  work 
out  solutions. 

File  sharing  is  another  immediate  user 
benefit  because  it  is  user-friendly. 
FileShare  works  just  like  the  Finder: 
You  just  put  things  in  folders.  With 
FileShare,  users  can  pass  files  around, 
but  they  can  also  pass  whole  hard  disks 
around:  A  user  can  log  onto  his  or  her 
own  machine  from  somebody  else’s 
when  he  or  she  is  in  another  part  of  the 
building,  for  example. 

Espinosa  also  demonstrated  aliasing. 
“I  can  leave  my  system  running,”  he 
said,  “go  across  the  Charles  River  to 
our  Cambridge  office,  find  a  System  7 


machine  and  put  my  diskette  into  it, 
and  see  an  icon  of  my  hard  disk  back 
on  my  desk  in  Cupertino.  I  can  double¬ 
click  that  hard  disk  and  it’ll  go  out  over 
the  network,  find  the  right  zone,  find 
my  machine,  log  me  in,  ask  for  a  pass¬ 
word,  and  open  my  hard  disk.”  While 
the  actual  functionality  is  remote  login 
with  transparent  file  transfer,  it  pre¬ 
sents  itself  to  the  user  as:  “see  an  icon, 
double-click  it,  and  it  opens  up.”  The 
Macintosh  way. 

So  when  System  7  is  released  around 
the  end  of  this  year  (if  Apple  pulls  that 
off),  the  immediate  user  appeal  will 
be  better  type,  more  memory  or  appli¬ 
cations  without  more  RAM  (virtual  mem¬ 
ory),  and  more  ease  of  use. 

Building  System  7  Apps 

Ultimately,  what  will  make  System  7 
pay  off  is  the  new  applications  that 
will  be  developed  to  take  advantage 
of  its  capabilities.  All  the  nice  user  fea¬ 
tures  can  be  viewed  as  bait  to  hook  as 
large  a  user  base  as  possible  as  quickly 
as  possible  for  these  new  applications. 
As  I  see  it,  Apple  has  provided  at  least 
two  important  categories  of  support 
for  such  applications. 

The  biggest  item  is  interapplication 
communications.  System  7  has,  as  I’ve 
mentioned  here  before,  several  levels 
of  LAC,  including  live  cut-and-paste  (Ap¬ 
ple  calls  this  “Publish  and  Subscribe”), 
in  which  changes  in  the  source  are 
reflected  in  the  destination;  AppleEvents, 
a  set  of  events  that  can  be  passed  be¬ 
tween  applications  so  that  applications 
can  export  their  functionality  to  other 
applications;  and  low-level  inter-pro¬ 
cess  communications,  which  will  al¬ 
low  application  developers  to  build 
tightly  integrated  suites  of  applications. 
Apple  sees  these  capabilities  as  laying 
the  groundwork  for  a  new  generation 
of  applications:  smaller,  more  focused, 
and  with  more  opportunity  for  small 
add-on  products  that  use  the  function¬ 
ality  of  larger  applications. 

The  other  area  of  support  for  a  new 
generation  of  software  has  to  do  with 
multimedia.  The  new  support  for  sound 
is  impressive,  but  what’s  more  funda¬ 
mental  is  the  planned  support  for  time- 
sensitive  information  in  the  form  of  a 
set  of  standards.  The  umbrella  term  for 
this  effort  is  QuickTime. 

Apple  is  soliciting  developer  input 
in  the  definition  of  both  QuickTime 
and  AppleEvents.  Since  these  technolo¬ 
gies  will  help  to  define  the  shape  of  the 
next  generation  of  applications,  it  might 
be  wise  to  take  them  up  on  this. 
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Dear  Al ... 


Every  now  and  then  I  spend  time 
catching  up  on  the  letters  from 
readers.  In  recent  times  my  mail¬ 
box  has  contained  some  interest¬ 
ing  comments  on  the  contents  of  the 
column  and  the  C  language.  Being  hard- 
pressed  for  new  copy  this  month  (July) 
and  as  a  result  of  a  time-consuming 
boondoggle  trip  to  a  jazz  festival  in 
England,  I  thought  I’d  cop  out  and  let 
some  of  you  do  my  job  for  me. 

Here  then  is  the  mostly  reader-writ¬ 
ten  “C  Programming”  column  for  this 
month. 

Token  Pasting 

In  two  previous  columns  I  discussed 
the  ANSI  preprocessor  ##  token-past¬ 
ing  operator,  complaining  that  its  pur¬ 
pose  is  not  obvious.  Even  though  the 
ANSI  documentation  explains  the  be¬ 
havior  of  ##,  it  does  not  adequately 
explain  the  operator’s  reason  for  be¬ 
ing.  Several  readers  responded  with 
their  comments,  and  some  sent  code 
that  illustrates  their  use  of  the  ##  op¬ 
erator.  Because  those  readers  were  good 
enough  to  enlighten  me,  I  thought  it 
only  proper  that  I  should  pass  the  good 
news  on  to  the  rest  of  you. 

Robert  L.  White  of  Danbury,  Con¬ 
necticut  presents  an  example  from  a 
menu  interpreter:  I  use  [the  ##  opera¬ 
tor]  frequently  in  macro  definitions  to 


Al  Stevens 


simplify  the  generation  of  tables.  It  tends 
to  make  the  differences  in  tables  stand 
out  better. 

Here’s  an  example  from  a  menu  in¬ 
terpreter.  This  thing  used  tables  to  de¬ 
scribe  various  menus.  In  order  to  keep 
our  sanity,  we  developed  a  naming 
convention.  Lists  of  valid  keys  for  a 
given  menu  went  in  the  XXXJText  ar¬ 
ray,  and  lists  of  functions  went  in  the 
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XXX_Funcs  array.  The  addresses  of 
these  various  lists  were  stored  in  a  struc¬ 
ture  called  a  Menu  Descriptor. 

struct  MenuDesc 

( 

int  "keys; 

char  "Text; 

int  ("FuncsX ); 

); 

We  could  have  had  a  table  that  looked 
like  this: 

struct  MenuDesc  AllMenusl]  = 

( 

Main_Keys,  Main_Text,  Main_Funcs, 
BrainJKeys,  Brain_Text,  Brain_Funcs, 
Bone_Keys,  Bone_Text,  BoneJFuncs, 
/*  .  .  .  etc.  ...  V 


But,  using  the  following  macro,  we 
made  the  table  simpler. 

^define  MENU(name)\ 

name##_Keys,  name##_Funcs, 
struct  MenuDesc  AllMenusO  = 
f 

MENU(Main), 

MENU(Brain), 

MENU(Bone), 

/*  .  .  .  etc.  ...  V 

); 

Our  tables  were  actually  much  more 
complex  than  this,  but  this  gives  you 
an  idea  of  how  we  used  the  token¬ 
pasting  operator  to  simplify  the  source 
code.  Token-pasting  also  increases  the 
code’s  validity  by  eliminating  opportu¬ 
nities  for  misspelling. 

Mr.  White’s  application  of  the  ## 
operator  hits  home  because  his 
MenuDesc  structure  closely  resembles 
the  one  that  I  used  in  the  menu  drivers 
for  the  SMALLCOM  project  last  year. 
His  example  illustrates  one  of  the 
strengths  of  the  ##  operator  —  its  abil¬ 


ity  to  reduce  repetitious  code  and  there¬ 
fore  reduce  the  potential  for  coding 
errors. 

Fred  Smith  of  Stoneham,  Massachu¬ 
setts  sends  us  some  history:  I  have  just 
re-read  your  column  in  the  July  1990 
issue,  and  note  that  you  are  apparently 
unaware  of  the  origin  of  token  pasting 
in  C.  Don't  feel  bad,  for  that  is  cer¬ 
tainly  not  widespread  information.  It 
may  be  that  I  don ’t  have  all  the  details 
either,  but  here’s  what  I  know  about  it: 
There  is  at  least  one  preprocessor  in 
widespread  use  on  Unix  systems  (I  have 
heard  it  called  "the  Reiser  preproces¬ 
sor")  which  allows  the  use  of  an  empty 
comment  "/**/"  as  a  token-pasting  op¬ 
erator  in  preprocessor  statements.  This 
preprocessor  is  used  on  (at  least)  many 
BSD-derived  systems ,  such  as  Sun  work¬ 
stations.  Example: 

^define  pasteup(a,b)  (a/**/b) 

to  give  you  the  “Reiser"  equivalent  of 
your  example  on  page  134  of  the  July 
issue. 

This  is  a  horrible  kludge,  as  it  di¬ 
rectly  violates  what  K&R  said  about 
what  the  preprocessor  does  with  com¬ 
ments,  i.e.,  comments  are  replaced  with 
white  space.  Clearly,  at  least  in  the  case 
of  an  empty  comment,  this  preproces¬ 
sor  actually  replaces  them  with  noth¬ 
ing.  Now,  this  is  occasionally  useful, 
but  it  certainly  isn ’t  C!  (to  say  nothing 
of  being  highly  non-portable!). 

At  my  last  job  I  had  the  (mis)fortune 
to  be  involved  with  a  (very)  large  C 
program  which  was  full  of  non-port¬ 
able  Sunisms  and  BSD-isms,  includ¬ 
ing  this  one.  An  interesting  use  was 
made  of  the  token-pasting  hack,  though. 
It  was  used  to  create  a  general- purpose 
queue  (or  linked  list)  management  pack¬ 
age  implemented  entirely  in  the  pre¬ 
processor. 

There  were  at  least  a  dozen  macros 
defined  as  part  of  the  package  —  one 
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/overeating  in  the  preprocessor  the  dec¬ 
laration  of  the  data  structures  you 
wanted,  one  to  initialize  it,  one  to  add 
a  new  element,  one  to  remove  an  ele¬ 
ment,  macros  for  traversing  the  list, 
allocating  space  for  each  structure,  etc. 

One  of  the  strengths  of 
the  ##  operator  is  its 
ability  to  reduce 
repetitious  code  and 
therefore  reduce  the 
potential  for  coding 
errors 


The  following  is  a  sample  macro  which 
shows  the  (simplified)  flavor  of  these 
macros: 

^define  Q_NEXT(a,b)\ 

(Q_/’*/a  +>b.nextchild) 

so  that  if  this  were  used  in  a  program 
like  this: 

child=Q_NEXT(pending_illo_list, 

current_item); 

the  expansion  would  look  like  this: 

child=(  Q_pending_illo_list  -> 

current_item.nextchild); 

I  admit  that  this  capability  is  useful 
and  powerful.  However,  I  think  that 
this  kind  of  power  is  easily  abused  be¬ 
cause  it  makes  for  code  that  can  be 
extremely  terse  and  difficult  to  read, 
even  with  the  macro  expansions  in 
hand  (note  that  the  actual  macros  in 
the  package  I  describe  were  much  more 
complex  than  the  example  I  give  here). 
Because  of  both  the  obfuscation  factor, 
and  the  blatant  non-portability  of  to¬ 
ken  pasting  (either  the  ANSI  sort  or  the 
Reiser  sort)  I  would  think,  not  twice, 
but  more  like  twenty  times  before  per¬ 
petrating  such  code. 

Mr.  Smith  goes  further  to  reveal  that 
the  pre-ANSI  token-pasting  technique 
I  found  in  a  C++  header  file  works  with 
Microsoft  C  5.1  and  fails  with  QuickC 
2.0.  His  linked-list  example  hints  at  ways 
to  use  the  preprocessor  token-pasting 
to  build  a  primitive  form  of  parameter¬ 
ized  data  types,  an  issue  currently  be¬ 
ing  addressed  by  the  C++  community. 
Steve  Pritchard  of  Willowdale,  On¬ 


tario  uses  the  ##  token  paster  to  hide 
the  elements  of  C  syntax  and  make  the 
operative  values  more  prominent  when 
defining  a  table.  He  tells  us  his  design 
philosophies:  In  programming  I  try  to 
use  the  compiler  to  assist  me  in  making 
code  understandable  and  maintain¬ 
able.  I  know  there  are  diversities  of 
thought  as  to  whether  this  means  using 
exotic  tricks  or  just  using  the  basic  com¬ 
piler  functions.  In  the  style  of  coding  I 
use,  I  sequence  in  the  following  prior¬ 
ity: 

1.  Removal  of  multiple,  scattered  de¬ 
pendencies/references 

2.  Removal  of  redundant  information 

3.  Keeping  things  simple 

Mr.  Pritchard  sent  a  lot  of  code  with 
his  letter.  I  will  try  to  capture  the  es¬ 
sence  of  his  token-pasting  ideas  with 
this  fragment  that  uses  the  ##  operator 
to  eliminate  clutter  in  a  table  of  hexa¬ 
decimal  values. 

#define  h(n)  0x##n 

^define  tbl(a,b,c,d)  h(a),h(b),h(c), 

h(d) 

int  mytableO  = 

{ 

tbl(02,09,2a,ff), 

tbl(00,la,lb,e5) 


This  code  is  not  an  exact  extract 
from  Mr.  Pritchard’s  examples,  which 
are  in  the  context  of  a  bigger  problem, 
irrelevant  to  this  discussion.  I  took  the 
liberty  of  recasting  the  technique  into 
a  more  general  example. 

There  is  room  for  debate  about 
whether  the  elimination  of  the  Ox  nota¬ 
tion  in  the  table  initializers  adds  to 
readability  or  confusion.  By  hiding  the 
C  syntax,  you  could  mislead  the  reader 
of  the  code.  That  02  initializer  looks 
suspiciously  like  an  octal  constant.  The 
ff  looks  like  an  identifier.  Others  look 
like  syntax  errors.  The  camouflage  is 
effective  only  if  the  reader  knows  how 
the  coder  used  the  preprocessor.  But 
there  is  the  germ  of  an  idea  here.  You 
can  use  this  technique  effectively  to 
initialize  unusually  big  tables  and  thus 
make  the  code  easier  to  read  but  only 
if  you  use  eye-catching  comments  and 
place  the  macros  nearby  the  tables 
where  the  reader  can  readily  find  them. 

Probably  the  most  ambitious  of  the 
token-pasters  is  Gregory  Colvin  of  Boul¬ 
der,  Colorado  who  writes:  I  have  found 
token-pasting  invaluable  for  automati¬ 
cally  creating  the  many  declarations 
necessary  to  imitate  C++  style  objects 
in  C  code. 

We  are  using  macros  to  implement 
a  user  interface  library  that  needs  to 
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(continued  from  page  132) 
be  portable  across  all  the  popular  GUI 
systems.  Having  spent  the  last  year  work¬ 
ing  in  Object  Pascal  and  C++  on  the 
Mac,  I  didn ’t  want  to  give  up  object- 
oriented  programming.  But  my  team 
at  work  insists  on  sticking  with  C.  These 
macros  have  proven  a  reasonable  com¬ 
promise.  I  also  found  they  had  the  vir¬ 
tue  of  removing  some  of  the  mystery 
from  object-oriented  programming  by 
making  the  implementation  much  more 
apparent. 

Programmers  and 
authors  should  know 
that  thieves  have 
franchised  a 
significant  segment  of 
their  marketplace 
—  Scurvy  dogs 


Mr.  Colvin  sent  several  source  files 
that  do  what  he  requires.  The  code 
includes  definitions  of  a  base  member 
class  complete  with  common  methods. 
Then  it  implements  a  form  of  class 
inheritance  by  defining  a  CLASS  macro 
that  associates  the  inherited  members 
and  methods  of  a  child  class  to  those 
of  the  base.  The  ##  operator  pastes  the 
common  elements  of  the  various  struc¬ 
ture  names  to  that  of  the  specific  class. 
I  have  not  used  Mr.  Colvin’s  approach 
but  have  often  thought  that  such  a  tech¬ 
nique  might  be  possible.  I  have  in¬ 
cluded  the  three  source  files,  class. h, 
class. c,  and  test.c  as  Listing  One,  page 
147,  Listing  Two,  page  148,  and  Listing 
Three,  page  148  for  your  enjoyment 
and  experimentation. 

Greg  Colvin  works  at  Information 
Access  Systems  in  Englewood,  Colo¬ 
rado.  The  group  he  works  in  uses  a 
version  of  this  code  in  a  standard  user 
interface  tool  kit. 

An  Author  Responds 

I  reviewed  two  MIDI  books  by  Jim 
Conger  in  July.  He  sent  me  a  nice  thank- 
you  letter  wherein  he  corrected  my 
impression  of  his  views  of  computers 
and  people.  Here,  in  part,  is  Jim’s  re¬ 
sponse. 

Your  quotes  about  computers  and 
MIDI  threatening  musicians  are  actu¬ 
ally  from  the  preface  written  by  my 
able  technical  editor,  Mark  Gavin.  I 
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(continued  from  page  134) 
stuck  to  writing  code  and  explana¬ 
tions. 

My  own  vision  of  the  future  role  of 
computers  in  music  is  less  imaginative 
than  that  described  in  your  column.  I 
do  not  see  computers  replacing  com¬ 
posers  any  more  than  I  can  see  com¬ 
puters  replacing  authors.  Like  word  proc¬ 
essors  of  music,  MIDI  sequencers  have 
made  the  task  of  writing  much  more 
efficient  and  (to  me)  more  satisfying. 
The  authors  and  composers  remain. 

MIDI  equipment  can  replace  perform¬ 
ers,  but  with  mixed  results.  Even  my 
best  efforts  on  an  expensive  MIDI  setup 
are  far  less  expressive  than  those  on  a 
300  year  old  wooden  flute.  Synthetic 
music  seems  best  in  the  background  of 
a  film,  not  on  the  front  of  a  stage. 

My  late  father,  also  a  programmer, 
continually  encouraged  me  to  try  algo¬ 
rithmic  composition.  This  would  seem 
a  natural  for  someone  like  myself,  long 
trained  in  both  programming  and  mu¬ 
sic.  After  a  few  experiments  I  discarded 
the  sterile  outputs,  similar  to  the  non¬ 
sense  poetry  written  by  word  pattern 
analyzers.  Intellectually  interesting 
once,  but  of  no  emotional  content. 

The  limits  of  what  computers  can 
do  seem  to  result  from  the  limits  built 
into  people.  We  are  not  beings  of  logic 
but  are  beings  of  emotion.  Music  ad¬ 


dresses  our  emotions  directly  and  fails 
when  it  attempts  to  reach  us  through 
our  conscious  thoughts.  Millions  of  years 
of  patterning  lead  us  to  a  person,  talk¬ 
ing,  singing,  or  performing  with  an 
instrument.  Computers  will  have  a  diffi¬ 
cult  time  filling  this  role. 

Binding  Codes  and  Messages 

The  letter  from  Robert  White  also  in¬ 
cluded  this  gem:  I  have  what  I  think  is 
an  innovative  C  programming  tech¬ 
nique  that  I  want  to  pass  on  to  other 
programmers.  Some  of  my  fellow  pro¬ 
grammers  think  it  is  too  exotic  because 
it  uses  the  macro  preprocessor  and  enu¬ 
merated  constants  which  many  C pro¬ 
grammers  (can  you  believe  it?)  think 
are  advanced  elements  of  C  language. 
[Not  DDJ readers,  Bob.  — AS] 

The  idea  is  to  guarantee  that  sym¬ 
bolically  named  indexes  into  a  table 
always  reference  the  correct  element 
of  the  table  even  after  several  iterations 
of  the  code.  Sometimes  this  is  hard  to 
guarantee  when  several  developers  are 
working  on  the  same  project. 

The  classic  example  of  such  a  pair¬ 
ing  of  index  to  object  is  the  use  of  error 
codes  to  look  up  error  strings.  Here  is 
the  simple  way  of  doing  this. 

/* - ERRCODE.H  - —  V 

^define  SUCCESS  0 


#define  BrainError  1 

#define  BoneError  2 

/* - ERRTEXT.C  - —  7 

char  *ErrorStrings[]  = 

I 

“No  error", 

"Brain  error", 

"Bone  error" 

1; 

What  if  one  of  the  programmers  on 
the  project  has  an  old  version  of  the  list 
of  error  codes  and  doesn ’t  know  it?  He 
or  she  could  spend  a  good  portion  of 
the  day  trying  to  track  down  the  wrong 
error. 

Wouldn’t  it  be  wonderful  if  there 
was  a  way  of  specifying  the  error  code 
and  the  error  string  on  the  same  source 
code  line?  If  the  same  source  code  line 
specified  both  the  code  and  the  string 
they  would  always  be  in  sync. 

Here’s  how  to  do  it.  We  construct  a 
new  include  file  that  will  serve  double 
duty.  When  we  want  it  to  generate  the 
error  strings,  we  will  set  a  flag  for  the 
preprocessor  and  have  the  preprocessor 
spit  out  a  list  of  error  strings.  If  the  flag 
is  not  defined,  we  will  force  the  prepro¬ 
cessor  to  spit  out  a  set  of  enumerated 
constants  guaranteed  to  match  the  list 
of  error  strings. 

We  do  this  by  creating  two  defini¬ 
tions  for  a  simple  macro.  If  the  flag  is 
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defined,  the  macro  expands  to  the  first 
argument  only.  If  the  flag  is  not  de¬ 
fined,  the  macro  expands  to  the  second 
argument. 

#if  defined  MakeTheStringTable 
#define  Err(string,code)  string 
#else 

#define  Err(string,code)  code 
#endif 

The  include  file  will  contain  the follow¬ 
ing  invocations  of  this  macro: 

/* - ERRCODE.H  - —  7 

ErrC'No  Error",  SUCCESS), 

Err("Brain  Error",  BrainError), 

Err("Bone  Error",  BoneError) 

To  define  the  table  of  error  messages 
we  now  do  this: 

^define  MakeTheStringTable 
char  ‘ErrorStringsO  = 

( 

^include  "errcode.h" 

); 

To  define  the  table  of  indexes  we  do 
this: 

#undef  MakeTheStringTable 
enum  ErrorCode 
( 

^include  "errcode.h" 


There  is  no  need  to  limit  this  tech¬ 
nique  to  generating  constants  and  ta¬ 
bles.  It  is  really  an  aligning  technique 
for  any  set  of  lists.  The  most  common 
way  of  aligning  various  lists  is  to  com¬ 
bine  them  into  records  or  stmctures. 
This  way  you  only  have  one  list  and  all 
related  information  is  defined  on  one 
source  line.  However,  sometimes  this  is 
not  possible  or  desirable  and  lists  must 
be  defined  as  separate  arrays.  Through 
a  cleverly  defined  macro  inside  an  in¬ 
clude  file,  elements  of  both  lists  can  be 
defined  on  the  same  line  of  source  code. 

This  solution  is  simple  and  effective. 
It  solves  a  problem  that  I’ve  had  main¬ 
taining  error  codes  which  were  imple¬ 
mented  exactly  the  way  that  Mr.  White 
suggests. 

TopSpeed  C 

I  looked  at  TopSpeed  C  in  April,  and 
JPI  responded  with  a  letter  to  the  editor 
in  August.  I  chided  TSC  for  not  allow¬ 
ing  you  to  call  an  interrupt  function  the 
way  that  Turbo  C  and  Microsoft  C  do. 
Without  this  capability,  an  interrupt- 
driven  program  cannot  always  chain 
interrupts.  I  mentioned  this  deficiency 
to  the  president  of  JPI  in  February,  and 
he  agreed  then  that  it  needed  to  be 
addressed.  JPI  reports  in  their  letter, 


however,  that  the  _chain_intr( )  func¬ 
tion  provides  a  way  for  you  to  call  an 
interrupt  function  in  TSC.  Not  always 
enough.  If  the  documentation  is  cor¬ 
rect,  this  function  chains  —  rather  than 
calls  —  the  called  interrupt  function  to 
a  calling  interrupt  function.  This  ap¬ 
proach  has  two  deficiencies.  First,  you 
can  execute  an  interrupt  function  only 
from  within  another  interrupt  function. 
Secpnd,  the  executed  interrupt  func¬ 
tion  returns  to  the  place  from  where 
the  calling  function  was  invoked,  not 
to  the  calling  function  itself.  There  are 
many  circumstances  where  an  inter¬ 
rupt  driver  needs  to  directly  call  an 
interrupt  function  which  returns  to  the 
calling  function.  TSC  does  not  allow 
this,  and  that  restriction  renders  TSC 
useless  for  the  development  of  many 
interrupt-driven  programs. 

Avast,  Maties 

The  pirates  thrive,  and  I  jump  from  my 
mailbox  to  my  soapbox.  A  letter  from 
Kwee  S.  Phua  of  Victoria,  Australia  tells 
me  he  bought  two  of  my  C  books  and 
needs  to  get  the  source  code.  Dr.  Phua 
says  both  books  were  printed  in  Asia 
by  TP  Publications  of  Singapore.  Dr. 
Phua  found  my  name  in  DD/and  wrote 
me  here.  I  have  never  heard  of  TP 
Publications  and  neither  has  MIS  Press, 
the  publisher  of  my  books.  But  appar¬ 
ently  when  TP  builds  illegal  copies  of 
computer  books,  they  lack  the  grace 
to  include  the  diskette  order  forms.  I 
guess  they  are  too  stupid  to  bootleg  the 
diskettes  as  well.  Bob  Williams,  the 
boss  at  MIS  Press,  tells  me  the  Sin¬ 
gapore  book  stores  are  loaded  with 
pirated  copies  of  books  by  Norton,  Dun¬ 
can,  Schildt,  and  other  notable  authors. 
I  shall  not  feel  left  out  now,  being  in 
such  prominent  company.  But  Bob  also 
says  that  nothing  can  be  done  about  it. 
Programmers  and  authors  should  know 
that  thieves  have  franchised  a  signifi¬ 
cant  segment  of  their  marketplace  — 
Scurvy  dogs. 

Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
online.  To  order  the  disk,  send  $14.95 
(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  M&T’s  Telepath  online  service 
(via  TYMNET)  and  through  the  DDJ  Fo¬ 
rum  on  CompuServe  (type  GO  DDJ). 

DDJ 

(Listings  begin  on  page  147.) 
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Sex  and 
Algorithms 


Regardless  of  obvious  empirical  evi¬ 
dence  as  close  as  any  mirror,  the 
fact  that  our  parents  had  sex  often 
astonishes  us.  Sex  is  something 
we  invented,  after  all  —  nothing  so  dan¬ 
gerous,  messy,  or  purely  delightful  could 
be  more  than  a  few  years  old. 

(And  the  circle  is  unbroken.  All  over 
America,  balding  and  crow-footed  ex¬ 
hippies  are  trying  earnestly  to  explain 
human  reproduction  to  their  nearly- 
pubescent  children,  who  then  can  only 
exclaim,  “You  mean  you  and  Daddy 
did  thaf?\?\  Eeeeee-yukkh!”) 

I  realized  recently  that  I  had  been 
guilty  of  a  similar  sort  of  chauvinism 
when  I  made  use  of  a  day-of-the-week 
function  someone  had  given  me  in  Pas- 
cal/MT+  for  CP/M-80  almost  ten  years 
back.  The  algorithm  involved  was  called 
“Zeller’s  Congruence,”  and  was  as  to¬ 
tally  opaque  to  me  as  the  window  of  a 
Congressman’s  limo.  Regular  readers 
of  this  column  might  remember  a  note 
tucked  into  the  comments  of  my  “when 
stamp”  object  presented  in  the  April 
1990  installment: 

“Note  that  this  particular  algorithm 
turns  into  a  pumpkin  in  2000.  BTW, 
don’t  ask  me  to  explain  how  this  crazy 
thing  works.  I  haven’t  the  foggiest  no¬ 
tion.  If  I  ever  meet  Mr.  Zeller,  I’ll  ask 
him.” 

I  was  not  being  facetious.  I  pictured 
Zeller  as  a  distinguished  grey-bearded 
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researcher  in  the  CS  department  at  MIT, 
Yale,  or  some  other  exalted  institution 
of  higher  learning,  with  a  Unix  termi¬ 
nal  on  his  desk,  and  lifetime  tenure.  I 
figured  I  might  in  fact  meet  him  at  a 
conference  or  seminar,  and  I  really  did 
intend  to  ask  him  how  his  crazy  soft¬ 
ware  gizmo  pulled  dates  out  of  the  air. 

Sadly,  I  won’t  get  the  chance.  Herr 
Zeller  has  been  dead  for  almost  a  hun¬ 


dred  years.  On  learning  that,  my  first 
thought  was,  “Cripes!  He  didn’t  even 
have  a  computer!  How  could  he  possi¬ 
bly  have  come  up  with  an  algorithm?” 

You  mean  people  were  doing  algo¬ 
rithms  in  1887?  Eeeee-yukkh! 

Back  to  the  Source 

They  were  indeed.  And  just  as  we  used 
to  make  numbers  in  the  pre-calculator 
era  by  rubbing  two  sticks  together,  peo¬ 
ple  managed  some  amazing  mathemati¬ 
cal  feats  in  times  past  with  nothing 
more  than  pencil,  paper,  and  persis¬ 
tence.  Zeller  was  one,  and  at  least  one 
of  his  numerical  recipes  has  come  to 
dominate  its  niche  in  the  software  eco- 
sphere. 

There  are  some  problems.  Several 
mutant  versions  of  Zeller’s  Congruence 
are  kicking  around.  All  are  utterly 
opaque,  and  some  of  them  work  better 
than  others.  This  bothered  me,  since 
my  own  copy  ceased  to  work  correctly 
as  of  January  1,  2000.  Because  I  didn’t 
know  how  it  worked,  I  couldn’t  even 
begin  to  try  to  fix  it. 

I  would  have  left  it  at  that,  but  for  the 
help  of  my  friend  Hugh  Kenner,  who 
did  what  any  good  researcher  would 
do  and  went  right  to  the  source.  The 
source  was  a  paper  published  in  Ger¬ 
man  by  Zeller  in  “Acta  Mathematica” 
#7,  Stockholm,  1887.  Hugh  translated 
the  essence  of  the  very  brief  paper  for 
me,  and  I  implemented  it  in  both  Pas¬ 
cal  and  Modula-2. 

The  Expression  from  Hell 

I  find  it  a  little  strange  that  the  current 
versions  of  Zeller  that  I  have  seen  differ 
so  thoroughly  from  the  original  recipe. 
Most  versions  you  see  today  revolve 
around  a  very  strange  expression  ripe 
with  floating-point  values: 

Trunc(Int(2.6  *  Month  -  0.2)) 

Not  only  does  this  seem  utterly  arbi¬ 


trary,  I  don’t  trust  it.  I  distrust  integer- 
output  algorithms  that  use  floating¬ 
point  constants  like  this  internally,  be¬ 
cause  differences  in  the  way  compilers 
and  computers  handle  floating-point 
values  can  easily  cause  the  output  to 
be  off  by  one. 

And  most  remarkably,  Zeller  used 
no  such  floating-point  constants  in  his 
paper.  As  simply  as  I  can  put  it,  Zeller 
laid  out  the  algorithm  like  this: 

Given: 

J  =  Century  (e.g.  19) 

K  =  Year  (e.g.  90) 
q  =  Day  of  the  month 
m  =  Month,  but  with  a  twist:  March 
is  still  month  #3,  but  January  and  Febru¬ 
ary  are  considered  months  #13  and 
#14,  but  of  the  previous  year.  In  other 
words,  if  you’re  going  to  calculate  a 
day  of  the  week  value  for  a  date  in 
January  of  1990,  you  must  call  the  month 
#13  and  the  year  89- 
Assuming  the  Gregorian  calendar,  we 
evaluate  the  expression  in  Example  1. 
We  then  divide  the  value  of  the  expres¬ 
sion  by  7  and  use  the  remainder  as  the 
index  of  the  day  of  the  week,  with  1  = 
Sunday  and  2  =  Monday,  and  so  on. 

No  floating-point  constants.  Now 
while  it’s  true  that  division  introduces 
remainders  into  the  calculation  such 
that  it’s  not  truly  an  integer  operation, 
Zeller  himself  (in  the  example  he  used 
to  illustrate  his  algorithm)  simply  took 
the  dividend  in  each  term  and  ignored 
the  remainder.  This  is  the  equivalent  of 
using  the  DIV  operator  in  Pascal  and 
Modula-2.  Look,  Ma,  no  real  numbers! 

Almost  Comprehensible 

What  I’ve  shown  you  is  how  it’s  done. 
Zeller  says  very  little  in  his  paper  about 
how  it  works.  In  broad  terms,  the  algo¬ 
rithm  describes  how  the  day  of  the 
week  advances.  Most  people  realize 
that  for  every  year,  the  day  of  the  week 
for  a  given  day  generally  advances  by 
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1;  that  is,  June  29  is  on  a  Friday  in  1990, 
but  it  will  be  on  a  Saturday  in  1991. 
Other  things,  however,  can  alter  this 
advance  of  the  day  of  the  week.  In 
1992,  June  29  will  be  on  a  Monday 
rather  than  the  expected  Sunday  — 
because  1992  is  a  leap  year,  and  the 
extra  day  in  February  pushes  things 
ahead  by  one  additional  day. 

So  it’s  easy  to  understand  the  K  term, 
since  for  every  year  the  day  of  the 
week  advances  by  one.  Ditto  the  K/4 
term,  which  tosses  in  an  extra  day  ev¬ 
ery  four  years,  and  the  J/4  term,  which 
tosses  in  an  extra  day  every  four  hun¬ 
dred  years,  when  the  “century  year” 
leap  year  that  is  ordinarily  skipped  is 
instead  observed.  (1700, 1800,  and  1900 
were  not  leap  years;  however,  1600 
and  2000  are.)  The  day  of  the  month 
term  q  advances  the  value  from  the 
start  of  the  month. 


The  peculiar  term  (m+l)*26/10  ad¬ 
vances  the  count  to  the  start  of  the 
given  month.  The  term  (which  is  in 
fact  the  single  most  right-brainedly  bril¬ 
liant  part  of  the  whole  shebang)  com¬ 
pensates  for  the  fact  that  the  months 
have  different  numbers  of  days  in  them. 
The  twist  in  the  month  numbering  (that 
part  about  making  January  and  Febru¬ 
ary  months  13  and  14  instead  of  1  and 
2)  serves  the  Expression  from  Hell  by 
putting  the  most  pathological  month 
of  all  (February)  at  the  end  of  every¬ 
thing.  This  allows  the  oscillations  of 
the  leap  years  to  be  accounted  for  else¬ 
where  in  the  expression,  since  the 
(m+l)*26/10  term  only  takes  you  to  the 
beginning  of  a  given  month.  Variations 
in  the  length  of  February  thus  stay  out 
of  the  (m+l)*26/10  term. 

The  one  part  of  the  calculation  that 
I  truly  don’t  understand  is  the  subtrac¬ 


tion  of  the  2*J  term.  It’s  there.  The  algo¬ 
rithm  doesn’t  work  without  it.  So  be  it. 

Pumpkin  Problems 

My  own  from-the-source  implementa¬ 
tion  of  Zeller  is  contained  in  the  func¬ 
tion  CalcDayOfWeek  in  Listing  One 
(page  149,  which  is  little  more  than  a 
frame  allowing  you  to  enter  different 
dates  to  try  it  out.  I  encourage  you  to 
try  to  break  it,  and  let  me  know  if  it 
breaks.  So  far  it  has  worked  for  every 
date  I’ve  tried  (comparing  the  produced 
day-of-the-week  value  against  that 
shown  in  the  Sidekick  calendar). 

Notice  that  I  have  implemented  the 
calculation  in  a  leisurely  fashion,  accu¬ 
mulating  the  sum  in  the  intermediate 
variable  Holder  rather  than  rolling  it  all 
up  again  into  something  big  and  mathe- 

The  roach  in  the 
Riesling  has  always 
been  that  development 
for  Windows  is 
needlessly  difficult 


(m  +  1)  *  26 

K  J 

q  + 

+  K  + - + - -  2* J 

10 

4  4 

Example  1:  Evaluating  the  expression  for  the  Gregorian  calendar. 


matical-looking.  My  purpose  is  to  make 
the  workings  clearer,  and  because  you 
wouldn’t  ever  need  to  call  this  thing 
from  inside  a  tight  loop,  the  lack  of 
performance  shouldn’t  get  in  the  way. 
Feel  free  to  pass  it  through  your  own 
code-compactors  if  you  like. 

There  was  one  infuriating  detail  left 
unmentioned  by  Zeller  in  his  paper. 
For  certain  dates  (mostly  in  March  early 
in  a  given  century)  the  result  of  the  full 
expression  comes  out  negative,  because 
the  2*J  term  is  greater  than  everything 
else  taken  together.  For  every  date  in 
which  the  expression  went  negative, 
the  day  of  the  week  value  was  off  by 
one.  This  was  actually  the  reason  my 
inherited  implementation  of  Zeller  turns 
into  a  pumpkin  in  the  year  2000. 

This  sounded  oddly  familiar.  I  went 
back  to  my  files  and  found  a  nice  letter 
from  Carl  E.  Ohlen  of  Corvallis,  Ore¬ 
gon,  pointing  this  out  in  the  wake  of  my 
April  column.  Carl  suggested  that  when 
the  expression  went  negative  I  should 
add  7  to  the  expression  until  it  became 
positive,  and  only  then  use  the  MOD  7 
operation  on  it.  I  tried  it.  It  works. 

Zeller  says  nothing  about  such  cases, 
but  he  was  a  mathematician  and  must 
have  been  aware  of  them.  If  anyone 
can  explain  this  lapse,  I’d  like  to  hear  it. 


140 


Dr.  Dobb’s  Journal,  October  1990 

965 


TopSpeed  Modula-2  Objects 

The  Modula-2  implementation  of  Zeller’s 
Congruence  is  embedded  in  Listing 
Three,  page  149,  which  is  my  when 
stamp  object  implemented  in  Version 
2.0  of  TopSpeed  Modula-2. 

Objects  are  a  natural  in  Modula-2. 
They  are  a  natural  refinement  of  the 
inherent  modularity  of  the  language, 
which  has  always  bundled  code  and 
data  together  at  the  logistical  level  by 
placing  them  together  in  modules.  A 
Modula-2  object  is  rather  like  a  module 
turned  into  a  data  structure,  with  the 
addition  of  inheritance  and  late  bind¬ 
ing.  At  least  that’s  a  good  place  to  start 
thinking  of  it  if  you  have  been  on  the 
sidelines  watching  Turbo  Pascal  give 
birth  to  objects  in  the  structured  pro¬ 
gramming  world. 

JPI  has  done  an  extremely  good  job 
implementing  objects  in  Modula-2.  What 
they  have  done  is  very  close  to  the 
Turbo  Pascal  5.5  object  extensions  in 
many  ways.  A  good  place  to  start  is 
with  Listing  Two,  page  149,  which  is 
the  definition  module  for  the  module 
implementing  the  when  stamp.  The  defi¬ 
nition  of  type  When  is  nearly  identical 
to  the  definition  of  When  in  Turbo 
Pascal.  The  main  difference  is  the  use 
of  the  CLASS  reserved  word  rather  than 
the  OBJECT  reserved  word.  TopSpeed 
Modula-2  calls  object  types  classes  rather 
than  object  types,  falling  into  line  with 
Smalltalk,  Actor,  and  C++.  While  I 
thought  that  the  “object  type”  coinage 
was  a  good  idea  at  first,  I’ve  reversed 
myself.  Object  types  are  classes.  We 
should  probably  call  them  classes  across 
the  board.  Calling  an  object  type  a  class 
reduces  the  inevitable  confusion  be¬ 
tween  an  object  type  and  an  object 
instance. 

Where  TopSpeed  differs  most  from 
Turbo  Pascal  is  in  the  implementation 
syntax.  Turbo  Pascal  5.5  uses  a  quali¬ 
fier  in  the  method  header  to  indicate 
connection  with  a  particular  object  defi¬ 
nition: 

PROCEDURE  When.PutNow; 

TopSpeed  Modula-2  simply  enlarges 
the  headers-only  class  definition  given 
in  the  definition  module  to  include  the 
bodies  of  the  methods.  Everything  is 
bracketed  between  the  two  ends  of  the 
definition  (see  Example  2).  There  is 
no  qualifier  on  the  method  header.  Be¬ 
cause  the  method  is  fully  implemented 
between  When  =  CLASS  and  END,  the 
compiler  always  knows  to  which  class 
a  method  implementation  belongs. 

In  a  reflection  of  Modula-2’s  module 
structure,  class  definitions  minus  method 
bodies  are  usually  placed  in  definition 
modules,  whereas  full  class  implemen¬ 


tations  are  placed  in  implementation  Modula-2  objects  follow  Turbo  Pascal 
modules.  nearly  to  the  letter.  There  is  a  hidden 

At’/. /-'parameter  passed  implicitly  to  ev- 
Inheritance  and  Virtual  Methods  ery  method  call,  providing  a  connec- 

Most  of  the  other  details  of  TopSpeed  tion  within  a  method  definition  to  the 


TYPE  When  = 

CLASS 

(*  All  data  field  defintions 

*i 

(*  are  fully  re-stated  here. 

*i 

(*  The  full  method  imple- 

(*  mentations,  including 

*> 

(*  bodies,  are  given  here. 

END; 

Example  2:  The  two  ends  of  definitions  are  bracketed. 
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particular  object  instance  from  which 
the  method  call  was  made. 

Inheritance  is  handled  identically  to 
Turbo  Pascal,  in  that  the  name  of  the 
parent  class  is  given  in  parentheses  at 
the  top  of  the  child  class  definition: 

TYPE 

KidGadget  = 

CLASS(ParentGadget); 

Late  binding  is  handled  through  a  new 
reserved  word,  VIRTUAL.  Again,  just 
as  in  Turbo  Pascal,  a  method  is  made 
virtual  by  following  the  definition  of  its 
procedure  header  with  VIRTUAL. 

PROCEDURE  Edit(  );  VIRTUAL; 

Calls  to  virtual  methods  are  handled 
through  a  virtual  method  table,  which 
is  a  table  of  code  addresses  for  all 
virtual  methods  belonging  to  an  object 
class.  There  is  one  virtual  method  table 
for  each  class  definition.  Each  object 
instance  contains  a  pointer  to  the  vir¬ 
tual  method  table  belonging  to  its  class. 
This  pointer  is  not  ordinarily  visible, 
and  in  general  it  never  needs  to  be 
referenced.  However,  a  new  standard 
function  MTA( )  returns  the  address  of 
the  virtual  method  table  if  you  ever 
need  to  find  it. 

In  one  important  departure  from  the 
Turbo  Pascal  scheme,  TopSpeed  Modu¬ 
la-2  does  not  implement  constructors 
or  destructors. 

No  Privacy 

As  with  Turbo  Pascal,  there  is  no  ability 
to  implement  a  “private”  data  field  or 
method  in  the  implementation  of  the 
class,  if  that  field  or  method  was  not 
originally  defined  in  the  definition  of 
the  class. 

This  is  unfortunate.  Every  object 
should  be  allowed  to  have  some  ma¬ 
chinery  that  it  keeps  to  itself,  and  that 
machinery  should  nonetheless  be  able 
to  access  all  other  fields  and  methods 
belonging  to  that  class.  C++  offers 
classes  that  ability,  and  sooner  or  later 
such  things  will  have  to  be  added  to 


Pascal  and  Modula-2  to  keep  pace. 

Nor  does  TopSpeed  Modula-2  im¬ 
plement  the  multiple  inheritance  fea¬ 
ture  that  TopSpeed  Pascal  will  contain 
when  released.  JPI  is  hinting  that  multi¬ 
ple  inheritance  will  be  migrated  to  their 
Modula-2  in  a  future  release,  once  their 
new  Pascal  compiler  proves  out  the 
technology. 

Listings  Two  and  Three  will  provide 
you  with  a  detailed  look  at  the  syntac¬ 
tic  conventions  surrounding  object  defi¬ 
nition  and  encapsulation.  The  code  is 
a  straight-line  translation  of  the  Turbo 
Pascal  when  stamp.  The  only  proce¬ 
dure  that  has  been  seriously  reworked 
is  CalcDayOfWeek ,  which  I  rewrote 
from  scratch  in  Modula-2  as  well  as  in 
Pascal,  according  to  Zeller’s  original 
published  algorithm. 

I  haven’t  had  time  to  really  probe  the 
limits  of  TopSpeed’s  OOP  extensions 
just  yet;  in  particular,  I  have  some  ques¬ 
tions  involving  the  creation  and  deallo¬ 
cation  of  objects  on  the  heap.  You'll 
get  the  full  report  as  I  figure  things  out. 

In  general,  I  strongly  recommend  up¬ 
grading  to  TopSpeed  Modula-2  V2.0  if 
you  are  already  a  user.  Just  about  all 
aspects  of  the  product  have  been  greatly 
improved.  The  documentation  is  much 
improved,  with  the  lone  exception  of 
the  section  on  the  OOP  extensions, 
which  should  have  been  much  larger 
and  more  detailed.  On  the  other  hand, 
if  you’ve  experimented  with  Turbo  Pas¬ 
cal  objects,  the  JPI  system  will  feel  pretty 
familiar  and  won’t  take  a  great  deal  of 
additional  study. 

Jumping  through  Windows,  Take  3 

Since  last  column  a  pallet  load  of  new 
software  has  made  its  way  to  Cactus 
Country,  some  of  it  remarkable  indeed. 
Certainly  the  most  important  for  the 
long  haul  is  Windows  3  0.  I’ve  been  a 
Windows  user  since  well  before  Win¬ 
dows  1.0  was  shipping,  back  during 
my  tenure  at  PC  Tech  Journal.  Between 
the  product’s  own  gradual  improve¬ 
ment  and  the  relentless  RAMcharging 
of  our  own  machines,  Windows  has 
become  a  viable  operating  platform,  far 
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The  Whitewater  Group 

206-462-0501 
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quicker  than  any  Mac  system  of  com¬ 
parable  price,  and  better-looking  too. 

The  roach  in  the  Riesling  has  always 
been  that  development  for  Windows 
is  hideously  and  needlessly  difficult  if 
you’re  using  Microsoft’s  SDK.  I’ve  stated 
before  that  Actor  is  the  only  reasonable 
way  to  develop  for  Windows,  but  that's 
becoming  less  and  less  the  case. 

One  promising  alternative  is  Asymet¬ 
rix’s  ToolBook,  a  new  development 
system  featuring  a  brand-new  language 
and  a  potent  suite  of  resource  editing 
tools.  The  language  reminds  me  a  little 
of  a  fully  structured  and  object-oriented 
Cobol  (don’t  sneer ...  10  billion  lines 
of  code  can’t  all  be  wrong  .  .  .  )  and  a 
little  bit  of  the  database  language  Clar¬ 
ion,  and  that  may  turn  out  to  be  a  fine 
thing  indeed. 

As  with  Clarion,  you  can  approach 
ToolBook  development  from  two  di¬ 
rections:  From  the  high  end,  by  using 
the  platform’s  prototyping  tools  to  build 
screens  and  menu  structures  interac¬ 
tively,  while  writing  as  little  code  as 
possible,  or  from  the  low  end,  by  es¬ 
chewing  the  tools  and  going  for  the 
throat  with  the  programming  language 
from  the  very  start. 

One  thing  is  for  sure:  You  can  build 
a  simple  app  in  ToolBook  in  almost 
no  time  at  all,  once  you’ve  spent  an 


evening  getting  familiar  with  the  envi¬ 
ronment.  The  system  makes  excellent 
use  of  Windows,  and  (in  fact)  all  cop¬ 
ies  of  Windows  3.0  are  being  shipped 
with  DayBook,  an  app  written  in  Tool¬ 
Book.  A  look  at  DayBook  will  give  you 
an  excellent  feel  for  what  ToolBook 
can  do. 

The  downside  is  that  (for  now,  at 
least)  ToolBook  is  agonizingly  slow.  It 
thrashes  the  disk  constantly  for  reasons 
unclear;  perhaps  loading  DLLs,  perhaps 
virtualizing  something  that  I  might  be 
able  to  keep  in  memory  if  I  had  more 
than  my  current  4  Mbytes.  I  don’t  know 
just  yet,  but  if  you’ve  landed  a  copy  of 
ToolBook  be  prepared  to  grit  your  teeth 
a  little,  and  for  heaven’s  sake  have  a 
fast  386  with  as  much  RAM  as  you  can 
afford. 

Actor  3  0  showed  up  a  few  days  ago, 
with  full  support  for  Windows  3  0.  A 
description  will  have  to  wait  until  a 
future  column,  but  it  looks  a  little  faster 
and  has  some  interesting  new  features. 
Sadly,  it’s  significantly  more  expensive 
now,  and  no  low-end  version  is  in  sight. 
Still,  for  my  money,  Actor  remains  the 
way  to  go  for  Windows  3  0  develop¬ 
ment. 

Other  Windows  3.0  tools  have  shown 
up,  but  most  are  C-specific  and  will 
have  to  wait  on  Al  Stevens.  (Then  there’s 


Turbo  C++  from  Borland  —  fine  piece 
of  work!)  Announced  but  not  yet  ship¬ 
ping  are  a  Windows  3-0  version  of  Small¬ 
talk-80  from  ParcPlace  Systems,  and 
Knowledge  Pro  Windows,  which  is  dif¬ 
ficult  to  describe  and  could  be  the 
guldurndest  thing  to  turn  up  this  year, 
judging  from  the  promotional  literature 
Knowledge  Pro  honcho  John  Slade  sent 
me  recently.  More  on  both  when  I  get 
my  hands  on  them  —  but  it  looks  very 
much  like  the  developer  community 
has  decided  that  for  Windows,  the  third 
time  is  the  charm. 

A  Hundred  and  WHAT? 

No,  you  don’t  want  to  know.  Summer 
has  come  to  Phoenix.  Whereas  out  in 
Chicago  every  June  they  run  pictures 
in  the  paper  of  reporters  frying  eggs 
on  the  sidewalk,  out  here  they  don’t 
do  that  because  the  eggs  catch  fire  and 
the  neighbors  complain  about  the  stink. 
And  as  I  write  it  is  —  I  would  not  kid 
you  about  this  —  122  degrees. 

Now  just  wait,  people  say,  until  July! 

DDJ 
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PAMUM/LETS  BOOKSHELF 


The  Theory  and 
Practice  of  Computer 
Design  and 
Implementation 


John  L.  Hennessy  and  David  A.  Pat¬ 
terson’s  new  book,  Computer  Ar¬ 
chitecture:  A  Quantitative  Approach, 
is  a  uniquely  lucid  and  accessible 
presentation  of  the  theory  and  prac¬ 
tice  of  computer  design  and  implementa¬ 
tion.  First,  the  authors  explain  basic 
principles  of  computer  performance 
measurement  and  cost/benefit  analy¬ 
sis.  They  then  apply  these  principles 
to  instruction-set  design,  processor  im¬ 
plementation,  pipelining,  vectorization, 
memory-hierarchy  design,  and  input 
and  output.  Each  chapter  contains  real- 
life  examples  drawn  from  four  com¬ 
puter  architectures  —  the  IBM  360/370, 
the  DEC  VAX,  the  Intel  8086,  and  the 
“DLX”  (a  sort  of  hypothetical  compos¬ 
ite  of  the  currently  popular  RISC  ma¬ 
chines)  —  and  each  chapter  concludes 
with  three  entertaining  sections  entitled 
“Putting  It  All  Together, ’’“Fallacies  and 
Pitfalls,”  and  “Historical  Perspective.” 

It’s  almost  impossible  to  convey  the 
authority,  scope,  and  vigor  of  this  book 
in  a  brief  review.  The  book  is  highly 


Ray  Duncan 


technical,  of  course;  nevertheless,  it’s 
as  engrossing  as  a  novel  because  of  the 
incredible  depth  and  breadth  of  the 
authors’  knowledge  and  experience. 
It’s  literally  packed  with  fascinating  ar¬ 
chitectural  vignettes,  on  topics  as  di¬ 
verse  as  the  use  and  misuse  of  bench¬ 
marks,  interrupts,  microcode,  silicon 
die  yields,  cache  strategies  and  trade¬ 
offs,  and  the  IBM  3990  I/O  subsystem. 


Computer  Architecture: 
A  Quantitative 
Approach 

John  L.  Hennessy  and 
David  A.  Patterson, 

San  Mateo,  Calif.:  Morgan  Kaufmann 
Publishers  Inc.,  1990 
784  pages,  hardcover,  $54.95 
ISBN  1-55860-069-8 


In  addition,  virtually  every  point  in  the 
book  is  supported  and  clarified  by  his¬ 
torical  anecdotes  which  reveal  how  the 
important  features  of  modern  computer 
architectures  were  invented  and  refined. 
For  example: 

IBM  brought  microprogramming  into  the 
spotlight  in  1964  with  the  IBM  360  fam¬ 
ily.  Before  this  event,  IBM  saw  itself  as 
many  small  businesses  selling  different 
machines  with  their  own  price  and  per¬ 
formance  levels,  but  also  with  their  own 
instruction  sets.  (Recall  that  little  pro¬ 
gramming  was  done  in  high-level  lan¬ 
guages,  so  that  programs  written  for  one 
IBM  machine  would  not  run  on  another.) 
Gene  Amdahl,  one  of  the  chief  archi¬ 
tects  of  the  IBM  360,  said  that  managers 
of  each  subsidiary  agreed  to  the  360 
family  of  computers  only  because  they 
were  convinced  that  microcoding  made 
it  feasible  —  if  you  could  take  the  same 
hardware  and  microprogram  it  with  sev¬ 
eral  different  instruction  sets,  they  rea¬ 
soned,  then  you  must  also  be  able  to 
take  different  hardware  and  micropro¬ 
gram  them  to  run  the  same  instruction 
set.  To  be  sure  of  the  viability  of  micro¬ 


programming,  the  IBM  vice  president 
of  engineering  even  visited  Wilkes  [who 
built  the  first  microprogrammed  CPU  in 
1958]  surreptitiously  and  had  a  “theoreti¬ 
cal”  discussion  of  the  pros  and  cons  of 
microcode.  IBM  believed  the  idea  was 
so  important  to  their  plans  that  they 
pushed  the  memory  technology  inside 
the  company  to  make  microprogram¬ 
ming  feasible. 

Stewart  Tucker  of  IBM  was  saddled 
with  the  responsibility  of  porting  soft¬ 
ware  from  the  IBM  7090  to  the  new  IBM 
360.  Thinking  about  the  possibilities  of 
microcode,  he  suggested  expanding  the 
control  store  to  include  simulators,  or 
interpreters,  for  older  machines.  Tucker 
coined  the  term  emulation  for  this,  mean¬ 
ing  full  simulation  at  the  microprogram¬ 
med  level.  Occasionally,  emulation  on 
the  360  was  actually  faster  than  the  origi¬ 
nal  hardware.  Emulation  became  so  popu¬ 
lar  with  customers  in  the  early  years  of 
the  360  that  it  was  sometimes  hard  to 
tell  which  instruction  set  ran  more  pro¬ 
grams. 

In  spite  of  such  diversions,  the  book 
is  so  well-organized,  and  the  material 
is  developed  so  logically,  that  each  con¬ 
clusion  as  it  is  reached  seems  self- 
evident  —  even  inevitable. 

One  of  the  particular  strengths  of  the 
authors  is  the  deceptive  ease  with  which 
they  transform  seemingly  simple  rules 
of  thumb  into  razor-sharp  analytical 
tools.  For  example,  they  introduce 
Amdahl’s  Law  within  the  first  few  pages: 
“The  performance  improvement  to  be 
gained  from  using  some  faster  mode 
of  execution  is  limited  by  the  fraction 
of  the  time  the  faster  mode  can  be 


Dr.  Dobb's Journal,  October  1990 


145 

969 


PROGRAMMER'S  BOOKSHELF 


used.”  At  first  glance,  this  law  appears 
to  be  as  trivial  (and  as  useless)  as  the 
classic  syllogism  “Socrates  is  a  man, 
men  are  mortal,  therefore  Socrates  is 
mortal.”  But  the  authors  demonstrate 
otherwise;  they  return  to  Amdahl’s  Law 
again  and  again  throughout  the  book 
to  demonstrate  why  well-intentioned 
changes  in  hardware  or  software  don’t 
always  yield  the  hoped-for  benefits. 
For  example: 

Suppose  we  could  improve  the  speed 
of  the  CPU  in  our  machine  by  a  factor 
of  five  (without  affecting  I/O  perfor¬ 
mance)  for  five  times  the  cost.  Also  as¬ 
sume  that  the  CPU  is  used  50%  of  the 
time,  and  the  rest  of  the  time  the  CPU  is 
waiting  for  I/O.  If  the  CPU  is  one-third 
of  the  total  cost  of  the  computer,  is 
increasing  the  CPU  speed  by  a  factor  of 
five  a  good  investment  from  a  cost/ 
performance  standpoint? 

The  speedup  obtained  is 

1  l 

Speedup  - - - - =  1.67 

0.5  0.6 

0.5+ - 

5 


professor  at  Stanford  University,  was 
one  of  the  founders  of  MIPS  Computer 
Systems  and  is  still  that  company’s  chief 
scientist.  The  authors  are,  consequently, 
legendary  figures  in  the  RISC  move¬ 
ment,  but  their  discussion  of  RISC  tech¬ 
nology  in  this  book  is  balanced  and 
dispassionate.  Much  of  their  profiling 
and  cost/performance  data  supports 

One  of  the  particular 
strengths  of  the  authors 
is  the  deceptive  ease 
with  which  they 
transform  seemingly 
simple  rules  of  thumb 
into  razor-sharp 
analytical  tools 


The  new  machine  will  cost 


5  =  2.33  times  the  original  machine 


Since  the  cost  increase  is  larger  than  the 
performance  improvement,  this  change 
does  not  improve  cost/performance. 

At  this  point,  the  thoughtful  reader 
might  be  inclined  to  reflect  on  the  ap¬ 
plication  of  Amdahl’s  Law  to  more  mun¬ 
dane,  practical  matters,  such  as  the  in¬ 
stallation  of  80386  accelerator  boards 
into  classic  IBM  PCs  with  4.77  MHz, 
8-bit  I/O  buses. 

In  the  last  chapter,  the  authors  specu¬ 
late  on  future  directions  in  computer 
architecture,  with  particular  emphasis 
on  multiprocessors  and  compiler  tech¬ 
nology.  The  book  ends  with  a  set  of 
appendices  that  would  more  than  jus¬ 
tify  the  book’s  price  in  themselves:  A 
succinct  but  comprehensive  essay  on 
computer  arithmetic  by  David  Gold¬ 
berg  of  Xerox’s  Palo  Alto  Research  Cen¬ 
ter,  detailed  profiles  of  instruction  set 
frequencies  and  execution  times  for 
the  VAX,  IBM  360,  and  Intel  8086,  and 
a  comparative  survey  of  four  of  the 
most  popular  RISC  architectures  (Intel 
860,  MIPS,  Motorola  88000,  and  SPARC). 

Patterson,  a  professor  at  the  Univer¬ 
sity  of  Calif ornia-Berkeley,  was  respon¬ 
sible  for  the  design  and  implementa¬ 
tion  of  RISC  I  —  the  direct  ancestor  of 
Sun’s  SPARC  processor.  Hennessy,  a 


RISC  concepts,  but  it’s  strictly  a  soft 
sell  —  the  reader  is  left  in  peace  to 
draw  his  own  conclusions.  Thus,  the 
book’s  advocacy  of  RISC  is  quite  indi¬ 
rect,  but  is  made  all  the  more  powerful 
by  the  authors’  command  of  every  facet 
of  CISC  architectures. 

Computer  Architecture:  A  Quantita¬ 
tive  Approach  is  a  tour-de-force  on  sev¬ 
eral  levels.  The  book  is  a  masterpiece 
of  technical  writing  —  Hennessy  and 
Patterson’s  clear,  direct  style  is  absorb¬ 
ing  and  effective,  and  their  enthusiasm 
for  their  subject  is  contagious.  The  de¬ 
sign  and  production,  too,  are  impecca¬ 
ble.  Furthermore,  because  the  book 
presents  a  hardheaded  and  pragmatic 
approach  to  computer  design,  based 
on  real  examples,  real  measurements, 
and  lessons  learned  from  the  successes 
and  misadventures  of  the  past,  it  should 
revolutionize  the  teaching  of  computer 
architecture  and  implementation. 

Although  this  book  was  not  written 
primarily  for  programmers,  it  is  a  thor¬ 
ough  and  extraordinarily  wide-ranging 
education  in  that  magical  interface  be¬ 
tween  the  programmer’s  intentions  and 
the  electron’s  actions.  It  should  be  read 
by  every  software  craftsman  who  cares 
about  wringing  the  last  drop  of  perfor¬ 
mance  from  his  machine. 

DDJ 
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Listing  One  (Text  begins  on  page  131) 

/************  CLASS. H  COPYRIGHT  1990  GREGORY  COLVIN  ************ 
This  program  may  be  distributed  free  with  this  copyright  notice. 

♦include  <stddef.h> 

♦include  <assert.h> 

/“  All  objects  must  be  descendants  of  the  Base  class,  so  we 
define  the  members  and  methods  of  Base  here.  “/ 


♦define  Base_MEMBERS 

♦define  Base_METHODS  \ 

Base  * (‘create)  (void  *table);  \ 

Base  *(*clone)  (void  ‘self);  \ 

Base  ‘(‘copy)  (void  ‘self,  Base  ‘other);  \ 

void  (‘destroy) (void  ‘self); 


typedef  struct  Base_methods  Base_Methods; 
typedef  struct  Base_members  Base; 
struct  Base_members  { 

Base_Methods  ‘methods; 

In¬ 
struct  Base_methods  ( 
char  ‘name; 
size_t  size; 

Base_Metnods  ‘selfTable; 

Base_Methods  ‘nextTable; 

Base_METHODS 

In- 

extern  Base_Methods  Base_Table,  *Class_List; 

Base_Methods  ‘TableFromName (char  ‘name); 

Base  ‘ObjectFromName (char  ‘name); 

/“  The  CLASS  macro  declares  a  Child  class  of  the  Parent.  Note 
that  Ch i 1 d ♦ ♦ _MEMBE RS ,  ChildH_METHODS,  Parent ♦♦_MEMBERS,  and 
ParentM_METHODS  must  be  already  defined.  All  methods  except 
create ()  require  the  first  parameter,  self,  to  be  a  pointer 
to  an  object  of  Child  type;  it  can  be  declared  void  to  stop 
compiler  warnings  when  Parent  methods  are  invoked,  at  the 
possible  cost  of  warnings  when  methods  are  bound.  The  method 
table,  ChildH_Table,  must  be  defined  as  a  global  structure.  “/ 


♦define  CLASS (Parent, Child)  \ 

typedef  struct  Chi ld^ ♦jnethods  ChildM_Methods;  \ 

typedef  struct  ChildMjnembers  Child;  \ 

struct  Childs ♦jnembers  (  \ 

Child^ ♦_Methods  ‘methods;  \ 

Parents?  MEMBERS  \ 

Child##  MEMBERS  \ 

I;  \ 

struct  Child##_methods  (  \ 

char  ‘name;  \ 

size_t  size;  \ 

Child##  Methods  ‘selfTable;  \ 


Base_Methods  ‘nextTable;  \ 

Parent  ♦  #_METHODS  \ 

Child##  METHODS  \ 

I;  "  \ 


extern  Chi Id# #_Methods  Child##_Table 

/“  The  INHERIT  and  BIND  macros  allow  for  binding  functions  to 
object  methods  at  run-time.  They  must  be  called  before 


objects  can  be  created  or  used.  “/ 

♦define  INHERIT (Parent, Child)  \ 

Child##_Table  =  *  (Child##_Methods‘) &Parent##_Table;  \ 

Child##_Table .  name  =  ♦Child;  \ 

Child##_Table.size  =  sizeof  (Child) ;  \ 

Child##_Table . selfTable  =  &Child##_Table;  \ 

Child##_Table.  nextTable  =  Class_List;  \ 

Class_List  =  (Base_Methods  *) &Child##_Table 

♦define  BIND (Class, Method, Function)  \ 

Class##  Table. Method  =  Function 


/“  The  CREATE  macro  allocates  and  initializes  an  object  pointer 
by  invoking  the  create ()  method  for  the  specified  Class. 

The  DEFINE  macro  declares  an  object  structure  as  an 
automatic  or  external  variable;  it  can  take  initializers 
after  a  WITH,  and  ends  with  ENDDEF.  The  NAMED  macro  creates 
an  object  pointer  from  a  class  name.  “/ 

♦define  CREATE (Class)  \ 

(Class  *)  (*Class##_Table. create)  (&Class##_Table) 

♦define  DEFINE (Class, Ob jectStruct)  \ 

Class  ObjectStruct  =  (  &Class##_Table 
♦define  WITH  , 

♦define  ENDDEF  ) 

♦define  NAMED (ClassName)  Ob jectFromName (ClassName) 

/“  The  VALID  macro  tests  the  method  table  self  reference.  “/ 
♦define  VALID (Ob jectPtr)  \ 

( (ObjectPtr) ->methods->selfTable  ==  (ObjectPtr) ->methods) 

/“  The  SEND  and  CALL  macros  invoke  object  methods,  through  the 
object's  methods  pointer  with  SEND,  or  directly  from  a 
method  table  with  CALL.  Method  parameters  besides  self  may 
be  sent  using  WITH,  and  END  terminates  the  invocation.  “/ 


♦define  SEND (Message, ObjectPtr)  \ 

(  assert (VALID (Ob jectPtr) ) ,  \ 

(* ( (ObjectPtr) ->methods->Message) ) ( (ObjectPtr) 

♦define  CALL (Class, Method, ObjectPtr)  \ 

(  assert (VALID (ObjectPtr) ) ,  \ 

assert  (ClassH_Table. selfTable  ==  &ClassM_Table) ,  \ 

(*  (ClassMjTable. Method) )  ( (ObjectPtr) 


( continued  on  page  148) 
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Listing  One  (Listing  continued,  text  begins  on  page  13U 

♦define  END  ) ) 

/“  The  DESTROY  macro  invokes  an  objects  destroy!)  method  “/ 

♦define  DESTROY (Ob jectPtr)  SEND (destroy, (Ob jectPtr) )  END 


&Base_Table, 

0, 

BaseCreate, 

BaseClone, 

BaseCopy, 

BaseDestroy 

I; 

Base_Methods  *Class_List  =  &Base_Table; 


End  Listing  One 


Listing  Two 


/************  CLASS. C  COPYRIGHT  1990  GREGORY  COLVIN  ************ 


This  program  may  be  distributed  free  with  this  copyright  notice. 


♦include  <assert.h> 
♦include  <string.h> 
♦include  <stdlib.h> 
♦include  <stdio.h> 
♦include  "class. h" 


Base_Methods  *TableFromName (char  *name) 

1  Base_Methods  *table; 

char  *pname,  *tname=table->name; 

for  (table=Class_List;  table;  table=table->nextTable) 
for  (pname=name;  *pname  ==  *tname++;  pname++  ) 
if  (!*pname) 

return  table; 

return  0; 


Base  *ObjectFromName (char  *name) 

(  Base_Methods  *table  =  TableFromName (name) ; 
if  (table) 

return  table->create (table) ; 
return  0; 

} 


Base  *BaseCreate (Base_Methods  ‘table) 

{  Base  ‘new  =  (Base  *) calloc (1, table->size) ; 
assert (new) ; 
new->methods  =  table; 
return  new; 


Base  ‘BaseClone (Base  ‘self) 

(  Base  ‘new  =  (Base  *)malloc (self->methods->size) ; 
assert (new) ; 

memcpy (new, self, self->methods->size) ; 
return  new; 


Base  ‘BaseCopy (Base  ‘self,  Base  ‘other) 

(  memcpy (self, other, self->methods->size) ; 
return  self; 

} 

void  BaseDestroy (Base  ‘self) 
f  if  (self) 

free (self) ; 

} 

Base_Methods  Base_Table  =  ( 

"Base", 
sizeof (Base) , 


) 

/“  A  function  to  be  called  in  main  to  initialize  My  method  table.  “/ 
void  Mylnit (  void  ) 

(  INHERIT (Base, My) ; 

BIND (My, set,MySet) ; 

BIND (My , next , MyNext ) ; 

) 

/**  Make  My  class  do  something.  “/ 

My  *test(  int  i  ) 

{  int  j; 

♦  if  1 

My  *ob jectPtr  =  CREATE (My);  /*  One  way  to  make  an  object  */ 

♦else 

DEFINE (My, object) ENDDEF;  /*  Another  way  */ 

My  *objectPtr=  (My  *) SEND (clone, sobject) END; 

♦endif 

CALL (My, set, ob jectPtr)  WITH  i  END; 
if  (j  =  SEND (next, ob jectPtr) END) 
return  objectPtr; 

DESTROY (ob jectPtr) ; 
return  0; 

) 

main  (int  argc,  char  “argv) 

(  int  arg  =  atoi (argv[l] ) ; 

My  ‘out; 

Mylnit  () ; 

if  (out  =  test (arg))  ( 
printf ("%d\n",out->stuff) ; 

DESTROY (out) ; 

)  else 

printf ("0\n") ; 

I 


End  listing  Two 


Listing  Three 


/“  TEST.C  Add  one  to  argv[l]  the  hard  way.  This  program  serves 
no  real  purpose  except  invoking  most  of  the  CLASS  macros.  “/ 
♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  "class. h" 

/“  Define  My  class  members  and  methods.  “/ 

♦define  My_MEMBERS  int  stuff; 

♦define  My_METHODS  void  (‘set) (void*, int) ;  int  (‘next) (void*) ; 
CLASS (Base, My) ; 

/“  Define  space  for  My  method  table.  “/ 

My_Methods  My_Table; 

/**  Define  functions  to  implement  My  methods.  “/ 
void  MySet (My  ‘self,  int  new) 

{  self->stuff  =  new; 


int  MyNext (My  ‘self) 

(  return  ++sel f->stuf f : 


End  listings 
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STRUCTURED  PROGRAMMING 


Listing  One  (Text  begins  on  page  139.) 

PROGRAM  ZelTest;  {  From  DDJ  10/90  } 

CONST 

DayStrings  :  ARRAY[0..6]  OF  STRING  = 

( ' Sunday' , ' Monday' , ' Tuesday' , ' Wednesday' , ' Thursday' , ' Friday' , ' Saturday' ) ; 
VAR 

Month,  Day,  Year  :  Integer; 


FUNCTION  CalcDayOfWeek (Year, Month, Day  :  Integer)  :  Integer; 

VAR 

Century, Holder  :  Integer; 

BEGIN 

(  First  test  for  error  conditions  on  input  values:  } 

IF  (Year  <  0)  OR 

(Month  <  1)  OR  (Month  >12)  OR 
(Day  <  1)  OR  (Day  >  31)  THEN 

CalcDayOfWeek  :=  -1  (  Return  -1  to  indicate  an  error  } 

ELSE 

{  Do  the  Zeller' s  Congruence  calculation  as  Zeller  himself  ) 

(  described  it  in  "Acta  Mathematica"  #7,  Stockhold,  1887.  ) 

BEGIN 

(  First  we  separate  out  the  year  and  the  century  figures:  } 
Century  :=  Year  DIV  100; 

Year  :=  Year  MOD  100; 

{  Next  we  adjust  the  month  such  that  March  remains  month  #3,  } 

(  but  that  January  and  February  are  months  #13  and  #14,  } 

(  *but  of  the  previous  year*:  } 

IF  Month  <  3  THEN 
BEGIN 

Inc (Month, 12) ; 

IF  Year  >  0  THEN  Dec (Year, 1)  {  The  year  before  2000  is  } 

ELSE  {  1999,  not  20-1...  ) 

BEGIN 

Year  :=  99; 

Dec (Century) ; 

END 

END; 


(  Here's  Zeller1 
Holder  :=  Day; 
Holder  :=  Holder 
Holder  :=  Holder 
Holder  :=  Holder 
Holder  :=  Holder 
Holder  :=  Holder 
WHILE  Holder  <  0 
Inc (Holder, 7) ; 


s  seminal  black  magic:  } 

{  Start  with  the  day  of  month  } 
( ( (Month+1)  *  26)  DIV  10);  {  Calc  the  increment  } 


Year; 

(Year  DIV  4); 
(Century  DIV  4); 
Century  -  Century; 


Holder  :=  Holder  MOD  7; 


Add  in  the  year  } 

{  Correct  for  leap  years  } 

(  Correct  for  century  years  } 

{  DON'T  KNOW  WHY  HE  DID  THIS!  ) 
(  Get  negative  values  up  into  ) 
(  positive  territory  before  } 
(  taking  the  MOD...  ) 

{  Divide  by  7  but  keep  the  ) 

(  remainder  rather  than  the  ) 

(  quotient  ) 


{  Here  we  "wrap"  Saturday  around  to  be  the  last  day:  ) 
IF  Holder  =  0  THEN  Holder  :=  7; 


(  Zeller  kept  the  Sunday  =  1  origin;  computer  weenies  prefer  to  ) 
(  start  everything  with  0,  so  here's  a  20th  century  kludge:  .) 

Dec (Holder) ; 

CalcDayOfWeek  :=  Holder;  (  Return  the  end  product!  } 

END; 

END; 


RECORD 
CASE  : 
TRUE 
FALSE 

END; 

END; 


BOOLEAN  OF 
:  FullStamp 
:  TimePart 
DatePart 


LONGCARD; 

CARDINAL; 

CARDINAL 


When  = 

CLASS 

WhenStamp  :  WhenUnion; 

TimeString  :  String9; 

Hours, Minutes, Seconds  :  CARDINAL 
DateString  :  String20; 

LongDateString  :  String50; 

Year, Month, Day  :  CARDINAL; 

DayOfWeek  :  INTEGER; 

PROCEDURE  GetTimeStamp ( ) 

PROCEDURE  GetDateStampO 
PROCEDURE  PutNow; 

PROCEDURE  PutWhenStamp (NewWhen  :  LONGCARD); 
PROCEDURE  PutTimeStamp (NewStamp  :  CARDINAL); 
PROCEDURE  PutDateStamp (NewStamp  :  CARDINAL); 
PROCEDURE  PutNewDate (NewYear, NewMonth, NewDay 
PROCEDURE  PutNewTime (NewHours, NewMinutes, NewSeconds 
END; 

END  TimeDate. 


(* 
(* 
(* 

(* 

CARDINAL; 

CARDINAL; 


Combined  time/date  stamp  *) 
i.e.,  "12:45a"  *) 

Seconds  is  always  even!  *) 
i.e.,  "06/29/89"  *) 

i.e.,  "Thursday,  June  29,  1989"  * 

0=Sunday,  l=Monday,  etc.  *) 

(*  Returns  DOS-format  time  stamp 
(*  Returns  DOS-format  date  dtamp 


CARDINAL) ; 

CARDINAL) ; 


End  Listing  Two 


Listing  Three 


*  TIMEDATE 

*  A  Time-and-date  stamp  object  for  TopSpeed  Modula-2 

*  Implementation  module 

*  TopSpeed  Modula-2  V2.0 

*  by  Jeff  Duntemann 

*  Last  update  6/16/90 


*) 


*) 

*) 

*) 

*) 

*) 

*) 

*) 

*) 


IMPLEMENTATION  MODULE  TimeDate; 


FROM  FIO 
FROM  Str 
FROM  Bitwise 


IMPORT  GetCurrentDate; 

IMPORT  CardToStr,Concat, IntToStr, Length, Slice; 
IMPORT  And,  Or.;  (*  From  DDJ  for  March  1990  *) 


TYPE 

TMonthTags  =  ARRAY  [1..12]  OF  String9; 
TDayTags  =  ARRAY  ( 0 . .6]  OF  String9; 


VAR 

Tempi  :  String50; 

Dummy  :  CARDINAL; 
DayTags  :  TDayTags; 
MonthTags  :  TMonthTags; 


PROCEDURE  CalcTimeStamp (Hours, Minutes, Seconds  :  CARDINAL)  :  CARDINAL; 


BEGIN 

Write ('Month  (1-12):  ');  Readln (Month) ; 

Write ('Day  (1-31):  ');  Readln (Day); 

Write ('Year  :  ');  Readln (Year) ; 

Writeln('The  day  of  the  week  is 

DayStrings [CalcDayOfWeek (Year, Month, Day) ] ) ; 

Readln; 

END. 


BEGIN 

RETURN  Or (Or ((Hours  «  11), (Minutes  «  5) ), (Seconds  »  1) ) ; 
END  CalcTimeStamp; 


PROCEDURE  CalcDateStamp (Year, Month, Day  :  CARDINAL)  :  CARDINAL, 
BEGIN 

RETURN  Or (Or (((Year  -  1980)  «  9),  (Month  «  5)), Day); 

END  CalcDateStamp; 


End  Listing  One 


PROCEDURE  CalcTimeSt ring (VAR  TimeString  :  String9; 

Hours, Minutes, Seconds  :  CARDINAL); 


Listing  Two 


VAR 

Tempi, Temp2 

AMPM 

I 

OK 


String9; 

CHAR; 

INTEGER; 

BOOLEAN; 


I* - *) 

(*  TIMEDATE  *) 
(*  *) 
(*  A  Time-and-date  stamp  object  for  TopSpeed  Modula-2  *) 
(*  *) 
(*  Definition  module  *) 
(*  TopSpeed  Modula-2  V2.0  *) 
(*  by  Jeff  Duntemann  *) 
(*  Last  update  6/1/90  *) 
(*  *) 
(* - *) 


DEFINITION  MODULE  TimeDate; 

TYPE 

String9  =  ARRAY [0.. 9]  OF  CHAR; 
String20  =  ARRAY[0..20]  OF  CHAR; 
String50  =  ARRAY[0..50]  OF  CHAR; 


BEGIN 

I  :=  Hours; 

IF  Hours  =  0  THEN  I  :=  12;  END;  (*  "0"  hours  =  12am  *) 

IF  Hours  >  12  THEN  I  :=  Hours  -  12;  END; 

IF  Hours  >  11  THEN  AMPM  :=  'p'  ELSE  AMPM  :=  'a';  END; 

IntToStr (LONGINT( I) , Tempi, 10, OK) ; 

IntToStr (LONGINT (Minutes) ,Temp2, 10, OK) ; 

IF  Length (Temp2)  <  2  THEN  Concat (Temp2, ' 0' ,  Temp2);  END; 
Concat (TimeString, Tempi, ' : ' ) ; 

Concat (TimeString, TimeString, Temp2 ) ; 

Concat (TimeString, TimeString, AMPM) ; 

END  CalcTimeString; 


PROCEDURE  CalcDateString (VAR  DateString  :  String20; 

Year, Month, Day  :  CARDINAL); 

VAR 


WhenUnion  = 


(continued  on  page  150) 
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STRUC1URED  PROGRAMMING 


(Listing  continued,  text  begins  on  page  139  ) 


OK  :  BOOLEAN; 

BEGIN 

CardToStr (LONGCARD (Month) , DateString, 10, OK) ; 
CardToStr (LONGCARD (Day) , Tempi, 10, OK) ; 

Concat (DateString, DateString, ' /' ) ; 

Concat (DateString, DateString, Tempi) ; 
CardToStr (LONGCARD (Year) , Tempi, 10, OK) ; 

Concat (DateString, DateString, ' /' ) ; 

Slice (Tempi, Tempi,  3, 2) ; 

Concat (DateString, DateString, Tempi ) ; 

END  CalcDateString; 


PROCEDURE  CalcLongDateString (VAR  LongDateString  :  String50; 

Year, Month, Date, DayOfWeek  :  CARDINAL); 

VAR 

Tempi  :  String9; 

OK  :  BOOLEAN; 

BEGIN 

Concat (LongDateString, DayTags [DayOfWeek] , ' ,  ' ) ; 

CardToStr (LONGCARD (Date) , Tempi, 10, OK) ; 

Concat (LongDateString, LongDateString, MonthTags [Month] ) ; 

Concat (LongDateString, LongDateString, '  ' ) ; 

Concat (LongDateString, LongDateString, Tempi) ; 

Concat (LongDateString, LongDateString, ' ,  ' ) ; 

CardToStr (LONGCARD (Year) , Tempi , 10, OK) ; 

Concat (LongDateString, LongDateString, Tempi) ; 

END  CalcLongDateString; 


This  calculates  a  day  of  the  week  figure,  where  0=Sunday,  l=Monday,  *) 
and  so  on,  given  the  year,  month,  and  day.  The  year  must  be  passed  *) 
in  full;  that  is,  "1990"  not  just  "90".  Another  century  is  at  hand,*) 
gang...  *) 


PROCEDURE  CalcDayOfWeek (Year, Month, Day  :  INTEGER)  :  INTEGER; 
VAR 

Century, Holder  :  INTEGER; 


BEGIN 

(*  First  test  for  error  conditions  on  input  values:  *) 
IF  (Year  <  0)  OR 

(Month  <  1)  OR  (Month  >  12)  OR 
(Day  <  1)  OR  (Day  >  31) 

THEN 

RETURN  -1  (*  Return  -1  to  indicate  an  error  *) 


ELSE 

(*  First  we  separate  out  the  year  and  century  figures:  *) 

Century  :=  Year  DIV  100; 

Year  :=  Year  MOD  100; 

(*  Next  we  adjust  the  month  such  that  March  remains  #3,  *) 

(*  but  that  January  and  February  are  months  #13  and  #14,  *) 

(*  *but  of  the  previous  year.*  *) 

IF  Month  <  3  THEN 
INC (Month, 12) ; 

IF  Year  >  0  THEN  DEC (Year, 1)  (*  1900/2000  etc.  ("year  0") 

ELSE  (*  must  be  treated  specially. 

Year  :=  99;  (*  You  can't  just  decrement  the 

DEC (Century)  {*  year  to  -l...you  must  make 

END;  (*  it  year  99  of  the  previous 

END;  (*  century. 


(*  Here's  Zeller's 
Holder  :=  Day; 
Holder  :=  Holder  + 
Holder  :=  Holder  + 
Holder  :=  Holder  + 
Holder  :=  Holder  + 
Holder  :=  Holder  - 
WHILE  Holder  <  0  DO 


seminal  black  magic:  *) 

(*  Start  with  the  day 
( ( (Month+1)  *  26)  DIV  10);  (*  Calc  increment 

Year;  (*  Add  in  the  year 

(Year  DIV  4);  (*  Correct  for  leap  years 

(Century  DIV  4);  (*  Correct  for  century  years 
Century  -  Century;  (*  Take  out  century  twice 
(*  Avoid  taking  MOD  of  negative  quantity 


INC (Holder, 7) ; 
END; 


Holder  :=  Holder  MOD  7;  (*  Take  Modulo  7  of  (positive)  result 


(*  Here  we  "wrap"  Saturday  around  to  be  the  last  day:  *) 
IF  Holder  =  0  THEN  Holder  :=  7  END; 


*) 

*) 

*) 

*) 

*) 

*) 


*) 

*) 

*) 

*) 

*) 

*) 

*) 


(*  Zeller  kept  the  Sunday  =  1  origin;  computer  weenies  prefer  to  *) 
(*  start  everything  with  0,  so  here's  a  20th  century  kludge:  *) 

DEC (Holder) ; 

(*  We've  got  it:  Sunday  =  0,  Monday  =  1,  etc.  Return  the  value:  *) 
RETURN  Holder; 

END;  (*  IF  *) 

END  CalcDayOfWeek; 


TYPE 
When  = 

CLASS 

WhenStamp  :  WhenUnion; 

TimeString  :  String9; 

Hours, Minutes, Seconds  :  CARDINAL; 
DateString  :  String20; 
LongDateString  :  String50; 

Year, Month, Day  :  CARDINAL; 
DayOfWeek  :  INTEGER; 


(*  Combined  time/date  stamp  *) 

(*  i.e.,  "12:45a"  *) 

(*  Seconds  is  always  even!  *) 

(*  i.e.,  "06/29/89"  *) 

(*  i.e.,  "Thursday,  June  29,  1989"  *) 

{*  0=Sunday,  l=Monday,  etc.  *) 


(* - *) 

(*  There  will  be  many  times  when  an  individual  date  or  time  stamp  will  *) 
(*  be  much  more  useful  than  a  combined  time/date  stamp.  These  simple  *) 
(*  functions  return  the  appropriate  half  of  the  combined  long  integer  *) 
(*  time/date  stamp  without  incurring  any  calculation  overhead.  It's  *) 
(*  done  with  a  simple  value  typecast:  *) 

(* - - - *) 

PROCEDURE  GetTimeStampO  :  CARDINAL; 

BEGIN 

RETURN  WhenStamp. TimePart; 

END  GetTimeStamp; 


PROCEDURE  GetDateStampO  :  CARDINAL; 
BEGIN 

RETURN  WhenStamp. DatePart; 

END  GetDateStamp; 


(* - *) 

(*  To  fill  a  When  record  with  the  current  time  and  date  as  maintained  *) 
(*  by  the  system  clock,  execute  this  method:  *) 

(* - *) 

PROCEDURE  PutNow; 

BEGIN 

(*  Get  current  time  and  date  from  the  system:  *) 

WhenStamp. FullStamp  :=  GetCurrentDate ( ) ; 

(*  Calculate  a  new  time  stamp  and  update  object  fields:  *) 

PutTimeStamp (WhenStamp . TimePart ) ; 

(*  Calculate  a  new  date  stamp  and  update  object  fields:  *) 

PutDateStamp (WhenStamp . DatePart ) ; 

END  PutNow; 


I* - *) 

(*  This  method  allows  us  to  apply  a  whole  long  integer  time/date  stamp  *) 
(*  to  the  When  object.  The  object  divides  the  stamp  into  time  and  *) 

(*  date  portions  and  recalculates  all  other  fields  in  the  object.  *) 

{* - *) 

PROCEDURE  PutWhenStamp (NewWhen  :  LONGCARD); 

BEGIN 

WhenStamp. FullStamp  :=  NewWhen; 

(*  We've  actually  updated  the  stamp  proper,  but  we  use  the  two  *) 

(*  "put"  routines  for  time  and  date  to  generate  the  individual  *) 

(*  field  and  string  representation  forms  of  the  time  and  date.  *) 

(*  I  know  that  the  "put"  routines  also  update  the  long  integer  *) 

(*  stamp,  but  while  unnecessary  it  does  no  harm.  *) 

PutTimeStamp (WhenUnion (WhenStamp) .TimePart) ; 

PutDateStamp (WhenUnion (WhenStamp) .DatePart) ; 

END  PutWhenStamp; 
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(* - *) 

(*  We  can  choose  to  update  only  the  time  stamp,  and  the  object  will  *) 
(*  recalculate  only  its  time-related  fields.  *) 
(* - *) 


PROCEDURE  PutTimeStamp (NewStamp  :  CARDINAL); 

BEGIN 

WhenUnion (WhenStamp) .TimePart  :=  NewStamp; 

(*  The  time  stamp  is  actually  a  bitfield,  and  all  this  shifting  left  *) 
(*  and  right  is  just  extracting  the  individual  fields  from  the  stamp:*) 
Hours  :=  NewStamp  »  11; 

Minutes  :=  And ( (NewStamp  »  5),3FH); 

Seconds  :=  And ( (NewStamp  «  1) , 1FH) ; 

(*  Derive  a  string  version  of  the  time:  *) 

CalcTimeString (TimeString, Hours, Minutes, Seconds) ; 

END  PutTimeStamp; 


<* - *) 

{*  Or,  we  can  choose  to  update  only  the  date  stamp,  and  the  object  *) 
(*  will  then  recalculate  only  its  date-related  fields.  *) 
(* - *) 


PROCEDURE  PutDateStamp (NewStamp  :  CARDINAL); 

BEGIN 

WhenUnion (WhenStamp) .DatePart  :=  NewStamp; 

(*  Again,  the  date  stamp  is  a  bit  field  and  we  shift  the  values  out  *) 
(*  of  it:  *) 

Year  :=  (NewStamp  »  9)  +  1980; 

Month  :=  And( (NewStamp  »  5),0FH); 

Day  :=  And (NewStamp, 1FH) ; 

(*  Calculate  the  day  of  the  week  value  using  Zeller's  Congruence:  *) 

DayOfWeek  :=  CalcDayOfWeek (Year, Month, Day) ; 

(*  Calculate  the  short  string  version  of  the  date;  as  in  "06/29/89":  *) 
CalcDateString (DateString, Year, Month,  Day) ; 

(*  Calculate  a  long  version,  as  in  "Thursday,  June  29,  1989":  *) 
CalcLongDateString (LongDateString, Year , Month, Day,  DayOfWeek) ; 

END  PutDateStamp; 


PROCEDURE  PutNewDate (NewYear, NewMonth, NewDay  :  CARDINAL); 

BEGIN 

(*  The  "boss"  field  is  the  date  stamp.  Everything  else  is  figured  *) 

(*  from  the  stamp,  so  first  generate  a  new  date  stamp,  and  then  *) 

(*  (odd  as  it  may  seem)  regenerate  everything  else,  ‘including*  *) 

(*  the  Year,  Month,  and  Day  fields:  *) 

PutDateStamp (CalcDateStamp (NewYear, NewMonth, NewDay) ) ; 

(*  Calculate  the  short  string  version  of  the  date;  as  in  "06/29/89":  *) 
CalcDateString (DateString, Year, Month, Day) ; 


(*  Calculate  a  long  version,  as  in  "Thursday,  June  29,  1989":  *) 
CalcLongDateString (LongDateString, Year, Month, Day, DayOfWeek) ; 

END  PutNewDate; 


PROCEDURE  PutNewTime(NewHours,NewMinutes,NewSeconds  :  CARDINAL); 

BEGIN 

(*  The  "boss"  field  is  the  time  stamp.  Everything  else  is  figured  *) 
(*  from  the  stamp,  so  first  generate  a  new  time  stamp,  and  then  *) 
(*  (odd  as  it  may  seem)  regenerate  everything  else,  ‘including*  *) 
(*  the  Hours,  Minutes,  and  Seconds  fields:  *) 

PutTimeStamp (CalcTimeStamp (NewHours, NewMinutes, NewSeconds) ) ; 

(*  Derive  the  string  version  of  the  time:  *) 

CalcTimeString (TimeString, Hours, Minutes,  Seconds) ; 

END  PutNewTime; 

END;  (*  ...of  CLASS  When  implementation  *) 


BEGIN  (*  Initialization  code  for  TimeDate  goes  here:  *) 

MonthTags  := 

TMonthTags ('January' , ' February' , 'March' , 'April' , 'May' , ' June' , ' July' , 
'August' , 'September' , 'October' , 'November' , 'December' ) ; 
DayTags  :=  TDayTags (' Sunday' , 'Monday' ,' Tuesday' , 'Wednesday' , 

' Thursday' , ' Friday' , ' Saturday' ) ; 

END  TimeDate. 


End  Listings 
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Implementing 

Cordic  Algorithms 


A  single  compact  routine  for  computing 
transcendental  functions 


Pitts  Jarvis 


Efficiently  computing  sines,  co¬ 
sines,  and  other  transcendental 
functions  is  a  process  about 
which  many  programmers  are 
blissfully  ignorant.  When  these 
values  are  called  for  in  a  graphics  or 
CAD  program,  we  usually  rely  on  a  call 
to  the  compiler’s  run-time  library.  The 
library  either  derives  the  necessary  val¬ 
ues  in  some  mysterious  manner  or  calls 
the  floating-point  coprocessor  to  assist 
in  the  task. 

The  CORDIC  (Coordinate,  Rotation 
Digital  Computer)  family  of  algorithms 
is  an  elegant,  efficient,  and  compact 
way  to  compute  sines,  cosines,  expo¬ 
nentials,  logarithms,  and  associated 
transcendental  functions  using  one  core 
routine.  These  truly  remarkable  algo¬ 
rithms  compute  these  functions  with  n 
bits  of  accuracy  in  n  iterations  —  where 
each  iteration  requires  only  a  small  num¬ 
ber  of  shifts  and  additions.  Further¬ 
more,  these  routines  use  only  fixed- 
point  arithmetic.  Using  these  algorithms, 
you  can  cast  your  entire  graphics  appli¬ 
cation  into  fixed-point,  and  thus  avoid 
the  cost  of  run-time  conversion  from 
fixed-  to  floating-point  representation 
and  back. 

Even  if  you  don’t  plan  on  recasting 
your  application  into  fixed-point,  you 
just  might  be  curious  how  your  floating¬ 
point  coprocessor  works.  The  Intel  nu- 
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merics  family  (8087,  80287,  and  80387) 
all  use  Cordic  algorithms,  in  a  form 
slightly  different  than  described  here, 
to  compute  circular  functions.  The  In¬ 
tel  implementations  are  described  by 
R.  Nave1  and  A.  K.  Yuen2. 

The  implementations  may  be  con¬ 
temporary,  but  the  algorithms  are  not 
new.  J.  E.  Voider3  coined  the  name  in 
1959.  He  applied  these  algorithms  to 
build  a  special-purpose  digital  com¬ 
puter  for  real-time  airborne  navigation. 
D.  S.  Cochran4  identifies  their  use  in 
the  HP-35  calculator  in  1972  to  calcu¬ 
late  the  transcendental  functions. 

Mathematical  Manipulation 

If  we  have  a  vector  [x,  yl,  we  can  rotate 
it  through  an  angle  a  by  multiplying  it 
by  the  matrix  Ra,  defined  in  Example 
1(a).  Explicitly  doing  the  matrix  multi¬ 
plication  yields  the  equation  in  Exam¬ 
ple  1(b). 

If  we  choose  x  =  1  and  y  =  0  and 
multiply  that  vector  by  Ra  we  are  left 
with  the  vector  [cos  a,  sin  a]. 

Multiplying  by  two  successive  rota¬ 
tion  matrices,  Ra  and  Rb  rotates  the 
vector  through  the  angle  a  +  b,  or  more 
formally  RaRb  -  Ra+b ■  If  we  choose 
to  represent  the  angle  a  as  a  sum  of 
angles  at  for  i  =  0  through  n  (see  Exam¬ 
ple  1(c)),  then  we  can  rotate  the  vector 
through  the  angle  a  by  multiplying  a 
series  of  rotation  matrices  Rao, 
Rai,  ■  ■  ■  Ran- 

By  picking  the  af  carefully,  we  can 
simplify  the  arithmetic.  Notice  that  we 


can  rewrite  the  rotation  matrix  by  fac¬ 
toring  out  cos  a  as  shown  in  Example 
1(d).  If  we  pick  at  such  that  tan  af  =  2 4 
for  i  =  0  through  n,  all  of  the  multiplica¬ 
tions  by  tan  af  become  right  shifts  by  i 
bits. 

Now  we  need  to  specify  an  algo¬ 
rithm  so  that  we  can  represent  a  as  the 
sum  of  the  af  Initialize  a  variable,  z, 
to  a.  This  z  will  be  a  residue  quantity, 
which  we  are  trying  to  drive  to  zero 
by  adding  or  subtracting  at  at  the  z'-th 
step.  At  the  first  step,  i  =  0.  At  the  z'-th 
step,  if  z  >  0  then  subtract  at  from  z. 
Otherwise  add  aj  to  z.  At  the  last  step 
i  =  n,  and  zis  the  error  in  our  represen¬ 
tation  of  a.  Notice  that  in  Example  1(e), 
for  large  i,  each  additional  step  yields 
one  more  bit  of  accuracy  in  our  repre¬ 
sentation  of  a. 

Figure  1  shows  the  relative  magni¬ 
tudes  of  the  incremental  angles,  af  Fig¬ 
ure  2  gives  an  example  of  the  conver¬ 
gence  process  with  an  initial  angle  of 
0.65.  Notice  that  successive  iterations 
do  not  necessarily  reduce  the  absolute 
error  in  the  representation  of  the  angle. 
Also  notice  that  the  error  does  not  os¬ 
cillate  about  zero. 

At  each  step  as  we  decompose  a  into 
the  sum  or  difference  of  the  a  Is  we 
could  also  multiply  our  vector  [x,  $  by 
the  appropriate  Ra.  or  R-a.  depending 
on  whether  we  add  or  subtract  af  Re¬ 
member,  these  multiplications  are  noth¬ 
ing  more  than  shifts.  We  must  also 
multiply  in  the  still  embarrassing  factor 
cos  a:.  However,  cosine  is  an  even 
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function  and  has  the  property  that 
cos  at  =  cos  {-a).  It  does  not  matter 
whether  we  add  or  subtract  the  angle  — 
we  always  multiply  by  the  same  factor! 
Because  all  of  the  cos  a.  can  be  fac¬ 
tored  out  and  grouped  together,  we 
can  treat  their  product  as  a  constant 
and  compute  it  only  once,  along  with 
all  the  at  =  tan'1  2"'. 

Not  all  angles  can  be  represented  as 
the  sum  of  ar  There  is  a  domain  of 
convergence  outside  of  which  we  can¬ 
not  reduce  the  angle  to  within  anA  of 
zero.  See  Example  1(f).  For  the  algo¬ 
rithm  to  work,  we  must  start  with  a 
such  that  I  a  I  <  am.lx  ~  1.74.  This  con¬ 
veniently  falls  just  outside  the  first  quad¬ 
rant.  If  we  are  given  an  angle  outside 
the  first  quadrant,  we  can  scale  it  by 
dividing  by  nh  obtaining  a  quotient  Q 
and  a  remainder  D  where  I  ZD  I  <n/2  < 
amm.  Since  the  algorithm  computes  both 
sine  and  cosine  of  D,  we  pick  the  ap¬ 
propriate  value  and  sign  depending  on 
the  value  of  Q. 

What  about  angles  within  the  do¬ 
main  of  convergence?  It’s  not  obvious 
that  the  strange  set  we’ve  picked  (see 
Example  1(g))  can  represent  all  angles 
within  the  domain  of  convergence  to 
within  a  j.  But,  using  mathematical 
induction,  Walther6  proves  that  the 
scheme  works. 

The  Circular  Functions 

One  variation  of  the  Cordic  algorithm 
computes  the  circular  functions  —  sin, 
cos,  tan,  and  so  on.  This  algorithm  is 
shown  in  pseudocode  in  Example  2(a). 

First,  start  with  lx,y,z\.  The  x  and  y 
are  as  before,  zis  the  quantity  that  we 
drive  to  zero,  with  an  initial  value  of 
angle  a.  The  first  step  in  the  loop  de¬ 


cides  whether  to  add  or  subtract  at 
from  the  residue  z.  The  variable  s  is 
correspondingly  positive  or  negative. 
The  second  step  reduces  the  magni¬ 
tude  of  z  and  effects  the  multiplica¬ 
tions  by  the  tan  af  The  expression 
y»i means  shift  y  right  by  i  bits. 

When  you  start  the  algorithm  with 
lx,y,z I  and  then  drive  2r  to  zero  as  speci¬ 
fied  by  Example  2(a),  we  are  left  with 
the  quantities  in  Example  3(a).  Where 
K  is  a  constant,  it  is  just  the  product  of 
the  cos  ap  as  in  Example  3(b). 

For  the  curious,  K~  0.607.  The  value 
of  K  can  be  precomputed  by  setting 
lx,y,zl  to  [1,  0,  0]  and  running  the  algo¬ 


Example  1:  Mathematical  expressions 


rithm  as  before.  The  result  is  shown  in 
Example  3(c).  Take  the  reciprocal  of 
the  final  x  and  we  have  K.  Therefore, 
to  compute  sin  a  and  cos  a,  set  [x,y,z\ 
to  [. K,  0,  a]  and  run  the  algorithm.  Ex¬ 
ample  3(d)  shows  the  result.  In  effect, 
we  start  with  a  vector  [x,  y],  and  rotate 
it  through  a  given  angle  a,  by  driving 
z  to  zero.  Running  the  algorithm  with 
the  special  case  where  the  vector  in¬ 
itially  lies  along  the  x  axis  and  is  of 
length  K,  rotates  the  vector  by  angle  a 
and  leaves  behind  cos  a  and  sin  a.  This 
relationship  is  shown  in  Figure  3. 

To  compute  tan-1  a,  instead  of  z,  we 
could  choose  to  drive  y  to  zero.  Driv- 


[” cos  a  -sin  a" 1 

(a) 

^3  =  sin  a  cos  a 

(b) 

[xl  rx  cos  a  -  y  sin  a  “1 

1  y  1  =  x  sin  a  +  y  cos  a 

(e) 

a  =  3q  +  a-|  +. . .+  an 

f  1  -tan  a" 1 

<d> 

Ra  =  cos  a  |^tan  a  ,  j 

(e) 

a;  =  tan'1  2''  2'1,  for  large  / 

(f) 

amax  =  tan'1  2'°  +  tan’1  2'1  +. .  .+  tan'1  2'n 

(9) 

±  tan'1  2'°±tan'1  2'1  ±  . . .  ttan'1  2'n 

(a) 

for  i  from  0  to  n  do 

if  (z>0)  then  s:=  1  else  s:=  -1 ; 

[x,y,z\  :=  [x  -s  y»i,  y  +  s  x»i,  z  -  s  a,-] 

(b) 

}• 

for  /  from  0  to  n  do 

1 

if  (y  >  0)  then  s:=  1  else  s:=  -1 ; 

[x,y,z\:=[x  +  s y»i,  y-  sx »i,z  +  s a/] 

} 

Example  2:  (a)  The  basic  algorithm;  (b)  the  inverse  algorithm 


0.650 


Figure  2:  Example  of  convergence  with  an  initial  angle  of  0.65 
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ing  y  to  zero  rotates  the  vector  through 
the  angle  a ,  the  angle  subtended  by  the 
vector  and  the  x  axis,  leaving  the  vec¬ 
tor  lying  along  the  xaxis.  Start  with  the 
vector  anywhere  in  the  first  or  fourth 
quadrant  and  an  initial  value  of  zero 
in  z.  The  first  or  fourth  quadrant  is  used 
because  almost  all  vectors  in  the  sec¬ 
ond  or  third  quadrant  will  not  con¬ 
verge.  At  the  z-th  step,  if  y  >  0,  the 
vector  lies  in  the  first  quadrant,  sub- 


Interesting  special  cases 
include  exponential, 
square  root,  and 
logarithm 


tract  a.  from  z.  Move  the  vector  closer 
to  the  x  axis;  rotate  it  by  negative  ai  by 
multiplying  by  the  rotation  matrix  R-a 
If  y  <  0,  the  vector  lies  in  the  fourth 
quadrant,  add  a,  to  z  and  multiply  the 
vector  by  Rat.  At  the  end,  z  has  the 
negative  of  the  angle  of  the  original 
vector  Lx,  y],  tan'1  y/x  =  tan  ''a. 

Changing  the  sign  of  at  has  no  effect 
on  the  computed  values  of  x  and  y  and 
leaves  the  original  angle  a  in  z  rather 
than  its  negative.  With  this  change,  the 
inverse  algorithm  to  drive  y  to  zero 
becomes  the  expression  shown  as  in 
the  algorithm  in  Example  2(b). 

Starting  with  [x,_y,z]  and  then  driving 
y  to  zero  using  the  inverse  algorithm 
leaves  behind  the  quantities  in  Exam¬ 
ple  3(e). 

Hyperbolic  Functions 

The  hyperbolic  functions  (sinh,  cosh, 
and  so  on)  are  similar  to  the  circular 
functions.  The  correspondences  be¬ 
tween  these  two  types  of  functions  are 
shown  in  Table  1 . 

By  analogy,  use  Ha  as  the  rotation 
matrix  and  represent  a  using  the  set  a . 
=  tanh"1  2'1  for  z  =  1  to  n.  Notice  that  for 
hyperbolics,  aQ  is  infinity. 

Given  the  change  in  the  a.,  can  we 
still  represent  any  angle  a  within  the 
domain  of  convergence  the  same  way 
we  did  for  the  circular  functions?  Un¬ 
fortunately,  the  answer  is  no!  Walther 
points  out  that  repeating  an  occasional 
term  makes  the  representation  converge 
in  the  hyperbolic  case.  Repeating  the 
terms  as  shown  in  Example  4(a)  does 
the  trick. 

Except  for  the  repeated  terms  and 
some  changes  of  sign,  the  algorithms 
for  hyperbolic  functions  are  identical 
to  the  circular  functions.  Listing  One, 


(a) 

a,a  ,a  ,a  . a,a  .... 

4  13  40  121  k  3fc+1 

(b) 

1  /  V  1  /  V 

[x,y,z\  -» [—  f  xcosh  z  +  ysinh  zi,“f  cosh  z  +  xsinh  zj,  0] 

(c) 

[x,y,z\  -» [— V  x2  -  0,  z  +  tanh"^ 

(d) 

[Z <Xa]  ->  [ea,  ea,  0] 

(e) 

K2  K2  1  K2  r-  1 

la  +  7'a‘T,2lnT!~>[^a,0'2lnal 

Example  4:  Hyperbolic  function  quantities 


y 

(x,y) 

X 

Figure  3:  The  basic  elements 


HvnertiPtic  Function _ Circular  Function 


„  x  .  „  -X 

6  +  G 

e  +  e 

2 

cos  x  = 

2 

-x 

e  -  e 

2 i 

2 

j~ cosh  a  sinh  a  1 

r 

a  "  sinh  a  cosh  a 

II 

sin  a  cos  a 

Ha«b=«a  +  b 


^sPb  ~  fla  +  b 


ex=  cosh  x  +  sinh  x 
-1  X-1 

In  x  =  2  tanh  — 7 
x+1 


Table  1 :  Hyperbolic  functions 
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(continued  from  page  154) 
page  157,  shows  this  in  detail. 

For  hyperbolic  functions,  we  start 
with  [x,y,zj  and  then  drive  z  to  zero. 
This  yields  the  quantities  in  Example 
4(b).  Starting  with  [x,y,z I  and  then  driv¬ 
ing  y  to  zero  gives  the  quantity  shown 
in  Example  4(c).  For  hyperbolics,  K 
=  1.21. 

Some  interesting  special  cases  include 
the  exponential,  square  root,  and  natu¬ 
ral  logarithm.  The  exponential  case  is  in 
Example  4(d)  while  the  square  root  and 
logarithm  cases  are  in  Example  4(e). 

Calculating  the  Constants 

The  algorithm  to  compute  the  circular 
and  hyperbolic  functions  requires  sev¬ 
eral  precomputed  constants.  These  in¬ 
clude  the  scaling  constant,  K,  for  both 
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circular  and  hyperbolic  functions,  and 
the  sets  shown  in  Example  5(a)  and 
5(b),  respectively.  Listing  One  illustrates 
this. 

The  program,  written  in  C,  uses  fixed 
point  arithmetic  for  all  calculations.  All 
constants  and  variables  used  to  calcu¬ 
late  functions  are  declared  as  the  type 
long.  The  code  assumes  that  a  long  is 
at  least  32  bits.  I  have  decided  to  repre¬ 
sent  numbers  in  the  range  -  4  <  x  <  4; 
this  lets  me  represent  e  as  a  fixed  point 
number.  The  high  order  bit  is  for  the 
sign.  The  low  order  fractionBits( a  con¬ 
stant  defined  as  29)  bits  hold  the  frac¬ 
tional  part  of  the  number.  The  remain¬ 
der  of  the  bits  between  the  sign  bit  and 
the  fractional  part  hold  the  integer  part 
of  the  number.  Figure  4  shows  the  fixed 
point  format  in  graphic  form. 

I  use  power  series  to  calculate  the 
incremental  angles  af  as  shown  in  Ex¬ 
ample  5(c)  and  5(d),  respectively.  How 
do  we  know  the  number  of  terms  nec¬ 
essary  to  evaluate  tan'1  and  tanh'1  to 
32  bits  of  precision?  First  consider  the 
value  of  x  for  which  tan'1  x  =  x  to  32 
bits  of  precision.  A  theorem  of  numeri¬ 
cal  analysis  states  that  for  an  alternat¬ 
ing  sum  where  the  absolute  values  of 
the  terms  decrease  monotonically,  the 
error  is  less  than  the  absolute  value  of 
the  first  neglected  term.  Solving  the 
equation  x}/$  =  2'32  for  x  yields  x  = 
3v6  •  2"11;  therefore  for  i>  11,  tan'1  2'1  = 
2  ' with  32  bits  of  precision. 

For  the  higher  powers  of  two,  we 
need  to  solve  the  relation  2~in/n  =  2'32 
for  n  for  each  of  the  cases  i  =  1  to  10. 
We  do  not  even  attempt  the  calculation 
for  i  =  0.  The  series  for  tan1  1  con¬ 
verges  very  slowly,  even  after  500  terms 
the  third  digit  is  still  changing.  Fortu¬ 
nately,  we  know  that  the  answer  is  %. 
Computing  the  rest  is  not  as  much  work. 
The  array  terms  has  the  gory  details. 

As  usual,  tanh1  is  more  perverse.  It 
is  not  an  alternating  sum  and  does  not 
meet  the  conditions  of  the  theorem 
used  above.  Consider  the  second  ne¬ 
glected  term  of  tanh'1  V2.  It  is  less  than 
*/4  of  the  first  neglected  term  because 
the  series  includes  only  every  other 
power  of  two.  All  of  the  other  neglected 
terms  can  have  no  effect  on  the  33rd 
bit.  The  series  for  the  other  arguments, 
V4,  Vs, . .  . ,  converges  even  faster.  There¬ 
fore,  the  number  of  terms  calculated 
for  tan'1  works  just  as  well  for  tanh'1  for 
32-bit  accuracy. 

Before  computing  the  power  series, 
we  still  need  to  compute  the  coeffi¬ 
cients,  l/k,  for  each  term  k  =  1,  3, 
5,  .  .  .  27.  We  fill  the  coefficient  array 
long  a[28]  with  odd  indices  by  calling 
the  routine  Reciprocal,  which  takes  two 
arguments  and  returns  a  long.  The  first 
argument  is  the  integer  for  the  desired 


reciprocal.  The  second  specifies  the 
desired  precision  for  the  fractional  part 
of  the  result.  Reciprocal  uses  a  simple 
as  can  be  restoring  division;  it  is  the 
algorithm  we  all  learned  in  grade  school 
for  long  division.  The  elements  of  the 
array  a  with  even  indices  get  OL  be¬ 
cause  there  are  no  terms  in  the  power 
series  with  even  exponents. 

Everything  is  ready  to  fill  the  arrays 
atan[fractionBits+l]  and  atanh[fraction 
Bits+lJ 

The  routine  Poly 2  evaluates  the  power 
series  for  the  specified  number  of  terms 
for  the  specified  power  of  two  using 
Homer’s  rule.  The  coefficients  come  from 
the  array  a,  which  we  just  carefully 
filled.  Homer’s  rule  is  the  recommended 
method  for  evaluating  polynomials.  A 
polynomial  as  in  Example  5(e)  can  be 
rewritten  as  in  Example  5(f).  This  sim¬ 
ple  recursive  formula  evaluates  the  poly¬ 
nomial  with  n  multiplications  and  n 
additions.  We  compute  the  prescaling 
constants  K  by  using  the  method  ex¬ 
plained  above;  in  the  program  we  call 
these  XOC  and  XOH ,  for  the  circular 
and  hyperbolic  constants,  respectively. 
Program  output  to  this  point  is  shown 
in  Listing  Two,  page  158. 

The  routines  Circular,  InvertCircu- 
lar,  Hyperbolic,  and  InvertHyperbolic 
are  the  C  implementations  of  the  algo¬ 
rithms  described  above.  They  all  take 
as  arguments  the  initial  values  for  lx,y,z\-, 
they  leave  their  results  in  the  global 
variables  X,  Y,  and  Z.  Considering  their 
versatility  and  the  wide  range  of  func¬ 
tions  they  compute,  these  routines  are 
compact  and  elegant! 
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Listing  One  (Text  begins  on  page  1 52.) 

/*  cordicC.c  —  J.  Pitts  Jarvis,  III 

*  cordicC.c  computes  CORDIC  constants  and  exercises  the  basic  algorithms. 

*  Represents  all  numbers  in  fixed  point  notation.  1  bit  sign, 

*  longBits-l-n  bit  integral  part,  and  n  bit  fractional  part.  'n=29  lets  us 

*  represent  numbers  in  the  interval  (-4,  4)  in  32  bit  long.  Two's 

*  complement  arithmetic  is  operative  here. 

*/ 

♦define  fractionBits  29 

♦define  longBits  32 

♦define  One  (010000000000»1) 

♦define  HalfPi  (014441766521»1) 


cordic  algorithm  identities  for  circular  functions,  starting  with  [x,  y,  z] 
and  then 

driving  z  to  0  gives:  [P* (x*cos (z) -y*sin (z) ) ,  P* (y*cos (z) +x*sin (z) ) ,  0] 

driving  y  to  0  gives:  [P*sqrt (xA2+yA2) ,  0,  z+atan(y/x)] 

where  K  =  1/P  =  sqrt(l+l)*  .  .  .  *sqrt {1+ (2* (— 2*i) ) ) 

special  cases  which  compute  interesting  functions 

sin,  cos  [K,  0,  a]  ->  [cos  (a),  sin  (a),  0] 

atan  [1,  a,  0]  ->  [sqrt (l+aA2) /K,  0,  atan(a)] 

[x,  y,  0]  ->  [sqrt (xA2+yA2) /K,  0,  atan(y/x)] 
for  hyperbolic  functions,  starting  with  [x,  y,  z]  and  then 
driving  z  to  0  gives:  [P* (x*cosh (z) +y*sinh (z) ) ,  P* (y*cosh (z) +x*sinh (z) ) ,  0] 
driving  y  to  0  gives:  [P*sqrt (xA2-yA2) ,  0,  z+atanh (y/x) ] 
where  K  =  1/P  =  sqrt (1- (1/2) A2) *  .  .  .  *sqrt (1- (2A (~2*i) ) ) 

[K,  0,  a]  ->  [cosh(a),  sinh(a),  0] 

[K,  K,  a]  ->  [eAa,  eAa,  0] 

[1,  a,  0]  ->  [sqrt (l-aA2) /K,  0,  atanh(a)] 

[x,  y,  0]  ->  [sqrt (xA2-yA2) /K,  0,  atanh(y/x)] 

*  In  [a+1,  a-1,  0]  ->  [2*sqrt (a) /K,  0,  ln(a)/2] 

*  sqrt  [a+ (K/2) A2,  a-(K/2)A2,  0]  ->  [sqrt(a),  0,  In (a* (2/K) A2) /2] 

*  sqrt,  In  [a+(K/2)A2,  a-(K/2)A2,  -In (K/2) ]  ->  [sqrt(a),  0,  ln(a)/2] 

*  for  linear  functions,  starting  with  [x,  y,  z]  and  then 

*  driving  z  to  0  gives:  [x,  y+x*z,  0] 

*  driving  y  to  0  gives:  [x,  0,  z+y/x] 

*/ 


sinh,  cosh 

exponential 

atanh 


long  X0C,  X0H,  X0R;  /*  seed  for  circular,  hyperbolic,  and  square  root  */ 

long  OneOverE,  E;  /*  the  base  of  natural  logarithms  */ 

long  HalfLnXOR;  /*  constant  used  in  simultanous  sqrt,  In  computation  */ 

/*  compute  atan(x)  and  atanh (x)  using  infinite  series 

*  atan(x)  =  x  -  xA3/3  +  xA5/5  -  xA7/7  +  .  .  .  for  xA2  <  1 

*  atanh  (x)  =  x  +  xA3/3  +  xA5/5  +  xA7/7  +  .  .  .  for  xA2  <  1 

*  To  calcuate  these  functions  to  32  bits  of  precision,  pick 

*  terms [i]  s.t.  ( (2A-i) A (terms [ i ] ))/ (terms [i] )  <  2A-32 

*  For  x  <=  2 A  (  — 11 ) ,  atan(x)  =  atanh (x)  =  x  with  32  bits  of  accuracy  */ 
unsigned  terms[ll]=  (0,  27,  14,  9,  7,  5,  4,  4,  3,  3,  3}; 

static  long  a [ 28 ] ,  atan [fractionBits+1] ,  atanh[fractionBits+l] ,  X,  Y,  Z; 
♦include  <stdio.h>  /*  putchar  is  a  marco  for  some  */ 


/*  Delta  is  inefficient  but  pedagogical  */ 
♦define  Delta  (n,  Z)  (Z>=0)  ?  (n)  :  - (n) 
♦define  abs(n)  (n>=0)  ?  (n)  :  -(n) 


/*  Reciprocal,  calculate  reciprocol  of  n  to  k  bits  of  precision 
*  a  and  r  form  integer  and  fractional  parts  of  the  dividend  respectively  */ 
long 

Reciprocal (n,  k)  unsigned  n,  k; 

{ 

unsigned  i,  a=  1;  long  r=  0; 

for  ( i=  0;  i<=k;  ++i)  (r  +=  r;  if  (a>=n)  (r  +=  1;  a  -=  n; } ;  a  +=  a;} 
return (a>=n?  r+1  :  r) ;  /*  round  result  */ 

) 

/*  ScaledReciprocal,  n  comes  in  funny  fixed  point  fraction  representation  */ 
long 

ScaledReciprocal (n,  k)  long  n;  unsigned  k; 

{ 

long  a,  r=0;  unsigned  i; 
a=  lL«k; 

for  (i=0;  i<=k;  ++i)  [r  +=  r;  if  (a>=n)  (r  +=  1;  a  -=  n;};  a  +=  a;); 
return (a>=n?  r+1  :  r) ;  /*  round  result  */ 

) 


/*  Poly2  calculates  polynomial  where  the  variable  is  an  integral  power  of  2, 

*  log  is  the  power  of  2  of  the  variable 

*  n  is  the  order  of  the  polynomial 

*  coefficients  are  in  the  array  a[]  */ 

long 

Poly2{log,  n)  int  log;  unsigned  n; 

{ 

long  r=0;  int  i; 

for  (i=n;  i>=0;  — i)  r=  (log<0?  r»-log  :  r«log)+a[i]; 
return (r) ; 

} 

WriteFraction  (n)  long  n; 
f 

unsigned  short  i,  low,  digit;  unsigned  long  k; 
putchar (n  <  0  ?  :  '  ');  n  =  abs(n); 

putchar  ( (n»fractionBits)  +  '0');  putchar  ('.') ; 

low  =  k  =  n  «  (longBits-fractionBits) ;  /*  align  octal  point  at  left  */ 
k  »=  4;  /*  shift  to  make  room  for  a  decimal  digit  */ 

for  (i=l;  i<=8;  ++i) 

{ 

digit  =  (k  *=  10L)  »  (longBits-4) ; 
low  =  (low  &  Oxf)  *  10; 

k  +=  ((unsigned  long)  (low»4) )  -  ((unsigned  long)  digit  «  (longBits-4) ) ; 
putchar (digit+ ' 0' ) ; 

) 

) 

WriteRegisters () 
f 

printf ("  X:  ");  WriteVarious (X) ; 
printf  ("  Y:  ");  WriteVarious  (Y) ; 
printf  (”  Z:  ");  WriteVarious  (Z) ; 

) 

WriteVarious (n)  long  n; 


I 

WriteFraction (n) ;  printf (" 

) 

Circular (x,  y,  z)  long  x,  y,  z; 

{ 

int  i; 

X  =  x;  Y  =  y;  Z  =  z; 

for  (i=0;  i<=fractionBits;  ++i) 

{ 

x=  X»i;  y=  Y»i;  z=  atan[i]; 

X  -=  Delta (y,  Z) ; 

Y  +=  Delta (x,  Z) ; 

Z  -=  Delta (z,  Z) ; 

) 

I 

InvertCircular (x,  y,  z)  long  x,  y, 

{ 

int  i; 

X  =  x;  Y  =  y;  Z  =  z; 

for  (i=0;  i<=fractionBits;  ++i) 

( 

x=  X»i;  y=  Y»i;  z=  atan[i]; 

X  -=  Delta (y,  -Y) ; 

Z  -=  Delta  (z,  -Y) ; 

Y  +=  Delta (x,  -Y) ; 

) 


(continued  on  page  158) 


Dr.  Dobb's Journal ,  October  1990 

980 


157 


CORDIC  ALGORITHMS 


listing  One  (Listing  continued,  text  begins  on  page  152.) 


Hyperbolic (x,  y,  z)  long  x,  y,  z; 

{ 

int  i; 

X  =  x;  Y  =  y;  Z  =  z; 

for  (i=l;  i<=fractionBits;  ++i) 

{ 

x=  X»i;  y=  Y»i;  z=  atanhji]; 
X  +=  Delta (y,  Z); 

Y  +=  Delta (x,  Z); 

Z  -=  Delta  (z,  Z) ; 
if  ( (i==4) : : (i==13) ) 

( 

x=  X»i;  y=  Y»i;  z=  atanh[i] 
X  +=  Delta (y,  Z)  / 

Y  +=  Delta (x,  Z)  ; 

Z  -=  Delta (z,  Z); 


InvertHyperbolic (x,  y,  z)  long  x,  y,  z; 
{ 

int  i; 

X  -  x;  Y  =  y;  Z  =  z; 

for  (i=l;  i<=fractionBits;  ++i) 

{ 

x=  X»i;  y=  Y»i;  z=  atanh[i]; 

X  +=  Delta (y,  -Y) ; 

Z  -=  Delta (z,  -Y) ; 

Y  +=  Delta (x,  -Y); 
if  ( (i==4) ! 1 (i==13) ) 

{ 

x=  X»i;  y=  Y»i;  z=  atanh[i]; 

X  +=  Delta  (y,  -Y) ; 

Z  -=  Delta  (z,  -Y); 

Y  +=  Delta (x,  -Y); 


Linear (x,  y,  z)  long  x,  y,  z; 

{ 

int  i; 

X  =  x;  Y  =  y;  Z  =  z;  z=  One; 
for  (i=l;  i<=fractionBits;  ++i) 


printf ("Grinding  on  [1,  0,  0]\n" ); 

Hyperbolic (One,  0L,  0L) ;  WriteRegistersO; 

printf ("\n  K:  ");  WriteVarious (X0H=  ScaledReciprocal (X,  fractionBits)); 
printf  ("  R:  ");  X0R=  X0H»1;  Linear(XOR,  0L,  XOR) ;  WriteVarious  (X0R=  Y)  ; 
printf ("XnGrinding  on  [K,  0,  0]\n"); 

Hyperbolic (XOH,  0L,  0L) ;  WriteRegisters () ; 

printf ("XnGrinding  on  (K,  0,  1]  ->  [1.54308064,  1.17520119,  0]\n"); 
Hyperbolic  (XOH,  0L,  One);  WriteRegistersO; 

printf ("XnGrinding  on  [K,  K,  -1]  ->  [0 .36787944,  0.36787944,  0]\n"); 
Hyperbolic  (XOH,  XOH,  -One);  WriteRegistersO; 

OneOverE  =  X;  /*  save  value  In (1/e)  =  -1  */ 

printf ("XnGrinding  on  [K,  K,  1]  ->  [2.71828183,  2.71828183,  0]\n"); 
Hyperbolic  (XOH,  XOH,  One);  WriteRegistersO; 

E  =  X;  /*  save  value  ln(e)  =  1  */ 

printf  ("\n - Inverse  functions - \n")  ; 

printf ("Grinding  on  [1,  0,  0]\n"); 

InvertHyperbolic  (One,  0L,  0L) ;  WriteRegistersO; 

printf ("XnGrinding  on  [1/e  +  1,  1/e  -  1,  0]  ->  [1.00460806,  0, 

-0.50000000] \n"); 

InvertHyperbolic (OneOverE+One, OneOverE-One,  0L) ;  WriteRegistersO ; 
printf ("XnGrinding  on  [e  +  1,  e  -  1,  0]  ->  [2.73080784,  0,  0 . 50000000] Xn") ; 
InvertHyperbolic  (E+One,  E-One,  0L) ;  WriteRegistersO; 
printf ("XnGrinding  on  (l/2)*ln(3)  ->  [0.71720703,  0,  0.54930614] \n") ; 
InvertHyperbolic  (One,  One/2L,  0L) ;  WriteRegistersO; 

printf ("XnGrinding  on  [3/2,  -1/2,  0]  ->  [1.17119417,  0,  -0 . 34657359] Xn") ; 
InvertHyperbolic (One+ (One/2L) ,  -  (One/2L) ,  0L) ;  WriteRegistersO; 
printf ("XnGrinding  on  sqrt(l/2)  ->  [0.70710678,  0,  0 . 15802389] Xn" )  ; 
InvertHyperbolic  (One/2L+XOR,  One/2L-XOR,  0L) ;  WriteRegistersO; 
printf ("XnGrinding  on  sqrt(l)  ->  [1.00000000,  0,  0.50449748] \n") ; 
InvertHyperbolic (One+XOR,  One-XOR,  0L) ;  WriteRegistersO; 

HalfLnXOR  =  Z; 

printf ("XnGrinding  on  sqrt(2)  ->  [1.41421356,  0,  0 . 85117107] \n" ) ; 
InvertHyperbolic  (One*2L+XOR,  One*2L-XOR,  0L) ;  WriteRegistersO; 
printf ("XnGrinding  on  sqrt(l/2),  In (1/2) /2  ->  [0.70710678,  0, 

-0.34657359] \n") ; 

InvertHyperbolic (One/2L+XOR,  One/2L-X0R,  -HalfLnXOR);  WriteRegistersO; 
printf ("XnGrinding  on  sqrt(3)/2,  ln(3/4)/2  ->  [0.86602540,  0, 

-0.14384104] \n"> ; 

InvertHyperbolic ( (3L*One/4L) +X0R,  (3L*One/4L) -XOR,  -HalfLnXOR) ; 
WriteRegisters () ; 

printf ("XnGrinding  on  sqrt(2),  ln(2)/2  ->  [1.41421356,  0,  0.34657359] \n") ; 
InvertHyperbolic (One*2L+XOR,  One*2L-XOR,  -HalfLnXOR); 

WriteRegisters ()  ; 
exit  (0) ; 


x  »=  1;  z  »=  1;  Y  +=  Delta  (x,  Z) ;  Z  -=  Delta  (z,  Z); 


InvertLinear (x,  y,  z)  long  x,  y,  z; 

{ 

int  i; 

X  =  x;  Y  =  y;  Z  =  z;  z=  One; 
for  (i-1;  i<=fractionBits;  ++i) 

( 

Z  -=  Delta  (z  »=  1,  -Y);  Y  +=  Delta  (x  »=  1,  -Y) ; 


Listing  Two 


End  Listing  One 


int  i;  long  r; 

/*system("date") ; *//*  time  stamp  the  log  for  UNIX  systems  */ 
for  (i=0;  i<=13;  ++i) 

( 

a[2*i]=  0;  a[2*i+l]=  Reciprocal (2*i+l,  fractionBits); 

1 

for  (i=0;  i<=10;  ++i)  atanh[i]=  Poly2(-i,  terms [i] ) ; 
atan[0] =  HalfPi/2;  /*  atan(2A0)=  pi/4  */ 
for  (i-1;  i<=7;  ++i)  a(4*i-l]=  -a [4*i-l] ; 
for  (i-1;  i<=10;  ++i)  atan[i]=  Poly2(-i,  terms [ i ] ) ; 

for  (i— 11;  i<=f ractionBits;  ++i)  atan[i]=  atanh[i]=  1L« (fractionBits-i) ; 
printf ("Xnatanh (2A-n) \n") ; 

for  (i-1;  i<=10;  ++i) (printf ("%2d  ",  i) ;  WriteVarious (atanh[i] ); ) 
r=  0; 

for  (i-1;  i<=f ractionBits;  ++i) 
r  +=  atanh [i] ; 
r  +=  atanh[4]+atanh[13] ; 

printf ("radius  of  convergence");  WriteFraction (r) ; 
printf ("\n\natan (2A-n) \n") ; 

for  (i=0;  i<=10;  ++i) [printf ("%2d  ",  i) ;  WriteVarious (atan [i] ); ) 
r=  0;  for  (i=0;  i<=f ractionBits;  ++i)  r  +=  atan[i]; 
printf ("radius  of  convergence");  WriteFraction (r) ; 

/*  all  the  results  reported  in  the  printfs  are  calculated  with  my  HP-41C  */ 

printf  ("\n\n - circular  functions - \n")  ; 

printf ("Grinding  on  [1,  0,  0]\n"); 

Circular  (One,  0L,  0L) ;  WriteRegistersO; 

printf ("\n  K:  ");  WriteVarious (X0C=  ScaledReciprocal (X,  fractionBits)); 
printf ("XnGrinding  on  [K,  0,  0]\n"); 

Circular  (X0C,  0L,  0L) ;  WriteRegistersO; 

printf ( "XnGrinding  on  [K,  0,  pi/6]  ->  (0.86602540,  0.50000000,  0]\n"); 
Circular  (X0C,  0L,  HalfPi/3L) ;  WriteRegistersO; 

printf ("XnGrinding  on  [K,  0,  pi/4]  ->  [0.70710678,  0.70710678,  0]\n"); 
Circular  (X0C,  0L,  HalfPi/2L) ;  WriteRegistersO; 

printf ("XnGrinding  on  [K,  0,  pi/3]  ->  [0.50000000,  0.86602540,  0]\n"); 
Circular  (X0C,  0L,  2L*  (HalfPi/3L) ) ;  WriteRegistersO; 

printf  ("Xn - Inverse  functions - \n") ; 

printf ("Grinding  on  [1,  0,  0]\n"); 

InvertCircular  (One,  0L,  0L) ;  WriteRegistersO; 

printf ("XnGrinding  on  [1,  1/2,  0]  ->  [1.84113394,  0,  0. 46364761] \n") ; 
InvertCircular  (One,  One/2L,  0L) ;  WriteRegistersO; 
printf ( "XnGrinding  on  [2,  1,  0]  ->  [3.68226788,  0,  0.46364761]Xn") ; 
InvertCircular  (One*2L,  One,  0L) ;  WriteRegistersO; 

printf ("XnGrinding  on  [1,  5/8,  0]  ->  [1.94193815,  0,  0 . 55859932 ] \n") ; 
InvertCircular  (One,  5L*(One/8L),  0L) ;  WriteRegistersO; 
printf ("XnGrinding  on  [1,  1,  0]  ->  [2.32887069,  0,  0.78539816] Xn") ; 
InvertCircular  (One,  One,  0L) ;  WriteRegistersO; 
printf  ( "\n - hyperbolic  functions - - Xn") ; 


1  0.54930614 

2  0.25541281 

3  0.12565721 

4  0.06258157 

5  0.03126017 

6  0.01562627 

7  0.00781265 

8  0.00390626 

9  0.00195312 

10  0.00097656 


0xll93ea7a 

0x082c577d 

0x04056247 

0x0200abll 

0x01001558 

0x008002aa 

0x00400055 

0x0020000a 

0x00100001 

0x00080000 


002144765172 

001013053575 

000401261107 

000200125421 

000100012530 

000040001252 

000020000125 

000010000012 

000004000001 

000002000000 


radius  of  convergence  1.11817300 


0  0.78539816 

1  0.46364760 

2  0.24497866 

3  0.12435499 

4  0.06241880 

5  0.03123983 

6  0.01562372 

7  0.00781233 

8  0.00390622 

9  0.00195312 

10  0.00097656 


0xl921fb54 
0x0ed63382 
0x07d6dd7e 
0x03fab753 
OxOlf f 55bb 
OxOOf feaad 
0x007ffd55 
0x003f f faa 
OxOOlf f f f 5 
OxOOOffffe 
0x0007ffff 


003110375524 

001665431602 

000765556576 

000376533523 

000177652673 

000077765255 

000037776525 

000017777652 

000007777765 

000003777776 

000001777777 


radius  of  convergence  1.74328660 


circular  functions 


0xl36e9db3  002333516663 


hyperbolic  functions 


0x26a3d0ed  004650750355 
0xbaal5bl  001352412661 


End  listings 
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Memory  Commander,  recently  an¬ 
nounced  by  V  Communications,  pro¬ 
vides  up  to  960K  of  contiguous  DOS 
memory,  maps  BIOS  ROMs  into  faster 
RAM,  has  LIM  4.0  EMS  emulation,  and 
loads  TSRs  and  device  drivers  into  high 
memory.  With  Memory  Commander 
you  can  install  networks,  drivers,  TSRs, 
and  large  applications  simultaneously. 

DDJ spoke  with  Rick  Gilligan  of  Com¬ 
puter  and  Software  Enterprises  Inc.,  who 
runs  MS-DOS  4.01  to  take  better  advan¬ 
tage  of  his  143-Mbyte  disk  drive.  He 
said  that  “with  Memory  Commander  I 
can  move  device  drivers  into  high  mem¬ 
ory  and  run  CAD  programs  that  require 
as  much  as  550K  of  low  memory.  I  can 
have  one  configuration  now  that  gives 
me  more  than  enough  memory,  and  I 
can  still  have  buffers,  files,  and  drivers 
for  my  programs.  Memory  Commander 
takes  care  of  a  lot  of  things  you  would 
have  to  use  separate  drivers  for;  it  in¬ 
cludes  EMS,  VCPI,  XMS,  and  ANSI  driv¬ 
ers.  The  only  conflict  is  with  Windows 
3.0,  but  no  DOS  extender  works  with 
Windows  in  protected  mode.” 

A  “control  panel”  describes  how  mem¬ 
ory  is  utilized  and  provides  control  op¬ 
tions  for  customizing  Memory  Com¬ 
mander  for  your  system.  A  built-in  RAM 
disk  and  an  internal  ANSI. SYS  replace¬ 
ment  are  included  for  extended  screen 
and  keyboard  support,  and  these  addi¬ 
tions  require  no  DOS  memory.  The 
product  sells  for  $129.95.  Reader  ser¬ 
vice  no.  20. 

V  Communications  Inc. 

4320  Stevens  Creek  Blvd.,  Ste.  275 
San  Jose,  CA  95129 
408-296-4224 
800-648-8266 

ROM-DOS,  a  special-purpose  ROMable 
DOS  for  non-PC  applications,  is  being 
offered  by  Datalight  This  small,  modi¬ 
fiable  operating  system  provides  the 
functionality  of  MS-DOS  3-2,  can  oper¬ 
ate  from  within  ROM,  and  can  boot 
from  a  floppy  or  hard  disk.  It  can  run 


MS-DOS  executable  COM  and  EXE  files 
generated  by  any  MS-DOS  compiler. 

Kevin  Kyriss  of  2Morrow,  makers  of 
a  hand-held  computer  called  “Silent 
Partner,”  told  DDJ  that  their  product 
had  a  limited  future  until  Datalight  put 
their  operating  system  on  it  and  “opened 
it  up  to  a  tremendous  amount  of  applica¬ 
tions.  We  can’t  have  a  disk  drive;  we 
have  RAM  that  is  write-protectable,  and 
ROM-DOS  goes  into  RAM  and  looks 
like  ROM.  You  can  execute  applica¬ 
tions  directly  out  of  ROM,  which  is 
more  efficient  for  RAM.” 

You  can  write  applications  with  the 
language  of  your  choice,  compile  it 
with  whatever  compiler  you  choose, 
and  then  load  it  into  ROM  along  with 
ROM-DOS  to  run  in  the  target  system 
with  no  other  modifications.  With  all 
functions  included,  ROM-DOS  takes 
about  34K  of  ROM  and  uses  as  little  as 
14K  of  RAM  when  running.  And  ROM- 
DOS  can  run  applications  directly,  con¬ 
serving  the  RAM  required  for  COM- 
MAND.COM. 

Datalight  has  developed  a  mini-BIOS 
for  use  in  embedded  systems,  which 
provides  support  for  a  remote  console, 
hardware  timer,  and  serial  ports.  ROM- 
DOS  can  be  customized  to  include  only 
those  functions  that  are  used  by  a  par¬ 
ticular  application.  A  ROM-DOS  Devel¬ 
oper’s  Kit  is  available  for  $495,  and  a 
license  to  the  source  code  costs  $10,000. 
Reader  service  no.  23. 

Datalight 

17505  68th  Ave.  NE,  Ste.  304 
Bothell,  WA  98011 
206-486-8086 

A  C  code  generator  for  Borland’s  Para¬ 
dox  Engine  is  available  from  Concept 
Dynamics.  PARAGen  examines  the 
data  structure  of  user-defined  Paradox 
tables  and  produces  code  to  perform 
a  variety  of  operations  on  those  tables. 

Daniel  Sullivan  of  Concept  Dynam¬ 
ics  told  DDJ  that  “we  developed 
PARAGen  for  our  own  internal  use. 
We  gave  a  demo  to  a  Paradox  user’s 
group,  and  found  lots  of  interest  in  it. 
We  are  trying  to  appeal  to  a  cross-over 
segment,  to  C  programmers  who  are 
interested  in  database  development  but 
haven’t  used  Paradox  because  of  the 
prior  inability  to  read  and  write  Para¬ 
dox  files.  Our  next  version  will  support 
C++  and  Pascal,  as  well  as  C.” 

PARAGen  allows  developers  to  use 
the  PC  to  generate  database  access  code 
specific  to  their  applications.  The  Para¬ 
dox  Engine  provides  generic  functions 
for  performing  table  operations  but 
these  have  no  knowledge  of  the  tables 
defined  by  the  application  developer  — 
PARAGen  links  an  application  with 
the  Paradox  Engine. 


Functions  generated  by  PARAGen 
will  open,  close,  create,  and  empty  Para¬ 
dox  tables.  Record-level  operations  in¬ 
clude  full  and  partial  key  searches,  first, 
last,  next,  and  previous  record  fetches, 
and  field  searches.  Append,  insert,  and 
delete  record  operations  are  also  pro¬ 
vided.  The  product  sells  for  $99,  and 
demonstration  versions  are  available 
on  CompuServe.  Reader  service  no.  21 . 
Concept  Dynamics  Ltd. 

1147  S.  Euclid 
Oak  Park,  IL  60304 
708-524-2814 

Version  2.1  of  TSX-32,  a  multiuser,  mul¬ 
titasking,  and  DOS-compatible  operat¬ 
ing  system  for  80386  and  80486  ma¬ 
chines,  has  been  announced  by  S&H 
Computer  Systems.  TSX-32  offers  vir¬ 
tual  memory  with  demand  paging,  file 
access  control,  printer  spooling  and 
queueing,  and  32-bit  program  execu¬ 
tion.  It  is  binary-compatible  with  DOS 
programs  that  use  Phar  Lap’s  DOS  Ex¬ 
tender. 

Some  new  features  are  faster  I/O 
(achieved  through  improvements  in  data 
caching,  cache  flushing,  and  desk  seek 
optimization) ,  VGA  and  EGA  color  graph¬ 
ics,  SCSI  host  adapters,  and  9-track  tape. 
The  system  uses  an  “Adaptive  Schedul¬ 
ing  Algorithm”  (ASA)  that  dynamically 
orders  and  reorders  system  priorities 
based  on  the  nature  of  the  tasks  to  be 
performed.  The  ASA  makes  distinctions 
between  interactive,  real-time,  and  low- 
priority  operations.  An  unlimited  users 
license  with  one  year  of  support  and 
updates  costs  $1,450.  Reader  service 
no.  32. 

S&H  Computer  Systems  Inc. 

1027  17th  Ave.  South 
Nashville,  TN  37212 
615-327-3670 

Microsoft  Windows  developers  may  be 
interested  in  JT  Software’s  JTW  C++ 
class  library,  which  provides  a  ready¬ 
made  environment  for  developing  Win¬ 
dows  applications. 

JTW  includes  more  than  96  classes, 
a  portion  of  which  act  as  a  high-level 
interface  between  Windows  and  the 
application  (to  facilitate  ports  to  other 
environments).  Other  classes  provide 
generic  means  for  representing  the  ap¬ 
plication’s  data,  either  in  the  form  of 
simple  container  classes,  or  in  a  higher- 
level  family  of  classes  that  integrate 
into  the  windowing  environment  by 
keeping  different  views  of  the  data  in 
sync,  and  by  providing  members  that 
generically  handle  common  operations 
such  as  those  required  by  a  standard 
File  menu. 

Additional  classes  represent  com- 
(continued  on  page  166) 
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(continued  from  page  161) 
monly  used  windows,  dialog  boxes, 
and  controls  (TextEdit,  OpenDialog, 
PushButton).  And  procedural  and  object- 
oriented  graphics  capability  is  included. 
The  $150  price  includes  full  sources, 
user  guide  and  reference  manual,  and 
sample  programs.  JTW  supports  the 
Zortech  and  Glockenspiel  C++  compil¬ 
ers  and  requires  Windows  SDK.  Reader 
service  no.  22. 

JT  Software 
P.O.  Box  4292 
Santa  Clara,  CA  95054 
408-727-8591 

SilverScreen,  a  3-D  CAD/Solids  Model¬ 
ing  software  system  from  Schroff  De¬ 
velopment  Corporation,  is  now  avail¬ 
able  for  licensing  as  a  CAD  engine. 
Some  of  SilverScreen’s  features  are  2-D 
and  3-D  Boolean  operations,  shading 
(and  shadows),  rendering,  hidden  line 
removal,  camera  walk,  text  editor,  as¬ 
sociative  dimensioning,  mass  proper¬ 
ties,  the  ability  to  import  and  export 
DXF  and  IGES  files,  and  the  ability  to 
export  in  the  HPGL  format. 

The  system  includes  a  resident  C  com¬ 
piler  that  allows  you  to  create  custom 
applications.  The  compiler  implements 
a  library  of  over  200  functions,  includ¬ 
ing  a  subset  of  the  standard  C  library. 
And  developers  have  access  to  a  large 
number  of  functions  which  use  the  Sil¬ 
verScreen  database  and  control  the  Sil¬ 
verScreen  environment.  Contact  the  com¬ 
pany  for  pricing  information.  Reader 
service  no.  24. 

Schroff  Development  Corp. 

4732  Reinhardt  Dr. 

Roeland  Park,  KS  66205 
913-262-2664 

GrafPrint,  printer  graphics  libraries  that 
support  Turbo  C/C++,  Microsoft  C/ 
QuickC,  and  Watcom  C  and  C/386  graph¬ 
ics  libraries,  are  available  from  AnSoft 
Inc.  You  can  develop  programs  in  any 
video  mode,  and  GrafPrint  maps  the 
screen  graphics  to  any  other  video  mode 
and  to  the  printer. 

It  currently  supports  output  on  HP 
LaserJet/DeskJet/PaintJet,  Epson  FX/MX/ 
LQ,  and  compatibles.  Grafprint  can  use 
EMM  3-2  and  over  and  adds  integer 
and  floating-point  viewports  on  the 
screen  and  printer.  GrafPrint  Personal 
sells  for  $150  and  Grafprint  Developers 
for  $300  (no  royalties).  Reader  service 
no.  31. 

AnSoft  Inc. 

8254  Stone  Trail  Ct. 

Laurel,  MD  20723 
301-  470-2335 

A  fully  supported  library  of  reusable 
C++  software  components  is  available 


from  Empathy  Inc.  Classix  incorpo¬ 
rates  object-oriented  design  techniques 
and  heuristics  in  C++  classes  that  cover 
abstractions  in  the  areas  of  data  struc¬ 
ture  design,  mathematical  support  ob¬ 
jects,  Smalltalk-like  classes,  and  mim¬ 
ics  of  the  primitive  data  types.  Classix 
also  includes  a  parameterization  utility 
for  reusing  classes  with  different  data 
types. 

Classix  has  over  35  classes  and  800 
operations,  and  includes  inheritance  and 
containment  in  the  underlying  design 
structure.  Classix  is  offered  in  source 
code  format  only  for  use  with  Glock¬ 
enspiel  C++,  Sun  C++,  GNU  C++, 
Zortech  C++,  and  MPW  C++.  Prices 
start  at  $295.  Reader  service  no.  25. 
Empathy  Inc. 

P.O.  Box  632 
Cambridge,  MA  02142 
617-787-3089 

NABJA  Software,  developer  of  object- 
oriented  programming  tools,  has  an¬ 
nounced  that  NABJAooc,  its  object- 
oriented  development  environment  for 
C,  now  supports  Microsoft  C  6.0. 

NABJAooc  uses  MS  C’s  help  system 
to  provide  an  online  hypertext  refer¬ 
ence  that  includes  a  full  class  hierarchy 
which  allows  the  user  to  browse  through 
both  system  and  user  class  definitions. 
It  was  designed  for  C  programmers 
who  want  to  code  in  ANSI  C  but  also 
want  the  benefits  of  OOP  —  without 
learning  a  new  language. 

NABJAooc  features  full  implementa¬ 
tion  of  the  object-oriented  paradigm, 
including  multiple  inheritance;  support 
for  integrated  programming  environ¬ 
ments;  compatibility  with  existing 
source-level  debuggers,  including  Code¬ 
View;  foundation  classes,  with  source 
code,  for  basic  data  structures;  a  mes¬ 
sage-trace  facility;  and  less  than  10K 
of  overhead  for  the  base  system.  NABJA¬ 
ooc  sells  for  $49,  or  $99  with  source 
code.  Reader  service  no.  27. 

NABJA  Software 
P.O.  Box  413 
Girard,  PA  16417-0413 
814-774-3699 

Bar  art’s  Tech  Letter,  a  publication 
covering  the  NeXT  Computer,  provides 
news  and  analysis  of  new  products 
and  technological  developments  for  and 
around  the  NeXT  Computer. 

Nicholas  Baran  told  DDJ  that  “there 
are  no  publications  for  the  NeXT  Com¬ 
puter  other  than  by  user  groups  and 
an  academic  report  published  by  the 
company”  and,  said  Baran,  “there’s  a 
need  for  a  publication  that’s  not  in  love 
with  Steve  Jobs.” 

Baran ’s  Tech  Letter  will  cover  such 
topics  as  third-party  software,  Postscript 


Level  2,  Motorola’s  96002  digital  signal 
processor,  and  the  level  of  dedication 
of  such  players  as  IBM.  IBM  has  li¬ 
censed  NextStep,  and  according  to  Ba¬ 
ran  appears  to  be  hedging  its  bets  on 
whether  NextStep  or  OSF  Motif  will 
emerge  dominant.  The  subscription  rate 
for  12  issues  is  $125.  Reader  service 
no.  28. 

Baran’s  Tech  Letter 
P.O.  Box  876 

Sandpoint,  ID  83864-0876 
208-265-5286 

Pixelab  has  released  GSPOT,  a  sym¬ 
bolic  debugger  for  the  Texas  Instru¬ 
ments  34010.  GSPOT  (short  for  “graph¬ 
ics  system  processor  operating  tool”) 
includes  full  floating-point  support  and 
TIGA  support,  and  is  designed  to  run 
on  a  PC  or  compatible.  Its  features  are 
designed  to  make  debugging  in  a  “host- 
target”  environment  simple;  for  exam¬ 
ple,  the  ability  to  install  GSPOT  as  a 
resident  program  while  using  another 
debugger  for  the  host  processor. 

GSPOT  can  be  configured  to  work 
with  any  GSP-based  hardware,  includ¬ 
ing  TI’s  SDB  board.  Other  features  in¬ 
clude  symbolic  debugging,  C  source 
debugging,  a  user-interface  similar  to 
CodeView,  online  assembly,  a  memory 
display/edit  mode,  watchpoints,  script 
files,  and  so  on.  Version  1.0  sells  for 
$995.  Reader  service  no.  30. 

Pixelab  Inc. 

4513  Lincoln  Ave.,  Ste.  105 
Lisle,  IL  60532 
708-960-9339 

ExploreNet  3000,  a  neural  network  ap¬ 
plication  development  environment  that 
uses  Windows  3.0,  has  been  announced 
by  HNC.  A  variety  of  predefined  exam¬ 
ple  applications  are  included.  Explore¬ 
Net  3000  is  a  flexible,  icon-based  envi¬ 
ronment  in  which  users  can  define  and 
create  applications  by  selecting  icons 
on  the  screen,  specifying  parameters, 
and  linking  individual  modules  together. 
Some  major  modules  are  the  file  mod¬ 
ule,  data  transformation  module,  pipe 
module,  network  module,  and  display 
module. 

ExploreNet  3000  also  incorporates 
watchpoints  and  control  functions  for 
monitoring  network  training  and  test¬ 
ing  results.  A  programmatic  interface 
is  provided  if  you  prefer  to  work  in  C. 
The  product  sells  for  $1,495.  Reader 
service  no.  29. 

HNC 

5501  Oberlin  Dr. 

San  Diego,  CA  92121-1718 
619-452-6524 
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Is  Copyrighting  Software  Futile? 


The  purpose  in  copyrighting  a  piece  of  software  is  to  control  its  copying  and/or  commercial 
use.  Richard  Stallman  has  extensively  questioned  the  desirability  of  this  purpose.  I’m  going 
to  do  something  simpler:  Question  its  feasibility.  Let’s  consider  three  cases. 

Case  I:  Copying  at  the  Office 

Laws  that  cannot  be  enforced  are  vacuous.  Laws  whose  violations  cannot  be  detected  cannot  be 
enforced.  Violations  occurring  in  an  office  cannot  be  detected  unless  an  employee  blows  the  whistle 
or  the  violator  is  careless.  Whistle-blowing  is  not  a  common  phenomenon.  Consider  conscientious 
office  worker  Clara  Tillinghast.  Her  company  pollutes  the  environment,  at  least  one  male  executive 
she  knows  of  makes  improper  advances  to  female  employees,  her  boss  regularly  lies  to  customers, 
and  the  person  in  the  next  office  has  an  unauthorized  copy  of  Lotus  1-2-3.  What  will  Clara  do? 

Even  if  Clara  doesn’t  get  on  the  phone  to  Lotus,  the  person  in  the  next  office  might  get  careless, 
leaving  a  hand-labeled  diskette  lying  about  when  Jim  Manzi  is  visiting  the  office,  say.  But  with  the 
prevalence  of  hard  disks,  there  need  be  no  illegal  diskette  to  observe,  and  the  illegal  copy  can  be 
erased  in  seconds.  No,  the  sad  fact  is  that  user  carelessness  is  not  something  software  vendors  can 
count  on. 

One  strategy  is  to  issue  site  license  contracts  that  are  cheap  enough  to  make  even  the  small  risk 
of  detection  unacceptable.  But  this  leaves  pricing  out  of  vendor  control.  Since  there  is  no  clear 
formula  for  determining  the  ratio  of  site  licensing  price  to  single  copy  price,  tight  competition  in 
any  product  category  could  conceivably  drive  this  ratio  arbitrarily  close  to  one.  That  is,  the  vendor 
will  effectively  sell  one  copy  per  office. 

But  it  has  been  mooted  that  what  really  sells  multiple  copies  of  a  program  into  an  office  is  the 
need  for  manuals.  If  so,  the  trend  toward  online  documentation  could  be  disastrous.  And  the  trend 
is  compelling:  The  user  really  ought  to  be  able  to  get  the  answer  at  the  point  and  in  the  medium 
where  the  question  arises;  software  can  be  produced  more  economically  without  hardcopy 
manuals;  and  it  can  be  produced  to  tighter  deadlines,  hence  more  competitively,  if  two  distinct 
production  lines  don’t  have  to  finish  simultaneously.  If  hardcopy  manuals  are  all  that  makes 
multiple  sales  to  an  office  possible,  the  elimination  of  hardcopy  manuals  will  also  lead  to  one  copy 
per  office. 

Case  II:  Copying  at  Home 

Here  the  risk  of  detection  due  to  carelessness  and  the  reward  for  whistle  blowing  both  drop  to  zero, 
which  is  why  copy  protection  hasn’t  gone  away  in  game  software.  But  games  are  generally  cheap 
and  ephemeral,  and  copy  protection  has  been  so  discredited  in  the  broad  business  software  market 
that  it  is  unlikely  to  come  back.  What  happens  if  the  trend  toward  working  at  home  continues? 

Consider  the  pressures.  The  company  supplies  ambitious  home-office  worker  Bob  Slocum  with 
mediocre  spreadsheet  program  X.  A  barrage  of  ads  tells  Bob  that  spreadsheet  program  Wwill  give 
him  the  edge  over  his  rival  for  promotion,  Jack  Green.  Bob  can’t  afford  to  buy  IVhimself  and  the 
company  won’t  spring  for  it,  but  he’s  sure  that  Jack  is  just  the  sort  of  guy  to  take  unfair  advantage 
by  pirating  W.  As  a  home-office  worker,  Bob  naturally  belongs  to  a  user  group,  where  he  knows 
he  can  pick  up  W for  nothing.  What  will  Bob  do? 

It’s  easy  to  imagine  a  vicious  cycle  developing,  with  home-office  workers  copying  software 
because  they  can’t  afford  to  buy  it  and  vendors  raising  prices  because  of  the  diminished  sales.  Pretty 
soon,  they’re  selling  one  copy  per  user  group. 

Case  III:  Copying  in  Cyberspace 

Let’s  postulate  what  many  would  call  the  worst  scenario,  and  what  I  have  been  painting  as  the 
most  plausible  scenario.  No  office  buys  more  than  one  copy  of  a  piece  of  software,  and  all  home 
users  get  their  software  from  friends  in  user  groups.  This  still  lets  the  software  vendor  sell  a  copy 
to  each  office  and  each  user  group,  right? 

It’s  actually  possible  to  imagine  an  industry  configured  this  way,  although  pricing  for  software 
would  have  to  be  high  because  every  purchase  would  be  a  group  purchase.  In  this  scenario,  the 
direct  customers  would  be  defined  by  access  considerations.  Since  copyright  violation  would  still 
be  illegal,  sending  unauthorized  copies  through  the  mail  might  be  seen  as  too  risky,  and  sending 
them  by  phone  would  surely  be  too  expensive.  Copying  would  all  be  local:  User  groups  would 
be  sneakernet-bound  and  offices  would  be  site-bound.  User  groups  would  have  to  find  a  way  to 
get  money  to  pay  for  the  software  they’d  buy,  but  selling  support  suggests  itself  as  a  possibility.  It 
might  work. 

Maybe.  We’ll  have  to  see  what  the  bit-per-second  pricing  for  phone  service  is  when  wide- 
bandwidth  phone  service  goes  national  in  1992. 

Michael  Swaine 
editor-at-large 
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Galveston  Dr.,  Redwood  City,  CA  94063, 
or  call  800-356-2002  (inside  Calif.)  or  800- 
533-4372  (outside  Calif.).  Specify  issue  num¬ 
ber  and  disk  format.  Code  is  also  available 
through  the  DDJ  Forum  on  CompuServe 
(type  GO  DDJ)  and  through  M&T’s  Telepath 
Conferencing  system. 


NEXT  ISSUE _ 

With  the  onset  of  winter,  we’ll  examine  the 
hard,  cold  facts  surrounding  data  communi¬ 
cations  and  connectivity  in  our  December 
issue. 
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EDIIOJI  A  L 


School  Days, 
Legal  Maze 


It  was  in  our  July  issue,  if  you  recall,  that  I  announced  the  Kent  Porter  Scholarship  for  college 
students  working  toward  degrees  in  computer  science.  Now  that  the  school  year  is  underway, 
I’m  honored  to  award  scholarships  (in  the  amount  of  $500  each)  to  the  following  individuals: 

Victor  J.  Duvanenko 
North  Carolina  State  University 
Raleigh,  North  Carolina 

Theresa  McMurray 
Stephen  F.  Austin  State  University 
Nacogdoches,  Texas 

Mark  S.  Kessel 

University  of  Colorado/Boulder 
Boulder,  Colorado 

James  D.  Marco 
State  University  of  New  York 
Utica,  New  York 

Congratulations  to  each  and  every  one.  Those  of  us  at  DDJ are  glad  to  play  at  least  a  small  part 
in  helping  you  realize  your  goals. 

I’d  also  like  to  once  again  thank  those  of  you  who  made  contributions  to  the  scholarship  fund. 
And  don’t  forget  that  because  the  program  is  on-going,  we’ll  be  awarding  scholarships  for  the 
1991-92  school  year. 

Software  Patents 

It’s  not  often  that  I  ask  you  to  read  a  particular  article,  but  this  month  is  an  exception.  For  goodness 
sakes,  turn  to  page  64  and  read,  think  about,  and  respond  in  some  way  to  the  article  “Software 
Patents.”  If  you  write  software,  this  analysis  may  be  one  of  the  most  important  articles  you’ll  read 
for  a  long  time  to  come. 

Is  the  practice  of  patenting  algorithms  dangerous  and,  in  the  end,  detrimental  to  the  spirit  of 
innovation  in  the  software  development  process?  Consider  this  recent  phone  call  from  a  DDJ  reader: 
The  small  software  house  where  the  caller  worked  had  spent  nearly  a  year  developing  an 
application  for  a  client.  The  program  did  what  it  was  supposed  to  do  very  well  and  the  client 
accepted  it.  Upon  examining  the  source  code,  however,  one  of  the  client’s  programmers  ran  across 
an  algorithm  he  knew  to  be  patented.  Until  that  time,  our  caller  had  no  knowledge  of  any  existing 
patents  on  the  algorithm.  Furthermore,  he  said,  he  may  very  well  have  implemented  several  other 
patented  algorithms  —  he  just  doesn’t  know.  The  algorithm  in  question  is  widely  implemented,  as 
were  others  in  the  same  program.  In  any  event,  the  client  is  now  requiring  licenses  on  all  patented 
algorithms  before  accepting  the  package.  The  caller  would  be  more  than  willing  to  pay  any 
necessary  license  fees,  if  he  just  knew  which  algorithms  were  patented  and  who  owns  thosi. 
patents.  The  first  question  you  might  ask  is,  what  would  you  do  if  you  were  in  the  caller’s  shoes? 
After  you  read  the  article,  don’t  stop  there.  Tell  us  what  you  think  about  the  subject.  Let  us  know 
if  you’ve  had  problems  dealing  with  patented  programming  techniques  such  as  that  described 
above.  Or,  for  that  matter,  tell  us  if  you  hold  a  software  patent  and  why  you  think  it  is  important 
to  do  so. 

Incidentally,  the  September/October  1990  issue  of  American  Heritage  magazine  includes  a 
historical  perspective  on  how  we  got  into  the  patenting  mess  we’re  in  today.  The  article,  entitled 
“The  Power  of  Patents”  by  Oliver  E.  Allen,  paints  a  not-so-pretty  picture,  and  you  can  easily  draw 
parallels  between  the  patent  process  in  the  Industrial  Age  in  the  first  part  of  this  century  and  what’s 
going  on  today.  For  further  study,  the  author  recommends  The  United  States  Patent  System:  Legal 
and  Economic  Conflicts  in  American  Patent  History  by  Floyd  L.  Vaughn  (University  of  Oklahoma 
Press,  1956)  and  America  by  Design  by  David  F.  Noble  (Alfred  A.  Knopf,  1977). 

Rhealstone  Lives! 

Nearly  two  years  ago,  DDJ  proposed  the  Rhealstone,  a  suite  of  benchmarks  for  evaluating  real-time 
systems,  authored  by  Robin  Kar.  (See  “Rhealstone:  A  Real-Time  Benchmarking  Proposal,”  February 
1989  and  “Implementing  the  Rhealstone  Real-Time  Benchmark,”  April  1990.) 

Our  proposal  was  just  that  —  a  proposal  —  and  we  wanted  others  to  evaluate,  criticize,  refine,  and 
continue  the  dialogue.  With  this  in  mind,  you  might  want  to  check  out  the  article  “Shootout  at  the  RT 
Corral”  by  Bruce  Koball  and  Alex  Novickis  in  Embedded  Systems  Programming  magazine  (September 
1990)  where  the  authors  analyze  and  polish  the  Rhealstone  (and  Hartstone)  benchmarks. 


Jonathan  Erickson 
editor-in-chief 
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Catching  A  Few  Rays 

Dear  DDJ 

Your  recent  article,  “Ray  Tracing,”  by 
Daniel  Lyke  (September  1990)  has 
touched  on  a  subject  close  to  my  heart. 
We  in  the  optics  business  are  always 
tracing  rays,  not  to  make  nice  pictures, 
but  to  design  lenses.  My  own  specialty 
is  stray  light  analysis,  in  which  even 
more  rays  are  traced.  The  equations 
used  in  the  article  to  describe  reflection 
in  terms  of  a  unit  normal  vector  and 
an  incident  ray  unit  vector,  are  among 
theequations  I  use  in  writing  stray  light 
analysis  programs.  In  stray  light  analy¬ 
sis  programs,  however,  we  also  com¬ 
pute  scattered  and  diffracted  “rays”  with 
good  radiometric  accuracy. 

Let  me  back  up  for  a  moment  and 
briefly  describe  what  stray  light  analy¬ 
sis  is.  I’m  sure  you’ve  heard  the  advice 
given  to  amateur  photographers  to  avoid 
shooting  into  the  sun.  The  reason  is 
that  the  sun  will  reflect  off  of  lens  sur¬ 
faces  and  scatter  off  the  inside  of  the 
lens  barrel,  causing  much  stray  light 
and  spoiling  the  picture.  The  job  of  the 
stray  light  analyst  is  to  quantify  this 
stray  light  versus  position  of  the  sun, 
or  any  other  bright  source  of  light.  Sev¬ 
eral  computer  programs  have  been  writ¬ 
ten  to  accurately  analyze  stray  light.  The 
accuracy  required  is  extreme:  An  opti¬ 
cal  system  may  reduce  stray  light  by  a 
factor  of  10'10  with  an  elaborate  system 
of  baffles,  and  the  answer  must  still  be 
known  within  about  a  factor  of  two. 

For  the  past  ten  years  I  have  main¬ 
tained  a  stray  light  analysis  program 
(written  in  Fortran  around  1970  for  a 
mainframe  computer),  and  I  have  re¬ 
cently  completed  a  new  stray  light  analy¬ 
sis  program  (under  contract)  written 
in  C  for  the  IBM  PC.  Both  use  Monte 
Carlo  methods  to  sample  the  stray  light. 
I  have  always  viewed  the  computer 
graphics  industry  from  afar,  with  envy, 
but  long  ago  realized  that  stray  light 
programs  would  make  wonderful  en¬ 
gines  for  creating  photo-realistic  im¬ 
ages.  Alas,  I  have  never  had  the  time 
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(i.e.  funding)  to  find  out  just  how  good 
they  would  be. 

The  programs  I  work  with  can  cur¬ 
rently  model  any  second-order  surface. 
By  this  I  mean  any  surface  that  can  be 
represented  by  a  second-order  equa¬ 
tion  in  Cartesian  coordinates.  This  in¬ 
cludes  spheres,  cones,  any  conic  sec¬ 
tion  of  revolution  (paraboloids,  ellip¬ 
soids,  hyperboloids,  oblate  spheroids), 
and  all  combinations  such  as  parabolic 
cylinders,  elliptic  cones,  hyperbolic  para¬ 
boloids,  etc.  They  can  also  model  planes 
and  tori,  which  are  fourth-order  sur¬ 
faces.  Many  objects  can  be  built  up 
from  these  basic  surface  types.  Not  only 
that,  but  stray  light  analysis  programs 
can  also  accurately  model  light  emitted 
by  hot  objects. 

The  aspect  of  your  article  that  struck 
home  is  that  the  same  techniques  you 
used  for  tracing  rays  are  also  used  in 
stray  light  analysis  programs,  with  sur¬ 
faces  being  represented  in  a  global  co¬ 
ordinate  system  and  second-order  ray- 
surface  intercepts  being  solved  using 
the  good  old  quadratic  equation.  The 
rest  of  the  optics  industry  represents 
surfaces  relative  to  one  another  with 
no  global  coordinate  system  and  uses 
specialized  ray  tracing  equations.  A  dif¬ 
ference  between  stray  light  and  com¬ 
puter  graphics  is  that  with  my  pro¬ 
grams,  I  often  trace  rays  starting  from 
the  source  and  going  toward  the  detec¬ 
tor,  just  like  the  real  photons.  (The 
detector  may  be  an  eye,  photographic 
film,  vidicon,  or  electro-optic  detec¬ 
tor.)  The  computer  graphics  industry 
seems  to  have  revived  the  ideas  of  the 
ancient  Greeks,  who  believed  that  light 
emanates  from  the  eyes  to  allow  the 
observer  to  see. 

In  conclusion,  I  have  nothing  to  re¬ 
port  other  than  my  own  enthusiasm 
and  hope  that  I  may  have  time  to  ex¬ 
periment  with  computer  graphics  be¬ 
fore  it’s  too  late.  I  am  soon  to  have  a 
486  computer  with  1024  VGA  display 
on  my  desk,  however,  so  I  may  find  the 
temptation  to  experiment  irresistible. 

Edward  R.  Freniere,  Vice  President 

Telic  Optics,  Inc. 

Marlborough,  Massachusetts 
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Optimizing  Super  VGA 

Dear  DDJ, 

Christopher  Howard’s  “Super  VGA  Pro¬ 
gramming”  (DZyjuly  1990)  is  well  writ¬ 
ten  and  informative.  I  have  a  problem, 
however,  with  his  inference  (at  the  top 
of  page  22)  that  checking  for  a  video 
bank  switch  must  be  done  on  a  pixel-by- 
pixel  rather  than  a  line-by-line  basis. 

It  is  entirely  possible  to  load  not  only 
a  line,  but  multiple  lines,  without  wor¬ 
rying  about  running  into  a  bank  bound¬ 
ary.  The  following  code  fragment  (taken 
directly  from  Blackhawk’s  “Database 
Graphics  Toolkit”)  illustrates  how  to  do 
this  (the  numbers  chosen  let  us  load  80 
columns  of  previously  formatted  16-line 
graphics-mode  text  with  a  single  move 
(80  x  8  =  640;  640  x  16  =  10240;  65536 
-  10240  =  55296)).  See  Example  1. 

The  substance  of  this  method  is  to 
divide  the  bank-switching  problem  into 
a  video  hardware  component  and  a 
memory  access  component;  it  works 
because  a  memory  reference  falling 
within  video  memory  will  always  be 
directed  to  video  memory,  whether  or 
not  the  segment  register  points  to  its 
start. 

A  possible  objection  to  the  method 
is  that,  on  a  dual-monitor  system,  one 
might  run  into  the  monochrome  video 
buffer  at  segment  0B000H,  but,  by  shift¬ 
ing  the  DI  register  down,  the  method 
itself  prevents  this. 

John  D.  Brink,  President 

Blackhawk  Data  Corporation 

Chicago,  Illinois 

Chris  responds:  My  quick  comment 
about  optimizations  only  stated  that 
some  optimizations  were  limited.  To 
expand  a  little  further,  1  know  of  some 
software  packages  that  optimize  by  stor¬ 
ing  an  array  of  pointers  to  each  scan¬ 
line.  This  gets  around  interleaving  prob¬ 
lems,  etc.,  but  it  does  not  work  if  the 
scanline  crosses  a  64K  bank  boundary. 

What  you  refer  to  in  your  letter  is 
similar  to  what  we  do  in  our  GX  Devel¬ 
opment  Series  of  program?ning  tools. 
We  call  it  Thresholding  which  defines 
the  point  at  which  we  can  move  a 
(continued  on  page  12) 
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bnkchk : 

push 

dx; 

AH:DI  contains  computed  offset. 

cmp 

ah,  BNK; 

Have  we  gone  past  a  boundary? 

je 

sambnk; 

If  so,  no  hardware  changes. 

mov 

BNK,  ah; 

Save  new  bank  number. 

call 

[BNKAD] ; 

Do  hardware  bank  switch. 

sambnk : 

mov 

dx, OaOOOh; 

Load  standard  VidRam  segment. 

cmp 

di, 55296; 

Memory  wraparound  possible? 

jb 

bnkext; 

If  not,  use  standard  VidRam  segment. 

add 

dx, 640 

Move  segment  forward  640  paragraphs. 

sub 

di, 10240; 

Move  index  back  same  amount . 

bnkext : 

mov 

es, dx; 

Set  ES  register. 

pop 

dx; 

DX  preserved,  AX  destroyed. 

ret; 

ES,DI  altered  on  return. 
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(continued  from  page  8) 
given  amount  of  data  the  fastest  way 
possible.  If  we  are  below  the  threshold , 
we  use  fast  rep  movsw  instructions.  If 
we  are  above  the  threshold,  we  need  to 
move  more  slowly  and  wait  for  the  point 
at  which  the  bank  needs  changing. 

However,  your  programming  exam¬ 
ple  is  incorrect  as  written.  When  you 
are  checking  for  a  memory  wrap¬ 
around,  you  are  in  effect  checking  for 
what  we  call  the  threshold.  Except  if  a 
wraparound  is  possible,  you  are  simply 
calculating  a  new  segment:  offset  for 
the  same  memory  location.  This  does 
not  prevent  the  wraparound,  it  merely 
insures  that  DI  does  not  overflow.  In 
fact,  it  converts  a  memory  wraparound 
problem  into  a  memory  overwrite  prob¬ 
lem.  Instead  of  wrapping  back  up  to 
AOOOH,  it  makes  sure  that  data  is  writ¬ 
ten  past  the  VGA  video  address  space 
into  BOOOH.  You  bring  up  this  point 
yourself,  but  you  mention  that  “the 
method  itself  prevents  this.  ”  By  your 
example,  the  method  does  not  prevent 
this.  You  are  correct  that  the  segment 
does  not  have  to  point  to  the  top  of 
video  memory  (an  address  is  an  ad¬ 
dress  —  you  can  point  to  the  same  place 
with  many  segment:offset  pairs),  but 
that  still  does  not  help  here. 

Perhaps  in  illustrating  your  point, 
some  code  was  inadvertently  left  out 
of  your  example.  In  any  case,  you  are 
correct  in  that  it  is  possible  to  optimize 
around  the  64K  bank  switching  with¬ 
out  testing  every  single  pixel.  The  point 
I  was  making  in  the  article  was  simply 
that  some  optimizations  are  not  possi¬ 
ble  or  are  more  difficult  to  implement 
if  the  bank  ends  in  the  middle  of  a 
scanline.  Your  example  serves  to  illus¬ 
trate  this  perfectly. 
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Throwing  A  Slow  Curve 

Dear  DDJ, 

Thanks  for  the  interesting  graphics  is¬ 
sue  (DDJ,  July  1990).  I  really  appreciate 
learning  about  algorithms  that  I  can 
actually  use.  When  I  first  read  Todd 
King’s  article  on  Bezier  curves,  I  was 
amazed  at  the  time  performance  differ¬ 
ence  he  found  between  the  deCasteljau 
and  literal  rendering  methods  of  draw¬ 
ing  Bezier  curves.  But  after  a  careful 
look  at  the  listing,  I  realized  that  most 
of  that  difference  is  due  to  a  difference 
in  the  number  of  lines  drawn  per  Be¬ 
zier  curve  by  the  methods,  rather  than 
differences  in  algorithmic  efficiency.  In 
King’s  program,  for  the  literal  render¬ 
ing  method,  101  lines  per  curve  are 
drawn;  for  the  deCasteljau  method, 
either  24  (for  cut-off  3)  or  48  (for  cut¬ 
off  4)  are  drawn.  By  changing  the  in¬ 
crement  in  the  for  loop  for  the  literal 
method  to  0.4  or  0.2,  25  or  51  lines  per 
curve  are  drawn  for  the  literal  method 
with  little  or  no  loss  in  appearance. 
(Note:  The  article  says  that  the  variable 
DPU  is  used  to  determine  the  number 
of  lines  drawn  for  the  literal  method, 
but  DPU  is  defined  in  the  listing,  then 
never  used.)  With  this  improvement, 
the  deCasteljau  method  is  only  2.8  times 
as  fast,  instead  of  five  to  ten  times  as  fast. 

The  literal  method  is  also  unneces¬ 
sarily  slow  in  King’s  implementation 
because  of  inefficient  coding.  I  replaced 
the  routine  draw_bezierl  with  the  code 
in  Example  2  to  avoid  recalculating 
reused  factors.  With  this  alteration,  the 
deCasteljau  method  is  only  about  twice 
as  fast  as  the  literal  method.  The  differ¬ 
ences  are  smaller  if  a  floating-point 
coprocessor  is  available:  deCasteljau 
is  only  about  1.2  times  as  fast  as  im¬ 
proved  literal  with  an  80a87. 


Further  improvements  can  be  made 
to  both  methods:  1)  If  a  curve  is  really 
a  straight  line,  it  should  be  drawn  as  a 
line,  not  a  Bezier  curve;  2)  When  a 
character  is  scaled  down,  many  of  the 
lines  in  each  curve  have  zero  length 
on-screen,  and  don’t  need  to  be  drawn; 
3)  General  efficiency  clean-ups. 

The  biggest  improvement  possible 
with  no  80^87  is  to  use  all  integer  and 
long  calculations.  I  have  used  carefully 
scaled  integers  and  the  literal  method 
in  my  shareware  PostScript  drawing 
program  PictureThis,  and  have  reduced 
the  drawing  time  dramatically.  To  draw 
King’s  six  a's  (with  no  fills)  on  an  XT- 
clone  with  no  80^87  takes  20.5  sec¬ 
onds  for  the  deCasteljau  method  (24 
lines/curve),  34  seconds  for  the  im¬ 
proved  literal  method  (21  lines/curve), 
47  seconds  for  the  unimproved  literal 
method  (21  lines/curve),  but  only  three 
seconds  for  PictureThis  with  an  integer 
literal  method  (19  lines/curve).  An  in¬ 
teger  deCasteljau  method  should  make 
PictureThis  slightly  faster. 

PictureThis  provides  kerning,  accent 
characters,  subscripts  and  superscripts, 
font  modifications,  yet  it  runs  quite  well 
even  on  a  4.77  MHz  PC  with  512K 
memory,  CGA  (including  Hercules  with 
CGA  emulation),  no  expanded  mem¬ 
ory,  no  mouse,  and  no  hard  disk.  Pic¬ 
tureThis  produces  standard  Encapsu¬ 
lated  PostScript  (EPS)  files  (with  “show- 
pages”!). 

Pat  Williams 
Hot  Ideas  Publishing 
Rt.  1,  Box  302 
Gravel  Switch,  KY  40328 

Todd  responds:  I  had  also  wondered 
about  the  speed  difference  between  the 
literal  and  deCasteljau  methods  of  cal¬ 
culating  a  Bezier  curve.  Admittedly,  I 
should  have  taken  a  closer  look  at  the 
code  and  I  should  have  done  the  same 
type  of  analysis  you  did  in  order  to 
make  a  more  fair  comparison.  One 
other  observation  is  that  with  either 
method,  a  curve  is  drawn  as  a  series 
of  line  segments.  'The  only  difference  is 
how  the  end  points  of  the  line  segments 
are  calculated.  In  the  deCasteljau 
method  the  calculation  involves  12  mul- 
tiplication/ division  operations  and  25 
addition/subtractions,  whereas  the  lit¬ 
eral  method  presented  in  the  article 
uses  28  multiplication/divisions  and 
18  addition/subtractions.  Your  im¬ 
proved  literal  method  uses  15  multipli¬ 
cation/divisions  and  11  addition/sub¬ 
tractions.  If  a  curve  is  drawn  with  the 
same  number  of  line  segments,  regard¬ 
less  of  the  method,  then  you  should 
expect  that  the  deCasteljau  and  your 
improved  literal  method  would  calcu- 
(continued  on  page  14) 

Dr.  Dobb’s Journal,  November  1990 

989 


draw_bezierl (bcurve) 

BEZIER-BOX  *bcurve; 

1 

float  x,  y; 

float  tm; 

float  t,  t2,  t3,  a,  b,  c; 

move  to ( (int)bcurve->a.x, (int)bcurve->a.y) ; 

for  (t=0 . 0;  t<=1.0;  t  +=  0.02)  { 
t2  =  t  *  t; 
t3  =  t2  *  t; 

a  =  1  -  3*t  +  3*t2  -  t3; 
b  =  3* (t  -  2*t2  +  t3) ; 
c  =  3*  (t2  -  t3)  ; 
x  =  a  *  bcurve->a.x 
+  b  *  bcurve->b.x 
+  c  *  bcurve->c.x 
+  t3  *  bcurve->d.x; 
y  =  a  *  bcurve->a.y 
+  b  *  bcurve->b.y 
+  c  *  bcurve->c.y 
+  t3  *  bcurve->d.y; 
lineto  ( (int)  x,  (int)y); 

} 
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(continued  from  page  12) 
late  in  approximately  the  same  amount 
of  time,  while  the  original  literal  method 
is  still  the  slowest  puppy  in  the  litter. 

Encapsulating  Memory  Allocation 

Dear  DDJ, 

The  article  “Encapsulating  C  Memory 
Allocation”  by  Jim  Schimandle  {DDJ, 
August  1990)  describes  a  code  con¬ 
struct  which  leads  to  “memory  leak¬ 
age,”  where  a  failure  in  a  sequence  of 
memory  allocations  results  in  losing 
those  pieces  successfully  allocated  (see 
Example  3).  I  agree  that  memory  leak¬ 
age  is  a  real  problem  area;  its  effect  is 
usually  only  made  noticeable  after  the 
passage  of  time  and  is  not  made  obvi¬ 
ous  in  one’s  program  by  simply  testing 
large  cases. 

The  brevity  of  constructs  such  as  in 
Example  3  is  quite  desirable.  In  an 
allocation  sequence,  explicitly  check¬ 
ing  success  and  freeing  unusable  mem¬ 
ory  areas  after  each  step  may  severely 
contort  the  code.  What  seems  to  be 
called  for  is  a  routine  which  will  cor¬ 
rectly  clean  up  after  an  aborted  alloca¬ 
tion  sequence.  I  devised  a  routine, 
vfree(),  which  takes  a  (NULL-termi- 


Example  3 


Listing  One 


Example  4 
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nated)  list  of  pointers  to  allocated  re¬ 
gions  and  frees  them  (Listing  One). 
This  allows  program  constructs  such 
as  that  in  Example  4. 

The  operation  of  vfree( )  is  quite 
simple  —  free  each  non-NULL  pointer 
in  the  list.  Argument  pointers  are  pre¬ 
sented  in  the  same  order  that  alloca¬ 
tions  were  attempted,  so  all  pointers 
to  valid  regions  are  contiguous  in  the 
beginning  of  the  list,  and  no  pointers 
past  the  first  NULL  need  be  considered. 
When  allocating  a  structure  and  its  fields, 
the  fields  must  be  initialized  to  NULL 
(through  calloc( )  or  a  custom  alloca¬ 
tor).  The  last  attempt’s  result  does  not 
need  to  be  included  in  the  arguments 
to  vfree( },  if  it  succeeds,  the  call  to 
vfree( )  will  not  be  made.  If  all  attempts 
before  it  succeed  and  it  is  the  only  one 
to  fail,  there  is  no  need  to  free  its  space. 

This  function  is  not  only  useful  in 
allocation-error  memory  recovery.  Us¬ 
ing  vfree( )  makes  the  coding  of  multi¬ 
ple  successive  free()  operations  cleaner. 
In  addition,  there  may  be  a  slight  run¬ 
time  benefit  as  well:  Whenever  you 
must  call  free( )  several  times  in  suc¬ 
cession,  the  compiler  must  generate 
code  to  push  each  pointer  on  the  stack 


and  then  code  to  call  free().  Using 
vfree( ),  all  of  the  argument-pushing  is 
retained,  but  only  one  function  call  is 
made. 

The  idea  is  quite  expandable.  Free¬ 
ing  of  nested  structures  can  be  accom¬ 
plished  by  creating  a  deallocation  func¬ 
tion  for  each  level  of  structure,  and 
extending  the  concept  of  vfree()  to 
take  deallocator/region  pairs  as  argu¬ 
ments.  If  you  need  to  free  a  grab  bag 
of  pointers,  some  of  which  may  be 
NULL  (such  as  in  the  cleanup  stage  of 
a  function  that  could  have  failed  or 
been  cancelled  at  several  places),  a 
form  of  vfree( )  can  be  written  which 
takes  the  number  of  pointers  as  its  first 
argument;  it  would  simply  count 
through  the  argument  list  and  skip  the 
NULLs. 

If  the  allocation  for  fooptr->string 
fails,  fooptr  is  freed.  If  the  allocation  for 
fooptr->field2  fails,  fooptr  and  fooptr 
->string  will  both  be  freed.  If  the  alloca¬ 
tion  for  fooptr->field3  fails,  fooptr,  foo- 
ptr->string,  and  fooptr->foo2  will  all 
be  freed. 

George  Spofford 

Northampton,  Massachusetts 

Jim  responds:  The  vfree(  )  routine  pro¬ 
posed  by  George  is  a  good  example  of 
using  a  single  routine  to  handle  a  fail¬ 
ure.  However,  I  do  not  agree  that  the 
brevity  of  construct  in  his  Example  3 
is  desired.  It  is  only  desired  //'mallocf )/ 
free( )  is  your  only  concern.  Most  data 
structures  require  more  cleanup  than 
a  simple  free( ) ,  Often  there  are  files  to 
close,  other  data  structures  that  must 
be  updated,  and  state  variables  that 
need  to  change.  For  the  example  pre¬ 
sented,  vfree( )  is  a  perfectly  good  solu¬ 
tion.  However,  it  is  not  generally  appli¬ 
cable.  What  you  really  need  is  a  con¬ 
structor/destructor  facility  as  is  found 
in  C++. 

The  only  code  benefit  to  be  derived 
is  in  code  size.  vfree( )  actually  im¬ 
poses  a  longer  execution  time  overhead 
because  all  the  pointers  must  be  copied 
on  the  stack  twice:  once  for  the  call  to 
vfree(  )  and  once  for  the  call  to  free(  ). 
Also,  the  copy  loop  in  the  vfree(  )  rou¬ 
tine  takes  time.  This  is  not  an  issue  if 
the  failure  of  the  malloc(  )  call  is  rela¬ 
tively  infrequent. 

DDJ 

We  welcome  your  comments  (and  sug¬ 
gestions).  Mail  your  letters  (include  disk 
if  your  letter  is  lengthy  or  contains  code) 
to  DDJ,  501  Galveston  Dr.,  Redwood 
City,  CA  94063,  or  send  them  electroni¬ 
cally  to  CompuServe  76704,50  or  via 
MCI  Mail,  c/o  DDJ.  Please  include  your 
name,  city,  and  state.  We  reserve  the 
right  to  edit  letters. 

Dr.  Dobb’s  Journal,  November  1990 


if  (  (fooptr  =  (F00  *)  malloc  (sizeof  (F00) ) )  ==  NULL 
!!  (fooptr->string  =  strdup  (name))  ==  NULL)  ( 
return  (NULL) ; 

If  the  strdup ()  call  fails,  the  memory  allocated  for  the  structure 
is  lost. 


♦include  <stdarg.h>  /*  for  variable  arg  macro  def's  */ 

/* —  VFREE  -  Author:  George  Spofford  - */ 

void  vfree  (void  *first, ...) 

( 

static  void  *ptrs [MAX_VFREE] ;  /*  reordering  area  */ 

int  i ; 

void  *p; 

va_list  argMarker;  /*  variable-args  marker  */ 

if  (first  ==  NULL)  /*  ensure  something  to  do  */ 

return; 

/***  First,  accumulate  all  pointers  into  array  */ 
ptrs[0]  =  first; 
va_start  (argMarker,  first); 

for  (i  =  1,  p  =  va_arg (argMarker,  void  *);  p  !=  NULL  ss  i  < 
MAX_ VFREE; 

++i,  p  =  va_arg (argMarker,  void  *)  ) 

ptrs [i]  =  p; 

/***  Now,  free  them  all,  in  reverse  order  */ 
while  ( — i  >=  0) 

free  (ptrs [i] ) ; 


if  (  (fooptr  =  (F00  *)  calloc  (1,  sizeof  (F00) ) )  ==  NULL 

!!  (f ooptr->string  =  strdup  (name))  ==  NULL 

!!  (fooptr->field2  =  (FI  *)  malloc  (sizeof  (FI)))  ==  NULL 

!!  (fooptr->f ield3  =  (F2  *)  malloc  (sizeof  (F2 ) ) )  ==  NULL 

vfree  (fooptr,  fooptr->string,  fooptr->field2,  NULL); 
return  (NULL) ; 


Roll  Your  Own 
Object-Oriented  Language 


Striking  a  chord  with  Object  Prolog 


Michael  Floyd 


A  special  relationship  exists  between  developing  soft¬ 
ware  and  writing  music.  Among  other  things,  the 
two  disciplines  share  precise  languages  containing 
symbols  that,  unlike  English,  carry  very  specific 
meanings.  Yet,  these  symbols  can  be  combined  in 
countless  ways  to  orchestrate  something  that  can  only  be 
termed  “harmonious.”  More  often  than  not,  the  unexpected 
becomes  the  norm,  and  more  to  the  point  of  this  article, 
what  could  be  more  unexpected  than  object-oriented  exten¬ 
sions  to  the  Prolog  language?  The  extensions,  which  I  call 
“Object  Prolog,”  involve  an  inheritance  mechanism  and 
message-passing  facility  that,  when  included  in  a  Prolog 
program,  allow  you  to  add  objects  to  your  programs.  I’ll  also 
provide  a  preprocessor  that  allows  you  to  define  your  own 
object  definition  language  and  spits  out  Object  Prolog  code. 

“But,”  you  say,  “I’m  no  logic  programmer.”  Well,  I’m  no 
Brahms  either,  but  you  should  know  that  Prolog’s  unique 
abilities  allow  it  to  serve  as  a  sort  of  “executable  specifica¬ 
tion,”  meaning  that  you  can  easily  rewrite  the  code  pre¬ 
sented  here  in  your  favorite  language.  In  addition,  the  parser 
presented  in  this  article  provides  a  code  generator  that  can 
be  modified  to  output  source  in  your  favorite  language. 

I  should  mention  that  I’m  using  PDC  Prolog  (formerly 
Turbo  Prolog)  from  the  Prolog  Development  Center.  The 
code  generated  by  the  preprocessor,  however,  should  run 
under  any  Prolog  compiler  with  only  slight  modifications. 

Object  Prolog 

Object  Prolog  is  a  small  language  set  that  I’ve  defined  to 
wrap  around  your  code.  When  written  correctly,  that  code 
will  exhibit  inheritance,  encapsulation,  abstraction,  poly¬ 
morphism,  and  persistence.  Object  Prolog  treats  everything  in 
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the  system  as  an  object  and,  as  such,  there  are  no  formal 
classes.  As  defined  here,  only  single  inheritance  is  sup¬ 
ported,  although  support  for  multiple  inheritance  can  be  added. 

Object  Prolog  uses  four  predefined  predicates  (equiva¬ 
lent  to  a  Pascal  procedure)  which  are  defined  in  OOP.PRO 
(see  Listing  One,  page  102).  The  method( )  predicate  is  used 
to  define  methods  in  the  program  and  takes  an  object  type 
and  the  method  name  as  its  two  arguments.  There  is  nothing 
unusual  about  method( )  except  that  it  is  invoked  by  the 
inheritance  mechanism.  A  method( ),  like  any  Prolog  predi¬ 
cate  may  call  any  other  predicate  in  the  system,  including 
other  methods. 

The  msg( )  predicate  is  used  to  send  messages  to  objects 
by  taking  an  object  identifier  and  a  message  identifier  as  its 
arguments  and  passing  the  message  through  the  inheritance 
mechanism  to  invoke  the  appropriate  method. 

The  is_a( )  predicate  is  a  database  predicate  that  simu¬ 
lates  a  table  defining  the  parent/child  relationships  in  the 
system.  is_a( )  is  generally  used  only  by  the  inheritance 
mechanism,  although  it  can  be  called  directly  anywhere  in 
the  program.  One  common  use  for  is_a( )  outside  of  the 
inheritance  mechanism  is  to  look  up  the  hierarchy  for  a 
specific  attribute  of  the  parent  object.  You’ll  see  this  action 
in  the  discussion  of  Listing  Two. 

Finally,  the  has( )  predicate  is  a  data  stmcture  that  repre¬ 
sents  the  dynamic  portion  of  the  objects  in  your  program. 
It  has  the  effect  of  an  instance  variable  and  stores  the  data 
associated  with  an  object.  has( )  is  a  database  predicate  so 
that  instances  of  objects  can  be  passed  around  in  memory. 
The  structure  for  has( )  consists  of  an  object  identifier  and 
a  list  (similar  to  a  linked-list)  of  slots  which  describe  the 
named  object.  Slots  are  recursively  defined  and  consist  of 
an  identifier  and  a  value.  For  instance,  a  slot  could  be  a 
variable  name  and  the  contents  of  that  variable.  A  value, 
however,  can  also  contain  lists  made  up  from  the  basic  data 
types,  another  slot,  or  a  list  of  slots. 
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Striking  Up  the  Band 

If  you  are  a  Turbo  Pascal  or  Turbo  C++  programmer,  you’re 
familiar  with  Borland’s  “Figures”  example  which  is  used  in 
the  Borland  documentation  to  get  budding  object-oriented 
programmers  up  to  speed.  The  example  defines  a  base 
object  type  (or  class)  called  point  that  is  used  to  derive  a 
circle,  and  later  an  arc.  I’ll  use  that  same  example,  both  as  a 
litmus  test  for  Object  Prolog  and  as  a  common  ground  for 
understanding. 

Listing  Two  (page  102)  presents  FIGURES. PRO,  which 
defines  four  shapes:  point,  circle,  rectangle,  and  solid  rec¬ 
tangle.  The  Clauses  section  (similar  to  procedure  defini¬ 
tions)  first  defines  the  methods  for  those  shapes.  Because 
PDC  Prolog  supports  the  Borland  Graphics  Interface  (BGI) 
library,  I’ll  use  the  BGI  to  draw  the  various  shapes  on  the 
screen.  The  hide  and  show  methods  for  point ,  for  instance, 
use  BGI’s  putpixel( )  routine  to  display  or  hide  a  point  on 
the  screen.  BGI. PRO  (Listing  Three,  page  104)  provides  the 
BGI  initialization  support. 

point  is  the  base  object  from  which  all  other  shapes  will 
inherit.  As  such,  point  demonstrates  the  use  of  abstraction 
in  Object  Prolog.  In  other  words,  points  purpose  is  to  act 
as  a  template  for  all  other  shapes  that  inherit  from  it  rather 
than  to  draw  points  on  the  screen  (although  there  would 
be  no  problem  in  doing  so),  points  init  and  done  methods 
represent  a  constructor  and  destructor,  respectively,  using 
assert  and  retract  to  create  and  destroy  objects  in  memory. 

I  mentioned  earlier  that  is_a( )  could  be  called  directly  in 
an  Object  Prolog  program.  method(circle,  drag),  for  in¬ 
stance,  uses  is_a( )to  send  a  message  to  method(point,drag). 
Note  that  there  is  no  explicit  circle,  drag  method  in  the 
Turbo  Pascal  or  Turbo  C++  counterparts  to  Figures.  These 
bindings  are  handled  by  a  Virtual  Method  Table  (VMT). 
Object  Prolog,  however,  does  not  setup  a  VMT  so  the 
lookup  is  done  explicitly  by  method(circle.drag).  This  is  a 
dynamic  lookup,  so  nothing  is  lost  in  the  way  of  polymor- 
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phism,  although  it  does  require  a  little  more  work. 

The  Figures  example  winds  up  with  arc,  a  new  object 
type,  arc  is  defined  as  a  child  of  point  and  therefore  reaps 
the  same  benefits  as  circle.  Note  that  arc  is  not  a  stand-alone 
object  file;  rather,  it  is  included  at  the  end  of  Listing  Two. 
The  reason  is  that  PDC  Prolog  requires  that  all  predicates 
be  grouped  together.  Therefore,  arc  must  consult  the  data¬ 
base  and  assert  the  appropriate  is_a  and  has  clauses.  There 
will  be  more  to  say  about  this  in  the  “Encore”  section. 

A  Bow  from  the  Director 

One  of  the  beauties  of  Prolog  is  its  ability  to  quickly  model 
an  algorithm.  This  is  apparent  in  the  instrument  that  orches¬ 
trates  the  symphony  —  the  inheritance  mechanism.  (The 
code  for  the  inheritance  mechanism  in  Listing  One,  for 
example,  is  a  paltry  11  lines  long.) 

The  inherit ( )  rules  are  actually  quite  powerful  and  can  act 
in  a  number  of  ways,  inherit  can  take  an  object  identifier  and 
return  its  associated  value.  Given  the  Figures  example,  for 
instance,  if  Object  is  instantiated  to  point,  the  first  inherit 
clause  will  call  description  to  look  for  a  matching  has  fact  in 
the  database.  In  this  case,  description  will  return  a  list  of  slots 
containing  the  values  for  the  x  and  y  coordinates  of  point. 

In  the  case  of  circle,  however,  no  explicit  fact  exists.  So, 
a  call  to  inherit  with  Object  instantiated  to  circle  will  invoke 
the  second  inherit  clause,  which  uses  is_a  to  look  up  the 
hierarchy  until  a  fact  is  found.  In  this  case,  inherit  will  return 
the  x  and  y  coordinates  with  no  explicit  has  reference  to 
circle. 

The  second  description  clause  comes  into  play  when  a 
has  clause  cannot  be  found.  The  assumption  is  that  if  it’s 
not  an  instance  variable,  it  must  be  a  method.  If  you’re 
concerned  about  performance  here,  don’t  worry.  Prolog 
(like  all  languages)  looks  at  the  data  structure  before  at¬ 
tempting  to  bind  variables,  so  the  instance  variables  are 
quickly  ruled  out. 
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A  point  for  C  programmers  to  note  here  is  that  you  can 
call  PDC  Prolog  from  C  (both  Turbo  and  Microsoft).  You  can 
then  get  a  cheap  inheritance  mechanism  by  linking  OOP.  PRO 
with  your  C  code  and  calling  inherit  directly! 

Objects  in  C  Minor 

Object  structures,  as  represented  by  has( ),  can  be  quite 
complex,  especially  if  an  object  slot  contains  lists  of  slots 
within  slots,  and  so  on.  I  decided  to  build  a  simple  prepro¬ 
cessor  that  allows  you  to  design  objects  at  a  higher  level, 
using  what  I  call  an  “object  definition  language”  (ODL).  The 
preprocessor  defines  a  syntax  similar  to  Turbo  Pascal’s, 
parses  the  code,  and  generates  Object  Prolog  source  code. 

FIGURES. OOP  (see  Listing  Four,  page  104)  presents  an 
example  of  the  ODL  that  I’ve  defined.  You’ll  note  that  this 
program  looks  more  like  the  Figures  example  in  the  Turbo 
Pascal  OOP  Guide  than  Listing  Two,  with  the  exception 
that  I’ve  borrowed  the  style  for  variable  declarations  from 
C.  (Note,  for  instance,  the  int  declaration  at  the  beginning 
of  point.)  Of  course,  there  is  no  virtual  keyword  for  the 
reasons  discussed  above. 

Turbo  Pascal  has  a  nifty  style  for  describing  objects.  In 
particular,  I  like  the  syntactic  style  used  in  defining  inheri¬ 
tance  relationships:  The  ancestor  is  named  in  the  argument 
to  object( ).  Introducing  an  inherit  keyword  as  defined  in 
“true”  Object  Pascal  works,  but  is  clumsy,  and  in  my  opin¬ 
ion,  less  eloquent.  Otherwise,  the  program  is  straightforward: 
Methods  are  encapsulated  directly  in  the  object  and  support 
predicates  are  contained  after  the  object  definitions.  As  with 
Object  Pascal,  the  end  statement  is  used  to  terminate  the 
object  definition  and  must  be  followed  by  a  period. 

Parsing  the  ODL 

PARSER. PRO  in  Listing  Five  (page  105)  presents  the  ODL 
parser;  a  top-down  parser  that  operates  in  a  recursive- 
descent  fashion.  Because  the  parser  need  generate  only 
Object  Prolog  code,  construction  of  a  state  machine  is  not 
necessary.  In  fact,  much  of  the  defined  syntax  is  a  reordering 
of  the  Object  Prolog  syntax  so  that  encapsulation  is  more 
natural.  Of  course,  the  parser  must  also  create  data  struc¬ 
tures  for  objects,  insert  inheritance  relationships,  and  bind 
static  variables. 

The  algorithm  for  the  parser  is  implemented  in  the  scan 
predicate.  As  with  many  parsers,  scan  does  not  actually 
construct  a  parse  tree,  but  mirrors  the  tree  through  predicate 
calls.  The  parser  takes  its  input,  one  line  at  a  time,  and 
passes  the  line  to  the  lexical  analyzer  via  tokl  for  tokeniza- 
tion.  scan  first  looks  for  the  object  definition,  and  then  for 
any  variable  declarations.  The  object  definition  is  stored  in 
the  database  via  insert_isa  for  later  insertion  into  the  is_a 
table,  and  the  object  identifier  is  recorded  in  objectname. 
Init_vars  then  scans  the  variable  string  and  asserts  their 
tokenized  counterparts  into  the  database  as  slots.  Later,  in 
the  code  generation  phase,  these  slots  will  be  referenced  to 
set  up  the  appropriate  has  clauses. 

scan_methods  then  scans  the  method  identifier  and  as¬ 
serts  the  tokenized  method  into  the  database  for  reference 
by  the  code  generator.  The  code  generator  inserts  the  object 
name  to  create  the  method  clause.  Also  note  that  methods 
may  span  several  lines  so  GetMethEnd  is  used  to  search  for 
the  end  of  a  method,  which  is  designated  by  a  period  (as  are 
traditional  Prolog  clauses).  scan_methods  continues  recur¬ 
sively  scanning  methods  until  an  end  statement  is  reached 

Finally,  the  code  generation  phase  takes  over.  Code  is 
generated  for  one  object  at  a  time;  then  scan  is  called  again 
to  parse  more  objects.  generate_code  begins  the  code  gen¬ 
eration  phase  by  grabbing  the  current  object  identifier  from 
the  database  and  calling  generate_ancestors  to  setup  the  is_a 


table.  Next,  generate_methods  is  called  to  insert  the  object 
identifier  and  write  any  methods  stored  in  memory,  gener- 
ate_vars  then  grabs  individual  slots  and  reasserts  them  as  a 
list  of  slots,  stored  as  vars.  Finally,  generate_code  retrieves 
the  vars  from  the  database  and  w'rites  out  the  has  clauses. 

Because  PDC  Prolog  requires  that  like  clauses  be  grouped 
together,  has ,  is_a,  and  method  clauses  are  stored  in  sepa¬ 
rate  temporary  files  and  merged  at  the  end  of  the  code 
generation  phase.  It  probably  makes  sense  to  store  has  and 
is_a  clauses  in  a  separate  consult  file.  In  fact,  this  is  a 
prerequisite  for  dynamic  objects  and  is  required  to  support 
object  persistence. 

As  mentioned  earlier,  the  lexical  analyzer  shown  in  List¬ 
ing  Six  (page  108)  is  called  by  the  parser  via  tokl  to  scan  and 
tokenize  lexemes,  tokl  uses  the  built-in  fronttoken  predicate 
to  strip  the  first  lexeme  from  the  input  stream,  then  calls 
scan_next  to  scan  the  rest  of  the  stream.  scan_next  also 
uses  fronttoken  to  assert  “lookahead”  lexemes  in  the  data¬ 
base  in  the  form  of  a  stack,  tokl  next  calls  tokenize  to 
tokenize  the  string,  tokenize  pulls  a  lexeme  from  the  input 
stream  and  passes  the  lexeme  to  str_tok,  which  takes  a  string 
and  returns  its  tokenized  representation.  In  most  cases,  this 
is  a  simple  lookup.  For  instance,  str_tok(“(”,  X)  will  return 
the  Ipar  token  in  X.  But  a  lookahead  is  necessary  in  the  case 
of  variable  declarations,  so  str_tok(“int”,  X)  must  pop  lex¬ 
emes  off  the  lookahead  stack  to  get  to  the  variable  identifi¬ 
ers.  These  identifiers  are  stored  in  the  database  as  they  are 
popped  off  the  stack. 

One  other  notable  point  is  that  str_tok  suffixes  an  under¬ 
score  character  to  lexemes  that  coincide  with  built-in  PDC 
Prolog  keywords.  For  instance,  str_tok  will  return  if_  for  the 
I/lexeme.  This  is  done  to  resolve  conflicts  between  the  object 
definition  language  and  PDC  Prolog  language  elements. 

An  Encore 

The  parser  makes  a  good  stepping  stone  for  designing  and 
developing  Object  Prolog  code,  but  is  by  no  means  com¬ 
plete  or  bulletproof.  Indeed,  the  parser  is  bare  bones  at  the 
moment  and  is  crying  for  improvements.  So,  if  you  plan  to 
use  the  extended  language  and  preprocessor  to  develop 
Object  Prolog  code,  you’ll  probably  want  to  make  some 
additions  to  the  parser  and  scanner.  The  first  step  is  to  add 
some  error  handlers  to  both  the  parser  and  lexical  analyzer. 
And  you’ll  want  to  add  support  for  any  built-in  predicates 
that  you  need. 

As  mentioned  earlier  on  in  this  article,  the  Figure  example 
included  arc ,  rather  than  linking  it  as  a  separate  object  file. 
Not  only  is  this  a  deterrent  to  polymorphism,  but  it  restricts 
the  size  of  your  object-oriented  system.  Another  problem 
lies  in  the  fact  that  every  clause  in  the  system  (except 
support  clauses)  is  a  methodC ).  Although  I’m  not  certain  of 
the  limit,  there  is  a  maximum  number  of  clauses  allowed  for 
a  given  predicate.  Undoubtedly,  someone  is  going  to  hit 
that  limit  at  some  point.  This  is  where  a  method  table  would 
come  in  handy. 

My  next  project  will  be  to  build  a  hierarchy  browser  to 
scan  the  is_a  relationships  and  present  a  tree  diagram  of  the 
hierarchy.  The  Prolog  Development  Center  provides  win¬ 
dow  and  menu  tools,  and  includes  a  tree  menu  predicate 
that  can  be  cannibalized  (most  of  the  toolbox,  including  tree 
menu,  comes  with  full  source  code)  to  aid  in  this  effort. 

In  any  case,  I  invite  you  to  pick  up  the  baton  and  have  a 
go  at  it.  Who  knows  what  melody  lurks  in  the  wings,  waiting 
to  be  played. 

DDJ 

(Listings  begin  on  page  102.) 

Vote  for  your  favorite  feature/article. 
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An  Existential 
Dictionary 

Superimposed  coding  packs  a  lot  of  information 
into  a  small  space 


Edwin  T.  Floyd 


Have  you  ever  needed  a  search 
routine  that  could  determine 
with  fair  accuracy  whether  or 
not  a  particular  piece  of  infor¬ 
mation  exists  without  the  over¬ 
head  of  a  conventional  search?  If  so, 
the  “superimposed  coding”  technique 
I  present  in  this  article  may  be  the  tool 
you’ve  been  waiting  for.  I’ve  imple¬ 
mented  the  system  as  a  Turbo  Pascal 
object  that  supports  superimposed  code 
dictionaries,  which  I  call  “existential 
dictionaries”  because  they  record  the 
fact  that  a  key  exists  without  storing  the 
key  itself.  Existential  dictionaries  can 
be  used  for  a  variety  of  applications, 
including  spell  checking,  document  re¬ 
trieval,  and  database  applications. 

The  technique  of  superimposed  cod¬ 
ing  packs  a  lot  of  information  into  a 
small  space.  An  existential  dictionary 
for  a  10,000-word  spelling  checker,  for 
instance,  can  occupy  as  little  as  23K. 
In  the  case  of  database  applications, 
an  existential  dictionary  can  save  time. 
For  example,  consider  a  10,000-record 
database  indexed  on  one  field.  A  su¬ 
perimposed  code  dictionary  for  10,000 
keys  can  be  as  small  as  18K  —  small 
enough  to  hold  in  memory.  Checking 
the  dictionary  for' a  key  before  search¬ 
ing  the  index  for  that  key  reduces  un¬ 
necessary  index  searches,  thus  reducing 


Edwin  is  manager  of  a  data  center  for 
the  Hughston  Foundation,  a  non-profit 
orthopaedic  and  sports  medicine  facil¬ 
ity  in  Columbus,  Georgia.  He  is  an 
occasional  contributor  to  DDJ.  Edwin 
can  be  reached  through  CompuServe 
at [76067,  747]. 


such  searches  by  a  factor  of  one  thou¬ 
sand. 


Small  existential  dictionaries  can  be 
used  as  “surrogate  keys”  to  help  locate 
documents  indexed  by  author  and  sub¬ 
ject  keyword  terms.  The  size  of  a  surro¬ 
gate  key  file  is  typically  10  to  20  percent 
of  the  size  of  a  conventional  index,  and 
the  surrogate  key  file  can  be  substantially 
quicker  when  searching  for  certain  types 
of  queries.  Surrogate  key  files  are  also 
used  in  place  of  conventional  indices 
in  some  very  large  databases. 

How  Superimposed  Coding  Works 

Consider  a  hypothetical  tiny  spelling 
checker  with  a  word  list  of  400  English 
words.  To  construct  an  existential  dic¬ 


tionary  for  it,  start  with  an  array  of  8000 
bits,  all  initially  off.  For  each  word  in 
the  list,  generate  a  hash  number  be¬ 
tween  0  and  7999,  and  tyrn  the  corre¬ 
sponding  bit  in  the  array  on.  If  the  hash 
function  is  sufficiently  random  (a  non¬ 
trivial  problem),  it  will  distribute  the 
on  bits  uniformly  in  the  table  with  very 
few  collisions.  (A  “collision”  happens 
when  two  words  hash  to  the  same  bit 
position.)  The  code  bits  for  all  words 
are  superimposed  in  the  same  table, 
without  regard  to  collisions. 

To  test  an  unknown  word  for  mem¬ 
bership  in  the  list,  first  generate  the 
word’s  hash  number.  If  the  correspond¬ 
ing  bit  is  off  we  are  certain  that  the 
word  is  not  in  the  list.  If  the  bit  is  on, 
the  word  is  either  in  the  list,  or  its  hash 
number  simply  happens  to  match  the 
hash  number  of  a  word  in  the  list.  This 
is  called  a  “false  drop.”  (A  false  drop 
happens  when  the  existence  test  suc¬ 
ceeds  incorrectly  due  to  a  collision.) 
For  this  dictionary,  the  probability  of  a 
false  drop  is  about  400/8000,  or  1/20. 
We  want  to  reduce  this  probability  as 
much  as  is  practical. 

One  way  to  reduce  the  false  drop 
probability  is  to  increase  the  size  of  the 
bit  table.  For  instance,  we  can  double 
the  size  of  the  bit  table  to  16,000  and 
change  the  range  of  the  hash  function 
correspondingly.  The  new  probability 
will  then  be  about  1/40.  Jon  Bentley, 
in  his  priceless  book  Programming 
Pearls,  describes  a  spelling-checker  pro¬ 
gram  written  by  Doug  Mcllroy.  Doug’s 
program  uses  a  227  (134  million)  bit 
table  to  store  existence  bits  for  about 
30,000  words.  His  false  drop  probabil- 
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(continued  from  page  20) 
ity  is  a  little  less  than  1/4000.  By  an 
ingenious  representation  trick,  Doug  man¬ 
ages  to  compress  this  1 6-Mbyte  table  to 
40K,  which,  plus  an  index,  makes  for 
a  total  dictionary  size  of  less  than  64K. 

Another  way  to  reduce  the  false  drop 


probability  is  to  represent  each  word 
by  more  than  one  bit.  In  our  example, 
we  can  use  two  hash  functions  on  each 
word  to  turn  about  800  bits  on  out  of 
a  total  of  8000.  In  this  case,  the  prob¬ 
ability  for  a  single-bit  collision  increases 
to  about  1/10.  A  false  drop  now  re¬ 


quires  two  collisions  with  a  combined 
probability  of  1/10  *  1/10  or  about 
1/100.  Thus,  using  two  bits  per  word 
improves  the  accuracy  of  this  diction¬ 
ary  fivefold.  Using  three  bits  per  word 
will  improve  the  accuracy  even  further. 

Our  dictionary  is  not  limited  to  Eng- 


Derivation  of  the  BitsOn  Equation 


Consider  an  array  of  TVbits,  all  initially 
off  and  an  iterative  process  that  se¬ 
lects  bits  at  random  and  turns  them 
on.  What  is  the  probability  of  a  “colli¬ 
sion,”  that  is,  the  probability  that  the 
random  process  will  select  a  bit  that 
is  already  on,  at  the  i th  iteration?  On 
the  first  iteration  (i  =  0),  the  probabil¬ 
ity  is  zero  because  all  bits  are  off  On 
the  second  iteration  (i  =  7),  the  prob¬ 
ability  is  1/N,  because  exactly  one  bit 
is  on.  Let  f  be  the  number  of  bits  on 


at  the  i th  iteration.  Then,  the  probabil¬ 
ity  of  a  collision  (call  it  IT  )  is  as 
shown  in  Figure  4(a).  The  probability 
of  a  non-collision  (call  it  is  shown 
in  Figure  4(b). 

We  can  see  that  each  time  the  pro¬ 
cess  succeeds  in  turning  a  bit  on  that 
was  previously  off,  the  probability  of 
a  non-collision  is  reduced  by  1/N. 
But  the  probability  of  selecting  an  off 
bit,  and  thus  succeeding  in  turning  it 
on,  is  the  current  probability  of  a  non¬ 


collision.  Combining  these  facts,  we 
can  write  a  recurrence  formula  for  the 
value  of  Q  at  any  iteration,  based  on 
the  previous  iteration,  see  Figure  4(c). 

Knowing  that  Q0  =  1,  we  can  con¬ 
vert  the  recurrence  formula  to  an  ex¬ 
plicit  equation  for  Q ;  (refer  to  Figure 
4[d]).  By  substituting  and  taking  the 
logarithm  of  both  sides,  we  arrive  at 
the  equation  shown  in  Figure  4(e). 
We  can  rearrange  this  equation  into 
the  equation  shown  in  Figure  4(0. 
As  //becomes  larger,  the  expression 
shown  in  Figure  4(g)  rapidly  becomes 
so  close  to  -1  that  we  can  neglect  the 
difference.  (Hint,  it's  a  “sick”  limit.) 
So,  for  practical  purposes,  the  equa¬ 
tion  becomes  that  shown  in  Figure 
4(h).  Solving  for  Jt,  we  have  the  equa¬ 
tion  in  Figure  4(0,  which  is  the  ex¬ 
pression  for  the  number  of  bits  that 
were  originally  off  but  are  now  on, 
in  a  table  of  N  bits,  after  i  iterations 
of  the  random  process.  In  our  appli¬ 
cation,  the  number  of  iterations  is 
simply  the  product  of  the  number  of 
keys  and  the  number  of  bits  per  key. 
So,  i  =  BK,  and  we  have  the  BitsOn 
equation. 

The  false  drop  probability  is  P/f 
By  differentiation,  we  can  show  that 
J.  /N  =  1/2  minimizes  the  false  drop 
probability.  (The  proof  is  left  as  an 
exercise  to  the  reader.  Hint,  differen¬ 
tiate  [ BitsOn/Nf  rsp.  B.)  So,  in  an 
optimal  table,  the  relationship  shown 
in  Figure  4(j)  holds  true.  Solving  for 
N,  we  arrive  at  the  optimal  table-size 
equation  shown  in  Figure  4(k).  This 
is  the  expression  for  the  size  in  bits 
of  an  optimal  bit  table  containing  K 
keys  with  B  bits  per  key. 

The  value  of  -  Ln(0.5)  showed  up 
early  in  the  process  of  developing 
these  routines.  I  experimented  with 
various  sizes  of  bit  tables  by  counting 
iterations  while  turning  on  random 
bits,  until  half  of  the  bits  were  on.  The 
ratio  of  iterations  to  table  size  in  bits 
was  always  about  0.693.  This  deriva¬ 
tion  was  motivated  by  a  desire  to 
explain  this  mysterious  number. 

—  E.F. 
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Figure  4:  BitsOn  equations  (a):  Collision  probability  (b):  Non-collision 
probability  (c):  Recurrence  formula  (d):  Explicit  equation  (e):  Logarithm 
(f):  Rearranged  (g):  Limit  (h):  Approximation  (i):  BitsOn  (j):  Optimal  table 
(k):  Solved  for  N. 
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(continued  from  page  22) 
lish  words.  In  general,  any  sequence 
of  bytes,  or  “key”  can  be  represented 
as  a  set  of  bits  in  a  bit  table.  The  num¬ 
ber  of  bits  used  to  represent  a  key  is 
independent  of  the  length  of  the  key. 
As  more  bits  are  used  to  represent  each 
key  and  the  bit  table  fills  up,  two  ef¬ 
fects  become  noticeable. 

First,  more  collisions  occur.  The  num¬ 
ber  of  on  bits  in  the  table  is  signifi¬ 
cantly  less  than  the  number  of  keys 
multiplied  by  the  number  of  bits  per 
key.  In  fact,  if  our  hash  functions  ran¬ 
domize  well  and  the  bit  table  is  not  too 
small,  the  number  of  on  bits  will  be 
very  close  to  the  value  predicted  by  the 
BitsOn  equation  in  Figure  1(a).  In  this 
equation,  N  represents  the  size  of  the 
table  in  bits,  e  is  the  natural  logarithm 
base,  AT represents  the  number  of  keys, 
and  B  represents  the  number  of  bits 
per  key.  (See  the  accompanying  text- 
box  entitled  “Derivation  of  the  BitsOn 
Equation.”)  If  we  use  ten  bits  per  word 
in  our  hypothetical  dictionary,  then 
N=  8000,  K=  400,  and  .6=10.  According 
to  this  formula,  about  3150  bits  are  on. 

In  general,  the  false  drop  probability 
is  the  product  of  all  the  single  bit  colli¬ 
sion  probabilities,  each  of  which  is 
BitsOn/N ,  see  Figure  1(b).  This  equa¬ 
tion  yields  a  false  drop  probability  of 
(3150/8000)'°,  or  about  1/11,000,  as 
shown  in  the  example. 

The  second  effect  of  using  more  bits 
to  represent  each  key  is  that  the  accu- 


(a)  BitsOn  =  N  -  N  e'BK/N 


(b)  FalseDrop=[B't?0n  i 


KB  KB 

(c)  N=  -  = 

-Log  (0.5)  ~  0.693147.. 

e 


(d)  Expected  collisions  =  K  -  N  +  N  e  K/N 


Figure  1:  Dictionary  equations  (a): 
BitsOn  equation  (b):  FalseDrop  equa¬ 
tion  (c):  Optimal  table-size  equation 
( d ):  Expected  collisions 


DICTIONARY 


racy  of  the  dictionary  continues  to  im¬ 
prove  more  and  more  slowly  until  half 
of  the  bits  in  the  table  are  on.  At  that 
point,  the  accuracy  begins  to  deterio¬ 
rate.  At  the  optimal  point,  when  half 
of  the  bits  are  on ,  the  false  drop  prob¬ 
ability  is  l/2B.  Given  the  number  of 
keys  and  the  number  of  bits  per  key, 
we  can  rearrange  the  equations  de- 

Small  existential 
dictionaries  can  be  used 
as  “surrogate  keys”  to 
help  locate  documents 
indexed  by  author  and 
subject  keyword  terms 


scribed  earlier  into  a  simple  formula 
for  the  optimal  table  size,  as  shown  in 
Figure  1(c). 

To  use  Doug  Mdlroy’s  problem  as 
an  example,  we  have  30,000  keys  and 
we  want  the  false  drop  probability  to 
equal  1/4000  or  less.  Representing  each 
key  by  12  bits  in  an  optimal  bit  array 
will  yield  a  false  drop  probability  of 
1/212,  or  1/4096.  In  this  case,  the  array 
size  will  be  30,000*12/0.693,147  = 
519,370  bits,  or  64,921  bytes,  which  is 
somewhat  larger  than  Doug’s  diction¬ 
ary.  The  procedure  for  building  our  bit 
table  is  considerably  faster  and  simpler 
than  Doug’s  procedure,  which  requires 
a  sort.  Also,  by  making  our  bit  table  a 
little  larger  than  the  optimal  size,  we 
can  add  keys  dynamically.  For  instance, 
a  65,520-byte  table  at  12  bits  per  key 
becomes  optimal  at  about  30,277  keys. 
At  31,000  keys,  the  false  drop  probabil¬ 
ity  is  still  only  1/3369. 

The  Hash  Function 

With  these  formulae,  we  can  engineer 
a  bit  table  for  any  number  of  keys  and 
with  any  desired  degree  of  accuracy. 
The  calculated  performance  is  guaran¬ 
teed,  as  long  as  the  hash  function  is 
sufficiently  random.  I  evaluated  a  num¬ 
ber  of  hash  functions  found  in  the  lit¬ 
erature  for  speed  and  randomization 
and  eventually  created  one  based  upon 
a  random-number  generator  described 
by  Steven  Park  and  Keith  Miller  in  a 
1988  Communications  of  the  ACM  arti¬ 
cle  entitled  “Random  Number  Genera¬ 
tors:  Good  Ones  are  Hard  to  Find.”  The 
“Minimal  Standard”  generator  described 
in  their  article  is  a  simple  multiplicative 
congruence  algorithm  that  generates  a 


sequence  of  seeds: 

Next  seed  =  (seed*l6807)  modulo 
2,147,483,647 

The  Park-Miller  generator  is  a  31-bit, 
full-period  generator.  Given  any  31-bit 
starting  seed  (except  zero),  it  will  not 
return  to  that  seed  or  repeat  a  number 
for  2,147,483,647  cycles.  The  sequence 
passes  most  tests  of  randomness.  It  is 
not,  of  course,  truly  random.  A  given 
starting  seed  always  generates  the  same 
sequence  of  “random”  numbers.  Be¬ 
cause  of  this,  we  call  it  a  “pseudo¬ 
random”  number  generator. 

In  the  January,  1990  Communica¬ 
tions  of  the  ACM,  David  Carta  described 
a  fast  machine-language  implementa¬ 
tion  of  the  Park-Miller  generator.  My 
version  of  the  Carta  implementation 
for  the  8086  instruction  set  requires 
only  two  16-bit  multiply  operations, 
plus  some  shifts  and  adds. 

A  good  pseudo-random  number  gen¬ 
erator  simplifies  the  task  of  creating 
hash  functions.  The  generator  elimi¬ 
nates  the  need  for  a  separate  hash  func¬ 
tion  for  each  dictionary  bit.  Instead, 
we  need  only  a  single  hash  function 
to  produce  a  suitable  starting  seed.  The 
random  number  generator  will  then 
beget  an  endless  supply  of  unique,  ran¬ 
dom,  31-bit  integers.  Each  integer, 
modulo  N,  is  a  bit  position  to  turn  on 
or  test. 

We  still  need  to  construct  a  suitable 
hash  function  to  generate  the  starting 
seed.  I  found  this  task  unexpectedly 
frustrating.  The  entire  responsibility  for 
avoiding  collisions  rests  with  the  seed- 
generator  function.  If  this  function  gen¬ 
erates  the  same  seed  number  for  two 
different  keys,  the  bits  selected  will 
also  be  the  same  for  those  two  keys. 
Therefore,  the  seed  function  must  gen¬ 
erate  as  few  31 -bit  seed  collisions  as 
possible  among  the  keys  of  interest 
and  should  also  be  quick.  What  is  a 
reasonable  collision  performance  to  ex¬ 
pect  from  a  hash  function?  I  set  out  to 
devise  a  suitable  test. 

First,  I  needed  a  large  number  of 
typical  keys.  I  started  with  a  list  of 
109,584  unique  English  words  obtained 
from  a  public  domain  source.  The 
words  averaged  8.5  characters  each.  I 
planned  to  use  a  hash  function  to  gen¬ 
erate  a  31-bit  number  for  each  word. 
If  the  hash  function  randomized  well, 
it  would  produce  about  the  same  num¬ 
ber  of  collisions  as  a  random  selection 
of  109,584  items  from  a  population  of 
231,  with  replacement.  I  computed  the 
number  of  collisions  to  expect  in  a 
random  selection  of  K  items  from  a 
population  of  N,  see  Figure  1(d).  Ac- 
( continued  on  page  28) 
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(continued  from  page  24) 
cording  to  this  equation,  for  A= 109 584 
and  7V=2147483647,  I  could  expect 
about  three  collisions,  which  is  not 
enough  for  a  meaningful  test. 

Accordingly,  I  expanded  the  num¬ 
ber  of  keys.  I  generated  three  keys 
from  each  English  word:  All  upper¬ 
case,  all  lowercase,  and  first  letter  capital¬ 
ized  with  the  rest  of  the  word  lower¬ 
case.  (I  excluded  the  single-letter  words 
“A”  and  “I.”)  I  now  had  328,751  keys. 
I  also  included  the  10-digit  ASCII  num¬ 
bers  from  zero  to  109,583,  which 
brought  the  count  to  K=  438  335  unique 
keys  and  45  expected  collisions.  To 
evaluate  each  hash  function,  I  used  it 
on  the  keys  to  generate  438,335  31-bit 
numbers.  Next,  I  sorted  the  numbers 
and  counted  the  duplicates.  Through¬ 
out  the  remainder  of  this  article,  I’ll 
refer  to  this  procecure  as  the  “collision 
test.” 

In  addition,  I  devised  a  realistic  test 
of  the  hash  function’s  false-drop  per¬ 
formance.  I  partitioned  the  word  list 
into  seven  disjoint  subsets  of  8000  to 
18,000  words  each.  To  evaluate  each 
hash  function,  I  used  it  to  create  an 
optimal  bit  table  for  each  subset,  using 
14  bits  per  word.  I  shifted  each  word 
to  lowercase  before  hashing.  Then,  for 
each  subset,  I  counted  the  number  of 


false  drops  from  the  entire  word  list.  I 
left  all  the  test  words  in  uppercase,  so 
that  none  of  them  matched  any  word 
in  a  subset.  The  false  drop  probability 

Existential  dictionaries 
can  be  used  for  a 
variety  of  applications, 
including  spell 
checking,  document 
retrieval,  and  database 
applications 


for  each  bit  table  is  about  1/16,384.  So, 
a  good  hash  function  should  produce 
about  7*109,584/16,384,  or  about  47 
false  drops  for  all  subsets  combined. 
In  the  following  text,  I’ll  refer  to  this 
procedure  as  the  "practical  test.” 

The  behavior  of  hash  functions  on 
this  scale  is  somewhat  counterintuitive. 
A  widely  used,  32-bit  CRC  function,  for 


instance,  generated  thousands  of  colli¬ 
sions.  Eventually,  I  ran  across  the  fol¬ 
lowing  reference  to  a  simple  hash  algo¬ 
rithm  in  Donald  Knuth’s  The  Art  of 
Computer  Programming. 

1  Generate  a  sequence  of  as  many 
pseudo-random  numbers  as  there 
are  bytes  in  the  key. 

2.  Multiply  each  byte  in  the  key  by  a 
different  member  of  the  sequence. 

3.  Add  up  the  results. 

Since  I  had  a  source  of  random  num¬ 
bers,  I  tried  this  hash  algorithm  with 
an  initial  seed  of  “1.”  The  resulting 
collision  count  was  61.  This  result  was 
close,  but  there  were  still  two  prob¬ 
lems  with  this  algorithm.  It  ignored  trail¬ 
ing  null  bytes,  and,  unless  the  starting 
seed  was  varied,  it  used  the  same  se¬ 
quence  of  multipliers  for  every  key. 
The  first  problem  was  easy  to  fix  —  I 
simply  added  a  constant  to  each  byte 
before  multiplying.  (I  used  65,280 
[FFOOhD 

I  am  ashamed  to  say  how  many  blind 
alleys  I  ran  down  before  settling  on  a 
solution  to  the  second  problem.  Be¬ 
cause  the  starting  seed  completely  de¬ 
termines  the  random  number  sequence, 
you  might  think  that  enough  variation 
could  be  easily  introduced  by  setting 
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(continued  from  page  28) 
the  seed  to  a  simple  function  of  the 
length  or  the  terminal  key  characters. 
Not  so.  The  only  reliable  method  I’ve 
found  to  randomize  the  starting  seed 
is  to  run  the  hash  function  twice  in  the 
following  manner:  The  first  time  you 
run  the  function,  start  with  a  constant 
seed.  The  second  time  around,  use  the 
result  of  the  first  run  as  the  seed. 


Each  different  starting  seed  defines 
a  different  hash  function.  I  tested  50 
starting  seeds  and  discovered  that  most 
of  them  performed  well  on  the  colli¬ 
sion  test,  but  poorly  on  the  practical 
test.  I  knew  that  after  the  hash  function 
determines  the  initial  seed,  the  practi¬ 
cal  test  uses  the  raw  random-number 
generator  to  select  bits.  This  fact  even¬ 
tually  led  me  to  suspect  the  “random¬ 


ness”  of  the  Park-Miller  generator’s  out¬ 
put.  Knuth  describes  a  simple  shuffling 
algorithm  that  improves  the  random¬ 
ness  of  even  poor  generators.  After  I 
incorporated  an  eight-way  shuffle  into 
the  Park-Miller  generator,  the  false  drop 
count  improved  significantly,  although 
it  was  still  17  percent  above  the  ex¬ 
pected  count.  The  eight-way  shuffling 
algorithm  is  shown  in  Figure  2. 

Superimposed  coding  is 
an  elegant  way  to  test 
for  key  existence 


Even  shuffling  will  not  randomize 
effectively  enough  where  extreme  ac¬ 
curacy  is  required.  An  optimal  bit  table 
for  26  or  more  bits  per  key  will  suffer 
from  the  unavoidable  collision  behav¬ 
ior  of  the  initial  hash  function.  In  such 
a  case,  I  would  not  use  the  random- 
number  generator  at  all.  Instead,  I  would 
repeat  the  hash  function  with  a  differ¬ 
ent  starting  seed  for  each  bit.  This 
method  would  require  a  fast  processor 
to  achieve  good  performance. 

Table  1  shows  the  first  30  seeds  and 
their  collision  and  false-drop  counts. 
Repeating  the  hash  algorithm  for  each 
bit  produced  43  false  drops. 

There  is  no  evidence  of  any  real 
pattern  here,  and  no  reason  to  believe 
that  any  particular  starting  seed  is  bet¬ 
ter  than  the  others  for  all  possible  key 
sets.  I  selected  a  starting  seed  of  26, 
which  led  to  the  recommended  hash- 
and  bit-selection  procedure  outlined 
in  Figure  3-  This  procedure  produces 
bit  tables  that  perform  according  to  the 
design  information  given  earlier. 

Implementation 

The  implementation  presented  here  is 
a  Turbo  Pascal  unit  (see  Listing  One, 
page  110)  that  supplies  a  Dictionary 
object;  the  methods  are  listed  in  Table 
2.  The  two  non-object  functions  are 
listed  in  Table  3-  (Refer  to  the  actual 
code  for  details  about  how  to  use  these 
routines.)  I’ve  also  developed  a  com¬ 
plete  batch-oriented  spelling  checker 
to  illustrate  the  use  of  the  dictionary 
objects.  Due  to  space  constraints,  the 
spelling  checker  isn’t  listed  in  this  arti¬ 
cle,  although  the  complete  program 
(including  documentation  and  sample 
terms),  is  available  through  DDJ.  (Refer 
to  the  “Source  Code  Availability”  sec¬ 
tion  on  page  3.) 

The  save  file  produced  by  the  Save- 
Dictionary  method  is  intended  for  di- 


Establish  the  initial  seed. 

Build  the  shuffle  table: 

fill  an  eight  entry  table  with  the  next  eight  Park-Miller  numbers;  save  the  ninth 
Park-Miller  number  in  a  variable  called  NextOut. 

To  generate  the  next  shuffled  random  number: 

select  a  table  entry  using  NextOut,  bits  1 7  through  1 9;  replace  NextOut  with  the 
contents  of  the  table  entry;  replace  the  table  entry  with  the  next  Park-Miller  number; 
return  the  contents  of  NextOut  as  the  random  number. 


Figure  2:  The  eight-way  shuffling  algorithm 
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Table  1:  Seed  performance 


Function  Hash  (seed,  key) 

Set  the  initial  value  of  the  function  result  to  zero. 

For  each  byte  in  the  key: 

generate  the  next  Park-Miller  seed; 

add  [(key  byte  +  65,280)  *  seed]  to  the  function  result. 

Limit  the  final  result  to  the  low-order  31  bits; 
if  it’s  zero,  increment  it. 

Employ  the  function  twice: 

Hash  (Hash  (26,  key),  key) 

The  final  hash  result  is  the  initial  seed  for  generating  bit  numbers: 

Build  the  shuffle  table. 

Repeat  B  times: 

generate  the  next  shuffled  random  number; 

set  (or  test)  the  bit  specified  by  the  number  modulo  N. 

If  you  have  a  fast  machine  and  wish  to  set  more  than  26  bits  per  key: 

Set  the  initial  seed  to  1 . 

Repeat  B  times: 

Set  (or  test)  the  bit  specified  by  Hash(Hash(seed,key),key);  increment  the  seed. 


Figure  3:  Recommended  hash  and  bit  selection  procedure 
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(continued  from  page  30) 
rect,  binary  portability  to  another  hard¬ 
ware  platform,  a  Tandem  NonStop  mini¬ 
computer.  The  only  concession  made 
to  the  Tandem  architecture  is  the  byte 
order  of  binary  integers.  These  are  byte- 
reversed  before  saving  to  disk,  and  re¬ 
versed  again  after  restoration. 

The  random-number  generator,  the 
hash  function,  and  the  bit-set  and  test 
functions  are  implemented  as  inline- 
assembler  macros.  The  bit  table  size  is 
limited  to  65,520  bytes  as  a  concession 
to  Turbo  Pascal’s  maximum  GetMem 
size,  and  to  improve  the  performance 
of  the  bit-set  and  test  functions.  You 
can  overcome  this  limitation  by  distrib¬ 
uting  keys  to  multiple  dictionaries.  For 
instance,  my  Tandem  spelling  checker 
divides  the  dictionary  by  the  first  letter 
of  a  word  into  seven  bit  tables:  A-B, 
C-D,  E-H,  I-N,  O-R,  S-T,  and  U-Z.  These 
are  the  same  partitions  used  in  the  prac¬ 
tical  test.  Observe  one  caution  when 
using  multiple  bit  tables:  You  must  add 
together  the  false  drop  probabilities  for 
each  existence  test  performed  on  the 
same  key.  For  instance,  if  you  test  a  key 
in  two  dictionaries  and  each  dictionary 
has  a  false  drop  probability  of  1/4096, 
the  combined  false  drop  probability  is 


2/4096  or  1/2048.  My  spelling  checker 
selects  the  appropriate  dictionary  for  the 
unknown  word  by  the  word’s  first  char¬ 
acter,  and  tests  only  in  that  dictionary. 

Performance 

To  get  an  idea  of  the  speed  of  the 
dictionary  methods,  I  performed  a  tim¬ 
ing  benchmark  on  an  8-MHz  NEC-V20. 
(This  machine  runs  about  three  times 
as  fast  as  the  original  PC.)  First,  I  built 
an  optimal,  14-bit  dictionary  from  a 
subset  of  the  109,584  word  list.  The 
subset  consisted  of  the  17,639  words 
beginning  with  “S”  and  “T.”  The  false 
drop  probability,  as  determined  by  count¬ 
ing  the  on  bits,  was  1/16,450. 

Secondly,  I  read  the  entire  109,584 
word  list  and  tested  each  word  against 
the  dictionary.  Actually,  I  read  each  list 
twice;  first  I  timed  the  read  alone,  and 
then  I  timed  the  read  with  the  diction¬ 
ary  method  calls.  The  differences  in 
timings  were  an  estimate  of  the  proces¬ 
sor  time  spent  in  the  dictionary  meth¬ 
ods.  In  this  benchmark,  the  methods 
inserted  250  keys  per  second  and  tested 
435  keys  per  second.  Existence  testing 
was  faster  than  inserting  because  al¬ 
most  all  of  the  words,  excepting  those 
beginning  with  “S”  and  “T”  were  re¬ 


jected.  The  existence  test  terminates 
as  soon  as  it  finds  the  first  zero  bit.  Key 
length  and  number  of  bits  per  key  af¬ 
fect  performance.  For  instance,  with 
the  same  files  at  12  bits  per  key,  the 
benchmark  inserted  273  keys  per  sec¬ 
ond  and  tested  447  keys  per  second. 
At  14  bits  per  key,  on  a  20-MHz  80386, 
the  benchmark  inserted  1558  keys  per 
second  and  tested  2611  keys. 

The  number  of  iterations  of  the  Park- 
Miller  algorithm  determines  the  perfor¬ 
mance  of  the  hash  and  bit-selection 
algorithms.  The  hash  algorithm  per¬ 
forms  2L  iterations,  where  L  is  the  length 
of  the  key.  The  total  number  of  itera¬ 
tions  for  the  hash  and  bit-selection  al¬ 
gorithms  is  2L+B+9 ,  where  B  is  the 
number  of  bits  per  key.  If  we  repeat  the 
hash  function  for  each  bit,  we  perform 
2BL  iterations.  When  the  hash  function 
is  repeated  for  each  bit,  the  80386  bench¬ 
mark  can  insert  only  361  keys  per  sec¬ 
ond  and  can  test  1712  keys. 

Conclusion 

Superimposed  coding  is  an  elegant  way 
to  test  for  the  existence  of  a  key.  This 
approach  has  applications  in  many  ar¬ 
eas  of  information  retrieval.  It  is  a  fast 
method,  especially  with  the  shortcuts 
afforded  by  the  Park-Miller  random- 
number  generator.  The  equations  avail¬ 
able  allow  us  to  engineer  an  optimal 
existential  dictionary  with  almost  any 
desired  capacity  and  accuracy. 
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Method 

Description 

InitfMaxKeys,  BitsPerKey) 

A  constructor  that  calculates  the  size 
of  the  bit  table.  Acquires  and  initializes 
storage  from  the  heap. 

Insertstring,  InsertBlock,  and  InsertHash 

Boolean  functions  which  set  bits  in  the 
bit  table.  These  functions  return  TRUE 
if  all  the  bits  are  already  on. 

StringlnDictionary,  BlocklnDictionary,  and 
HashtnDictionary 

Boolean  functions  which  return  TRUE 
if  all  bits  associated  with  a  key  or  initial 
hash  and  HashtnDictionary  seed  are 
on  in  the  bit  table. 

SaveDictionary  and  RestoreDictionary 

Preserve  the  attributes  and  contents 
of  the  bit  table  in  a  disk  file. 

EstError  and  ActError 

Floating-point  functions  which  return 
the  false  drop  probability.  EstError  es¬ 
timates  it  by  the  BitsOn  and  FalseDrop 
equations;  ActError  counts  the  on  bits 
and  uses  the  FalseDrop  equation  to 
compute  the  exact  probability.  In  nu¬ 
merous  tests,  these  functions  have 
always  returned  very  nearly  the  same 
result. 

Table  2:  Methods  for  Dictionary  object 

DictionaryBytes(MaxKeys,  BitsPerKey) 

A  Longlnt  function  that  uses  the  Optimal 
Table  Size  equation  to  compute  the  size 
in  bytes  of  an  optimal  bit  table  for  the 
specified  key  count  and  bits  per  key. 

DictHashfData,  Size) 

A  Longlnt  function  that  provides  access 
to  the  hash  algorithm. 

Table  3-'  Non-object  functions 
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Simon  Tooke 


his  article  discusses  strategies 
and  tools  for  object-oriented  de¬ 
bugging.  Because  of  its  facili¬ 
ties  for  data  abstraction  and  in¬ 
heritance,  and  because  of  its 
similarities  to  C,  the  language  used  to 
demonstrate  the  principles  in  this  arti¬ 
cle  will  be  C++,  and  a  good  portion  of 
the  content  will  be  C++  specific.  How¬ 
ever,  many  of  the  concepts  presented 
here  are  applicable  to  other  object- 
oriented  environments. 

C++  Debugging  is  Different 

Typical  C  applications  tend  to  be  pro¬ 
cedure  oriented.  Execution  flows  from 
point  A  to  point  B,  and  somewhere  in 
between,  a  function  may  be  called  to 
manipulate  data,  read  it  in,  or  write  it 
out.  Functions  may  have  side-effects 
involving  many  pieces  of  data  or  none. 
When  you  debug,  you  watch  statement 
execution  to  ensure  that  everything  hap¬ 
pens  in  expected  order. 

In  a  well-designed  C++  application, 
the  “methods”  (member  functions)  avail¬ 
able  to  manipulate  an  item  of  data  are 
well  defined.  Access  to  data  is  restricted 
via  a  clean  set  of  interface  routines. 
Because  of  this,  the  state  of  the  data  is 
very  important  and  is  what  we  are  typi¬ 
cally  concerned  with  when  verifying 
the  correctness  of  C++  code.  Thus,  in¬ 
telligent  access  to  data  is  as  important 
as  program  execution  flow  when  search- 
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ing  for  a  problem.  Designing  special 
debugging  routines  from  the  beginning 
can  make  accessing  that  data  less  of  a 
headache  for  the  programmer. 

C++  compilers  enforce  much  stricter 
type  checking  than  traditional  C  compil¬ 
ers.  This  all  but  eliminates  several  prob¬ 
lems  such  as  calling  functions  with  the 
wrong  arguments,  type  mismatches  in 
assignments,  and  attempts  to  store  data 
into  constant  objects.  There  are  far  more 
original  ways  to  shoot  yourself  in  the 
foot  these  days. 

A  Sample  Class 

For  examples  presented  in  this  article, 
I’ll  use  a  simple  string  class.  Several 
related  classes,  such  as  a  class  contain¬ 


ing  a  list  of  strings  and  a  class  that 
iterates  over  a  list  of  strings,  are  pre¬ 
sented.  These  classes  are  declared  in 
Listing  One  (page  114);  the  main( ) 
program  is  in  Listing  Two  (page  114). 

Many  of  the  functions  will  be  trivial 
when  applied  against  these  small 
classes;  it  is  not  my  intent  in  this  article 
to  advocate  bogging  down  a  20-line 
class  with  several  hundred  lines  of  ex¬ 
tra  debugging  code,  but  to  demonstrate 
practices  that  are  useful  when  dealing 
with  more  complex  classes. 

The  String  class  provides  us  with  a 
container  for  simple  text  strings.  Stor¬ 
age  allocation  for  buffers  is  performed 
via  malloc( ),  and  the  internal  pointer 
s  will  be  guaranteed  to  always  point  at 
a  null-terminated  string  of  length  0  or 
greater. 

A  StringList  is  an  ordered  container 
for  Strings.  This  class  is  implemented 
as  a  singly  linked  list  of  StringListEle- 
ments,  each  of  which  points  to  a  String 
and  to  the  next  element  in  the  list. 

By  declaring  an  instance  of  a  StringList- 
Iterator,  a  method  is  provided  to  ex¬ 
amine  the  individual  entries  in  a  String- 
List  without  having  any  knowledge  of 
the  internals  of  StringList. 

Debug  From  the  Start 

Too  often,  debugging  is  left  as  the  final 
stage  of  development,  because  prob¬ 
lems  only  become  evident  after  a  pro¬ 
gram  is  compiled  and  nan  for  the  first 
time.  Think  about  debugging  while  de¬ 
signing  data  structures.  This  forces  you 
to  ask  questions  such  as  “How  can  I 
prove  that  data  is  correct?”  “How  does 
this  function  modify  the  data?”  and 
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“What  assumptions  are  being  made 
here?”  at  a  point  where  something  can 
be  done  about  weaknesses  in  design. 

You  can  usually  afford  to  be  ineffi¬ 
cient  with  debugging  code,  but  you 
must  write  carefully;  incorrectly  flag¬ 
ging  an  error  can  lead  to  hard-to-find 
problems.  At  the  same  time,  debugging 
libraries  and  user  debug  code  are  also 
prone  to  errors.  I  once  spent  four  days 
tracking  a  problem  in  my  application 
because  a  beta  version  of  a  debugging 
malloc( )  library  incorrectly  told  me  I 
had  wild  data  pointers  —  and  then  had 
the  gall  to  abort  my  program. 

Using  Assert  Macros 

Long  familiar  to  C  users,  the  assert( ) 
macro  (which  is  trivial  to  write,  but  is 
supplied  by  most  compiler  vendors) 
finds  a  good  home  in  C++.  This  macro 
(defined  in  Listings  Three  and  Four, 
page  114)  takes  an  expression  as  a 
parameter,  and,  if  the  expression  is  false 
(has  the  value  0),  usually  halts  the  pro¬ 
gram  and  prints  a  message  giving  the 
line  number  and  file  where  the  prob¬ 
lem  occurred.  This  tendency  to  abort 
means  that  a  program  with  assert( ) 
scattered  throughout  is  less  resilient,  if 
that  program  is  not  fully  debugged. 

At  any  point  where  an  important  as¬ 
sumption  is  made  about  the  correctness 
of  calculated  data,  insert  an  assert( ) 
call,  which  will  display  a  message  if 
that  assumption  is  invalid.  assert( )  mac¬ 
ros  should  not  be  used  to  test  input 
data  for  correctness;  that  always  be¬ 
longs  within  the  program  proper  be¬ 
cause  it  is  a  likely  occurrence.  If  a  switch 
statement  doesn’t  have  a  default:  case, 
add  one,  wrap  it  in  #ifdef  DEBUG,  and 
add  an  assert( )  within  it.  For  portabil¬ 
ity,  never  include  character  strings  within 
the  condition;  many  implementations 
do  not  handle  this  properly. 

In  Figure  1,  StringListlterator.  :reset( ) 
(a  function  that  restarts  the  iterator  in¬ 
stance  on  the  current  class)  requires  a 
pointer  to  the  StringList  to  be  iterated 
over.  The  first  assertO  will  ensure  that 
the  current  instance  is  valid  before  we 
start  operating  on  it.  The  second  as- 
sert( ^ensures  that  this  instance  already 


Figure  1:  Using  the  assert(  )  macro 


points  to  a  StringList  before  trying  to 
access  the  beginning  of  that  list.  Al¬ 
though  an  instance  of  StringListlterator 
may  be  created  without  a  list  to  iterate 
over,  it  is  an  error  to  perform  a  reset( ) 
or  a  next( )  without  previously  point¬ 
ing  to  a  StringList. 

Find  invisible  compiler¬ 
generated  temporaries 
by  examining  the 
C  output 


assert(  )  is  a  macro,  and  because  of 
this  it  can  vanish  when  a  program  is 
compiled  for  production  use.  All  code 
that  is  added  for  debugging  only  should 
be  wrapped  in  preprocessor  *ifdef 
DEBUG/ #endif  directives  so  that  it  van¬ 
ishes  in  production  programs  when  DE¬ 
BUG  is  not  defined. 

Nevertheless,  it  may  be  desirable  to 
always  compile  assert ( )s  into  a  pro¬ 
gram  to  ensure  that  problems  in  the 
field  are  properly  detected.  Yet  often 
performance,  speed,  and  robustness  con¬ 
siderations  outweigh  this  desire.  A  pro¬ 
gram  that  keeps  running  may  be  more 
useful  to  a  user  than  one  that  aborts 
because  an  assert ( )  for  a  trivial  (or 
worse,  nonexistent)  error  has  been  trig¬ 
gered. 

Verifying  Data  Structures 

When  debugging  a  live  program,  it  is 
quite  easy  to  display  an  integer,  string, 
or  other  simple  data  structure,  look  at 
it,  and  say  “Yes,  this  looks  good.”  Veri¬ 
fication  of  more  complex  structures  may 
involve  several  layers  of  pointer  indi¬ 
rection.  It  may  be  tedious  to  examine 
all  elements  in,  say,  a  linked  list  by 
hand,  following  all  the  pointers  through 
until  the  end. 

If  you  write  functions  to  check  your 
structures,  these  can  be  called  within 
your  program  and  directly  by  you  at 


debug  time.  For  instances  of  classes, 
these  should  be  virtual  member  func¬ 
tions  so  that  the  correct  routine  is  called 
for  instances  of  derived  classes  accessed 
through  base  class  pointers.  Call  these 
functions  at  the  start  and  end  of  all 
other  member  functions  to  flag  cor¬ 
rupted  data  and  assist  in  isolating  the 
problem. 

If  an  assert  fails  at  the  start  of  the 
function,  some  agent  external  to  the 
class  was  able  to  modify  the  data.  If 
an  assert  fails  at  the  end  of  the  func¬ 
tion,  the  function  itself  incorrectly  modi¬ 
fied  the  data.  These  functions  are  use¬ 
ful  both  combined  with  assert ( )  mac¬ 
ros  and  when  called  from  the  debug¬ 
ger.  An  example  of  verify ( )  for  the 
StringListlterator  can  be  found  in  List¬ 
ing  Five  (page  114). 

Displaying  Data  Structures 

Examining  a  complex  structure  by  hand 
can  be  tedious  in  exactly  the  same  way 
that  verifying  that  structure  is.  The  struc¬ 
ture  may  be  complex,  involve  multiple 
pointer  indirections,  or  simply  be  so 
big  that  only  a  small  portion  is  actually 
useful.  It  is  therefore  advisable  to  add 
functions  to  display  data  structures  in 
some  concise  fashion.  Again,  within  a 
class  hierarchy  these  should  be  virtual 
member  functions.  These  may  never  be 
called  by  application  code,  but  are  use¬ 
ful  when  called  by  the  debugger.  The 
dump (  )  function  that  displays  data  for 
StringList  is  also  found  in  Listing  Five. 

Data  verification  and  data  display 
routines  should  be  named  consistently. 

I  chose  verify( )  and  dump( ),  so  that  I 
always  know  what  to  call  for  any  given 
structure. 

Use  Debugging  Libraries 

Since  data  is  often  the  primary  concern 
of  a  C++  program,  it  follows  that  many 
problems  may  surround  the  functions 
of  memory  allocation  and  deletion.  Link¬ 
ing  with  one  of  the  many  readily  avail¬ 
able  debugging  malloc( )  libraries  al¬ 
lows  runtime  checks  to  ensure  that  noth¬ 
ing  runs  past  the  end  of  a  malloc’d  area 
and  that  only  valid  pointers  are  passed 
to  free(  ). 

In  a  C++  program,  one  has  the  op¬ 
tion  of  overloading  new  and  delete  on 
a  class-by-class  basis  to  gather  statis¬ 
tics,  check  for  potential  problems,  or 
find  “memory  leaks.”  Depending  on 
the  compiler  implementation,  new  and 
delete  often  eventually  call  malloc( ) 
and  free( ),  in  which  case  a  debugging 
tnalloc( )  library  is  useful  here,  too. 

Deep  and  Shallow  Copy 

Many  C++  data  structures  differentiate 
between  “deep”  and  “shallow”  copies. 
A  deep  copy  copies  the  structure  itself 


//  reset( )  -  rewind  iterator  to  first  element  of  list 

void  StringListlterator::reset(void) 

{ 

//ensure  valid  data 
assert(verify( )); 

//  we  cannot  reset  if  no  list 
assert(list  !=  NULL); 

//  point  to  beginning  of  list 
nxt  =  list->head; 

1 
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(continued  from  page  38) 
and  any  items  that  pointers  in  the  struc¬ 
ture  point  to.  An  example  of  a  deep 
copy  is  String: :operator=  in  the  exam¬ 
ple  classes.  Deep  copies  ensure  inde¬ 
pendence  between  different  instances 
of  a  class  by  producing  an  entirely  new 
copy  of  a  structure.  Shallow  copies  usu¬ 
ally  copy  the  structure  itself  only,  but 
any  pointers  are  left  pointing  at  their 
original  targets. 

Shallow  copies  are  quick  and  good 
for  making  a  read-only  copy  of  an  ob¬ 
ject.  Since  the  shallow  copy  does  not 
have  control  over  the  items  it  points  to, 
care  must  be  taken  not  to  destroy  those 
objects  during  the  normal  use  of  either 
the  original  or  the  copy.  Often,  items 
pointed  to  by  objects  that  implement 
shallow  copies  contain  reference  counts, 
so  they  are  only  destroyed  when  they 
are  no  longer  required  by  any  object. 


The  Stroustrup  book  contains  a  good 
example  of  a  string  class  implemented 
using  reference  counts.  If  reference 
counts  are  used,  the  shallow  copy  is 
usually  as  good  as  a  deep  copy. 

C++  programs  tend  to 
be  more  data-driven 
than  those  in  C 


One  typical  problem  involves  de¬ 
stroying  the  original  object  after  a  shal¬ 
low  copy  has  been  made.  The  pointers 
within  the  copy  end  up  pointing  at  free 
storage,  which  may  “look”  perfectly 
normal  until  it  is  reused,  some  time 
later.  A  related  (and  usually  identical) 


problem  arises  if  the  copy  is  destroyed; 
then  the  original  may  be  invalidated. 

Memory  Leaks 

A  common  mistake  in  writing  an  over¬ 
loaded  operator  is  to  allocate  a  new 
instance  of  a  class,  calculate  the  new 
value  of  this  instance,  and  return  the 
pointer  to  this  new  instance.  This  will 
work,  but  the  compiler  has  no  way  of 
knowing  that  it  should  free  up  the  new 
data  after  it  has  finished  with  it.  A  pro¬ 
gram  may  work  perfectly  well  on  small 
amounts  of  data  but  crash  after  it  has 
used  most  of  available  memory.  This 
is  called  a  “memory  leak.”  The  code 
fragment  in  Figure  2  illustrates  one  such 
case. 

Multitasking  systems  such  as  Unix 
allow  you  to  take  a  suspect  section  of 
code  and  loop  through  it  again  and 
again  while  watching  the  size  of  the 
process  grow  and  grow,  but  DOS  does 
not  easily  allow  this.  With  DOS,  a  good 
debugging  mallocO  library  is  (again) 
useful.  Most  debugging  mallocO s  can 
produce  a  log  of  mallocC )  and  free() 
calls  which  can  then  be  examined  for 
problems. 

Trivial  Casting 

Casting  a  pointer  from  an  instance  of  a 
derived  class  to  a  base  class  does  not 
change  the  virtual  functions  associ¬ 
ated  with  that  instance.  In  particular, 
the  example  in  Figure  3  will  loop  for¬ 
ever  if  derivedClass::dump(  )  is  called. 
Since  baseClass.:dump( )  is  accessed 
through  the  virtual  function  table  (often 
referred  to  as  the  “vtbl”  due  to  one 
implementation  of  this  feature),  and 
the  virtual  function  entry  in  an  instance 
of  a  derived  class  points  to  derived- 
Class::dump( ),  the  statement  ( (base- 
Class  ,)(tbis))->dump( )  will  simply  call 
derivedClass::dump( )  recursively.  In 
this  case,  a  proper  call  to  the  desired 
function  would  use  the  syntax  base- 
Class::dump(  ). 

In  Figure  4  (ignoring  the  fact  that 
this  example  is  contrived  and  is  poor 
coding  practice),  the  compiler  silently 
creates  a  temporary  variable  of  type 
Classl  and  passes  a  reference  to  this 
temporary  into  func( ).  When  func( ) 
returns,  the  modified  temporary  is  de¬ 
leted  and  the  value  of  the  real  ptr->i  is 
unchanged.  This  all  happens  silently 
in  most  C++  compilers,  and  is  a  source 
not  only  of  inefficiency,  but  also  errors. 
Looking  at  the  C  output  (if  available) 
confirms  this,  but  it  is  a  hard  problem 
to  catch  unless  you  suspect  it  exists. 

Using  a  Debugger 

Use  a  good  debugger  to  help  to  know 
your  program.  Be  aware  of  its  capabili¬ 
ties  and  expand  them  through  the  ad- 


Thing&  operator  +(Thing&  one,  Things  two) 
{ 

Thing*  p  =  new  Thing; 

// . . .  .perform  some  magic  . . . 
return  *p; 

} 


Figure  2:  Hidden  memory  leak 


struct  baseClass 

{ 


int  i; 

virtual  void  dump( ) 


cerr « "i="  «  i «  An”; 


}; 

struct  derivedClass  :  baseClass 


{ 


int  j; 

virtual  void  dump( ) 

{ 

//  The  line  below  is  wrong: 
((baseClass  *)(this))->dump( ); 

cerr « "j=" « j  «”\n"; 


}; 


Figure  3:  Incorrect  use  of  pointer  casting 


struct  Classl  { int  i; }; 
struct  Class2  { int  i; }; 

void  func(Class1  &  ref) 

{ 

ref.i  =  5; 

} 


main( ) 

{ 


} 


Class2  *ptr  =  new  Class2; 
ptr->i  =  1 ; 

cerr « "before,  i=" « (ptr->i) « "\n" 

func((Class1)(*ptr)); 

cerr « "after,  i="  «  (ptr->i)  «  An"; 


Figure  4:  Invisible  (and  silent)  temporary  created  by  a  cast 
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(continued  from  page  40) 

dition  of  debugging  routines  where  it 

falls  short. 

Most  C  debugging  sessions  consist 
of  stack  traces,  setting  simple  break¬ 
points,  and  single-stepping.  Since  G++ 
is  more  data-driven,  debugger  features 
such  as  conditional  breakpoints  sud¬ 
denly  become  very  useful.  For  exam¬ 
ple,  setting  a  breakpoint  in  a  member 
function  for  a  particular  instance  of  a 
class  may  become  trivial  if  your  debug¬ 
ger  supports  commands  of  the  form 
“Stop  in  ClassName::Function  if 
this==&instance.” 

Fiandling  all  of  C++  features  in  an 
intelligent  way  is  a  challenge  for  a  de- 
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bugger.  A  good  debugger  will  allow 
you  to  think  in  C++,  type  in  C++  names, 
and  call  C++  functions  properly.  Better 
yet,  it  will  resemble  a  Smalltalk  browser, 
automatically  cross-referencing  classes 
and  instances. 

Compiling  with  -g  (or  the  equiva¬ 
lent)  adds  debugging  information  to 
an  executable,  but  there  may  be  other 
switches  on  your  compiler  that  provide 
increased  functionality.  For  example, 
some  debuggers  are  incapable  of  set¬ 
ting  breakpoints  in  inline  functions  un¬ 
less  inlining  has  been  turned  off  at 
compile  time.  Listing  Six  (page  115) 
shows  the  Make  file  for  our  sample 
programs. 


If  the  C++  implementation  is  capable 
of  it,  it  may  produce  C  source  code  as 
one  of  the  steps  in  the  compilation 
sequence.  There  are  debuggers  that  al¬ 
low  you  to  step  through  the  C  code  in 
much  the  same  way  as  you  would  step 
through  assembler  when  debugging  C. 

Null  Pointer  Dereferencing 

In  C++,  a  common  problem  is  to  call  a 
member  function  using  a  null  pointer 
to  instance.  If  the  pointer  ptr  is  NULL, 
then ptr->function( ) behaves  quite  dif¬ 
ferently,  depending  on  the  type  of  the 
function.  If  function( )  is  static,  it  will 
be  called  and  nothing  out  of  the  ordi¬ 
nary  will  occur;  the  pointer  value  is  not 
passed.  If functionO  is  non-virtual,  then 
it  will  be  called,  but  references  within 
the  function  will  attempt  to  access  data 
at  location  0.  If,  however,  function( ) 
is  virtual,  then  C++  will  dereference  the 
pointer  in  an  attempt  to  access  the  vir¬ 
tual  function  table  for  that  class.  An 
(effectively)  random  pointer  to  func¬ 
tion  will  be  read,  and  the  program  will 
probably  fly  south  for  the  winter. 

Debuggers  with  hardware  capabili¬ 
ties  (such  as  add-in  boards  or  access 
to  CPU  debug  registers)  usually  allow 
trapping  on  read  access.  This  feature  is 
not  only  useful  to  trace  program  access 
to  a  particular  variable,  but,  when  loca¬ 
tion  0  is  trapped,  should  catch  attempts 
to  access  data  through  null  pointers. 

Conclusion 

The  key  to  C++  (as  to  most  object- 
oriented  languages)  is  that  only  a  small, 
known  section  of  the  program  deals 
with  manipulating  a  given  type  of  data. 
If  that  data  is  wrong,  then  only  a  known 
portion  of  the  program  (the  member 
functions)  can  be  responsible.  Careful 
design  will  insure  that  any  given  mem¬ 
ber  function  expects  an  internally  con¬ 
sistent  object  when  called,  and  leaves 
the  object  correct  on  leaving. 

Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
online.  To  order  the  disk,  send  $14.95 
(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal ,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  M&T’s  Telepath  online  service 
(via  Tymnet)  and  through  the  DDJ  Fo¬ 
rum  on  CompuServe  (type  GO  DDJ). 

DDJ 


(Listings  begin  on  page  114.) 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  3. 


Dr.  Dobb’s  Journal,  November  1990 

1003 


A  Message  Logging  Class 


A  tool  that  augments  your  development  environment 


William  D.  Cramer 


f  you’re  like  me,  you’ve  probably 
had  some  exposure  to  more  tradi¬ 
tional  development  environments 
on  more  traditional  platforms.  You 
know  the  sort  of  environment  I 
mean  —  a  top-to-bottom  program  run¬ 
ning  on  a  dumb-terminal  or  PC.  The 
kind  of  platform  where  just  a  few  well- 
placed  printf(  )s  can  mean  the  differ¬ 
ence  between  taking  two  minutes  to 
pinpoint  an  error  and  taking  two  hours. 

Most  Macintosh  programs  provide 
the  user  with  a  very  visual,  very  inter¬ 
active  interface.  When  developing  such 
applications,  you  might  test  a  particu¬ 
lar  feature  by  playing  the  role  of  the 
user  —  if  you  see  an  anomaly,  you  use 
the  Think  C  debugger  to  set  a  few  key 
breakpoints,  and  then  repeat  your  steps 
until  you  hit  one  of  them.  At  that  point, 
you  can  poke  around  until  you  find 
some  stray  pointer  or  uninitialized  vari¬ 
able  and  correct  the  problem. 

However,  there’s  a  whole  set  of  prob¬ 
lems  that  don’t  lend  themselves  to  this 
kind  of  debugging.  For  example,  ac¬ 
tions  involving  a  good  number  of  cal¬ 
culations,  iterations,  or  deeply  embed¬ 
ded  function  calls  —  all  based  on  a 
single  user  action  —  add  complexity  if 
a  problem  occurs.  Then,  too,  there  are 
operations  that  rely  on  certain  timing 
constraints:  If  the  user  is  expected  to 
respond  within  a  given  time  period,  for 
example,  debugging  with  breakpoints 


Bill  is  a  software  engineering  project 
manager  for  IEX  Corp.,  a  Plano, 
Texas  engineering  and  consulting 
firm.  He  can  be  reached  via  e-mail  at 
u  u  net!iex!cra  mer. 


can  ruin  the  whole  timing  frame.  Fi¬ 
nally,  programs  that  deal  with  a  non¬ 
human  interface  (such  as  AppleTalk 
or  MacTCP)  can  cause  no  end  of  heart¬ 
ache  when  that  external  interface 
doesn’t  play  fair. 

This  article  describes  a  simple  tool 
that  augments  your  development  envi¬ 
ronment  with  a  general-purpose  mes¬ 
sage  logging  window.  The  tool,  built 
out  of  existing  Think  Class  Library  ob¬ 
jects,  furnishes  you  with  some  basic 
printf( )  capabilities  and  lets  you  de¬ 
fine  categories  of  messages.  By  enabling 
and  disabling  these  categories,  you  can 
selectively  control  which  events  get 
logged. 


What  is  CTrace? 

CTrace  evolved  from  a  Unix-based  tool 
I  wrote  several  years  ago.  That  version 
in  turn  evolved  from  various  logging 
mechanisms  found  in  systems-level 
daemons.  What  I’ve  tried  to  do  is  ex¬ 
tract  the  best  of  these  older  versions 
and  add  on  a  Mac  flavor. 

The  CTrace  class  consists  of  three 
major  elements  —  a  control  mechanism 
through  which  you  submit  messages 
for  conditional  logging,  a  circular  buffer 
containing  your  logged  messages,  and 
a  display  window  that  gives  you  a  view 
of  the  buffer. 

The  logging  control  mechanism,  a 
subclass  of  CDocument,  uses  a  bit  mask 
that  defines  up  to  32  event  categories. 
I’ve  included  some  basic  categories  — 
errors,  warnings,  general  information, 
and  function  entry/exit  —  and  you  can 
add  your  own  to  fit  your  application. 
Your  application  submits  requests  to 
trace  with  a  call  like  that  in  Example  1 . 

When  Trace( )  receives  this  message, 
it  compares  the  mask  passed  as  a  pa¬ 
rameter  (in  this  example,  T_INFO)  with 
its  internally  stored  mask.  If  you  have 
enabled  that  particular  category,  Trace( ) 
writes  your  data  (along  with  a  time  stamp) 
into  the  log  buffer.  Otherwise,  it  hap¬ 
pily  ignores  the  request  and  returns. 

The  log  buffer,  based  on  the  Think 
C  class  CList,  stores  some  finite  number 
of  text  strings.  When  it  reaches  the 
predefined  limit,  it  begins  overwriting 
the  oldest  entries  with  the  newest.  A 
scan  of  the  list  will  always  show  the 
contents  from  the  earliest  entry  to  the 
most  recent  entry. 

The  display  window  shows  the  con- 
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(continued  from  page  44) 
tents  of  the  circular  buffer.  Because  the 
buffer  can  potentially  contain  thousands 
of  messages,  the  display  window  uses 
a  subclass  of  the  CPanorama  class  en¬ 
closed  within  a  CWindow.  Hence,  you 
can  scroll  to  any  part  of  the  buffer,  you 
can  grow  and  shrink  the  window,  and 
you  can  hide  the  window  when  you 
don’t  need  it.  The  buffer  and  window 
operate  independently  of  each  other, 
so  even  when  you  have  hidden  the 
window,  logging  to  the  buffer  contin¬ 
ues.  The  window  looks  like  the  one 
shown  in  Figure  1.  You  enable  and 
disable  categories  via  a  modal  dialog 
conjured  up  from  a  command  on  the 
Trace  menu.  It  presents  you  with  a 
dialog  box  like  the  one  shown  in  Fig¬ 
ure  2.  You  can  set  the  trace  mask  at  any 
time.  For  example,  you  may  want  to 
leave  all  categories  disabled  until  you 
reach  a  point  where  you  want  to  exam¬ 
ine  a  particular  string  of  events.  Just 
before  starting  the  transaction,  sum¬ 
mon  up  the  dialog,  make  the  appropri¬ 
ate  changes,  and  continue. 

The  Gory  Details 

I  won’t  dwell  too  much  on  the  im¬ 
plementation  of  the  code  —  it  contains 


a  plethora  of  comments  and  is  built  out 
of  standard  Think  C  core  classes  —  but 
I  do  want  to  describe  a  bit  of  its  family 
heritage  so  that  you  can  understand 
how  to  include  CTrace  in  your  pro¬ 
grams.  The  tool  consists  of  three  classes, 
CTrace  (see  CTrace. h  in  Listing  One, 
page  116  and  CTrace. c  in  Listing  Two, 
page  116),  CLogPanorama  (see  CLog- 
Panorama.h  in  Listing  Three,  page  118, 
and  CLogPanorama. c  in  Listing  Four, 
page  118),  and  CLogList  (see  Listing 
Five,  page  120,  for  CLogList. h  and  List¬ 
ing  Six,  page  120,  for  CLogList. c).  Of 
these,  CTrace  is  specific  to  this  tool, 
while  CLogPanorama  and  CLogList  ate 
fairly  generic. 

CTrace  is  a  subclass  of  the  CDocu- 
ment  class  that  contains  two  local  in¬ 
stance  variables: 

•  currMask,  the  bit  mask  describing 
which  categories  are  enabled  and 
which  are  disabled. 

•  itsLogPanorama ,  a  CLogPanorama 
that  displays  the  log  messages. 

The  class  defines  five  local  methods: 

•  ITrace(  )  initializes  the  object  to  con¬ 
tain  some  maximum  number  of  log 
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Trace  Log 


AddGroup(linebuff=iex.general:S:1:40:) 
AddGroupO  returns 

AddGroup(linebuff=iex.photon:U:1 :1 50:233) 
AddGroupO  returns 
BuildGroupRec()  entry 
GetNth(index=1,groupRec=0x267A26 
GetNth()  returns  TRUE 
BuildDisplayText  (buff=0x26795A,groupRec= 
BuildDisplayText()  returns  TRUE 
including  comp.sys.mac 
GetNth(index=2,groupRec=0x267A26 
GetNth()  returns  TRUE 
BuildDisplayText(linebuff=0x0026795A,grou 
BuildDisplayTextO  returns  TRUE 


Figure  1:  CTrace  message  logging  window 

Errors  [ 

Warnings  [ 

£3  General  Info  [ 

□  Func  entrg  [ 

□  Func  enit  [ 

□  User  cmds  [ 

□  NNTP rqst  [ 

□  NNTP  rspns  [ 


□  SMTP  rqst 

□  SMTP  rspns 

□  TCP  Info 

□  Undefined 

□  Undefined 

□  Undefined 

□  Undefined 

□  Undefined 

I  Cancel  | 


Figure  2:  CTrace  dialog  box 
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(continued  from  page  46) 
records. 

•  ToggleTraceWindou>( )  shows  and 
hides  itsWindow  ( itsWindow  is  a 
CWindow  object  inherited  from 
CDocument). 

•  SetTraceMask( )  presents  a  dialog  for 
enabling  and  disabling  individual 
trace  mask  bits. 

®  Trace( )  receives  a  user  message  and 
category  from  the  application  and 
conditionally  adds  it  to  its  buffer  and 
window.  The  class  defines  an  exter¬ 
nal,  gTrace ,  which  points  to  the  class, 
so  that  code  can  reference  this 
method  directly  as  gTrace->Trace( ) 
instead  of  using  several  levels  of  in¬ 
direction  via  the  application. 

•  IsItVisible( ^returns  the  state  of  itsWin¬ 
dow  so  that  the  application  can  up¬ 
date  its  menus  appropriately. 

It  overrides  three  inherited  methods: 

•  UpdateMenusC  )  disables  some  of  the 
non-applicable  CDocument  methods. 

•  DoSaveAsC )  copies  the  buffer  con¬ 
tents  to  a  file. 


*  Close( )  hides  the  window  but  does 
not  actually  close  the  CTrace  docu¬ 
ment. 

CLogPanorama  is  a  subclass  of  the 
CPanorama  class  that  contains  a  sin¬ 
gle,  local  instance  variable: 

*  itsLogList,  a  CLogList  circular  buffer 
that  contains  the  logged  messages. 

It  defines  two  local  methods: 

•  lLogPane  initializes  the  panorama  and 
installs  it  in  the  owner’s  window  (in 
this  case,  CTrace’s  itsWindow ). 

•  AddString  inserts  an  ASCII  string  into 
itsLogList.  When  the  window  is  vis¬ 
ible,  it  also  draws  the  string  into  the 
panorama  and  does  whatever  is  re¬ 
quired  to  make  sure  that  the  newly 
displayed  line  is  visible.  This  involves 
a  bit  of  special  case  code;  refer  to  the 
inline  comments  for  more  elaborate 
details. 

The  class  overrides  one  of  its  inher¬ 
ited  methods  using  Draw( )  to  draw 


Resource  ID 

Type 

Description 

2000 

MENU 

dtitled  Trace,  with  the  items  Show  (command  2000)  and 

Mask  (command  2001 ). 

2000 

DITL 

buttons  OK  and  Cancel  (items  1  and  2),  checkboxes  Er¬ 
rors,  Warnings,  Info,  Func  entry,  and  Func  exit  (items  3 
through  7),  plus  27  additional  checkboxes  (items  8  through 

34)  titled  Undefined  and  marked  as  disabled. 

2000 

DLOG 

coordinates  (14, 34), (508, 286),  procID  1,  marked  as  vis¬ 
ible,  and  linked  to  DITL  2000. 

2000 

WIND 

titled  Trace  Log  at  coordinates  (1 6,52)(330,220),  procID  8, 
marked  not  visible,  with  the  goAwayFlag  enabled. 

1 

MBAR 

add  menu  res  ID  2000 

Table  1 :  Added/modified  resources 


gTrace->Trace  (T_INFO,  "Added  ' %s'  to  the  display  list", 
subject) ; 


Example  1:  Request  to  trace 


struct  CMyApp 

:  CApplication 

CTrace 

}; 

*itsTraceLog; 

Example  2:  Adding  CTrace  to 
CApplication 


itsTraceLog  =  new  (CTrace); 
itsTraceLog->ITrace  (1000); 


Example  3 •'  Initializing  CTrace 


gBartender->EnableMenu  (TRACE_MENU_ID) ; 
gBartender->EnableCmd  (TRACE_MENU_SHOW) ; 
gBartender->EnableCmd  (TRACE_MENU_MASK) ; 
if  (itsTraceLog->IsItVisible () ) 

gBartender-SCheckMarkCmd  (TRACE_MENU_SHOW,  TRUE) ; 

else 


gBartender->CheckMarkCmd  (TRACE_MENU_SHOW,  FALSE) ; 


Example  4:  Additions  to  UpdateMenusC  )  method 


the  visible  portion  of  the  buffer  text 
into  the  panorama. 

CLogList ,  based  on  CList ,  implements 
a  circular  buffer.  It  contains  tnaxRec,  a 
single,  local  instance  variable  that  de¬ 
fines  the  maximum  number  of  records 
allowed  in  the  list  and  five  local  meth¬ 
ods: 


•  ILogList( )  initializes  the  list  object. 

•  AddString( )  appends  the  string  to 
the  end  of  the  list.  If  the  list  has 
grown  to  its  maximum,  the  method 
also  deletes  the  first  record  in  the  list. 
Internally,  the  method  allocates  buffer 
space  dynamically  using  handles  on 
an  as-needed  basis. 

•  GetStringC )  returns  a  copy  of  a  par¬ 
ticular  entry  in  the  list. 

•  GetMaxRecordCount( )  returns  max- 
Rec. 

Finally,  CLogList  overrides  the  inher¬ 
ited  method  using  Dispose ( )  to  delete 
all  of  the  records  in  the  list. 

Using  Trace 

Like  most  classes,  CTrace  requires  a  bit 
of  preparation  to  use  in  your  program. 

First,  add  the  resources  in  Table  1  to 
your  application  (you  may  change  the 
resource  IDs  as  required,  but  be  sure 
to  update  the  references  in  the  header 
files  appropriately).  Within  your  code, 
you’ll  need  to  add  an  instance  like  that 
in  Example  2  of  the  CTrace  class  to 
your  application  class. 

In  your  IApplication( )  method  in¬ 
itialize  itsTraceLog  with  the  required 
number  of  records.  For  example,  the 
code  in  Example  3  prepares  CTrace  to 
accept  1000  entries  before  wrapping. 
In  your  application’s  UpdateMenusC ) 
method,  add  the  statements  in  Exam¬ 
ple  4.  Finally,  add  the  commands  in 
Example  5  to  your  application’s  DoCom- 
mand( )  method. 

To  use  CTrace  effectively,  you’ll  need 
to  define  masks  for  your  logging  cate¬ 
gories.  As  you  can  see  from  the  CTrace. h 
listing,  I’ve  defined  five  trace  masks: 

•  T_ERROR  for  logging  serious  errors 
that  may  prove  fatal. 

•  T_WARNING  for  logging  problems 
that  are  probably  not  fatal. 

•  T_LNFO  for  logging  valuable  runtime 
information. 

•  T_FUNC_LN  for  logging  function  or 
method  entry  (I  usually  include  pa¬ 
rameters  passed  into  the  function  as 
arguments  to  Trace(  J). 

•  T_FUNC_  OUT  for  logging  exit  from 
functions  or  methods  (I  usually  in¬ 
clude  the  return  value,  if  applicable, 
as  an  argument  to  Trace(  J). 

(continued  on  page  52) 


48 

1006 


Dr  Dobb’s Journal,  November  1990 


C  T  R  A  C  E 


0 continued  from  page  48) 

You  can  add  your  mask  definitions 
directly  to  the  CTrace.h  file,  or  you  may 
want  to  define  them  in  a  separate 
header.  In  any  case,  define  each  as  a 
unique  long  word  with  one  bit  set  as 
shown  in  Example  6.  You’ll  also  want 
to  edit  the  tracemask  DITL  resource  to 
put  meaningful  names  on  the  set  mask 
dialog  box.  A  couple  of  comments  may 
be  appropriate  here.  First,  the  mask 
can  contain  up  to  32  categories,  but 
your  application  may  not  require  this 
many.  You  may  want  to  resize  and 
rearrange  the  dialog  box  to  show  only 
those  categories  that  you  have  defined. 
Note  that  DITL  item  #3  corresponds  to 
mask  0x000000001,  DITL  #4  to  mask 
0x00000002,  and  so  on.  Also  note  that 


Example  5:  Additions  to  DoCommandl 


Example  6:  Adding  mask  definitions 


the  dialog  logic  disables  access  to  any 
items  titled  “Undefined.”  This  prevents 
you  from  enabling  categories  for  which 
there  is  no  corresponding  mask. 

At  this  point,  you  can  begin  embed¬ 
ding  log  requests  in  your  code.  I  have 
no  great  advice  to  give  you  with  regard 
to  when  and  where  to  place  Trace( ) 
statements  in  your  code.  I  usually  put 
them  at  the  entry  and  exit  points  in 
functions,  and,  depending  on  the  com¬ 
plexity  of  the  code,  before  or  after  vital 
actions.  And  you  should,  of  course, 
include  them  in  your  error  checking 
logic. 

One  note  with  regard  to  the  content 
of  your  log  messages  —  the  method 
uses  varargs.  Hence,  in  theory  you  can 
have  as  many  arguments  as  you  wish. 


)  method 


Internally,  however,  the  method  has 
some  self-preservation  safeguards  —  if 
you  try  to  form  a  message  longer  than 
200  characters,  it  will  truncate  your  mes¬ 
sage  back  to  this  limit. 

Hide  It  or  Remove  It? 

Once  you’ve  completed  all  of  the  cod¬ 
ing  and  debugging  for  your  program, 
you’ll  no  doubt  want  to  hide  CTrace 
from  the  end-user.  You  could  run 
through  all  of  your  code  and  purge  all 
references  to  CTrace,  but  it’s  really  much 
simpler  to  edit  the  MBAR  resource  so 
that  the  Trace  menu  entry  doesn’t  show 
up  on  the  menu  bar.  And,  because  the 
default  trace  mask  has  no  categories 
enabled,  you  won’t  be  using  up  much 
additional  memory  (remember  that 
CLogList allocates  buffer  space  dynami¬ 
cally).  You  could  make  an  argument 
that  all  of  those  TraceC )  calls  will  add 
unnecessary  overhead  to  your  program; 
I  won’t  disagree  that  it  adds  some  over¬ 
head,  but  because  TraceC )  returns  im¬ 
mediately  if  it  doesn’t  see  a  match  be¬ 
tween  the  passed  mask  and  its  internal 
mask,  you’re  really  looking  at  only  a 
handful  of  machine  instructions  per  call. 

Keeping  CTrace  in  the  wings  also 
enhances  your  support  capabilities  if 
you  have  friendly  users  —  if  some  anom- 
( continued  on  page  55) 


♦define  T_PICT_REDRAW  (0x00002000L)  /*  screen  refresh  logging  */ 


case  TRACE_MENU_SHOW  : 

itsTraceLog->ToggleTraceWindow ( ) ; 
break; 

case  TRACE_MENU_MASK  : 

itsTraceLog->SetTraceMask () ; 
break; 
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aly  arises  in  the  field,  CTrace  is  only  a 

ResEdit  away. 

Customizing  CTrace 

CTrace  is  ready  for  use  out  of  the  box. 
This  is  not  to  say  that  it  doesn’t  have 
room  for  improvement.  A  short  list  of 
possible  extensions  includes  the  fol¬ 
lowing: 

•  When  the  CTrace  methods  allocate 
internal  memory,  they  make  the  rash 
assumption  that  memory  will  be  avail¬ 
able.  My  own  version  of  CTrace  in¬ 
cludes  a  call  to  CheckAllocation( ) 
around  every  NewHandleC ),  but  I  left 
this  out  of  the  version  described  here 
because  you  probably  have  your  own 
strategies  for  dealing  with  low  mem¬ 
ory. 

•  A  clever  macro  could  perform  the 
mask  compare  inline  and  save  the 
expense  of  unnecessary  function  calls. 
I’m  more  pragmatic  than  clever,  so  I 
haven’t  spent  the  time  developing  such 
a  macro. 

•  The  log  pane  uses  simple  Quick¬ 
Draw  DrawStringC )  commands  to  place 
text  into  the  panorama.  This  limits  the 
number  of  records  you  can  store  in  the 
buffer  to  about  2700  records.  If  this 
proves  insufficient,  you  may  choose 
to  modify  the  methods  used  by 
CLogPanorama  to  circumvent  this  limit. 

•  One  of  the  predecessors  of  this  util¬ 
ity  embedded  the  file  and  the  line  num¬ 
ber  of  the  calling  program  as  part  of  the 
logged  message.  Think  C  supports  the 
necessary  macros  (_ FILE_  and  _LINE_, 
respectively),  but  I  chose  not  to  in¬ 
clude  them  in  this  version.  You  can 
certainly  add  them  to  your  version. 

•  While  CTrace  supports  the  DoSave- 
As()  CDocument  method,  it  does  so 
only  on  request.  A  nice  extension  to 
CTrace  may  include  writing  the  log 
message  to  a  file  as  well  as  the  CLogPano¬ 
rama.  This  may  come  in  handy  if  your 
programs  have  the  nasty  habit  of  leav¬ 
ing  your  Mac  in  some  altered  state! 

•  Finally,  while  I’ve  done  nothing  to 
inhibit  use  of  the  inherited  DoPrint( ) 
method,  I’ve  also  done  nothing  to  en¬ 
hance  it.  If  you  have  a  need  to  produce 
pretty,  formatted  printouts  of  the  trace 
log,  you  can  override  the  inherited 
PrintPageOJDoc( )  method. 

ddj 

(Listings  begin  on  page  116.) 
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Is  this  the  future  of  programming? 


by  The  League  for  Programming  Freedom 


Software  patents  threaten  to  dev¬ 
astate  America’s  computer  indus¬ 
try.  Newly  granted  software  pat¬ 
ents  are  being  used  to  attack  com¬ 
panies  such  as  Lotus  and  Micro¬ 
soft  for  selling  programs  that  they  have 
independently  developed.  Soon  new 
companies  will  be  barred  from  the  soft¬ 
ware  arena  —  most  major  programs  will 
require  licenses  for  dozens  of  patents, 
and  this  will  make  them  infeasible.  This 
problem  has  only  one  solution:  Soft¬ 
ware  patents  must  be  eliminated. 

The  Patent  System  and  Computer  Programs 

The  Framers  of  the  United  States  Con¬ 
stitution  established  the  patent  system 
so  that  inventors  would  have  an  incen¬ 
tive  to  share  their  inventions  with  the 
general  public.  In  exchange  for  divulg¬ 
ing  an  invention,  the  patent  grants  the 
inventor  a  17-year  monopoly  on  the 
use  of  the  invention.  The  patent  holder 
can  license  others  to  use  the  invention, 
but  may  also  refuse  to  do  so.  Indepen¬ 
dent  reinvention  of  the  same  technique 
by  others  does  not  give  them  the  right 
to  use  it. 


This  article  is  a  position  paper  of  the 
League  for  Programming  Freedom,  an 
organization  opposed  to  software  pat¬ 
ents  and  interface  copyrights  and  ivhose 
members  include,  among  others, 
Marvin  Minsky,  John  McCarthy,  and 
Robert  S.  Boyer.  Richard  Stallman  and 
Simson  Garfinkel  helped  prepare  this 
article  for  publication.  You  can  con¬ 
tact  the  League  through  Internet  mail 
fleague@prep.ai.mit.edul  or  at  l  Ken¬ 
dal  Square  #143,  P-O.  Box 91 71,  Cam¬ 
bridge,  MA  02139. 


Patents  do  not  cover  specific  com¬ 
puter  programs;  instead,  they  cover  par¬ 
ticular  techniques  that  can  be  used  to 
build  programs,  or  particular  features 
that  programs  can  offer.  Once  a  tech¬ 
nique  or  feature  is  patented,  it  may  not 
be  used  in  a  program  without  the  per¬ 
mission  of  the  patent  holder  —  even  if 
it  is  implemented  in  a  different  way. 
Since  a  program  typically  uses  many 
techniques  and  provides  many  features, 
it  can  infringe  many  patents  at  once. 

Until  recently,  patents  were  not  used 
in  the  software  field.  Software  develop¬ 
ers  copyrighted  individual  programs  or 
made  them  trade  secrets.  Copyright  was 
traditionally  understood  to  cover  the 
implementation  details  of  a  particular 
program;  it  did  not  cover  the  features 
of  the  program,  or  the  general  methods 
used.  And  trade  secrecy,  by  definition, 
could  not  prohibit  any  development 
work  by  someone  who  did  not  know 
the  secret. 

On  this  basis,  software  development 


was  extremely  profitable  and  received 
considerable  investment,  without  any 
prohibition  on  independent  software 
development.  But  this  scheme  of  things 
is  no  more.  A  few  U.S.  software  patents 
were  granted  in  the  early  1980s,  stimu¬ 
lating  a  flood  of  applications.  Now  many 
patents  have  been  approved  and  the 
rate  is  accelerating.  Many  programmers 
are  unaware  of  the  change  and  do  not 
appreciate  the  magnitude  of  its  effects. 
Today  the  lawsuits  are  just  beginning. 

Absurd  Patents 

The  Patent  Office  and  the  courts  have 
had  a  difficult  time  with  computer  soft¬ 
ware.  The  Patent  Office  refused  until 
recently  to  hire  computer  science  gradu¬ 
ates  as  examiners,  and  in  any  case  does 
not  offer  competitive  salaries  for  the 
field.  Patent  examiners  are  often  ill- 
prepared  to  evaluate  software  patent 
applications  to  determine  if  they  repre¬ 
sent  techniques  that  are  widely  known 
or  obvious  —  both  of  which  are  grounds 
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(continued  from  page  56) 
for  rejection.  Their  task  is  made  more 
difficult  because  many  commonly  used 
software  techniques  do  not  appear  in 
the  scientific  literature  of  computer  sci¬ 
ence:  Some  seemed  too  obvious  to  pub¬ 
lish  while  others  seemed  insufficiently 
general. 

Computer  scientists  know  many  tech¬ 
niques  that  can  be  generalized  to  widely 
varying  circumstances.  But  the  Patent 
Office  seems  to  believe  that  each  sepa¬ 
rate  use  of  a  technique  is  a  candidate 
for  a  new  patent.  For  example,  Apple 
has  been  sued  because  the  HyperCard 
program  allegedly  violates  patent  num¬ 
ber  4,736,308,  a  patent  that  covers  dis¬ 
playing  portions  of  two  or  more  strings 
together  on  the  screen  —  effectively 
scrolling  with  multiple  subwindows. 
Scrolling  and  subwindows  are  well- 
known  techniques,  but  combining  them 
is  apparently  illegal. 

The  granting  of  a  patent  by  the  Pat¬ 
ent  Office  carries  a  presumption  in  law 
that  the  patent  is  valid.  Patents  for  well- 
known  techniques  that  were  in  use 
many  years  before  the  patent  applica¬ 
tion  have  been  upheld  by  federal  courts. 

For  example,  the  technique  of  using 
ex clusive-or  to  write  a  cursor  onto  a 
screen  is  both  well-known  and  obvi¬ 
ous.  (Its  advantage  is  that  another  iden¬ 
tical  exclusive-or  operation  can  be  used 
to  erase  the  cursor  without  damaging 
the  other  data  on  the  screen.)  This  tech¬ 
nique  can  be  implemented  in  a  few 
lines  of  a  program,  and  a  clever  high- 


school  student  might  well  reinvent  it. 
But  it  is  covered  by  patent  number 
4,197,590,  which  has  been  upheld  twice 
in  court  even  though  the  technique 
was  used  at  least  five  years  before  the 
patent  application.  Cadtrak,  the  com¬ 
pany  that  owns  this  patent,  collects 
millions  of  dollars  from  large  computer 
manufacturers. 

English  patents  covering  customary 
graphics  techniques,  including  airbrush- 
ing,  stenciling,  and  combination  of  two 
images  under  control  of  a  third,  were 
recently  upheld  in  court,  despite  the 
testimony  of  the  pioneers  of  the  field 
that  they  had  developed  these  tech¬ 
niques  years  before.  (The  correspond¬ 
ing  United  States  patents,  including 
4,633,416  and  4,602,286,  have  not  yet 
been  tested  in  court,  but  they  probably 
will  be  soon.) 

All  the  major  developers  of  spread¬ 
sheet  programs  have  been  threatened 
on  the  basis  of  patent  4,398,249,  cover¬ 
ing  “natural  order  recalc,”  the  recalcula¬ 
tion  of  all  the  spreadsheet  entries  that 
are  affected  by  the  changes  the  user 
makes,  rather  than  recalculation  in  a 
fixed  order.  Currently  Lotus  alone  is 
being  sued,  but  a  victory  for  the  plain¬ 
tiff  in  the  case  would  leave  the  other 
developers  little  hope.  (The  League  for 
Programming  Freedom  has  found  prior 
art  that  may  defeat  this  patent,  but  this 
is  not  assured.) 

Nothing  protects  programmers  from 
accidentally  using  a  technique  that  is 
(continued  on  page  62) 


What  You  Can  Do 


The  League  for  Programming  Free¬ 
dom  is  a  grass-roots  organization  of 
programmers  and  users  opposing  soft¬ 
ware  patents  and  interface  copyrights. 
(The  League  is  not  opposed  to  copy¬ 
right  on  individual  programs.)  Annual 
dues  for  individual  members  are  $42 
for  employed  professionals,  $10.50  for 
students,  and  $21  for  others.  We  ap¬ 
preciate  activists,  but  members  who 
cannot  contribute  their  time  are  also 
welcome. 

To  contact  the  League,  phone  617- 
243-4091,  send  Internet  mail  to: 
league@prep.ai.mit.edu 
or  write  to: 

The  League  for  Programming 
Freedom 

1  Kendall  Square  #143 
P.O.  Box  9171 
Cambridge,  MA  02139 

In  the  .United  States,  another  way 
to  help  is  to  write  to  Congress.  You 


can  write  to  your  own  representa¬ 
tives,  but  it  may  be  even  more  effec¬ 
tive  to  write  to  the  subcommittees 
that  consider  such  issues: 

House  Subcommittee  on 
Intellectual  Property 
2137  Rayburn  Bldg. 

Washington,  DC  20515 

Senate  Subcommittee  on  Patents, 
Trademarks  and  Copyrights 
United  States  Senate 
Washington,  DC  20510 

To  write  your  own  representatives, 
use  the  following  addresses: 

Senator  name 
United  States  Senate 
Washington,  DC  20510 

Representative  name 
House  of  Representatives 
Washington,  DC  20515 
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(continued  from  page  58) 
patented  —  and  then  being  sued  for  it. 
Taking  an  existing  program  and  mak¬ 
ing  it  run  faster  may  also  make  it  violate 
half  a  dozen  patents  that  have  been 
granted,  or  are  about  to  be  granted. 

Even  if  the  Patent  Office  learns  to 
understand  software  better,  the  mis¬ 
takes  it  is  making  now  will  follow  us 
into  the  next  century,  unless  Congress 
or  the  Supreme  Court  intervenes  to  de¬ 
clare  these  patents  void. 

However,  this  is  not  the  whole  of  the 
problem.  Computer  programming  is  fun¬ 
damentally  different  from  the  other  fields 
that  the  patent  system  previously  cov¬ 
ered.  Even  if  the  patent  system  were 
to  operate  “as  intended”  for  software, 
it  would  still  obstruct  the  industry  it  is 
supposed  to  promote. 

What  is  "Obvious"? 

The  patent  system  will  not  grant  or  up¬ 
hold  patents  that  are  judged  to  be  obvi¬ 
ous.  However,  the  system  interprets  the 
word  “obvious”  in  a  way  that  might 
surprise  computer  programmers.  The  stan¬ 
dard  of  obviousness  developed  in  other 
fields  is  inappropriate  for  software. 

Patent  examiners  and  judges  are  ac¬ 
customed  to  considering  even  small, 
incremental  changes  as  deserving  new 
patents.  For  example,  the  famous  Po¬ 
laroid  vs.  Kodak  case  hinged  on  differ¬ 
ences  in  the  number  and  order  of  lay¬ 
ers  of  chemicals  in  a  film  —  differences 
between  the  technique  Kodak  was  us¬ 
ing  and  those  described  by  previous, 
expired  patents.  The  court  ruled  that 
these  differences  were  unobvious. 

Computer  scientists  solve  problems 
quickly  because  the  medium  of  pro¬ 
gramming  is  tractable.  They  are  trained 
to  generalize  solution  principles  from 
one  problem  to  another.  One  such  gen¬ 
eralization  is  that  a  procedure  can  be 
repeated  or  subdivided.  Programmers 
consider  this  obvious  —  but  the  Patent 
Office  did  not  think  that  it  was  obvious 
when  it  granted  the  patent  on  scrolling 
multiple  strings  as  described  above. 

Cases  such  as  this  cannot  be  con¬ 
sidered  errors.  The  patent  system  is 
functioning  as  it  was  designed  to  do  — 
but  with  software,  it  produces  outra¬ 
geous  results. 

Patenting  What  is  too  Obvious  to  Publish 

Sometimes  it  is  possible  to  patent  a 
technique  that  is  not  new  precisely  be¬ 
cause  it  is  obvious  —  so  obvious  that 
no  one  would  have  published  a  paper 
about  it. 

For  example,  computer  companies 
distributing  the  free  X  Window  System 
(developed  by  MIT)  are  now  being 
threatened  with  lawsuits  by  AT&T  over 
(continued  on  page  65) 
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(continued  from  page  62) 
patent  number  4,555,775,  covering  the 
use  of  “backing  store.”  This  technique 
is  used  when  there  are  overlapping 
windows;  the  contents  of  a  window 
that  is  partly  hidden  are  saved  in  off¬ 
screen  memory,  so  they  can  be  put 
back  quickly  on  the  screen  if  the  ob¬ 
scuring  window  disappears  (as  often 
happens). 

The  technique  of  backing  store  was 
used  in  an  earlier  MIT  project,  the  Lisp 
Machine  System,  before  AT&T  applied 
for  the  patent.  The  Lisp  Machine  devel¬ 
opers  published  nothing  about  this  de¬ 
tail  at  the  time,  considering  it  too  obvi¬ 
ous.  It  was  mentioned  years  later  when 
the  programmers’  reference  manual  ex¬ 
plained  how  to  turn  it  on  and  off. 

The  Lisp  Machine  was  the  first  com¬ 
puter  to  use  this  technique  only  because 
it  had  a  larger  memory  than  earlier  ma¬ 
chines  that  had  window  systems.  Prior 
window  system  developers  must  have 
dismissed  the  idea  because  their  ma¬ 
chines  had  insufficient  memory  space 
to  spare  any  for  this  purpose.  Improve¬ 
ments  in  memory  chips  made  develop¬ 
ment  of  backing  store  inevitable. 

Without  a  publication,  the  use  of 
backing  store  in  the  Lisp  Machine  Sys¬ 
tem  may  not  count  as  prior  art  to  de¬ 
feat  the  patent.  So  the  AT&T  patent 


may  stand,  and  MIT  may  be  forbidden 
to  continue  using  a  method  that  MIT 
used  before  AT&T. 

The  result  is  that  the  dozens  of  com¬ 
panies  and  hundreds  of  thousands  of 
users  who  accepted  the  software  from 

Computer  scientists  are 
trained  to  generalize 
solution  principles  from 
one  problem  to  another 


MIT  with  the  understanding  that  it  was 
free  are  now  faced  with  possible  law¬ 
suits.  (They  are  also  being  threatened 
with  Cadtrak’s  exclusive-or  patent.)  The 
X  Window  project  was  intended  to  de¬ 
velop  a  window  system  that  all  de¬ 
velopers  could  use  freely.  This  public 
service  goal  seems  to  have  been 
thwarted  by  patents. 

Why  Software  is  Different 

Software  systems  are  much  easier  to 
design  than  hardware  systems  of  the 
same  number  of  components.  For  ex¬ 
ample,  a  program  of  100,000  compo¬ 


nents  might  be  50,000  lines  long  and 
could  be  written  by  two  good  program¬ 
mers  in  a  year.  The  equipment  needed 
for  this  costs  less  than  $10,000;  the  only 
other  cost  would  be  the  programmers’ 
living  expenses  while  doing  the  job. 
The  total  investment  would  be  less  than 
$100,000.  If  done  commercially  in  a 
large  company,  it  might  cost  twice  that. 
By  contrast,  an  automobile  typically 
contains  under  100,000  components; 
it  requires  a  large  team  and  costs  tens 
of  millions  of  dollars  to  design. 

And  software  is  also  much  cheaper 
to  manufacture:  Copies  can  be  made 
easily  on  an  ordinary  workstation  cost¬ 
ing  under  $10,000.  To  produce  a  hard¬ 
ware  system  often  requires  a  factory 
costing  tens  of  millions  of  dollars. 

Why  is  this?  A  hardware  system  has 
to  be  designed  using  real  components. 
They  have  varying  costs;  they  have  lim¬ 
its  of  operation;  they  may  be  sensitive 
to  temperature,  vibration,  or  humidity; 
they  may  generate  noise;  they  drain 
power;  they  may  fail  either  momentar¬ 
ily  or  permanently.  They  must  be  physi¬ 
cally  assembled  in  their  proper  places, 
and  they  must  be  accessible  for  re¬ 
placement  in  case  they  fail. 

Moreover,  each  of  the  components 
in  a  hardware  design  is  likely  to  affect 
the  behavior  of  many  others.  This  greatly 


Dr.  Dobb’s  Journal,  November  1990 

1012 


65 


PATENTS 


complicates  the  task  of  determining 
what  a  hardware  design  will  do:  Mathe¬ 
matical  modeling  may  prove  wrong 
when  the  design  is  built. 

By  contrast,  a  computer  program  is 
built  out  of  ideal  mathematical  objects 
whose  behavior  is  defined,  not  mod¬ 
eled  approximately,  by  abstract  rules. 
When  an  if  statement  follows  a  while 
statement,  there  is  no  need  to  study 
whether  the  if  statement  will  draw 
power  from  the  while  statement  and 
thereby  distort  its  output,  nor  whether 
it  could  overstress  the  while  statement 
and  make  it  fail. 

Despite  being  built  from  simple  parts, 
computer  programs  are  incredibly  com¬ 
plex.  The  program  with  100,000  parts 
is  as  complex  as  an  automobile,  though 
far  easier  to  design. 

While  programs  cost  substantially  less 
to  write,  market,  and  sell  than  automo¬ 
biles,  the  cost  of  dealing  with  the  pat¬ 
ent  system  will  not  be  less.  The  same 
number  of  components  will,  on  the 
average,  involve  the  same  number  tech¬ 
niques  that  might  be  patented. 

The  Danger  of  a  Lawsuit 

Under  the  current  patent  system,  a  soft¬ 
ware  developer  who  wishes  to  follow 
the  law  must  determine  which  patents 
a  program  violates  and  negotiate  with 
each  patent  holder  a  license  to  use  that 
patent.  Licensing  may  be  prohibitively 
expensive,  as  in  the  case  when  the 
patent  is  held  by  a  competitor.  Even 
“reasonable”  license  fees  for  several 
patents  can  add  up  to  make  a  project 
infeasible.  Alternatively,  the  developer 
may  wish  to  avoid  using  the  patent 
altogether;  but  there  may  be  no  way 
around  it. 

The  worst  danger  of  the  patent  sys¬ 
tem  is  that  a  developer  might  find,  after 
releasing  a  product,  that  it  infringes 
one  or  many  patents.  The  resulting  law¬ 
suit  and  legal  fees  could  force  even  a 
medium-size  company  out  of  business. 

Worst  of  all,  there  is  no  practical  way 
for  a  software  developer  to  avoid  this 
danger  —  there  is  no  effective  way  to 
find  out  what  patents  a  system  will 
infringe.  There  is  a  way  to  try  to  find 
out  —  a  patent  search  —  but  searches 
are  unreliable  and  in  any  case  too  ex¬ 
pensive  to  use  for  software  projects. 

Patent  Searches  are  Prohibitively  Expensive 

A  system  with  100,000  components  can 
use  hundreds  of  techniques  that  might 
already  be  patented.  Since  each  patent 
search  costs  thousands  of  dollars,  search¬ 
ing  for  all  the  possible  points  of  danger 
could  easily  cost  over  a  million.  This  is 
far  more  than  the  cost  of  writing  the 
program. 

The  costs  don’t  stop  there.  Patent 
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applications  are  written  by  lawyers  for 
lawyers.  A  programmer  reading  a  pat¬ 
ent  may  not  believe  that  his  program 
violates  the  patent,  but  a  federal  court 
may  rule  otherwise.  It  is  thus  now  nec¬ 
essary  to  involve  patent  attorneys  at 
every  phase  of  program  development. 

Yet  this  only  reduces  the  risk  of  be¬ 
ing  sued  later  —  it  does  not  eliminate 
the  risk.  So  it  is  necessary  to  have  a 
reserve  of  cash  for  the  eventuality  of  a 
lawsuit. 

When  a  company  spends  millions 
to  design  a  hardware  system,  and  plans 
to  invest  tens  of  millions  to  manufac¬ 
ture  it,  an  extra  million  or  two  to  pay 
for  dealing  with  the  patent  system  might 
be  bearable.  However,  for  the  inex¬ 
pensive  programming  project,  the  same 
extra  cost  is  prohibitive.  Individuals  and 
small  companies  especially  cannot  af¬ 
ford  these  costs.  Software  patents  will 
put  an  end  to  software  entrepreneurs. 

Patent  Searches  are  Unreliable 

Even  if  developers  could  afford  patent 
searches,  these  are  not  a  reliable  method 
of  avoiding  the  use  of  patented  tech¬ 
niques.  This  is  because  patent  searches 
do  not  reveal  pending  patent  applica¬ 
tions  (which  are  kept  confidential  by 
the  Patent  Office).  Since  it  takes  several 
years  on  the  average  for  a  software  pat¬ 
ent  to  be  granted,  this  is  a  serious  prob¬ 
lem:  A  developer  could  begin  designing 
a  large  program  after  a  patent  has  been 
applied  for,  and  release  the  program 
before  the  patent  is  approved.  Only 
later  will  the  developer  learn  that  distri¬ 
bution  of  the  program  is  prohibited. 

For  example,  the  implementors  of 
the  widely  used  public  domain  data 
compression  program  compress  fol¬ 
lowed  an  algorithm  obtained  from  IEEE 
Computer  magazine.  They  and  the  user 
community  were  surprised  to  learn  later 
that  patent  number  4,558,302  had  been 
issued  to  one  of  the  authors  of  the 
article.  Now  Unisys  is  demanding  roy¬ 
alties  for  using  this  algorithm.  Although 
the  program  is  still  in  the  public  domain  — 
using  it  means  risking  a  lawsuit. 

The  Patent  Office  does  not  have  a 
workable  scheme  for  classifying  soft¬ 
ware  patents.  Patents  are  most  fre¬ 
quently  classified  by  end  results,  such 
as  “converting  iron  to  steel,”  but  many 
patents  cover  algorithms  whose  use  in 
a  program  is  entirely  independent  of 
the  purpose  of  the  program.  For  exam¬ 
ple,  a  program  to  analyze  human  speech 
might  infringe  the  patent  on  a  speedup 
in  the  Fast  Fourier  Transform;  so  might 
a  program  to  perform  symbolic  algebra 
(in  multiplying  large  numbers);  but  the 
category  to  search  for  such  a  patent 
would  be  hard  to  predict. 

(continued  on  page  70) 
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(continued  from  page  67) 

You  might  think  it  would  be  easy  to 
keep  a  list  of  the  patented  software 
techniques,  or  even  simply  remember 
them.  However,  managing  such  a  list 
is  nearly  impossible.  A  list  compiled  in 
1989  by  lawyers  specializing  in  the  field 
omitted  some  of  the  patents  mentioned 
in  this  article. 

Obscure  Patents 

When  you  imagine  an  invention,  you 
probably  think  of  something  that  could 
be  described  in  a  few  words,  such  as  “a 
flying  machine  with  fixed,  curved 
wings”  or  “an  electrical  communicator 
with  a  microphone  and  a  speaker.” 
But  most  patents  cover  complex  de¬ 
tailed  processes  that  have  no  simple 
descriptions  —  often  they  are  speed- 
ups  or  variants  of  well-known  processes 
that  are  themselves  complex. 

Most  of  these  patents  are  neither  ob¬ 
vious  nor  brilliant;  they  are  obscure.  A 
capable  software  designer  will  “invent” 
several  such  improvements  in  the  course 
of  a  project.  However,  there  are  many 
avenues  for  improving  a  technique,  so 
no  single  project  is  likely  to  find  any 
given  one. 

For  example,  IBM  has  several  pat¬ 
ents  (including  patent  4,656,583)  on 
workmanlike,  albeit  complex,  speed- 
ups  for  well-known  computations  per¬ 
formed  by  optimizing  compilers,  such 
as  register  coloring  and  computing  the 
available  expressions. 

Patents  are  also  granted  on  combi¬ 
nations  of  techniques  that  are  already 
widely  used.  One  example  is  IBM  pat¬ 
ent  4,742,450,  which  covers  “shared 
copy-on-write  segments.”  This  tech¬ 
nique  allows  several  programs  to  share 
the  same  piece  of  memory  that  repre¬ 
sents  information  in  a  file;  if  any  pro¬ 
gram  writes  a  page  in  the  file,  that  page 
is  replaced  by  a  copy  in  all  of  the 
programs,  which  continue  to  share  that 
page  with  each  other  but  no  longer 
share  with  the  file. 

Shared  segments  and  copy-on-write 
have  been  used  since  the  1960s.  This 
particular  combination  may  be  new  as 
a  specific  feature,  but  is  hardly  an  in¬ 
vention.  Nevertheless,  the  Patent  Of¬ 
fice  thought  that  it  merited  a  patent, 
which  must  now  be  taken  into  account 
by  the  developer  of  any  new  operating 
system. 

Obscure  patents  are  like  land  mines: 
Other  developers  are  more  likely  to 
reinvent  these  techniques  than  to  find 
out  about  the  patents,  and  then  they 
will  be  sued.  The  chance  of  running 
into  any  one  of  these  patents  is  small, 
but  they  are  so  numerous  that  you  can¬ 
not  go  far  without  hitting  one.  Every 
basic  technique  has  many  variations, 


and  a  small  set  of  basic  techniques  can 
be  combined  in  many  ways.  The  pat¬ 
ent  office  has  now  granted  more  than 
2000  software  patents  —  700  in  1989 
alone.  We  can  expect  the  pace  to  ac¬ 
celerate.  In  ten  years,  programmers  will 
have  no  choice  but  to  march  on  blindly 
and  hope  they  are  lucky. 

Patent  Licensing  has  Problems,  too 

Most  large  software  companies  are  try¬ 
ing  to  solve  the  problem  of  patents  by 
getting  patents  of  their  own.  Then  they 
hope  to  cross-license  with  the  other 
large  companies  that  own  most  of  the 
patents,  so  they  will  be  free  to  go  on 
as  before. 

While  this  approach  will  allow  com¬ 
panies  such  as  Microsoft,  Apple,  and 
IBM  to  continue  in  business,  it  will 
shut  new  companies  out  of  the  field. 
A  future  start-up,  with  no  patents  of  its 
own,  will  be  forced  to  pay  whatever 
price  the  giants  choose  to  impose.  That 
price  might  be  high:  Established  com¬ 
panies  have  an  interest  in  excluding 
future  competitors.  The  recent  Lotus 
lawsuits  against  Borland  International 
and  the  Santa  Cruz  Operation  (although 
involving  an  extended  idea  of  copy¬ 
right  rather  than  patents)  show  how 
this  can  work. 

Even  the  giants  cannot  protect  them¬ 
selves  with  cross-licensing  from  com¬ 
panies  whose  only  business  is  to  buy 
patents  and  then  threaten  to  sue.  For 
example,  the  New  York-based  Refac 
Technology  Development  Corporation, 
a  company  that  represents  Forward  Ref¬ 
erence  Systems  (owners  of  the  patent 
for  natural  order  recalc) ,  recently  sued 
Lotus  Corporation.  Natural  order  re¬ 
calc  is  Refac’s  first  foray  into  the  soft¬ 
ware  patent  arena;  for  the  past  40  years, 
the  company  has  negotiated  licenses 
in  the  fastener  and  electronic  compo¬ 
nent  industries.  The  company  employs 
no  programmers  or  engineers. 

Refac  is  demanding  —  in  the  neigh¬ 
borhood  of — five  percent  of  sales  of 
all  major  spreadsheet  programs.  If  a 
future  program  infringes  on  20  such 
patents  —  and  this  is  not  unlikely,  given 
the  complexity  of  computer  programs 
and  the  broad  applicability  of  many 
patents  —  the  combined  royalties  could 
exceed  100  percent  of  the  sales  price. 

The  Fundamental  Question 

According  to  the  Constitution  of  the 
United  States,  the  purpose  of  patents 
is  to  “promote  the  progress  of  science 
and  the  useful  arts.”  Thus,  the  basic 
question  at  issue  is  whether  software 
patents,  supposedly  a  method  of  en¬ 
couraging  software  progress,  will  truly 
do  so,  or  will  retard  progress  instead. 

So  far  we  have  explained  the  ways 
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in  which  patents  will  make  ordinary 
software  development  difficult.  But  what 
of  the  intended  benefits  of  patents:  More 
invention,  and  more  public  disclosure 
of  inventions?  To  what  extent  will  these 
actually  occur  in  the  field  of  software? 

There  will  be  little  benefit  to  society 
from  software  patents  because  inven¬ 
tion  in  software  was  already  flourish¬ 
ing  before  software  patents,  and  inven¬ 
tions  were  normally  published  in  jour¬ 
nals  for  everyone  to  use.  Invention  flour¬ 
ished  so  strongly,  in  fact,  that  the  same 
inventions  were  often  found  again  and 
again. 

In  Software,  Independent  Reinvention  is 
Commonplace 

A  patent  is  an  absolute  monopoly;  ev¬ 
eryone  is  forbidden  to  use  the  patented 
process,  even  those  who  reinvent  it 
independently.  This  policy  implicitly 
assumes  that  inventions  are  rare  and 
precious,  because  only  in  those  cir¬ 
cumstances  is  it  beneficial. 

The  field  of  software  is  one  of  con¬ 
stant  reinvention;  as  some  people  say, 
programmers  throw  away  more  “in¬ 
ventions”  each  week  than  other  peo¬ 
ple  develop  in  a  year.  And  the  com¬ 
parative  ease  of  designing  large  soft¬ 
ware  systems  makes  it  easy  for  many 
people  to  do  work  in  the  field.  A  pro¬ 
grammer  solves  many  problems  in  de¬ 
veloping  each  program.  These  solu¬ 
tions  are  likely  to  be  reinvented  fre¬ 
quently  as  other  programmers  tackle 
similar  problems. 

The  prevalence  of  independent  rein¬ 
vention  negates  the  usual  purpose  of 
patents.  Patents  are  intended  to  en¬ 
courage  inventions  and,  above  all,  the 
disclosure  of  inventions.  If  a  technique 
will  be  reinvented  frequently,  there  is 
no  need  to  encourage  more  people  to 
invent  it;  because  some  of  the  develop¬ 
ers  will  choose  to  publish  it  (if  publica¬ 
tion  is  merited),  there  is  no  point  in 
encouraging  a  particular  inventor  to 
publish  it  —  not  at  the  cost  of  inhibit¬ 
ing  use  of  the  technique. 

Overemphasis  of  Inventions 

Many  analysts  of  the  American  and  Japa¬ 
nese  industry  have  attributed  Japanese 
success  at  producing  quality  products 
to  the  fact  that  they  emphasize  incre¬ 
mental  improvements,  convenient  fea¬ 
tures,  and  quality  rather  than  notewor¬ 
thy  inventions. 

It  is  especially  true  in  software  that 
success  depends  primarily  on  getting 
the  details  right.  And  that  is  most  of  the 
work  in  developing  any  useful  soft¬ 
ware  system.  Inventions  are  a  com¬ 
paratively  unimportant  part  of  the  job. 

The  idea  of  software  patents  is  thus 
an  example  of  the  mistaken  American 


preoccupation  with  inventions  rather 
than  products.  And  patents  will  further 
reinforce  this  mistake,  rewarding  not 
the  developers  who  write  the  best  soft¬ 
ware,  but  those  who  were  first  to  file 
for  a  patent. 

Impeding  Innovation 

By  reducing  the  number  of  people  en¬ 
gage  in  software  development,  soft¬ 
ware  patents  will  actually  impede  in¬ 
novation.  Much  software  innovation 
comes  from  programmer’s  solving  prob¬ 
lems  while  developing  software,  not 
from  projects  whose  specific  purpose 
is  to  make  invention  and  obtain  pat¬ 
ents.  In  other  words,  these  innovations 


are  byproducts  of  software  develop¬ 
ment. 

When  patents  make  development 
more  difficult,  and  cut  down  on  devel¬ 
opment  projects,  they  will  also  cut  down 
on  the  byproducts  of  development  — 
new  techniques. 

Could  Patents  Ever  be  Beneficial? 

Although  software  patents  are  in  gen¬ 
eral  harmful  to  society  as  a  whole, 
we  do  not  claim  that  every  single  soft¬ 
ware  patent  is  necessarily  harmful.  Care¬ 
ful  study  might  show  that  under  cer¬ 
tain  specific  and  narrow  conditions 
(necessarily  excluding  the  vast  major¬ 
ity  of  cases)  it  is  beneficial  to  grant 
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software  patents. 

Nonetheless,  the  right  thing  to  do 
now  is  to  eliminate  all  software  patents 
as  soon  as  possible,  before  more  dam¬ 
age  is  done.  The  careful  study  can  come 
afterward. 

Clearly,  software  patents  are  not  ur¬ 
gently  needed  by  anyone,  except  patent 
lawyers.  The  prepatent  software  indus¬ 
try  had  no  problem  that  was  solved  by 
patents;  there  was  no  shortage  of  in¬ 
vention  and  no  shortage  of  investment. 
Complete  elimination  of  software  pat¬ 
ents  may  not  be  the  ideal  solution,  but 
it  is  close,  and  is  a  great  improvement. 
Its  very  simplicity  helps  avoid  a  long 
delay  while  people  argue  about  details. 


PATENTS 


If  it  is  ever  shown  that  software  patents 
are  beneficial  in  certain  exceptional 
cases,  the  law  can  be  changed  again 
at  that  time  —  if  it  is  important  enough. 
There  is  no  reason  to  continue  the  pre¬ 
sent  catastrophic  situation  until  that  day. 

Software  Patents  are  Legally  Questionable 

It  may  come  as  a  surprise  that  the  ex¬ 
tension  of  patent  law  to  software  is  still 
legally  questionable.  It  rests  on  an  ex¬ 
treme  interpretation  of  a  particular  1981 
Supreme  Court  decision,  Diamond  vs. 
Deihr.  (See  “Legally  Speaking”  in  Com¬ 
munications  of  the  ACM,  August  1990.) 

Traditionally,  the  only  kinds  of  pro¬ 
cesses  that  could  be  patented  were  those 


for  transforming  matter  (such  as  for 
transforming  iron  into  steel).  Many  other 
activities  which  we  would  consider  pro¬ 
cesses  were  entirely  excluded  from  pat¬ 
ents,  including  business  methods,  data 
analysis,  and  “mental  steps.”  This  was 
called  the  “subject  matter”  doctrine. 

Diamond  vs.  Deihr  has  been  inter¬ 
preted  by  the  Patent  Office  as  a  re¬ 
versal  of  this  doctrine,  but  the  court  did 
not  explicitly  reject  it.  The  case  con¬ 
cerned  a  process  for  curing  rubber  —  a 
transformation  of  matter.  The  issue  at 
hand  was  whether  the  use  of  a  com¬ 
puter  program  in  the  process  was 
enough  to  render  it  unpatentable,  and 
the  court  ruled  that  it  was  not.  The 
Patent  Office  took  this  narrow  decision 
as  a  green  light  for  unlimited  patenting 
of  software  techniques,  and  even  for 
the  use  of  software  to  perform  specific 
well-known  and  customary  activities. 

Most  patent  lawyers  have  embraced 
the  change,  saying  that  the  new  bounda¬ 
ries  of  patents  should  be  defined  over 
decades  by  a  series  of  expensive  court 
cases.  Such  a  course  of  action  will  cer¬ 
tainly  be  good  for  patent  lawyers,  but 
it  is  unlikely  to  be  good  for  software 
developers  and  users. 

One  Way  to  Eliminate  Software  Patents 

We  recommend  the  passage  of  a  law 
to  exclude  software  from  the  domain 
of  patents.  That  is  to  say  that,  no  matter 
what  patents  might  exist,  they  would 
not  cover  implementations  in  software; 
only  implementations  in  the  form  of 
hard-to-design  hardware  would  be  cov¬ 
ered.  An  advantage  of  this  method  is 
that  it  would  not  be  necessary  to  clas¬ 
sify  patent  applications  into  hardware 
and  software  when  examining  them. 

Many  have  asked  how  to  define  soft¬ 
ware  for  this  purpose  —  where  the  line 
should  be  drawn.  For  the  purpose  of 
this  legislation,  software  should  be  de¬ 
fined  by  the  characteristics  that  make 
software  patents  especially  harmful: 

•  Software  is  built  from  ideal  infallible 
mathematical  components,  whose  out¬ 
puts  are  not  affected  by  the  compo¬ 
nents  they  feed  into. 

•  Ideal  mathematical  components  are 
defined  by  abstract  rules,  so  that  fail¬ 
ure  of  a  component  is  by  definition 
impossible.  The  behavior  of  any  sys¬ 
tem  built  of  these  components  is  like¬ 
wise  defined  by  the  consequences 
of  applying  the  rules  step  by  step  to 
the  components. 

•  Software  can  be  easily  and  cheaply 
copied. 

Following  this  criterion,  a  program 
to  compute  prime  numbers  is  a  piece 
of  software.  A  mechanical  device  de- 
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signed  specifically  to  perform  the  same 
computation  is  not  software,  because 
mechanical  components  have  friction, 
can  interfere  with  each  other’s  motion, 
can  fail,  and  must  be  assembled  physi¬ 
cally  to  form  a  working  machine. 

Any  piece  of  software  needs  a  hard¬ 
ware  platform  in  order  to  run.  The  soft¬ 
ware  operates  the  features  of  the  hard¬ 
ware  in  some  combination,  under  a 
plan.  Our  proposal  is  that  combining 
the  features  in  this  way  can  never  cre¬ 
ate  infringement.  If  the  hardware  alone 
does  not  infringe  a  patent,  then  using 
it  in  a  particular  fashion  under  control 
of  a  program  should  not  infringe  either. 
In  effect,  a  program  is  an  extension  of 
the  programmer’s  mind,  acting  as  a 
proxy  for  the  programmer  to  control 
the  hardware. 

Usually  the  hardware  is  a  general- 
purpose  computer,  which  implies  no 
particular  application.  Such  hardware 
cannot  infringe  any  patents  except  those 
covering  the  construction  of  comput¬ 
ers.  Our  proposal  means  that,  when  a 
user  runs  such  a  program  into  a  general- 
purpose  computer  no  patents  other  than 
those  should  apply. 

The  traditional  distinction  between 
hardware  and  software  involves  a  com¬ 
plex  of  characteristics  that  used  to  go 
hand  in  hand.  Some  newer  technolo¬ 
gies,  such  as  gate  arrays  and  silicon 
compilers,  blur  the  distinction  because 
they  combine  characteristics  associated 
with  hardware  with  others  associated 
with  software.  However,  most  of  these 
technologies  can  be  classified  unambi¬ 
guously  for  patent  purposes,  either  as 
software  or  as  hardware,  using  the  cri¬ 
teria  above.  A  few  gray  areas  may  re¬ 
main,  but  these  are  comparatively  small, 
and  need  not  be  an  obstacle  to  solving 
the  problems  patents  pose  for  ordinary 
software  development.  They  will  end 
up  being  treated  as  hardware,  as  soft¬ 
ware,  or  as  something  in  between. 

Fighting  Patents  One  by  One 

Until  we  succeed  in  eliminating  all  pat¬ 
enting  of  software,  we  must  try  to  over¬ 
turn  individual  software  patents.  This 
is  very  expensive  and  can  solve  only  a 
small  part  of  the  problem,  but  that  is 
better  than  nothing. 

Overturning  patents  in  court  requires 
prior  art,  which  may  not  be  easy  to 
find.  The  League  for  Programming  Free¬ 
dom  will  try  to  serve  as  a  clearing  house 
for  this  information,  to  assist  the  defen¬ 
dants  in  software  patent  suits.  This  de¬ 
pends  on  your  help.  If  you  know  about 
prior  art  for  any  software  patent,  please 
send  the  information  to  the  League  (see 
the  accompanying  text  box.) 

If  you  work  on  software,  you  can 
personally  help  prevent  software  pat¬ 


ents  by  refusing  to  cooperate  in  apply¬ 
ing  for  them.  The  details  of  this  may 
depend  on  the  situation. 

Conclusion 

Exempting  software  from  the  scope  of 
patents  will  protect  software  develop¬ 
ers  from  the  insupportable  cost  of  pat¬ 
ent  searches,  the  wasteful  struggle  to 
find  a  way  clear  of  known  patents,  and 
the  unavoidable  danger  of  lawsuits. 

If  nothing  is  changed,  what  is  now 
an  efficient  creative  activity  will  be¬ 
come  prohibitively  expensive.  The 
sparks  of  creativity  and  individualism 
that  have  driven  the  computer  revolu¬ 
tion  will  be  snuffed  out. 


To  picture  the  effects,  imagine  that 
each  square  of  pavement  on  the  side¬ 
walk  has  an  owner  and  that  pedestri¬ 
ans  must  obtain  individual  licenses  to 
step  on  particular  squares.  Think  of  the 
negotiations  necessary  to  walk  an  en¬ 
tire  block  under  this  system.  That  is 
what  writing  a  program  will  be  like  in 
the  future  if  software  patents  continue. 
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Roll  your  Own 

DOS  Extender:  Part  II 


Under  the  hood 


Al  Williams 


Last  month,  I  discussed  80x86  pro¬ 
tected  mode  in  general  and  pre¬ 
sented  the  basics  of  PROT,  the 
DOS  extender  described  in  this 
two-part  article.  In  this  installment, 
I’ll  examine  both  80386  debugging  and 
exceptions,  then  take  you  under  the 
DOS  extender’s  hood.  Listings  One 
through  Three  were  covered  in  Part  I. 
In  this  installment,  I  cover  Listings  Four 
through  Seven:  STACKS. INC  (Listing 
Four,  page  122)  contains  the  stack  seg¬ 
ments;  INT386.INC  (Listing  Five,  page 
122)  is  for  386  interrupt  handling; 
TSS.INC  (Listing  Six,  page  126)  con¬ 
tains  the  task  state  segment  definitions; 
and  CODE16.INC  (Listing  Seven,  page 
126)  is  the  16-bit  DOS  entry/exit  code. 

Because  most  programs  don’t  work 
right  the  first  few  hundred  times  you 
try  them,  PROT  contains  full  debug¬ 
ging  support.  Of  course,  the  386  has 
many  hardware  debugging  features  built- 
in.  Except  for  the  single-step  capabil¬ 
ity,  these  features  are  all  available  with 
PROT.  In  addition,  EQUMAC.INC  (see 
Listing  Three  in  last  month’s  install¬ 
ment)  contains  macros  to  set  normal, 
conditional,  and  counter  breakpoints. 
When  a  breakpoint  or  unexpected  in¬ 
terrupt  occurs,  PROT  will  display  a  reg¬ 
ister  and  stack  dump.  You  can  also 


Al  is  a  systems  engineer  on  the  space 
station  Freedom  project for Jackson  and 
Associates.  Look  for  an  expanded  ver¬ 
sion  of  PROT  in  his  book  DOS:  A  De¬ 
veloper’s  Guide,  which  will  be  avail¬ 
able  from  M&T  Books  early  in  1991 
Al  can  be  reached  at  310  Ivy  Glen  Ct., 
League  City,  TX  77573,  or  via  Compu¬ 
Serve  at  72010,3574. 


instruct  PROT  to  dump  a  memory  re¬ 
gion  along  with  the  register  dump. 

Figure  3  shows  the  screen  PROT  dis¬ 
plays  when  an  unexpected  interrupt 
occurs.  This  interrupt  may  be  a  break¬ 
point  (INT  3)  or  an  80386  exception 
(refer  to  Table  4).  Most  likely,  it  will 
be  INT  ODH,  the  dreaded  general-pro¬ 
tection  interrupt. 

PROT  prints  the  display  on  the  screen 
using  OUCH  and  its  related  routines. 
This  means  that  if  you  have  changed 
the  video  mode  or  the  page  in  your 
program,  you  may  have  to  modify  the 
OUCH  routine  to  accommodate  those 
changes.  You  could,  for  instance,  mod¬ 
ify  OUCH  to  output  to  a  printer.  Be 
careful,  however,  not  to  use  any  DOS 
or  BIOS  routines  in  OUCH,  you  can’t 
be  sure  what  state  the  system  will  be 
in  when  OUCH  is  called. 

The  display  is  largely  self-explana¬ 
tory.  PROT  displays  the  registers  and 
the  interrupt  number  at  the  top  of  the 
screen.  Below  the  registers,  PROT  dis¬ 


plays  a  stack  dump,  starting  with  the 
location  at  ESP  and  continuing  to  the 
end  of  the  stack  segment.  If  the  loca¬ 
tion  DUMP_SEL  is  non-zero,  PROT  also 
prints  DUMP_CNT  bytes  starting  at 
DUMP_SEL:DUMP_  OFF.  Note  that  the 
BREAKDUMP  and  NBREAKDUMP  mac¬ 
ros  (see  Table  5  for  complete  list  of 
macros  to  set  breakpoints)  automati¬ 
cally  set  these  values  for  you.  After 
printing  this  screen,  PROT  returns  to 
DOS  with  an  error  code  of  7FH. 

Some  80386  exceptions  push  an  er¬ 
ror  code  on  the  stack.  For  these  excep¬ 
tions,  that  will  be  the  first  word  on  the 
stack.  The  next  two  words  will  be  the 
value  of  CS:EIP  at  the  time  of  the  inter¬ 
rupt.  In  Figure  3,  for  example,  the  value 
of  CS:EIP  is  88H:2BH.  The  next  word 
will  be  the  flags  (202H  in  Figure  3).  The 
stack  dump  displays  the  protected- 
mode  stack,  even  if  a  VM86  mode  pro¬ 
gram  was  interrupted.  If  you  need  to 
look  at  your  VM86  stack,  you  can  use 
the  memory  dump  feature.  When  an 
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(continued from,  page  74) 
interrupt  occurs  during  a  VM86  pro¬ 
gram,  the  words  following  the  flags 
on  the  stack  are  the  SS,  ES,  DS,  FS,  and 
GS  registers,  in  that  order.  Any  seg¬ 
ment  register  values  on  the  stack  will 
have  their  top  16  bits  set  to  unpredict¬ 
able  values  by  the  386. 

80386  Exceptions 

The  80386  defines  15  different  excep¬ 
tions  that  it  generates  internally  to  indi¬ 
cate  certain  conditions.  Table  4  sum¬ 
marizes  all  of  the  possible  exceptions 
and  why  they  occur.  Exceptions  fall 
into  three  classes:  faults,  traps,  and 
aborts.  A  fault  is  restartable;  the  offend¬ 


ing  instruction  hasn’t  executed  yet,  and 
CS:EIP  points  to  the  instruction  that 
faulted.  In  a  trap  exception,  the  offend¬ 
ing  instruction  has  already  executed. 
CS:EIP  then  points  to  the  instruction 
that  will  execute  after  the  offending 
instruction.  Aborts  are  exceptions  so 
severe  that  you  will  usually  terminate 
the  program  generating  them.  Table  6 
presents  these  exceptions  in  detail. 

The  only  exception  that  doesn’t  fall 
into  one  of  these  categories  is  INT  1, 
the  debug  exception.  Some  debug  ex¬ 
ceptions  are  faults  and  some  are  traps. 
Remember,  PROT  ends  the  running  pro¬ 
gram  and  does  a  debug  dump  when 
(continued  on  page  80) 


ES=0040 

DS-0090 

FS=0010 

GS-0038 

EDI=00000000 

ESI=00000000 

EBP=00000000 

ESP=OOOOOFFO  EBX=00000000 

EDX=00000000 
Stack  Dump: 

ECX=00000000 

EAX=00000000 

INT=03  TR=0070 

0000002B  00000088  00000202 

Figure  3-  PROT  interrupt/breakpoint  display 


Name 

INT# 

Type 

Error  Code 

Possible  causes 

Divide  error 

0 

FAULT 

No 

DIVorlDIV 

Debug 

1 

N/A 

No 

Debug  condition 

Breakpoint 

3 

TRAP 

No 

INT  3 

Overflow 

4 

TRAP 

No 

INTO 

Bounds  check 

5 

FAULT 

No 

BOUND 

Bad  opcode 

6 

FAULT 

No 

Illegal  instruction 

No  80x87 

7 

FAULT 

No 

ESC,  WAIT  with  no  copro¬ 
cessor  or  when  coproces¬ 
sor  was  last  used  by  an¬ 
other  task 

Double  fault 

8 

ABORT 

Yes  (always  0) 

Any  instruction  that  can 
generate  an  exception 

NPX  overrun 

9 

ABORT 

No 

Any  operand  of  an  ESC  that 
wraps  around  the  end  of  a 
segment. 

Invalid  TSS 

10 

FAULT 

Yes 

JMP,  CALL,  IRETor 
interrupt 

No  segment 

11 

FAULT 

Yes 

Any  reference  to  a  not- 
present  segment 

Stack  error 

12 

FAULT 

Yes 

Any  reference  with  SS 
register 

Gen’l  protect 

13 

FAULT 

Yes 

Any  memory  reference 
including  code  fetches 

Page  fault 

14 

FAULT 

Yes 

Any  memory  reference 
including  code  fetches 

NPX  error 

16 

FAULT 

No 

ESC,  WAIT 

Table  4:  80386/80486  exceptions 


Macro 

Description 

BREAKPOINT 

Execution  will  stop  at  this  point,  causing  a  debug  dump. 

BREAKON 

Turns  on  conditional  breakpoints.  If  followed  by  an  integer  num¬ 
ber,  that  number  of  conditional  breakpoints  must  execute  before 
the  breakpoint  actually  occurs. 

BREAKOFF 

Turns  off  conditional  breakpoints. 

NBREAKPOINT 

Conditional  breakpoint  macro.  Until  a  BREAKON  command  exe¬ 
cutes,  this  instruction  will  have  no  effect. 

BREAKDUMP 

Causes  an  unconditional  breakpoint  and  dumps  a  region  of  mem¬ 
ory  following  the  stack  dump. 

NBREAKDUMP 

Conditional  breakpoint  with  the  memory  dump  feature  of 
BREAKDUMP  added. 
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(continued  from  page  76) 
any  unexpected  exception  occurs,  un¬ 
less  you  reprogram  the  interrupt  rou¬ 
tines  to  do  differently. 

Some  exceptions  push  an  error  code 
on  the  stack.  Exception  14  has  a  special 
error  code;  but  all  the  other  exceptions 
simply  push  the  segment  selector  that 
caused  the  fault  onto  the  stack.  The 


Table  6:  80386 exceptions  in  detail 


error  code  0  means  that  the  fault  was 
caused  by  either  the  null  selector  or  a 
selector  which  the  80386  was  unable 
to  determine. 

What  Went  Wrong? 

Real-mode  debuggers,  such  as  Code¬ 
View,  Turbo  Debugger,  or  DEBUG, 
won’t  help  you  troubleshoot  PROT  pro- 


Exception 

Description 

INTO 

Occurs  if  you  ask  the  80386  to  divide  by  0,  or  if  a  division  gives  a 
result  that  will  not  fit  in  the  specified  accumulator  (AL,  AX,  or  EAX). 

INTI 

Vector  for  a  multitude  of  debugging  interrupts.  Hardware  data  break¬ 
points,  single-step  breakpoints,  and  task-switch  breakpoints  are  all 
considered  traps.  Hardware  code  breakpoints  and  general  detect 
exceptions  are  both  faults.  Enabling  any  of  these  breakpoints  re¬ 
quires  manipulating  the  debug  registers  (DR0-DR7). 

INT  3 

Occurs  when  an  INT  3  instruction  executes.  Convenient  for  placing 
breakpoints  in  your  code. 

INT  4 

Check  arithmetic  operations  for  overflow.  If  an  INTO  instruction 
executes  with  the  OF  flag  set,  INT  4  occurs. 

INT  5 

The  BOUND  instruction  generates  this  interrupt  if  it  finds  an  array 
index  outside  of  the  array’s  limits.  Real-mode  programmers  don’t  use 
the  BOUND  instruction  because  the  ROM  BIOS  uses  INT  5  for  the 
print  screen  routine. 

INT  6 

Occurs  when  the  80386  reads  an  unknown  opcode  or  when  a 
legitimate  instruction  receives  a  bad  operand. 

INT  7 

Occurs  when:  1 .  A  coprocessor  instruction  executed,  but  the  system 
contains  no  coprocessor  (as  indicated  by  the  EM  flag  in  CR0);  2.  A 
coprocessor  instruction  executed,  but  the  last  coprocessor  operation 
occurred  in  another  task.  This  exception  is  only  generated  when  the 

MP  flag  in  CR0  equals  one.  The  second  form  of  INT  7  is  useful  for 
maintaining  the  coprocessor’s  consistency  when  several  different 
tasks  are  using  the  80387. 

INT  8 

One  exception  occurred  while  trying  to  begin  service  for  another 
exception.  May  require  terminating  the  program. 

INT  9 

Occurs  when  a  coprocessor  instruction  runs  over  the  end  of  a 
segment. 

INT  10 

Occurs  when  a  task  switch  occurs  to  an  improperly  formed  TSS. 
Handling  this  exception  properly  requires  interrupt  pass  through  a 
task  gate.  PROT  does  not  do  this,  however.  If  you  plan  to  do 
extensive  multitasking  with  PROT,  you  should  supply  your  own  INT 

10  handler  to  simplify  debugging. 

INT  11 

Occurs  when  the  processor  loads  a  not-present  segment  descriptor 
or  uses  a  not-present  gate  descriptor. 

INT  12 

Indicates  that  the  stack  has  over-  or  under-run,  or  that  the  stack 
segment  register  (SS)  was  loaded  with  a  not-present  segment. 

INT  13 

General  protection  fault  is  perhaps  the  most  familiar  interrupt  for 

80386  programmers.  This  covers  any  error  not  handled  by  the  other 
exceptions. 

INT  14 

Occurs  when  a  referenced  memory  page  is  absent,  or  a  page’s 
privilege  is  higher  than  the  program  that  attempted  to  access  it.  This 
is  the  primary  vehicle  used  to  implement  virtual  memory  on  the 

80386. 

INT  16 

Occurs  when  the  80387  detects  an  error. 

.  386P 

SEGMENT  EXAMPLE  PARA  'CODE32'  USE32 
BACKWARD : 


CMP  EBX, EAX 

JA  FORWARD  ;  This  jump  is  OK 

JB  BACKWARD  ;  This  jump  is  improperly  assembled 


FORWARD : 


Example  4:  32-bit  offset  generation  problems 
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grams.  When  an  exception  display 
screen  appears,  you  should  note  the 
CS:EIP  (from  the  stack  dump).  By  re¬ 
ferring  to  the  listing  file  generated  by 
the  assembler,  you  should  be  able  to 
pinpoint  the  exact  instruction  that 
caused  the  exception. 

Exceptions  are  commonly  caused  by 
referencing  segment  registers  that  con¬ 
tain  zero  (the  null  selector),  addressing 
outside  of  a  segment,  or  attempting  to 
write  into  a  code  segment.  Another 
common  error  stems  from  the  linker’s 
inability  to  generate  1 6-bit  relative  off¬ 
sets.  For  instance,  consider  the  code 
fragment  in  Example  4.  This  code  makes 
two  conditional  jumps,  one  if  the  value 
in  EBX  is  above  EAX  and  the  other  if  it 
is  below. 

Because  the  code  contains  the  .386P 
(or  .386)  directive,  all  conditional  jumps 
default  to  32-bit  relative  jumps  in  a 
32-bit  segment.  The  first  jump  will  be 
correct  because  it  requires  a  positive 
offset  less  than  64K  away.  The  second 
jump  will  probably  cause  a  general- 
protection  fault  because  the  linker  only 
generates  2  bytes  of  the  4-byte  offset. 
For  example,  if  the  jump’s  offset  is  -10 
(FFFFFFF6  hex),  the  linker  will  gener¬ 
ate  FFF6  hex,  a  32-bit  offset  of  65,526. 
This  is  sure  to  cause  an  unexpected 
result.  If  you  are  lucky,  the  segment 


isn’t  that  large  and  a  general-protection 
fault  occurs.  Otherwise,  the  386  will 
just  jump  to  a  new  location.  Some¬ 
times,  this  location  will  not  contain  a 
valid  instruction,  which  will  cause  an 
exception  6.  Other  times,  your  pro- 

Exceptions  fall  into  three 
classes:  faults,  traps, 
and  aborts 


gram  will  just  start  doing  entirely  un¬ 
predictable  things.  To  prevent  this,  and 
for  efficiency’s  sake,  you  should  spec¬ 
ify  all  jumps  to  be  short,  if  possible.  If 
not,  you  can  use  the  JCC32  macro  pro¬ 
vided  in  Listing  Three  (Part  I)  to  gener¬ 
ate  proper  32-bit  conditional  jumps. 

Under  the  Hood 

Most  of  the  implementation  of  PROT 
is  straight  out  of  the  Intel  documenta¬ 
tion.  The  program  sets  up  the  Global 
Descriptor  Table  (GDT),  disables  inter¬ 
rupts,  and  switches  the  machine  into 
protected  mode.  In  protected  mode, 
PROT  sets  up  the  Interrupt  Descriptor 
Table  (IDT),  reprograms  the  interrupt 


controllers,  and  reenables  interrupts. 
PROT  then  calls  the  user’s  code.  While 
running  DOS  or  BIOS  code,  PROT  emu¬ 
lates  the  PUSHF,  POPF,  577,  CLI,  INT, 
and  TKETinstructions. 

As  mentioned  earlier,  software  inter¬ 
rupts  pose  the  single  biggest  problem 
for  a  DOS  extender.  The  easy  case  oc¬ 
curs  when  a  program  calls  an  interrupt 
routine  with  INT,  and  the  interrupt  rou¬ 
tine  ends  with  IRET.  Most  of  the  DOS/ 
BIOS  calls,  however,  return  informa¬ 
tion  in  the  flag  register.  Because  IRET 
will  restore  the  flags,  these  calls  have 
to  use  some  method  of  overriding  the 
old  flags.  From  a  DOS  extender’s  point 
of  view,  the  right  thing  to  do  is  modify 
the  flags  on  the  stack.  This  causes  IRET 
to  restore  the  flags  we  want  instead  of 
the  original  ones. 

Unfortunately,  most  of  the  system 
calls  don’t  do  this.  One  common  method 
of  sending  flags  back  to  the  caller  is  to 
return  using  a  RETF  2  instruction  in¬ 
stead  of  IRET.  In  real  mode,  this  has  the 
same  effect  as  IRET,  except  for  destroy¬ 
ing  the  saved  flags.  Of  course,  a  VM86 
RETF  instruction  can’t  return  to  a  pro- 
tected-mode  task,  so  a  DOS  extender 
has  to  find  a  way  around  this. 

There  is  yet  another  way  DOS  han¬ 
dles  flags:  The  absolute  disk  read  and 
(continued  on  page  82) 
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CALL  FAR  ISR 

Case  1 

Normal INT/IRET 

ISR: 

IRET 

Interrupt  10H  service  routine 

INT  10H 

;  perform  interrupt 

Case? 

PUSHF/PUSH  ADDRESS/  IRET 

ISR: 

;  Interrupt  10H  service  routine 

PUSHF 

Jump  to  address  TARGET 

Case  2 

IRET 

PUSH  SEG  TARGET 
PUSH  OFFSET  TARGET 

INT/RETF  2 

IRET 

INT  10H_ 

;  perform  interrupt 

TARGET: 

: 

Destination  of  IRET 

ISR: 

;  Interrupt  10H  service  routine 

-or- 

PUSHF 

Simulate  interrupt 

RETF2 

PUSH  SEG  RETAD 

Case  3 

INT/RETF  (only  used  by 

INT  25H  and  26H) 

RETAD: 

PUSH  OFFSET  RETAD 
JMP  FAR  ISR 

INT  10H 

;  perform  interrupt 

ISR: 

; 

Interrupt  routine 

ISR: 

;  Interrupt  10H  service  routine 

IRET 

RETF 

Case  4 

PUSHF/FAR  CALL 

PUSHF 

;  simulate  interrupt 

Figure  4:  Problem  cases  associated  with  software  interrupts.  Case  1,  normal  interrupt  routine  call  and  return;  case  2 , 
returning  from  an  interrupt  using  FAR  RETURN  2;  case  3,  returning  from  an  interrupt  using  a  FAR  RETURN;  case  4, 
simulating  an  interrupt  with  a  FAR  CALL;  case  5,  using  IRET  to  transfer  control  to  an  arbitrary  address. 
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write  interrupts  (INT  25H  and  26H) 
leave  the  original  flags  at  the  top  of  the 
stack.  These  interrupt  routines  accom¬ 
plish  this  by  executing  RETF.  This  is 
similar  to  the  previous  case,  and  PROT 
handles  it  in  the  same  way. 

Another  problem  lies  in  the  DOS 
and  BIOS  methods  of  calling  interrupts. 
Most  often,  these  routines  use  an  INT 
instruction  to  start  an  interrupt  routine. 
However,  systems  routines  will  some¬ 
times  push  flags  on  the  stack  and  then 
do  a  FAR  CALL.  In  real  mode,  this  is 
exactly  equivalent  to  an  INT.  In  pro¬ 
tected  mode,  however,  this  will  cause 
havoc  in  our  attempts  to  emulate  the 
IRET  instruction.  Luckily,  the  method 
we  will  use  to  handle  the  RETF  2  return 
also  suggests  a  solution  to  this  problem. 

Finally,  the  system  routines  some¬ 
times  pass  control  by  pushing  the  flags 


qisr  segment  para  'C0DE16'  usel6 
assume  cs:qisr 
qiret : 

push  0 
push  0 
push  0 
iret 
qisr  ends 


Example  5:  QISR  code  for  the  VMS 6 
mode  segment 


and  an  address  on  the  stack  and  then 
executing  an  IRET  instruction.  This  re¬ 
sembles  the  FAR  CALL/ IRET  case,  and 
PROT  handles  it  in  the  same  manner. 
These  problem  cases  are  detailed  with 
the  code  fragments  in  Figure  4. 

The  Seven  Percent  Solution 

Our  DOS  extender  must  have  a  VM86 
mode  segment  (I’ve  called  it  QISR), 
that  contains  the  code  shown  in  Exam¬ 
ple  5.  When  the  DOS  extender  detects 
an  /AYlnstruction  being  executed  from 
real  mode,  it  emulates  it  much  as  out¬ 
lined  in  the  Intel  documentation.  The 
80386  places  the  actual  flags  and  return 
address  on  the  Privilege  Level  0  (PLO) 
stack  via  the  general-protection  fault 
caused  by  the  INT.  The  secret  to  man¬ 
aging  DOS’s  odd  interrupt  handling  lies 
in  manipulating  the  VM86  stack.  You 
can  push  a  1 6-bit  copy  of  the  flags  on 
the  VM86  stack,  followed  by  the  ad¬ 
dress  of  qiret.  Then  the  DOS  extender 
transfers  control  (in  VM86  mode)  to  the 
real-mode  interrupt  handler. 

When  an  IRET  executes,  another  gen¬ 
eral-protection  fault  occurs.  We  can  deter¬ 
mine  which  case  happened  by  examin¬ 
ing  the  top  of  the  VM86  stack.  If  the  top 
three  words  of  the  stack  are  all  zeros, 
we  have  found  case  2  or  3  in  Figure  4. 
If  the  address  on  the  top  of  the  stack  is 


qirets,  then  the  normal  case  (case  1) 
occurred.  Any  other  address  at  the  top 
of  the  stack  indicates  case  4  or  5. 

Now  that  we  know  what  case  caused 
the  IRET,  what  action  does  the  DOS 
extender  take?  PROT  uses  the  follow¬ 
ing  logic: 

In  case  1,  merge  the  1 6-bit  flags  on 
the  VM86  stack  with  the  top  16  bits  of 
the  flags  pushed  on  the  PLO  stack  dur¬ 
ing  the  INT  handling.  This  may  seem 
redundant,  but  the  system  routines  may 
modify  these  flags,  and  the  caller  will 
expect  the  modified  flags.  Balance  the 
VM86  stack  and  restore  the  return  ad¬ 
dress  from  the  PLO  stack;  cases  2  and  3 
are  much  the  same  as  case  1,  except 
that  PROT  restores  the  current  flags 
(which  are  on  the  PLO  stack)  instead 
of  the  flags  on  the  VM86  stack.  Cases 
4  and  5  don’t  go  through  the  /AYTogic 
just  described.  Therefore,  the  DOS  ex¬ 
tender  must  build  an  artificial  PLO  stack 
frame  that  looks  as  though  the  INT 
logic  executed  earlier.  The  execution 
then  continues  as  in  case  1. 

When  a  protected-mode  program 
needs  to  call  a  DOS  or  BIOS  service,  it 
calls  the  call86  routine.  This  routine 
uses  PROT’s  INT 30H function  to  build 
a  stack  frame  much  like  the  one  used 
in  cases  4  and  5  and  simulates  the  DOS 
(or  BIOS)  interrupt. 
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(continued  from  page  83) 

Hardware  Interrupts 

INT 30H  directly  handles  hardware  in¬ 
terrupts.  Because  hardware  interrupts 
can  occur  at  any  time,  PROT  examines 
the  flags  of  the  interrupted  program.  If 
the  interrupted  program  is  a  VM86  pro¬ 
gram,  PROT  uses  the  VM8 6  stack  to 
handle  the  interrupt.  If  the  program  is 
a  protected-mode  program,  PROT 
switches  to  a  special  stack  for  hard¬ 
ware  interrupt  processing. 

The  PC’s  first  interrupt  controller  is 
reprogrammed  to  generate  different  in¬ 
terrupts  than  normal.  PROT  translates 
these  interrupts  to  the  correct  service 
routines.  This  prevents  hardware  inter¬ 
rupts  from  being  confused  with  80386 
exceptions.  Also,  the  interrupts  from 
the  second  controller  (on  AT-style  ma¬ 
chines  only)  are  reprogrammed  to  sim¬ 
plify  constructing  the  interrupt  table. 

Future  Directions 

While  PROT  is  a  complete  protected- 
mode  environment,  there  are  still  some 
interesting  enhancements  you  may  want 
to  try.  For  completeness,  PROT  should 
emulate  IRETD,  PUSHFD,  and  POPFD 
in  VM86  mode.  Adding  a  scheduler 
that  would  run  off  the  PC’s  timer  inter¬ 
rupt  would  make  PROT  more  useful 
in  multitasking  applications.  Additional 
support  for  memory  paging  would  be 
helpful  as  well. 

PROT’s  most  noticeable  shortcom¬ 
ing  is  it’s  inability  to  work  with  other 
386-specific  programs.  Standards  such 
as  the  Virtual  Control  Program  Inter¬ 
face  (VCPI)  and  the  DOS  Protected 
Mode  Interface  (DPMI)  allow  programs 
like  PROT  to  share  the  386  with  other 
programs  that  also  use  the  processor’s 
special  features.  Adding  VCPI  or  DPMI 
support  to  PROT  should  not  be  very 
difficult.  The  specification  for  VCPI  is 
available,  free  of  charge,  from  Phar  Lap 
Software  Inc.,  60  Aberdeen  Ave.,  Cam¬ 
bridge,  MA  02138,  617-661-1510.  The 
DPMI  spec  can  be  ordered  free  of  charge 
from  Intel  Literature  Sales,  P.O.  Box 
58130,  Santa  Clara,  CA  95052,  800-548- 
4725  (Intel  part  #  240763-001). 

DOS  extenders  provide  a  way  for 
today’s  developers  to  launch  sophisti¬ 
cated  applications  now,  and  with  a 
much  larger  potential  market  than  any 
other  option.  By  using  PROT,  you  will 
be  able  to  learn  more  about  develop¬ 
ing  protected-mode  software.  The  ex¬ 
perience  you  gain  will  not  only  help 
you  expand  your  DOS  applications  to¬ 
day,  it  will  also  give  you  a  headstart 
on  the  operating  systems  of  the  future. 

DDJ 

(Listings  begin  on  page  122.) 
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EXAMINING  ROOM 


Programmer  Tools 
For  Actor  3.0 

Data  management  and  resource  editing 
for  Windows  development 


Marty  Franz 


A  colleague  of  mine  (who  shall 
remain  nameless)  has  a  favor¬ 
ite  aphorism:  If  a  program  is 
tough  to  write,  it  should  be 
tough  to  use.  Given  this  mind¬ 
set,  it  should  come  as  no  surprise  that 
he  dislikes  writing  programs  for  Micro¬ 
soft  Windows,  especially  in  C.  I  don’t 
agree  with  this  statement,  but  I  do  agree 
with  its  contrapositive:  If  a  program  is 
easy  to  use,  it  should  be  easy  to  write. 
Therefore,  I  have  avoided  using  C  to 
program  for  Windows.  Instead,  I  use 
Actor. 

The  Whitewater  Group,  mindful  of 
Actor’s  emergence  as  a  serious  Win¬ 
dows  development  language,  has  de¬ 
cided  to  provide  two  new  program¬ 
ming  tools  for  Actor:  WinTrieve,  an 
ISAM  (Indexed  Sequential  Access 
Method)  for  Actor  (and  C)  programs 
running  under  Windows;  and  the  White- 
water  Resource  Toolkit,  an  editor  for 
building  and  editing  all  the  miscellane¬ 
ous  resources  (menus,  accelerators,  cur¬ 
sors,  and  so  on)  needed  by  a  Windows 
program. 

Before  these  tools  were  around,  de¬ 
veloping  comparable  programs  for  Win¬ 
dows  meant  writing  these  programs  in 
C.  In  this  article,  I’ll  examine  these  tools 
and  how  they’re  used  to  build  an  appli¬ 
cation  that  actually  uses  “real”  files  and 
Windows  resources  —  but  with  con¬ 
siderably  less  suffering. 

Actor  3.0 

Although  Actor  3.0’s  support  of  Win- 


Marty  is  a  software  engineer  with  Allen 
Testproducts  Inc.  of  Kalamazoo,  Michi¬ 
gan.  He  is  the  author  of  Object-Ori¬ 
ented  Programming  Featuring  Actor, 
published  by  Scott  Foresman  &  Co. 


dows  3-0  was  what  made  the  news, 
there  were  other  improvements  over 
Version  2.0  as  well.  In  Actor  2.0,  for 
instance,  an  innovative  “memory  swap¬ 
ping”  technique  was  implemented  (see 
the  article  “Object  Swapping”  by  Jan 
Bottorff  and  Jim  Bolland,  DDJ,  May 
1990)  whereby  the  640-Kbyte  barrier 
was  effectively  broken,  allowing  you 
to  write  extremely  large  Actor  programs. 
With  Actor  3.0,  this  technique  has  been 
extended  to  use  Windows’  standard 
and  enhanced  80386  modes  to  create 
applications  up  to  2  Mbyte  in  size. 

Another  feature  worth  mentioning 
is  a  streamlined  seal-off  procedure.  The 
term  “seal-off’  refers  to  the  process  of 
removing  the  development  classes  from 
the  workspace  so  just  the  application 
objects  and  classes  remain:  In  effect, 
“compiling”  the  Actor  program  so  it 
can  run  as  a  standalone  Windows  ap¬ 
plication.  In  prior  versions  of  Actor, 
this  could  be  cumbersome.  In  Versions 
2.0  and  3  0,  there’s  a  menu  option  and 
a  dialog  to  fill  out,  and  the  rest  of  the 
seal-off  process  is  automatic. 

There  are  also  numerous  other  im¬ 
provements  in  the  product,  including 
a  System  object  for  encapsulating  oper¬ 
ating  system  dependencies,  and  more 


Windows-specific  classes.  The  new  Win¬ 
dows  classes  include  convenient  Win¬ 
dows  printing  and  dynamic  menus  and 
dialogs.  The  class  library  improvements 
have  been  added  with  an  eye  toward 
compatibility  with  prior  versions  of  Ac¬ 
tor,  a  lesson  Borland  and  Microsoft 
could  leam  from  the  Whitewater  Group. 

Dynamic  dialog  and  menu  classes 
make  rapid  application  prototyping 
much  easier.  In  earlier  versions  of  Ac¬ 
tor,  there  were  only  simple  modal  and 
nonmodal  dialogs  available  as  classes 
without  resorting  to  the  Actor’s  Win¬ 
dows  Call  facility.  This  new  version 
allows  complex  dialogs  to  be  built  with 
more  object-oriented  means,  as  shown 
in  Example  1. 

In  the  recDlg( )  method  shown  in 
Example  1,  a  new  dialog  is  constructed 
and  returned.  The  setSize( )  message 
gives  the  overall  dimensions  of  the  dia¬ 
log  box,  while  each  addltem( )  adds  a 
control  or  field.  Static  text,  edited  fields, 
and  a  pushbutton  to  cancel  the  dialog 
are  added,  along  with  their  control  IDs. 
Dynamic  Dialogs  are  used  in  the  sam¬ 
ple  program  to  create  a  multi-field  in¬ 
put  dialog  for  the  record  being  added 
or  updated  in  the  database. 

Other  Actor  3.0  features  include  be- 


/*  Build  a  record  dialog.  */ 

Def  recDlglself,  dPhone,  dPerson,  dCompany  :  D) 

(  D  :=  new(DialogDesign) ; 
setSize (D,  808,  1850120); 

addItem(D,  newStatic (Dlgltem,  "Phone;",  100,  5010,  40010,  0)); 
addItem(D,  newEdit (Dlgltem,  dPhone,  PHONE,  50010,  35012,  0) ) ; 
addltemfD,  newStatic (Dlgltem,  "Person:",  100,  5025,  40010,  0)); 
addItem(D,  newEdit (Dlgltem,  dPerson,  PERSON,  50025,  125012,  0 ) ) ; 
addItem(D,  newStatic (Dlgltem,  "Company:",  100,  5040,  40010,  0 ) ) ; 
addItem(D,  newEdit (Dlgltem,  dCompany,  dCompany,  50040,  35012,  0)); 
addltemfD,  newButton (Dlgltem,  "Cancel",  IDCANCEL,  115095,  40014,  0)  )  ; 
AD; 


Example  1:  Constructing  and  returning  new  dialog 
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(continued  from  page  86) 
ing  able  to  more  easily  go  between 
Actor  and  C  or  Assembler,  including 
writing  your  own  primitives  in  C  and 
linking  them  into  the  Actor  image. 

WinTrieve 

WinTrieve  is  a  data  manager  for  both 
Actor  and  C  that  provides  an  Indexed 
Sequential  Access  Method  (ISAM)  for 
Windows  programs.  Without  it,  fledg- 

Actor  can  use  Windows’ 
standard  and 
enhanced  80386  modes 
to  create  applications  up 
to  2  Mbyte  in  size 


ling  Windows  programmers  must  write 
their  application  using  only  the  file  ac¬ 
cess  provided  through  the  basic  Actor 
or  C  language.  This  means  there’s  no 
support  for  addition  and  retrieval  of 
keyed  records.  Since  many  (if  not  most) 
business-type  applications  require  this 
type  of  function,  it  meant  hand-build¬ 
ing  this  support  into  Actor  or  C  pro¬ 
grams  —  not  the  most  entertaining  job. 

WinTrieve  provides  the  capability  to 
create,  add,  delete,  and  retrieve  records 
using  a  key.  While  not  a  complete  data¬ 
base-management  system,  this  support 
goes  a  long  way  to  building  a  DBMS 
and  in  fact  provides  a  sizable  chunk  of 
the  function  needed  by  most  business 
programs.  WinTrieve  also  provides 
some  limited  relational  capabilities,  such 
as  linking  fields  between  ISAM  files. 
Locking  is  available  in  a  fully  automatic 
mode,  a  manual  mode,  or  none.  Both 
entire  files  and  individual  records  may 
be  locked. 

WinTrieve  has  three  parts:  An  ISAM 
server,  which  runs  as  a  separate  Win¬ 
dows  application,  and  two  Application 
Program  Interfaces  (APIs),  one  for  Ac¬ 
tor,  the  other  for  C.  The  Actor  API 
consists  of  several  classes  that  are  loaded 
into  the  Actor  image.  These  include  an 
IsamManager  class,  an  IsamFile  class, 
and  several  IsamKey  classes.  The  C  API 
consists  of  header  files  and  libraries  (one 
for  each  memory  model)  and  can  be 
linked  into  your  Microsoft  C  programs. 

The  ISAM  Manager  is  loaded  as  a 
separate  Windows  program  and  runs 
“outside”  of  the  Actor  workspace.  This 
means  that  programs  written  outside 
of  Actor  can  use  it,  provided  they  ad¬ 
here  to  the  protocol.  This  has  been 
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documented  in  the  WinTrieve  manual 
and  shouldn’t  prove  any  problem  to 
experienced  Windows  programmers. 

Using  an  object-oriented  language 
has  advantages  when  writing  programs 
that  use  an  ISAM.  The  OOP  metaphor 
means  you  can  think  about  the  ISAM 
file  as  another  collection  or  file  object. 
Once  written,  the  often-convoluted  logic 
of  dealing  with  recovery,  transaction 
locking,  and  journaling  can  be  safely 
placed  in  the  class  tree  and  inherited 
without  a  lot  of  fuss  later. 

WinTrieve  is  an  access  method,  pro¬ 
viding  the  application  with  services  to 
build  and  use  indexed  files;  it’s  not  a 
complete  DBMS.  This  limitation  is  both 
good  news  and  bad.  The  downside  is 
that  you  don’t  get  a  lot  of  the  features 
of  a  full  DBMS  —  query  facilities  and 
application  and  report  generators.  The 
good  news  is  that  you  get  a  simpler, 
more  flexible  tool  with  considerably 
less  overhead.  If  you  need  the  addi¬ 
tional  DBMS-like  facilities,  you  can  build 
them  in  Actor  or  C. 

Whitewater  Resource  Toolkit 

One  of  the  limitations  in  earlier  ver¬ 
sions  of  Actor  was  that  programmers 
were  dependent  on  the  Microsoft  Win¬ 
dows  SDK  for  customizing  application 
resources.  What  a  drag.  The  power  of 
a  state-of-the-art  language  such  as  Ac¬ 
tor  was  harnessed  in  tandem  with  a 
plowhorse  like  the  Resource  Compiler. 
It  made  using  static  resources  in  Actor 
programs  a  chore,  enough  so  —  un¬ 
less  you  were  writing  production-qual¬ 
ity  programs  in  Actor  —  that  you  didn’t 
do  it. 

The  Whitewater  Resource  Toolkit  is 
a  solution  to  this  problem.  It  supports 
both  C  and  Actor  programs  and  can 
handle  resources  in  RES,  BMP,  ICO, 
CUR,  and  EXE  formats.  The  individual 
editors  in  it  work  like  MacDraw  or 
MacPaint:  You  are  presented  with  a 
graphical  view  of  the  resource  you  are 
editing  and  you  use  a  selection  of  tools, 
chosen  from  a  palette,  to  edit  them. 

At  the  time  I’m  writing  this,  the  Re¬ 
source  Toolkit  doesn’t  run  support  for 
Windows  3  0.  But,  by  the  time  you’re 
reading  this,  the  Resource  Toolkit  will 
likely  support  Windows  3-0.  Until  then, 
you’ll  have  to  edit  resources  under  Win¬ 
dows  2.1,  and  bring  them  over. 

Within  the  Resource  Toolkit  are  edi¬ 
tors  for  each  type  of  resource:  graphics 
editors  (for  bitmaps,  cursors,  and  icons), 
a  menu  editor,  a  dialog  editor,  an  ac¬ 
celerator  editor,  and  a  string  editor. 
These  editors  are  all  linked  by  a  tool 
called  the  “Mover,”  which  allows  you 
to  view,  move,  copy,  select,  and  delete 
various  resources  in  various  files. 

The  editors  are  all  organized  along 


the  same  lines.  A  File  menu  loads  and 
saves  the  resource  you’re  editing,  and 
an  Edit  menu  cuts,  copies,  and  pastes 
parts  of  a  shape.  In  the  graphics  edi¬ 
tors,  the  palettes  have  tools  for  drawing 
lines,  rectangles,  and  ellipses,  and  mov¬ 
ing  shapes  and  changing  their  colors. 

The  Resource  Toolkit  is  easy  and  fun 
to  use  and  makes  you  want  to  custom¬ 
ize  your  application  beyond  the  limits 
of  good  taste  and  user-friendliness.  It’s 

The  term  “ seal-off  ” 
refers  to  the  process  of 
removing  the 
development  classes 
from  the  workspace  so 
just  the  application 
objects  and  classes 
remain 


also  entirely  written  in  Actor  and  makes 
a  convincing  demonstration  of  what 
the  language  is  capable  of. 

Putting  it  to  Work 

To  demonstrate  and  evaluate  these  new 
tools,  I  took  the  Book  Browser  applica¬ 
tion  provided  with  WinTrieve  and  modi¬ 
fied  it  into  a  Rolodex  file.  ROLO.H  (List¬ 
ing  One,  page  132)  is  the  application 
header  file.  As  in  a  C  program,  this  file 
contains  constants,  including  menu  item 
numbers  and  dialog  constants. 

ROLO.ICO  (available  electronically, 
see  “Source  Code  Availability”  on  page 
3)  is  the  Rolodex  application  icon.  I 
took  the  icon  provided  for  the  Book 
Browser  and  modified  it  using  the  Re¬ 
source  Toolkit,  adding  a  spiral  binding 
to  the  side  of  the  “book.”  Voila!  instant 
Rolodex. 

ROLO.ACT  (Listing  Two,  page  132) 
adds  some  additional  methods  to  the 
String  class  for  the  Rolodex.  ROLO.RC 
(see  “Availability”)  is  the  resource  file 
for  the  sealed-off  application.  To  build 
this  file,  I  simply  modified  what  was 
in  the  Book  Browser’s  resource  file 
using  Actor’s  File  Editor. 

ROLOAPRCLS  (Listing  Three,  page 
132),  ROLOFILE.CLS  (Listing  Four,  page 
132),  and  ROLOWIND.CLS  (Listing  Five, 
page  132)  are  all  class  files  for  the 
application.  Listing  Three  implements 
the  RoloApp  class,  the  “wrapper”  for 
the  sealed-off  application.  It  has  a  sin- 
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gle  message,  initC ),  sent  when  the  appli¬ 
cation  is  started.  It  performs  necessary 
initialization  and  passes  control  to  Rolo- 
Window,  the  application’s  main  class. 
One  of  the  initialization  steps  performed 
in  initC )  is  to  start  the  ISAM  Manager, 
and  either  create  or  open  the  Rolodex 
database. 

ROLOFILE  (Listing  Four)  is  a  descen¬ 
dant  of  the  IsamFile  class.  It  defines  the 
structure  of  the  ISAM  file  that  contains 
the  Rolodex.  The  ISAM  file  has  three 
fields:  The  entry’s  phone  number,  the 
primary  key,  the  person’s  name,  a  sec¬ 
ondary  key,  and  the  person’s  company 
affiliation.  All  these  fields  are  30-char¬ 
acter  strings.  The  sole  purpose  of  this 
class  is  to  pass  this  initialization  infor¬ 
mation  to  the  ISAM  Manager  when  the 
application  is  started. 

Finally,  ROLOWIND  (Listing  Five)  im¬ 
plements  the  workhorse  of  the  applica¬ 
tion;  the  Rolo  Window  class.  Since  we’re 
developing  a  standalone  Windows  pro¬ 
gram,  it’ll  also  be  the  window  that  gets 
control  when  the  program  starts.  The 
RoloWindow  class  is  a  descendant  of 
TextWindow,  so  it  automatically  inher¬ 
its  all  of  that  class’s  features,  including 
text  entry  and  a  text  cursor.  But  the 
RoloWindow  c lass  adds  a  menu  handler 
that  performs  the  functions  of  the  appli¬ 
cation,  including  perusing  the  database 
by  moving  forwards  and  backwards  and 
inserting  and  deleting  entries. 

The  RoloWindow  class  is  relatively 
large  because  it  must  support  an  elabo¬ 
rate  protocol  for  Windows.  This  in¬ 
cludes  not  only  the  messages  needed 
to  handle  menu  commands  to  the  win¬ 
dow,  but  also  each  menu  function’s 
message,  such  as  deleteRec( )  to  re¬ 
move  the  current  record  from  the  file 
and  updateRecC )  to  update  the  current 
record  if  it’s  been  changed. 

The  bulk  of  the  work  in  RoloWind. 
CLS  is  done  in  validatelnput( )  and  its 
private  messages  getPerson( )  and 
getPhoneC ).  These  obtain  and  validate 
input  from  the  user  using  Actor’s  Dy¬ 
namic  Dialogs.  The  recDlgO  message 
constructs  this  dialog  when  the  Rolo¬ 
Window  is  initialized  using  several  add- 
Item( )  messages.  It  builds  a  Dictionary 
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containing  the  name  of  each  field  as  a 
key  symbol  and  the  field’s  contents  as 
the  value.  These  are  not  to  be  confused 
with  the  actual  ISAM  records,  which 
have  the  same  field  names  but  are  in 
all  uppercase. 

The  amount  of  code  in  RoloWindow 
is  reduced  by  using  Actor’s  powerful 
performC )  message.  This  allows  us  to 
create  a  collection  of  methods  and  mes¬ 
sages  for  all  the  possible  responses  to 
RoloWindow’s  commandC )  message. 
When  the  commandC )  message  is  sent 
with  a  menu  number  after  a  menu  item 
is  picked  by  the  user,  commandC )  sim¬ 
ply  passes  control  to  the  method  match¬ 
ing  the  menu  ID.  No  multiway  branches 
are  needed.  This  means  that  new  menu 
options  can  be  easily  added  to  the 
Rolodex  later. 

To  get  the  application  working,  you 
must  first  load  the  ISAM  Manager’s 
classes  into  the  Actor  workspace.  On 
my  home  PC  (a  10-MHz  286  with  only 
640  Kbyte  of  RAM)  I  had  to  chop  Ac¬ 
tor’s  dynamic  and  static  storage  alloca¬ 
tions  before  both  the  ISAM  Manager 
and  Actor  could  coexist  under  Win¬ 
dows.  The  Whitewater  Group  recom¬ 
mends  having  at  least  1  Mbyte  of  RAM 
when  using  WinTrieve  and  Actor  to¬ 
gether.  On  my  work  PC,  a  20-MLLz  386 
with  2  Mbyte  of  RAM,  this  was  not  a 
problem.  The  sealed-off  application, 
however,  ran  fine  on  both  machines. 

Once  the  ISAM  manager  is  loaded, 
you  need  to  load  the  Rolodex  classes 
by  loading  the  ROLO.LOD  (see  “Avail¬ 
ability”)  load  file.  You  can  then  start 
the  Rolodex  interactively  using: 

Sam  :=  new(RoloApp); 

init(Sam,  nil); 

Conclusion 

Actor  was  always  a  convenient  pro¬ 
gramming  tool  for  Windows,  and  a  good 
way  to  become  familiar  with  Windows’ 
facilities  even  if  you  wrote  the  final 
program  in  C.  With  Version  3  0,  Actor 
is  now  better  suited  to  developing  real 
applications.  The  addition  of  WinTrieve 
and  the  Whitewater  Resource  Toolkit 
boost  Actor’s  capabilities  as  a  profes¬ 
sional  applications  and  rapid  prototyp¬ 
ing  language.  Programmers  despairing 
of  C  for  writing  Windows  programs  are 
encouraged  to  consider  Actor  for  their 
next  programming  project.  You  might 
find  that  programs  that  are  easy  to  use 
can  also  be  easy  to  write. 

DDJ 

(Listings  begin  on  page  132.) 
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For  users,  Windows  3-0  has  sig¬ 
nificantly  increased  the  visibility 
of  Graphical  User  Interfaces 
(GUIs).  For  programmers,  how¬ 
ever,  creating  sophisticated  Win¬ 
dows  applications  has  proven  to  be 
no  mean  feat.  Even  the  simplest  Win¬ 
dows  programs  require  the  overhead 
of  message  reception  and  dispatch  func¬ 
tions,  and  demand  that  programmers 
master  new  interfaces.  To  go  beyond 
the  “simple”  dialog-box/built-in  con¬ 
trol  level  of  interface,  programmers  must 
often  write  their  own  code  for  manipu¬ 
lating  text,  identifying  the  location 
clicked  on  by  the  mouse,  and  display¬ 
ing  graphics. 

Furthermore,  Windows,  and  indeed 
any  GUI,  pays  a  penalty  in  speed  and 
program  size  for  its  user  friendliness, 
and  programmers  usually  need  to  com¬ 
pensate  by  making  data  storage  as  com¬ 
pact  and  efficient  as  possible.  This  was 
certainly  the  case  with  the  checking 
account  manager  which  I  describe  in 
this  article.  This  application  provides 
cash-based  accounting  for  an  individ¬ 
ual  or  small  business  by  letting  the  user 
balance  multiple  checkbooks  and  dis¬ 
tribute  transactions  across  multiple  cate¬ 
gories  of  expenses. 

This  checking  account  manager  con¬ 
sists  of  setup  screens  —  for  accounting 
information,  names  and  addresses  of 
check  recipients,  recurring  entries,  and 
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so  on.  The  part  of  this  application  that 
I’ll  focus  on  is  a  general  check  entry 
screen  that  uses  data  from  these  setup 
screens  (see  Figure  1).  Key  to  this  user 
interface  are  the  combobox-style  selec¬ 
tors  which  let  the  user  select  transac¬ 
tion  types,  check  payees,  and  distribu¬ 
tion  accounts.  These  comboboxes  al¬ 
low  the  user  direct  access  to  the  data¬ 
base,  based  on  either  the  name  or  code 
order.  Another  very  significant  element 
is  the  visual  representation  of  the  check¬ 
book  register  that  lets  the  user  actively 
select  which  check  to  edit. 

The  Development  Process 

Our  development  team  consisted  of 
an  accountant  (who  did  the  specifica¬ 
tion  research),  a  User-Interface  (UI)  de¬ 
signer,  two  ToolBook  programmers, 
and  a  Windows/C  programmer.  Al¬ 
though  ours  was  a  five-member  team, 
there’s  no  reason  why  one  or  two 
broadly  disciplined  individuals  couldn’t 
have  accomplished  what  we  did. 

ToolBook  was  the  front-end  for  the 
application  because  of  its  graphical  rich¬ 
ness,  programming  language,  and  rela¬ 
tively  straightforward  interface  to  Win¬ 
dows  Dynamic  Link  Libraries  (DLLs). 
For  the  database  engine,  we  chose 
db_VISTA  III  Windows  DLL  because 
of  its  relatively  small  size  and  signifi¬ 
cant  speed  advantage  over  the  more 
traditional  relational  or  flat-file  man¬ 
ager.  For  optimizing  our  ToolBook/ 
db_VISTA  application,  we  used  the  Win¬ 
dows  SDK  and  Microsoft’s  C  5.1  com¬ 
piler.  We  also  used  the  SDK  reference 
material  to  guide  our  interface  to  the 


Windows  kernel  functions  for  interfac¬ 
ing  ToolBook  and  db_VISTA. 

After  we  had  defined  the  basic  func¬ 
tionality  for  the  program,  the  account¬ 
ant  sketched  the  screens  using  Tool¬ 
Book’s  drawing  tools.  Because  our  main 
“user”  developed  the  basic  components 
of  the  UI,  we  avoided  the  usual  cycles 
of  capturing  the  user’s  requirements 
and  refining  the  idea. 

Because  ToolBook  provides  a  func¬ 
tional  flat-file  database  with  its  record 
field  object,  we  took  the  UI  designer’s 
screens,  put  some  minimal  functional¬ 
ity  behind  them,  and  had  a  functional 
application  prototype  up  and  running 
in  slightly  more  time  than  it  would 
have  taken  using  a  slide  show  demo 
program.  We  then  tried  out  the  pro¬ 
gram  on  “real”  users  to  test  our  general 
conceptions  and  data  flows. 

While  the  UI  designer  was  busy  pol¬ 
ishing  the  screens  and  menus,  the  pro¬ 
gramming  team  focused  on  implement¬ 
ing  the  database  in  its  final  form.  Tool¬ 
Book’s  internal  object-oriented  database 
was  ideal  for  the  prototype,  but,  like 
all  OODBMSs,  the  overhead  of  using 
ToolBook’s  database  for  a  traditional 
“data  processing”  database  appeared 
to  be  too  high. 

As  part  of  its  OpenScript  language, 
ToolBook  provides  an  interface  that 
allows  links  to  external  database  en¬ 
gines  which  can  store  data  outside  the 
ToolBook  OODBMS.  (Additionally,  the 
interface  allows  manipulation  of  the 
Windows  functions,  including  Windows 
memory  management.)  To  use  this  in¬ 
terface,  the  external  functions  must  be 
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(continued  from  page  92) 
in  a  Windows-compatible  DLL  and  must 
not  need  to  call  back  into  the  instance 
that  calls  them.  This  task  is  made  sig¬ 
nificantly  easier  if  the  external  func¬ 
tions  use  the  Pascal  calling  convention 
(as  is  typical  of  Windows  functions). 

In  reality,  a  checking  account  man¬ 
ager  is  a  hierarchically-structured  com¬ 
plex  accounting  system.  Although  this 
structure  is  more  clearly  modeled  with 
a  hierarchical  database  than  a  relational 
one,  we  needed  more  flexibility  than  a 
traditional  hierarchical  database  pro¬ 
vides.  We  also  needed  some  relational 
features  (keys,  for  example),  and  some 
common  features  of  small,  fast  datasets 
with  multiple  owners.  And,  given  our 
time  constraints  (we  had  to  prove  the 
technology  and  deliver  the  application 
to  the  client  on  schedule)  we  needed 
a  working  Windows  3.0-compatible 
DLL.  The  dbJVISTA  database  engine 
provided  this. 

Building  the  Database 

Our  basic  database  design  goal  was  to 
make  the  performance  fast.  To  com¬ 
pensate  for  the  overhead  display  of 
Windows  and  ToolBook  with  their  com¬ 
plex  graphics  (for  example,  ToolBook 
pages  take  up  more  disk  space  than 
db_VISTA  records,  and  disk  access  is 
understandably  slower),  we  knew  we 
could  optimize  data  access  so  that  the 
users  would  feel  the  system  was  re¬ 
sponsive.  Because  the  fastest  way  to 
access  data  in  a  hierarchical  database 
is  through  the  set  pointers,  we  defined 
a  database  that  has  more  small  sets 
than  might  be  usual  for  an  application 
of  this  size. 

Ordered  sets,  because  they  are  doubly- 
linked  lists,  degrade  linearly  with  the 
number  of  entries  in  the  set.  We  thus 
designed  the  database  so  that  the  typi¬ 


cal  maximum  number  of  members  of 
an  ordered  set  would  be  150,  and  the 
average  number  of  members  would  stay 
below  50.  This  necessitated  making 
some  of  the  sets  “sets-of-sets.” 

We  then  used  keys  for  access  across 
multiple  sets.  Because  keys  are  used 
primarily  for  reporting  rather  than  for 
transaction  processing,  we  were  will¬ 
ing  to  have  slightly  slower  access.  The 
end  result  was  the  design  shown  in 
Figure  2.  We  then  coded  this  database 
in  db_VISTA’s  data  definition  language. 
(See  Listing  One,  page  136.)  The  first 
part  of  the  definition  defines  three  da¬ 
tabase  files  and  a  key  file.  dbJVISTA 
could  have  combined  all  records  into 
one  file,  but  to  minimize  disk  usage, 
we  chose  to  separate  them.  The  sec¬ 
ond  section  of  the  definition  defines  the 
record  structures  in  a  rather  C-like  lan¬ 
guage;  the  third  defines  the  sets  we  are 
using.  We  used  two  orderings  of  sets: 

•  Ascending ,  which  orders  the  set  from 
lowest  to  highest  in  either  the  numeric 
or  text  collation  sequence.  This  order¬ 
ing  can  exact  a  penalty  in  insertion 
because  it  forces  a  linear  search  of  the 
link  list  for  the  insertion  point. 

»  Next,  which  inserts  the  new  record 
into  the  set  sequence  directly  after  the 
current  record.  This  “ordering”  is  very 
fast  on  the  insertion,  but  not  readily 
searchable. 

dbJVISTA  provides  three  other  or¬ 
derings:  first,  last,  and  descending.  Sets 
can  be  ordered  (for  example  in 
payor_accountcode )  by  more  than  one 
field,  as  long  as  the  fields  are  in  the 
same  record. 

Coupling  db_VISTA  and  ToolBook 

Once  the  database  was  designed,  we 
had  to  hook  up  db_VISTA  with  Tool¬ 
Book.  ToolBook’s  OpenScript  language 


ToolBook  Check! n g  Acco tint 


file  Edit  Setup  Actions  Register 


Asher  EJ  Rt/geiald 
5833  Columbia 
Stover.  MO  65078 


Check  J 


&  moant 
jjiriribiTteil  to: 


Memo 


Figure  1:  Main  setup  screen  for  the  checkbook  accounting  system 
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(continued  from  page  94) 
provides  three  means  for  linking  to  and 
using  a  DLL:  LinkDLL,  function  calls, 
and  pointers  and  pointer  conversions. 


LinkDLL  identifies  the  functions  in 
the  DLL  that  ToolBook  will  call  and 
specifies  the  DLL  which  contains  them. 
Functions  are  then  prototyped  using 
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Figure  2:  Database  design 
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(continued  from  page  96) 

the  data  types  for  which  ToolBook  has 

built-in  coercion.  (See  Table  1.) 

Listing  Two  (page  136)  is  the  Link- 
DLL  structure  for  the  check  manager 
application  where  we  link  to  four  DLLs: 
The  Windows  3.0  kernel  for  memory 
management  functions;  ToolBook’s 
tbkfile.dll ,  to  check  the  drive  and  direc¬ 
tory;  db_VLSTA’s  vista.dll  for  database 
management  (we  use  about  half  the 
functions  of  the  DLL  in  this  applica¬ 
tion);  and  chekmate.dll ,  our  own 
helper.DLL. 

Once  a  function  has  been  linked  in 
a  LinkDLL  structure,  the  function  is 
called  just  like  an  OpenScript  intrinsic 
function.  If  we  call  db_VISTA’s  find 
first  member  of  set  function  in  C,  we 
use  something  like  error  =  dt_findfm 
(PAYEE_ACCOUNT,  hCurrentTask, 
nDBnum);  In  ToolBook,  it’s  much  the 
same:  set  vError  to  dt_findfm(20002, 
svhCurrentTask,  svDBnum). 

Most  DLLs  pass  data  back  and  forth 
by  reference  as  well  as  by  value; 
db_VISTA  is  no  exception.  OpenScript 
provides  a  pointer  dereferencing  func¬ 
tion  for  each  of  its  coercible  data  types. 
For  example,  the  function  for  convert¬ 
ing  to  and  from  a  LONG  is  pointer - 
LONG.  To  dereference  the  second  ele¬ 
ment  of  a  db_VISTA  database  address 
array  (they  are  longs  declared  as  DBA 
payee[20f),  we  would  set  the  second 
element  to  pointer Long(4, payee)  and 
the  third  to  get  pointerLong(8, payee- 
,39421). 


BYTE 

unsigned  char 

INT 

signed  int 

WORD 

unsigned  int 

LONG 

signed  long 

DWORD 

unsigned  long 

FLOAT 

float 

DOUBLE 

double 

POINTER 

void  far  *. 

STRING 

LPSTR,  or  void  far ". 

'ToolBook  displays  a  pointer  as  segment, offset 

"ToolBook  requires  a  string  to  be  zero 
terminated. 

Table  1:  DLL  functions  called  by 
ToolBook 


Because  ToolBook  has  its  own  inter¬ 
nal  values  system,  you  can’t  directly 
pass  by  reference.  When  your  DLL  re¬ 
quires  pointers  instead  of  values  (and 
dbJVISTA  does),  you  need  to  allocate 
Windows  global  memory  that  both  Tool¬ 
Book  and  your  DLL  can  use. 

Memory  Management  Calls 

ToolBook  is  “just”  a  Windows  program, 
and  db_VISTA  is  “just”  a  Windows  DLL. 
That  means  that  all  memory  has  to  be 
manipulated  through  Windows’  ker- 
nel.EXE s  memory  management  func¬ 
tions.  The  five  key  functions  are  listed 
in  Table  2. 

Because  all  of  these  calls  can  fail 
under  low-memory  conditions,  check 
that  your  calls  were  executed  and  re¬ 
cover  if  not.  We  haven’t  included  this 
error  checking  in  the  examples,  but 
Listing  Three  (page  138)  shows  how  it 
could  be  done.  InitGlobals  allocates 
and  locks  the  three  global  memory 
blocks  we  use  as  sharable,  zero  initial¬ 
ized  memory.  FreeGlobals  does  the 
cleanup.  It  is  called  when  the  system 
shuts  down.  The  ToolBook  system  vari¬ 
ables,  which  point  to  the  Windows  glo- 
bals,  are  set  to  null  so  that  the  Tool¬ 
Book  coercion  system  will  trap  unini¬ 
tialized  memory  pointers  for  us,  rather 
than  sending  them  off  to  Windows  to 
cause  general-protection  violations. 

Global  Memory  Blocks  and  Communication 
with  the  DLL 

Because  ToolBook’s  values  are  not  di¬ 
rectly  available  to  the  DLL  world,  we 
constructed  two  primary  global  blocks. 
The  first  is  a  simple  255-byte  buffer 
that  we  can  pass  back  and  forth  be¬ 
tween  ToolBook  and  dbJVISTA.  You’ll 
see  it  in  the  listings  as  svptrDbBuffer. 
Since  ToolBook  is  a  protected-mode 
only  application,  leaving  the  memory 
locked  makes  no  difference  to  Win¬ 
dows  use. 

The  other  main  block  is  a  structure 
which  is  mainly  an  array  of  handles  to 
Windows  memory.  To  maximize  per¬ 
formance,  we  needed  to  buffer  a  num- 


Function 

Description 

GlobalAlloc 

Returns  a  handle  to  memory.  Handles  are  put  in  a  table,  so  that  memory 
can  be  moved  around  unless  locked  down.  You  can't  directly  use  the 
allocated  memory  unless  you  "lock  it  down”  and  get  a  pointer  to  it. 

Global  ReAlloc 

Resizes  a  memory  block.  This  function  returns  a  new  handle  which  may 
be  the  same  as  the  old  one. 

GlobalLock 

Takes  a  handle  and  returns  a  pointer  to  fixed  memory.  Because  Windows 
is  multitasking,  you  don't  want  to  lock  memory  for  any  longer  than  abso¬ 
lutely  necessary. 

GlobalUnLock 

Unlocks  the  memory  so  that  it  can  move.  Because  the  memory  can  move, 
this  function  invalidates  the  pointers  to  the  block. 

Global  Free 

Frees  the  memory  so  that  it  can  be  reused. 

Table  2:  Memory  management  functions 
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ber  of  relatively  small  blocks  of  data, 
particularly  the  combobox  selectors  for 
accounts  and  vendors.  The  structure 
definition  for  this  control  block  is  in 
Listing  Four  (page  138).  The  code  and 
name  array  handles  point  to  these  se¬ 
lectors  and  the  database  addresses  for 
each  of  these  selector  fields. 

We  could  access  this  block  by  using 
the  pointer  function  when  we  need  it, 
but  it’s  better  to  centralize  setting  and 
getting  values,  particularly  when  the 
structure  is  changing.  Listing  Five  (page 
138)  is  the  accessor  code  for  the  Tool¬ 
Book  side  of  this  control  block.  The 
first  to  get  handler,  or  ToolBook  func¬ 
tion  to  get  bControl,  returns  the  value 
of  the  individual  element  by  getting  the 
offset  through  the  ControlOffset  func¬ 
tion  and  dereferencing  the  structure. 
The  other  handler  in  this  example  is 
orthogonal  to  the  get  function  to  set 
hControl  and  uses  the  same  ControlOff¬ 
set  function  to  get  the  offset  before 
using  the  second  form  of  the  pointer 
functions  to  set  values  in  the  control 
block. 

Shell  Calls  to  db_VISTA 

The  db_VISTA  engine,  which  was  de¬ 
signed  to  be  called  from  a  C  program, 
provides  several  header  files  to  make 
the  interface  in  a  multiple-tasking  envi¬ 
ronment  such  as  Windows  simple  and 
clean.  db_VISTA  requires  the  calling 
program  to  specify  both  a  pointer  to 
an  instance  control  block  and  the  data¬ 
base  identifier.  In  order  to  emulate  the 
simplicity,  we  began  to  shell  calls  to 
db_VISTA  so  that  we  only  needed  to 
pass  the  relevant  parameters  inside  our 
main  program.  We  also  used  to  set  and 
to  get  handlers  to  provide  parallelism 
in  the  function  structure.  Because  of 
space  constraints,  the  actual  shell  code 
for  general-database  access  is  not  in¬ 
cluded  with  this  article  but  is  available 
electronically  (see  “Source  Code  Avail¬ 
ability”  on  page  3). 

Optimizing 

While  ToolBook,  like  any  other  general- 
purpose  programming  environment 
does  many  things  well,  there  are  areas 
that,  either  for  speed  or  ease  of  mainte¬ 
nance,  require  optimization.  We  identi¬ 
fied  the  key  areas,  then  applied  a  good 
dose  of  “vitamin  C.”  The  most  impor¬ 
tant  step  in  any  optimization  is  to  iden¬ 
tify  what  really  needs  to  be  optimized. 
We  identified  three  key  areas  where 
optimization  would  give  us  noticeable 
performance  benefits: 

•  Putting  the  text  and  database  addresses 
of  the  combobox  selectors  in  global 
memory 

•  Building  and  maintaining  the  check 
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register  image  in  global  memory 
•  Maintaining  account  balances 

The  combobox  selectors  are  on  the 
check-image  page  and  on  various  other 
pages.  We  could  have  left  them  there, 
but  they  need  to  be  updated  through¬ 
out  the  system,  and  this  takes  time. 
We  elected  to  keep  these  in  global 
memory  and  copy  them  into  ToolBook 
fields  when  needed. 

By  keeping  the  database  addresses 
available,  we  can  access  the  account 
and  payee  information  quickly;  we  can 
also  connect  records  quickly  without 
having  to  actually  retrieve  them  from 
the  database.  It  is  significantly  faster  to 
dereference  the  25th  element  of  an  ar¬ 
ray  than  to  get  the  25th  item  of  a  Tool¬ 
Book  list.  Therefore,  we  put  this  infor¬ 
mation  in  global  memory.  We  first  im¬ 
plemented  this  optimization  using  Tool¬ 
Book’s  OpenScript.  (For  those  of  you 
who  are  interested,  this  code  is  also 
available  online  and  on  disk.) 

After  we  completed  all  optimizations, 
we  came  back  and  optimized  our  Tool¬ 
Book  optimization  in  MS  C  5.1  as  shown 
in  Listing  Seven  on  page  139.  (The 
original  ToolBook  version  appears  in 
Listing  Six,  page  138.)  This  code  dem¬ 
onstrates  one  of  the  best  uses  of  Tool¬ 
Book  as  a  prototyping  tool.  Except  for 
breaking  CreateSelectorList  into  two  func¬ 
tions,  there  is  a  direct  correspondence 
in  the  C  code  and  the  OpenScript  code. 
By  prototyping  even  those  functions, 
which  we  knew  would  be  recoded  in 
C,  we  saved  several  compile-link-test 
cycles  in  ToolBook’s  interactive  envi¬ 
ronment. 

We  had  planned  from  the  start  to 
manage  the  register  and  its  balances 
in  a  helper.DLL.  While  computation  in 


Product  Information 

ToolBook  v.  1.0 
Asymetrix  Corp. 

110  110th  Ave.  N.E.,  Ste.  717 
Bellevue,  WA  98004 
206-462-0501 

db_VISTA  III  v.  3.15 
Raima  Corp. 

3245  146th  PI.  S.E. 

Bellevue,  WA  98007 
206-747-5570 

Windows  3-0 
Windows  3.0  SDK 
Microsoft  C  5.1 
Microsoft  Corp. 

One  Microsoft  Way 
Redmond,  WA  98052-6399 
800-227-4679 


ToolBook  is  no  slouch,  we  could  get  a 
substantial  increase  in  speed  by  using 
integer  arithmetic  and  array  manipula¬ 
tion  in  the  helper.DLL  rather  than  Tool¬ 
Book’s  floating-point  arithmetic  and 
string  manipulation. 

There  are  three  columns  in  a  check 
register:  deposits,  withdrawals,  and  bal¬ 
ances.  We  stored  this  as  a  3-by -n  array 
of  longs  (longs  give  us  +/—  $21  million, 
definitely  large  enough  for  most  peo¬ 
ple’s  checkbooks!).  Because  the  bal¬ 
ances  are  never  stored  in  the  database, 
we  calculate  them  on-the-fly  from  the 
registerNumbers  array.  (You  can  get 
the  balance  maintenance  code  online 
or  on  disk.) 

We  planned  to  maintain  the  check 
register  image  and  its  database  address 
array  in  global  memory  as  part  of  the 
initial  design.  The  check  register,  as 
you  can  see  in  Figure  1,  is  an  array  of 
the  check  number,  date,  description, 
whether  or  not  the  check  has  been 
reconciled,  the  deposit,  withdrawal,  and 
balance  amounts.  We  build  each  line 
for  a  given  month  in  the  helper.DLL 
and  once  all  of  the  lines  are  created, 
we  copy  the  image  into  a  ToolBook 
field.  An  important  part  of  this  optimi¬ 
zation  is  the  same  technique  which 
we  used  with  the  combobox  text:  We 
maintain  an  array  of  database  addresses 
which  corresponds  to  the  register.  This 
allows  us  to  directly  access  a  check  by 
its  database  address.  (The  code  for  build¬ 
ing  the  register  is  also  available  online.) 

Conclusion 

By  using  development  tools  where  they 
have  their  greatest  strengths  —  Tool¬ 
Book  for  implementing  a  graphically 
sophisticated  interface,  db_VISTA  for 
handling  raw  data,  and  C  for  optimiza¬ 
tion  —  programmers  can  bring  an  ap¬ 
plication  from  conception  through  im¬ 
plementation  in  much  less  time  than  is 
required  for  typical  GUI  applications. 
Even  with  the  overhead  of  a  large  de¬ 
velopment  and  delivery  environment 
such  as  ToolBook,  we  were  able  to 
provide  solid  performance  by  carefully 
choosing  where  to  optimize  and  gain¬ 
ing  the  greatest  advantage  from  our 
optimization  effort. 
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listing  One  (Text  begins  on  page  16.) 

/*  File  :  OOP. PRO  --  Include  file  that  adds  inheritance  mechanism 
and  message  passing  facility.  This  file  also  declares  the 
object-oriented  predicates  msg(),  method (),  has(),  and  is_a(). 

Objects  are  implemented  using  a  technique  known  as  frames; 
the  inheritance  mechanism  is  based  on  the  article  "Suitable  for 
Framing"  by  Michael  Floyd  (Turbo  Technix,  April/May  '87). 

Michael  Floyd  —  DDJ  —  8/28/90  —  CIS:  [76703,4057]  or  MCI  Mail:  MFLOYD 


DOMAINS 


object 

=  object (string, slots)  %  not  actually  used  in  examples 

objects 

=  object* 

slot 

=  slot (string, value) 

slots 

=  slot* 

value 

=  int (integer)  ;  ints (integers)  ; 
real  (real)  ;  reals (reals)  ; 
str (string)  ;  strs (strings)  ; 
object (string, slots, parents)  ;  objects (objects) 

parents 

=  string* 

integers 

=  integer* 

reals 

=  real* 

strings 

=  string* 

%  -  OOP  preds  to  be  used  by  the  programmer  - 


DATABASE 

has (string, slots) 
is_a (string,  string) 
PREDICATES 

msg (string, string) 
method (string,  string) 


%  storage  for  instance  vars 
%  hierarchy  relationships 

%  send  a  message  to  an  object 
%  define  a  method 


%  —  Internal  Predicates  not  called  ditrectly  by  the  programmer  — 


inherit (string, slot) 
description (string, slot) 
member (slot, slots) 
CLAUSES 


%  inheritance  mechanism 
%  search  for  matching  clauses 
%  look  for  object  in  a  list 


/*  Inheritance  Mechanism  */ 
inherit (Object, Value) :- 

description (Object, Value) , ! . 
inherit (Ob ject, Value) :- 
is_a (Ob ject, Ob jectl) , 
inherit (Objectl, Value) , 
description (Objectl,_) . 
description (Ob ject, Value) :- 
has (Ob ject, Description) , 
member (Value, Description) . 
description (Object, slot (method, str (Value) ) ) :- 
method (Object, Value) . 

/*  Simple  message  processor  */ 
msg (Object, Message) :- 

inherit (Object, slot (method, str (Message) ) ) . 

/*  Support  Clauses  */ 

member (X, [X !_]):-! .  %  Find  specified  member  in  a  list 

member (X, [_!L] ) : -member (X,  L) . 


End  Listing  One 


Listing  Two 

/*  File:  FIGURES. PRO  --  Object  Prolog  example  that  models  FIGURES  example  in 
Turbo  C++  and  Turbo  Pascal  documentation 
Michael  Floyd  —  DDJ  —  8/28/90 


include  "bgi.pro" 
include  "OOP. PRO" 

domains 

key  =  escape;  up  arrow;  down_arrow;  left_arrow;  right_arrow;  other 
database  -  SHAPES 
anyShape (string) 

PREDICATES  %  Support  predicates 

horiz (integer,  integer,  string) 
vert (integer,  integer,  integer) 
readkey (integer,  integer,  integer) 
key_code (key,  integer,  integer,  integer) 
key_code2 (key,  integer,  integer,  integer) 
repeat 
main 

CLAUSES 
/*  Methods  */ 

/*  point  is  an  example  of  an  Abstract  object.  Note  that  variables  passed 
through  the  database  must  be  explicitly  called  by  the  child 
method  (i.e.  variables  are  not  inherited).  */ 

method (point,  init) :- 

assert (has (point, [slot (x_coord, int (150) ) , 
slot (y  coord, int (150) ) ] ) ) . 
method(point,  done):- 

retractall (has (point, _) ) . 
method (point, show) : - ! , 

has (point, [slot (x_coord, int  (X) ) , 

slot (y_coord, int (Y) ) ] ) , 
putpixel(X,Y,blue) . 
method (point , hide ) : - ! , 

has (point, [slot (x_coord, int (X) ) , 

slot (y_coord, int (Y) ) ] ) , 
putpixel (X, Y, black) . 
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/*  Example  of  a  virtual  method  */ 
method (point, moveTo) 
anyShape (Object) , 
msg (Object, hide) , 

retract (has (point, [slot (x_coord, int (DeltaX) ) , 

slot (y_coord, int (DeltaY) ) ] ) ) , 

msg (Object, show) . 
method (point, drag) :- 

has (point, [slot (x_coord, int (X) ) , 
slot (y_coord, int (Y) ) ] ) , 
anyShape (Shape) , ! , 
msg (Shape, show) , 
repeat, 

readkey (Key,  DeltaX,  DeltaY) , 

assertz (has (point, [slot (x_coord, int (DeltaX) ) , 

slot (y_coord, int (DeltaY) ) ] ) ) , 

msg (point , moveTo) , 

Key  =  27. 

/*  Circle  Methods  */ 
method (circle,  init):-!, 
method(point,  init), 
assert (anyShape (circle) ) . 
method (circle,  done):-!, 

retract (anyShape (circle) ) , 
method (point,  done) . 
method (circle,  show):-!, 

has (point, [slot (x_coord, int (X) ) , 

slot (y_coord, int  (Y) ) ] ) , 
setcolor (white) , 
circle(X, Y,50) . 
method (circle,  hide) : - ! , 

has (point, [slot (x_coord, int (X) ) , 
slot (y_coord, int (Y> ) ] ) , 
setcolor (black) , 
circle (X, Y, 50) . 
method (circle,  drag) :- 
msg (circle,  hide), 
is_a (circle,  Ancestor), 
msg (Ancestor,  drag), 
msg (circle,  show). 

/*  arc  Methods  */ 

method(arc,  init):-!, 
assert (anyShape (arc) ) , 
assert (has (point, [slot (x_coord, int (150) ) , 
slot (y_coord, int (150) ) ] ) ) , 
assert (has (arc, [slot (radius, int (50) ) , 

slot (startAngle, int (25) ) , 
slot (endAngle, int (90) )  ] ) ) . 

method(arc,  done) :- 

retract (anyShape (arc) ) , ! , 
retractall (has (arc,_) ) , 
msg (point,  done), 
method (arc,  show) :- 

has (point, [slot (x_coord, int (X) ) , 

slot (y_coord, int (Y) ) ] ) , 
has (arc, [slot (radius, int (Radius) ) , 

slot (startAngle, int (Start) ) , 
slot (endAngle, int (End) ))),!, 

setcolor (white) , 
arc(X,  Y,  Start,  End,  Radius). 
method(arc,  hide):- 

has (point, [slot (x_coord, int (X) ) , 

slot (y_coord, int (Y) ) ] ) , 
has  (arc,  [slot  (radius,  int  (Radius) ) , 

slot (startAngle, int (Start) ) , 
slot (endAngle, int (End) )]),!, 

setcolor (black) , 
arc(X,  Y,  Start,  End,  Radius), 
method (arc, drag) :- 
msg (arc,  hide), 
i s_a (arc, Ancestor) , ! , 
msg (Ancestor, drag) , 
msg (arc,  show). 

/*  rectangle  Methods  */ 
method (rectangle, init) :- 

has (rectangle,  [slot (length, int (L) ) , 

slot (width, int  (W) ) ] ) ,  ! . 
method (rectangle, init) :-! , 

write ("Enter  Length  of  rectangle:  "), 
readint (L) ,nl, 

write ("Enter  Width  of  rectangle:  "), 
readint (W) , nl, 

assert (has (rectangle, [slot (length, int (L) ) , 
slot (width, int (W) ) ] ) ) . 
method (rectangle, done) :- 

retract (has (rectangle, [slot (length, int (L) ) , 
slot (width, int (W) )))),! . 
method (rectangle, draw) :-!, 

has (rectangle, [slot (length, int (L) ) , 
slot (width, int  (W) )  ] ) , 

write ("Z") , 
horiz (1, L, "D") , 
write ("?") , nl, 
vert  (1,  W,  L) , 
write ("@") , 
horiz (1, L, "D") , 
write ("Y")  . 

method (rectangle, draw) :- 

write ("Cannot  draw  rectangle") ,nl. 

/*  Support  Methods  */ 
horiz (I,L,Chr) :- 
I  <=  L,  ! , 

Tempi  =1+1, 
write (Chr) , 
horiz (Tempi, L, Chr) . 
horiz (I,L,Chr) :-! . 
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Listing  Two  (Listing  continued ,  text  begins  on  page  16.) 

vert (I, w, L) 

I  <=  W, ! , 

Tempi  =1+1, 
write ("3") , 
horiz(l,L,  "  "), 
write ("3") , nl, 
vert (Tempi, W, L) . 
vert (I, W, L) :-! . 

/*  Ancestor/Child  relationships  -  should  be  stored  in  consult ()  file  */ 
is_a (circle, point) . 
is_a (arc, point) . 
is_a (triangle, shape) . 
is_a (rectangle, shape) . 
is_a (solid_rectangle, rectangle) . 

/*  Generic  clause  to  read  cursor  keys  -  used  by  the  Drag  method  */ 
readkey(Val,  NewX,  NewY) 
readchar (T) , 
char_int (T,  Val), 
key_code (Key,  Val,  NewX,  NewY). 
key_code (escape,  27,  0,  0)  !. 

key_code (Key,  0,  NewX,  NewY)  !, 
readchar (T) , 
char_int(T,  Val), 
key_code2 (Key,  Val,  NewX,  NewY). 
key  code2 (up_arrow,  72,  NewX,  NewY)  !, 
has  (point,  (slot  (x_coord,  int  (X) ) , 

slot (y_coord, int (Y) ) ] ) , 

NewX  =  X, 

NewY  =  Y  -  5. 

key_code2 (left_arrow,  75,  NewX,  NewY):-  !, 
has (point,  [slot (x_coord, int (X) ) , 

slot (y_coord, int (Y) ) ] ) , 

NewX  =  X  -  5, 

NewY  =  Y. 

key_code2 (right_arrow,  77,  NewX,  NewY)  !, 
has (point,  [slot (x_coord, int (X) ) , 

slot (y_coord, int (Y) ) ] ) , 

NewX  =  X  +  5, 

NewY  =  Y. 

key_code2 (down_arrow,  80,  NewX,  NewY)  !, 
has (point, (slot (x_coord, int  (X) ) , 

slot (y_coord, int (Y) ) ) ) , 

NewX  =  X, 

NewY  =  Y  +  5. 

key_code2 (other,  _,0,0). 

/*  Supports  the  repeat/fail  loop  */ 
repeat . 

repeat:-  repeat. 


main: - 
nl, 

initialize,  %  init  BGI  graphics 

makewindow (1, 7, 0,"", 0,0, 25, 80), 

msg(circle,  init),  %  create  and  manipulate  a  circle 

msg (circle,  show), 

msg (circle,  drag), 

msg (circle,  done), 

clearwindow, 

msg (arc,  init),  %  create  and  manipulate  an  arc 

msg (arc,  show), 
msg (arc,  drag), 
msg (arc,  done), 

closegraph,  %  return  to  text  mode 

makewindow (2, 2, 3, "",0,0,25,80) , 

msg (rectangle,  init),  %  create  a  rectangle  in  text  mode 

msg (rectangle,  draw), 
msg (rectangle,  done). 

goal 

main.  ...  _ 

End  Listing  Two 

Listing  Three 

/*  File:  BGI. PRO  —  Minimum  required  to  detect  graphics  hardware  and  initialize 
system  in  graphics  mode  using  BGI.  BGI.PRE  is  included  with  PDC  Prolog. 
Michael  Floyd  —  DDJ  --  8/28/90 

*/ 

include  "D: \\prolog\\include\\BGI .PRE" 

CONSTANTS 

bgi_Path  =  "D:\\prolog\\bgi" 

PREDICATES 
Initialize 

CLAUSES 

Initialize:- 

DetectGraph (G_Driver,  G_Mode) , 

InitGraph (G_Driver, G_Mode,  _,  _,  bgi_Path) , ! 

Listing  Four 

include  "bgi.pro" 
include  "support .pro" 
database  -  figures 
anyShape (string) 

point  =  object 

int  XCoord  YCoord 

method (init)  if  XCoord  =  150,  YCoord  =  150. 


End  Listing  Three 
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method (done)  if  retract (has (point, _)) . 
method (show)  if  putpixel (XCoord, YCoord, blue) . 
method(hide)  if  putpixel (XCoord, YCoord, black) . 
method (moveTo)  if 
anyShape (Object ) , 
msg (Object,  hide), 
retract (has (point , _) ) , 
msg (Object,  show), 
method (drag)  if 
anyShape (Shape) , 
msg (Shape, show) , 
repeat, 

readkey(Key,  DeltaX,  DeltaY) , 

XCoord  =  DeltaX, 

YCoord  =  DeltaY, 
msg (point, moveTo) , 

Key  =  27. 

end. 

circle  =  object (point) 
int  XCoord  YCoord 
method (init)  if 

XCoord  =  200,  YCoord  =  200, 
assert (anyShape (circle) ) . 
method (done)  if 

retract (anyShape (circle) ) , 
msg (point, done) . 
method (show)  if 
setcolor (white) , 
circle (XCoord,  YCoord,  50). 
method (hide)  if 
setcolor (black) , 
circle (XCoord,  YCoord,  50). 
method (drag)  if 

msg (circle, hide) , 
is_a (circle,  Ancestor) , 
msg (Ancestor, drag) , 
msg (circle, show) . 

end. 

arc  =  object (point) 

int  XCoord  YCoord  Radius  StartAngle  EndAngle 
method (init)  if 

Radius  =  50,  StartAngle  =  25,  EndAngle  =  90, 
msg (point,  init). 
method (done)  if 

retract (anyShape (arc) ) , 
retractall (has (arc, _) ) , 
msg (point,  done), 
method (show)  if 
setcolor (white) , 

arc (XCoord, YCoord, StartAngle, EndAngle, Radius) . 
method (hide)  if 
setcolor (black) , 

arc (XCoord, YCoord, StartAngle, EndAngle, Radius) . 


method (drag)  if 
msg (arc, hide) , 
is_a  (arc, Ancestor) , 
msg (Ancestor, drag) , 
msg (arc, show) . 

end. 


Listing  Five 


End  Listing  Four 


/*  File:  PARSER. PRO  —  Implements  parser  to  translate  ODL  to  Object  Prolog 
code.  Top-down  parser;  simulates  parse  tree  through  predicate  calls. 
Michael  Floyd  —  DDJ  —  8/28/90 

*/ 

include  "lex. pro" 


DOMAINS 

file  =  infile;  outfile;  tmpfile 

PREDICATES 
main 
repeat 
gen (tokl) 
scan 

scan_ob ject (tokl,  string) 
f indAncestor (tokl) 
init_vars 

scan_methods (string) 
getMethEnd (string,  string) 
write_includes 
generate_code 
generate_methods 
generate_ancestor (string) 
generate_vars 
fixVar (tokl) 
insert_isa (tokl) 
bindvars (tokl, tokl) 
addVarRef (tokl) 
assert_temp (strings,  tokl) 
construct_has (tokl) 
empty (tokl) 
isvar (tokl, tokl) 
is_op(tok) 
value (tok,  integer) 

search_ch (CHAR, STRING, INTEGER, INTEGER) 
process (string) 
read (string) 
datatype (string) 
headbody (tokl, tokl, tokl) 
search_msg (tokl ,  tokl ,  tokl ) 
constVar (string,  tok) 
writeSlotVars 

(continued  on  page  106) 


1038 


105 


OOP  LANGUAGE 


Listing  Five  (Listing  continued,  text  begins  on  page  16.) 

write_seperator (tokl) 
write_comma 
append (tokl, tokl, tokl) 

CLAUSES 
repeat . 

repeat : -  repeat . 

/****  Parser  ****/ 
scan: - 

readln (Ob jectStr) , 

ObjectStr  <> 
tokl (Ob jectStr, Ob jList) , 
scan_object (Ob jList, Object) , 
init_vars, 

scan_methods (Object) ,  ! , 
generate_code . 
scan:-  scan. 

scan_object ( [H ! List ] , S) :- 
member (object, List) , 
str_tok(S,H) , 
assert (objectname (S) ) , 
findAncestor (List) . 
scan_object (List,_) :- 

openappend(tmpfile, "headers . $$$") , 
writedevice (tmpf ile) , 
gen (List) , nl, 
writedevice (screen) , 
closef ile (tmpfile) , trace (off) , 
fail . 

findAncestor (List) :- 
member (lpar, List) , 
insert_isa (List) . 
findancestor (_) . 

insert_isa ( [HIList] )  :- 
str_tok(S,H) , 

S  <>  "(", 
insert_isa (List) . 
insert_isa ( [HI , H2 ! List ] )  :  - 
str_tok (Ancestor, H2) , 
assert (ancestor (Ancestor) ) . 

init_vars:- 

readln (VarStr) , 
process (VarStr) . 

process (VarStr) :- 

fronttoken (VarStr, Token,  RestStr) , 
datatype (Token) , 

tokl (VarStr, VarList) ,! .  %  tokenize/init  variables 

_ _  generate_vars:- 

findall(Var,var(Var), VarList) ,  % 

retractall (var (_) ) ,  % 

fixVar (VarList) , 

findall (X, var (X) , Slots) ,  % 

retractall (var (_)) ,  % 

assert (vars (Slots) ) .  % 

generate_vars:-  !. 

fixVar ( [] ) :-  ! . 

fixVar( [slot (UpToken, Const) IRest] ) :- 
upper_lower (UpToken, Token) , 
assert (var (slot (Token, Const) ) ) , 
fixVar (Rest) . 


generate_ancestor (Object) :- 

openappend (tmpfile, "isa.$$$") ,  % 

writedevice (tmpfile) ,  % 

objectname (Ob j) ,  % 

retract (ancestor (Parent) ) ,  % 

write("is_a(",Obj, ",  ",  Parent, ") .") , 
nl, 

writedevice (screen) ,  % 

closefile (tmpfile) .  % 

generate_ancestor  (_) :-  % 

writedevice (screen) ,  % 

closefile (tmpfile) .  % 


generate_methods : - 

retract (methods (Method) ) , ! , 
headBody (Method, Head,  Body) , 
bindvars (Body, NewBody) , 
gen (Head) , 
write (":-"),  nl, 
addVarRef (NewBody) , 
gen (NewBody ) , n 1 , 
generate_methods . 
generate_methods : - 

writedevice (screen) , 
closefile (tmpf ile) . 

/*  Binding  of  variable  names  in  for  has() 
addVarRef (Body) : - 

findall (Variable,  var (slot (Variable, 
findall (X,  var (slot (_, X) ) ,  XList), 
assert_temp (VList,  XList), 
construct_has (Body) . 
addVarRef (Body) . 

assert_temp ([],[]) :-  !. 
assert_temp ( [ V ! VList ] , [X ! XList ) ) : - 
const Var ( Type , X ) , 
assert (tempvar (V) ) , 
assert (temptype (Type) ) , 
assert_temp (VList, XList)  . 


assert (unread (VarStr) )  . 

datatype (int) .  % 

datatype (real) . 

constVar (int, int (_) ) .  % 

constVar (real, real_(_) ) . 

read(Str) 

retract (unread (Str) ) , ! . 
read(Str) :- 
readln (Str) . 

scan_methods (Methodld) :- 
readln (FirstLn) , 
getMethEnd (FirstLn, Method) , 
search_ch(' (', Method, 0,N) , 

Nl  =  N+l, 

fronttoken (MComma, Methodld, ", ") , 
frontstr (Nl, Method, Str,OUTl) , ! , 
fronttoken (Methodl, MComma, Out 1) , 
fronttoken (Method2, Str, Methodl) , 
tokl (Method2,MList) , 
not (member (end, MList) ) , 
assert (methods (MList) ) , 
scan_methods (Methodld) . 
scan_methods (_) : -  ! . 

getMethEnd (Linel, ReturnLn) :- 
search_ch ( ' . ' , Linel , 0 ,  N) , 

No  0, !, 

ReturnLn  =  Linel. 
getMethEnd (Linel, ReturnLn) :- 
readln (Line2) , 

fronttoken (AppendLn, Linel, Line2) , 
getMethEnd (AppendLn, ReturnLn) . 

/****  Entry  point  into  the  code  generator 
generate_code : - 

objectname (Object) , 

generate_ancestor (Object) , 

openappend (tmpfile, "methods . $$$") , 

writedevice (tmpfile) , 

generate_methods, 

generate_vars, 

vars (VarList) , ! , 

openappend (tmpfile, "has.$$$") , 

writedevice (tmpfile) , 

write ("has (", Object, ", ", VarList) , 

write (") .") ,nl, 

writedevice (screen) , 

closefile (tmpfile) , 

retract (objectname (Object) ) . 


datatypes  supported 


convert  tok  to  string 


%  Find  lpar  and  insert  Methodld 
%  and  add  comma 


%  Now  Tokenize  the  method 
%  Check  for  End  statement 
%  Store  method  list 
%  Look  for  more  methods 


retrieve  vars 
cleanup  database 

retrieve  new  vars 

cleanup  database 

store  vars  as  list  of  slots 


open  temp  file  for  is_a 
stdout  to  tmpfile 
get  current  object  id 
get  parent  in  hierarchy 
%  write  is_a  clause 

stdout  to  screen 
close  temp  file 
always  succeed 
stdout  to  screen 
close  temp  file 


lookups  */ 
J),  VList), 
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Listing  Five  (Listing  continued,  text  begins  on  page  16.) 


const ruct_has (Body) :- 
ob jectname (Object) , 
write  ("  has (", Object, 
writeSlotVars, 
writeC) ") , 

write_seperator (Body) , nl . 

write_seperator ([]):- 
write  (" . ")  . 
write_seperator (  ):- 
writer, ") . 

writeSlotVars :- 

retract (tempVar (Var) ) , 
retract (temptype (Type) ) , 
upper_lower (Var,  Varld) , 

write ("slot (", Varld, ",  ",  Type, " (", Var, "))"), 
write_comma, 
writeSlotVars. 
writeSlotVars:-  !, 
write  ("] ") . 

write_comma : - 
tempvar (_) , 
write (", ") . 
write_comma:-  !. 

Append  two  lists  */ 
append([],  List,  List), 
append ( [HIListl] ,  List2,  [H!List3]):- 
append(Listl,  List2,  List3) . 

search_msg( [H,H2 IBody] , (] ,Body) :- 
H  =  msg, 

H2  =  lpar. 

search_msg( (HI Method] ,  [HI Head],  Body):- 
search_msg (Method, Head, Body) . 


search_ch (CH, STR, N, N) : - 

frontchar (STR,  CH,_) , ! . 
search_ch (CH, STR, N, Nl ) : - 
frontchar (STR,_, SI) , 

N2  -  N  +  1, 

search_ch (CH,  SI,  N2,N1) . 

headbody ( (H! Body] ,  ( ] ,  Body) :- 
str_tok("if",H)  . 

headBody ( (H I  Method] ,  [HlHead],  Body): 
headBody (Method, Head,  Body) . 

bindvars (Method,  NewMethod) :- 
is_op (Op) , 
member (Op, Method) , 
isvar (Method, (HI RestMethod] ) , 
bindvars (RestMethod, NewMethod) . 

bindvars (NewMethod,  NewMethod) : -  ! . 


%  Search  for  char  in  string 
%  and  return  its  position 


%  supports  any  operator 
%  defined  by  is_op() 

%  locate  variable  in  method 
%  look  for  more  vars 
%  return  Method  w/out  vars 

%  simple  test  for  empty  list 


isvar ([] ,  []):-!. 

isvar ( [ id (X) , H2 , H3 ! RestMethod] ,  RestMethod) : - 
is_op(H2) , 
value (H3, Value) , 
ob jectname (Objld) , 


%  add  "var  not  decl."  error  here 


retract (var (slot (X,_) ) ) , ! , 
assert (var (slot (X,H3) ) )  . 

isvar ( [HI  Method] , NewMethod) :- 
isvar (Method, NewMethod) . 

is_op (equals) . 

is_op (plus) . 

value (int  (X) ,  X)  . 

gen ( [ ] ) : -  ! . 

gen ( [H! List] ) :- 
str_tok(S,H) , 
write (S) , 
gen (List) . 

write_includes : - 

write  ("include  V'oop.proV"')  ,nl. 


main:- 

/****  Reads  file  (e.g,  FIGURES. ODL)  specified  on  command  line.  First  order  of 
business  is  to  add  error  handling  for  command  line  processsor.  ****/ 
comline (Filename) , 
openread (infile,  Filename), 
readdevice (infile) , 
repeat, 

scan, 

eof (infile) , 
readdevice (keyboard) , 
openwrite (outfile, "newfig.pro") , 
writedevice (outfile) , 
write_includes , nl , 
file_str ("headers. $$$", Headers) , 
write (Headers) , nl, 
write ( "clauses\n" ) , 
f i le_s  t  r ( "methods .$$$", Met  hods ) , 
write (Methods) , nl, nl, 
file_str ("isa.$$$",  Isa) , 
write (Isa) ,nl,nl, 
file_str ("has.$$$", Has) , 
write (Has) , 
writedevice (screen) , 
closef ile (outfile) , 
closefile (infile) , 


deletef ile ( "headers. $$$") , 
deletef ile ("methods . $$$") , 
deletefile ("isa.$$$") , 
deletefile ("has.SSS") , 
write ("done")  . 


End  Listing  Five 


Listing  Six 


%  entry  point  into  the  scanner 
%  tokenize  a  string 
%  return  individual  token 
%  verify  member  is  in  list 
%  setup  lookahead  stack 


/*  File:  LEX. PRO  —  Implements  scanner  which  tokenizes  ODL.  To  modify,  add 
appropriate  DOMAIN  declarations  and  str_tok  definitions. 

Michael  Floyd  —  DDJ  —  8/28/90 

*/ 

DOMAINS 

tok  =  id (string); 

int (integer) ;  real_(real)  ; 
plus;  minus; 

mult;  div; 

lpar;  rpar; 

comma;  colon; 

semicolon;  period; 
object;  method; 

msg;  end; 

ancestor;  var (string) ; 

equals;  if_; 

slash;  bslash; 

slot (string, tok) ;  dummy 

tokl  =  tok* 
strings  =  string* 

DATABASE 

nextTok (string)  %  Token  lookahead 

ob jectname (string)  %  current  Object  ID 

vars (tokl)  %  variables  list 

methods (tokl)  %  methods  list 

var (tok)  %  individual  var 

ancestor (string)  %  tracks  Object's  ancestor 

unread (string) 

tempVar (string) 

temptype (string) 

PREDICATES 

tokl (string,  tokl)  %  entry  point  into  the  scanner 

tokenize (string, tokl)  %  tokenize  a  string 

str_tok (string,  tok)  %  return  individual  token 

member (tok,  tokl)  %  verify  member  is  in  list 

scan_next (string)  %  setup  lookahead  stack 

clauses 

str_tok ("int", slot (Token, int (0) ) ) :- 
retract (nextTok (Token) ) ,  ! , 
assert (var(slot (Token, int (0) ) ) ) , 
str_tok (”int",_) . 

str_tok ("int", slot (dummy, int (0) ) ) :-  ! , 
assert (nextTok (dummy) ) . 
str_tok ("real", slot (Token, real_(0) ) ) :- 
retract (nextTok (Token) ) ,  ! , 
assert (var (slot (Token, real_(0) ) ) ) , 
str_tok("real",_) . 

str_tok ("real", slot (dummy, real_(0) ) ) :-  ! . 

str_tok("(",  lpar):-  !. 

str_tok(")",  rpar):-  !. 

str_tok("=",  equals):-  !. 

str_tok("+",  plus):-  !. 

str_tok("-",  minus):-  !. 

str_tok("*",  mult):-  !. 

str_tok("/",  div):-  !. 

str_tok ("\"", bslash) :-  !. 

str_tok(",",  comma):-  !. 

str_tok(":",  colon):-  !. 

str_tok(";",  semicolon):-  !. 

str_tok(".",  period):-  !. 

str_tok ("if ",  if_):-  !. 

str_tok ("object",  object):-  !. 

str_tok ("method",  method):-  !. 

str_tok ("msg",  msg):-  !. 

str_tok ( "end" ,  end) : - ! . 

/*  str_tok(Var,  var(Var)):- 
f rontchar (Var,  X,_) , 

X  >=  'A' ,  X  <=  'V  .*/ 
str_tok (ID,  id(ID) ) :- 
isname (ID) , ! . 

str_tok (IntStr, int  (Int) )  :- 
str_int (Intstr, Int) . 

/*  Entry  point  into  the  scanner  */ 
tokl (Str,  Tokl) :- 

fronttoken (Str,  Token,  RestStr) , 
scan_next (RestStr) , 
tokenize (Str,  Tokl) . 

tokenize ("",[]) :-  !,  retractall (nexttok (_) ) . 
tokenize (Str,  [ToklTokl] ) :- 

fronttoken (Str,  Token,  RestStr), 
str_tok (Token,  Tok), 
tokenize (RestStr,  Tokl). 
scan_next  ("")  . 
scan_next (RestStr)  :- 

fronttoken (RestStr,  NextToken,  MoreStr) , 
assert (nexttok (NextToken) ) , 
scan_next (MoreStr) . 

member (X, [X I _ ] ) :-! . 

member (X, [_!L]) : -member (X,  L) . 


End  Listings 
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listing  One  (Text  begins  on  page  20.) 

f$A+,B-,D-,E-,F+, I+,L-,N-,0-,R-,S-,V+) 

Unit  Diet; 

Interface 

{  DICT.PAS  dictionary  object  and  methods  to  create  and  use  a  superimposed 
code  dictionary.  Copyright  Edwin  T.  Floyd,  1990.  } 

Type 

Dictionary  =  Object 

DictArray  :  Pointer;  {  Pointer  to  dictionary  bit  array  } 

DictCount  ;  Longlnt;  <  Number  of  key  entries  in  this  dictionary  } 

DictSize  :  Word;  {  Number  of  bytes  in  dictionary  bit  array  } 

DictBits  :  Byte;  {  Number  of  bits  per  key  entry  } 

Constructor  Init(MaxKeys  :  Word;  BitsPerKey  :  Byte); 

{  Initialize  dictionary,  specify  maximum  keys  and  bits  per  key.  ) 

Constructor  RestoreDictionary (FileName  :  String); 

{  Restore  dictionary  saved  on  disk  by  SaveDictionary  > 

{  Note:  Use  either  Init  or  RestoreDictionary,  not  both.  ) 

Destructor  Done; 

f  Release  storage  allocated  to  dictionary.  } 

Function  DictionarySize  :  Word; 

{  Returns  number  of  bytes  that  will  be  written  by  SaveDictionary.  } 

Procedure  SaveDictionary (FileName  :  String); 

(  Save  dictionary  in  a  disk  file.  ) 

Function  Insertstring (Var  s  :  String)  :  Boolean; 

(  Insert  string  in  dictionary;  returns  TRUE  if  string  is  already  there.  } 

Function  StringlnDictionary (Var  s  :  String)  :  Boolean; 

{  Returns  TRUE  if  string  is  in  dictionary.  } 

Function  InsertBlock (Var  Data;  Len  :  Word)  :  Boolean; 

(  Insert  block  in  dictionary;  returns  TRUE  if  block  is  already  there.  ) 

Function  BlocklnDictionary (Var  Data;  Len  :  Word)  :  Boolean; 

{  Returns  TRUE  if  block  is  in  dictionary.  } 

Function  InsertHash (Hash  :  Longlnt)  :  Boolean; 

(  Insert  hash  in  dictionary;  returns  TRUE  if  hash  is  already  there.  } 

Function  HashlnDictionary (Hash  :  Longlnt)  :  Boolean; 

(  Returns  TRUE  if  hash  is  in  dictionary.  ) 

Function  EstError  :  Real; 

(  Returns  estimated  probability  of  error.  } 

Function  ActError  :  Real; 

(  Returns  actual  probability  of  error  (slow,  counts  bits) .  } 

End; 

Function  DictionaryBytes (MaxKeys  :  Longlnt;  BitsPerKey  :  Byte)  :  Longlnt; 

{  Returns  the  size  in  bytes  of  the  optimal  dictionary  bit  table  for  the 
indicated  key  and  bit-per-key  counts.  ) 

Function  DictHash(Var  Data;  Len  :  Word)  :  Longlnt; 

(  Hash  data  block  to  a  positive  long  integer.  ) 

Implementation 

Const 

MagicNumber  =  $E501205F;  {  Used  to  validate  dictionary  save  file  ) 

RandMult  =  16807;  (  *7**5;  RandMult  must  be  expressable  in  16  bits. 

48271  may  give  better  "randomness"  (see  ACM  ref.)  } 

ShuffleBits  =  3; 

ShuffleShift  =  16  -  ShuffleBits; 

ShufTableEnd  =  $FFFF  Shr  ShuffleShift; 

HashSeed  :  Word  =  26;  (  Initial  hash  seed  ) 

RandSeed  :  Longlnt  =  1;  (  Random  number  seed:  0  <  RandSeed  <  2**31-1  ) 

Type 

SaveFileHeader  =  Record 

(  Header  for  dictionary  save  file  (all  numbers  are  byte-reversed)  ) 

Magic  :  Longlnt;  (  Magic  number  for  validity  test  } 

BitsCount  :  Longlnt;  (  Bits-per-key  and  entry  count  } 

Size  :  Word;  {  Size  of  dictionary  bit  map  in  bytes  ) 

End; 

Var 

ShufTable  :  Array(0. .ShufTableEnd]  Of  Longlnt; 

NextOut  :  Word; 

Function  IRand  :  Longlnt; 

(  Return  next  "minimal  standard",  31  bit  pseudo-random  integer.  This  function 
actually  computes  (RandSeed  *  RandMult)  Mod  (2**31-1)  where  RandMult  is 
a  16  bit  quantity  and  RandSeed  is  32  bits  (See  Carta,  CACM  1/90) .  } 

Inline ( 

$Al/>RandSeed+2/  (  mov  ax, [>RandSeed+2] } 

$BF/>RandMult/  (  mov  di, >RandMult ) 

$F7/$E7/  (  mul  di) 

$89/$C3/  {  mov  bx,ax) 

$89/$Dl/  {  mov  cx,dx) 

$Al/>RandSeed/  {  mov  ax, [>RandSeed] } 

$F7/$E7/  (  mul  di) 

$01/$DA/  (  add  dx,bx) 

$83/$Dl/$00/  {  adc  cx,  0  ;  cx:dx:ax  =  Seed  *  Mult  ) 

$D0/$E6/  {  shl  dh,l  ;  split  p  &  q  at  31  bits  } 

$D1/$D1/  {  rcl  cx, 1 } 

$D0/$EE/  {  shr  dh,l  ;  cx  =  p,  dx:ax  =  q  } 

$01/$C8/  (  add  ax,cx) 

$83/$D2/$00/  (  adc  dx,0  ;  dx:ax  =  p  +  q  } 

$71/$09/  (  jno  done] 

$05/501/500/  (  add  ax, 1  ;  overflow,  inc(p  +  q)  } 

583/5D2/500/  {  adc  dx,0) 


$80/$E6/$7F/ 

( 

(done: } 

and 

dh,$7F  ;  limit  to  31  bits 

$A3/>RandSeed/ 

{ 

mov 

[>RandSeed] ,  ax} 

$89/$16/>RandSeed+2) ; 

{ 

mov 

[>RandSeed+2] , dx) 

Function  Hash (Seed  :  Longlnt;  Var  Data;  Len  :  Word)  :  Longlnt; 

{  Hash  a  block  of  data  into  a  random  long  integer.  This  is  actually 
equivalent  to  the  following: 

RandSeed  :=  Seed; 

Hash  :=  0; 

For  i  :=  1  To  Len  Do  Hash  :=  Hash  +  (IRand  *  (Datafi]  +  5FF00) ; 
Hash  :=  Hash  AND  57FFFFFFF; 

If  Hash  =  0  Then  Inc (Hash); 


Overflow  is  ignored.  The  seed  is  kept  in  registers;  RandSeed. is  not 
affected  by  this  routine.  ) 


Inline ( 

$59/ 

( 

pop 

cx 

;  cx  :=  len) 

$5E/ 

( 

pop 

si 

;  bx:si  :=  @data) 

$5B/ 

( 

pop 

bx] 

$58/ 

{ 

pop 

ax 

;  dx:ax  :=  seed) 

$5A/ 

{ 

pop 

dx] 

$E3/ $59/ 

< 

jcxz 

alldone 

) 

$FC/ 

$1E/ 

{ 

( 

eld] 

push 

ds } 

58E/5DB/ 

{ 

mov 

ds,bx] 

$55/ 

{ 

push 

bp] 

$31/$DB/ 

{ 

xor 

bx,bx] 

$53/ 

( 

push 

bx 

;  zero  accumulator) 

$53/ 

{ 

push 

bx] 

$89/$E5/ 

{ 

mov 

bp,sp] 

$51/ 

[next: 

{ 

push 

cx] 

;  for  each  byte  of  data.. 

$BF/>RandMult/ 

1 

mov 

di,>RandMult] 

$89/$C3/ 

{ 

mov 

bx,ax) 

$89/$D0/ 

{ 

mov 

ax,dx 

;  compute  next  seed)  , 

$F7/$E7/ 

{ 

mul 

di] 

$93/ 

{ 

xchg 

ax,bx] 

$89/ $D1 / 

< 

mov 

cx,dx) 

$F7/$E7/ 

{ 

mul 

di] 

$01/$DA/ 

{ 

add 

dx,bx] 

$83/$Dl/$00/ 

{ 

adc 

cx,  0 

;  cx:dx:ax  =  Seed  *  Mult) 

$D0/$E6/ 

{ 

shl 

dh,  1 

;  split  p  &  q  at  31  bits] 

$D1/$D1/ 

{ 

rcl 

cx,l) 

$D0/$EE/ 

{ 

shr 

dh,  1 

;  cx  =  p,  dx:ax  =  q) 

$01/ $C8/ 

< 

add 

ax,cx] 

$83/$D2/$00/ 

{ 

adc 

dx,0 

;  dx:ax  =  p  +  q) 

$71/509/ 

{ 

jno 

noovfl) 

$05/501/500/ 

{ 

add 

ax,  1 

;  overflow,  inc(p  +  q) } 

$83/$D2/$00/ 

{ 

adc 

dx,0) 

$80/$E6/$7F/ 

{ 

and 

dh, $7F 

;  limit  to  31  bits) 

$89/ $C3/ 

(noovfl: } 

{  mov 

bx,ax 

;  save  seed) 

$89/ $D1/ 

{ 

mov 

cx,dx) 

$AC/ 

{ 

lodsb 

;  get  next  byte  +  $FF00) 

$B4/$FF/ 

{ 

mov 

ah, $FF) 

$89/$C7/ 

{ 

mov 

di,ax) 

$F7/$E1/ 

{ 

mul 

cx 

;  multiply  by  seed) 

$97/ 

{ 

xchg 

ax,di) 

$F7/$E3/ 

{ 

mul 

bx) 

$01/$FA/ 

{ 

add 

dx,di) 

$01/$46/$00/ 

{ 

add 

[bp+0] ,. 

ax  ;  accumulate) 

$ll/$56/$02/ 

{ 

adc 

[bp+2] , dx) 

$89/$D8/ 

{ 

mov 

ax,bx) 

$89/$CA/ 

( 

mov 

dx,cx) 

$59/ 

[ 

pop 

cx) 

$E2/$B9/ 

{ 

loop 

next 

;  until  out  of  data) 

$58/ 

[  i  i 
{ 

pop 

ax) 

$5A/ 

( 

pop 

dx) 

$5D/ 

< 

pop 

bp) 

$1F/ 

{ 

pop 

ds) 

$80/$E6/$7F/ 

{ 

and 

dh, $7F) 

$89/ $C3/ 

[alldone: } 

(  mov 

bx,ax) 

$09/$D3/ 

{ 

or 

bx,dx) 

$75/ $01/ 

{ 

jnz 

exit } 

$40); 

{ 

inc 

ax) 

(exit : 

1 

Procedure  Shuffle; 

(  Load  the  shuffle  table  } 

Begin 

For  NextOut  :=  0  To  ShufTableEnd  Do  ShufTable [NextOut]  :=  IRand; 

NextOut  :=  Word (IRand)  Shr  ShuffleShift; 

End; 

Function  SIRand  :  Longlnt; 

(  Return  the  next  shuffled  random  number  ) 

Var 

y  :  Longlnt; 

Begin 

y  :=  ShufTable (NextOut ] ; 

ShufTable [NextOut]  :=  IRand; 

NextOut  :=  Word(y)  Shr  ShuffleShift; 

SIRand  :=  y; 

End; 

Function  TestBit (Var  BitArray;  Size  :  Word;  BitNo  :  Longlnt)  :  Boolean; 

{  Returns  TRUE  if  indicated  bit  number,  modulo  size  of  bit  array,  is  set. 

Size  is  in  bytes.  ) 

Inline ( 

{;  dx:ax  :=  BitNo] 

$58/  (  pop  ax] 

$5A/  {  pop  dx] 

[;  bl  :=  bit  mask] 

$88/ $C1/  {  mov  cl, al] 

$80/$El/$07/  [  and  cl, $07) 

$B3/$80/  {  mov  bl , $80 } 

$D2/$EB/  {  shr  bl,cl] 


no 
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(;  dx:ax  :=  byte  offset) 


$D1/$EA/ 

(  shr 

dx,  1 ) 

SD1/SD8/ 

{  rcr 

ax,  1 ) 

SDl/SEA/ 

{  shr 

dx,  1 ) 

$D1/$D8/ 

{  rcr 

ax,  1 ) 

$D1/$EA/ 

{  shr 

dx,  1 ) 

$D1/$D8/ 

{  rcr 

ax,  1 ) 

{ ;  dx  :=  byte 

offset) 

$5F/ 

(  pop 

di) 

$39/ $D7 / 

{  cmp 

di,dx) 

$77/$0E/ 

{  ja 

quickdiv) 

{;  protect  against  overflow) 

$89/ $F9/ 

{  mov 

(protloop: ) 

cx,di) 

$D1/$E1/ 

{  shl 

cx,l) 

$39/$Dl/ 

{  cmp 

cx, dx) 

$76/$FA/ 

i  jbe 

protloop) 

$F7/$F1/ 

(  div 

cx) 

$  8  9/ $D0 / 

{  mov 

ax, dx) 

$31/ $D2 / 

{  xor 

(quickdiv: ) 

dx,dx) 

$F7/$F7/ 

(  div 

di) 

{;  es:di  :=  seg:ofs  of  byte) 

$5F/ 

1  pop 

di) 

$01/ $D7 / 

{  add 

di,dx) 

$07/ 

{  pop 

(;  test  bit) 

es) 

$30/$C0/ 

{  xor 

al,al) 

$26/ $22/$lD/ 

{  es:and 

bl, (di] } 

$74/$02/ 

{  jz 

notset) 

$FE/$C0) ; 

(  inc 

(notset: ) 

al) 

Function  SetBit(Var  BitArray;  Size  :  Word;  BitNo  :  Longlnt)  :  Boolean; 

(  Sets  the  indicated  bit  number  modulo  size  of  bit  array.  Returns  TRUE  if 


bit  was  already  set. 
Inline ( 

Size  is  in  bytes.  ) 

{;  dx:ax  BitNo) 

$58/ 

( 

pop 

ax) 

$5A/ 

( 

{; 

pop 

bl  :=  bit 

dx) 

.  mask) 

$88/ $C1/ 

( 

mov 

cl, al) 

$80/$El/$07/ 

( 

and 

cl, $07) 

$B3/ $80/ 

( 

mov 

bl, $80} 

$D2/$EB/ 

( 

(; 

shr 

dxrax  := 

bl, cl ) 

byte  offset) 

$D1/$EA/ 

( 

shr 

dx,  1 } 

$D1/$D8/ 

( 

rcr 

ax,  1 } 

$D1/$EA/ 

{ 

shr 

dx,  1 } 

$D1/$D8/ 

{ 

rcr 

ax,  1 } 

$D1/$EA/ 

( 

shr 

dx,  1 ) 

$D1/$D8/ 

{ 

{; 

rcr  ax,l) 

dx  :=*  byte  offset  mod 

$5F/ 

1  pop 

di) 

$39/$D7/ 

{  cmp 

di,dx) 

$77/$0E/ 

i  ja 

quickdiv) 

{;  protect  against  overflow) 

$89/$F9/ 

{  mov 

(protloop: ) 

cx,di) 

$D1/$E1/ 

(  shl 

cx,  1 } 

$39/ $D1 / 

(  cmp 

cx,dx) 

$76/$FA/ 

1  jbe 

protloop) 

$F7 / $F1/ 

(  div 

cx) 

$89/$D0/ 

(  mov 

ax, dx) 

$31 / $D2/ 

{  xor 

(quickdiv: ) 

dx, dx) 

$F7/$F7/ 

{  div 

di) 

{;  es:di  :=  seg:ofs  of  byte) 

$5F  / 

(  pop 

di) 

$01/$D7/ 

(  add 

di, dx) 

$07/ 

{  pop 

(;  test  bit) 

es) 

$30/$C0/ 

(  xor 

al, al ) 

$88/$DC/ 

(  mov 

ah, bl } 

$26/$22/$25/ 

{  es:and 

ah, [di] ) 

$74/$04/ 

(  jz 

notset ) 

$FE/$C0/ 

{  inc 

al) 

$EB/$03/ 

i  jn>P 

(notset: ) 

short  set) 

$26/$08/$lD) ; 

(  es:or 

(set: ) 

[di] , bl ) 

Function  LongSwap(n 

:  Longlnt)  :  Longlnt; 

(  Reverse  bytes  in  a 
Inline ( 

Longlnt.  ) 

$5A/ 

(  pop 

dx) 

$58/ 

{  pop 

ax) 

$86/ $C4/ 

(  xchg 

ah,al) 

$86/$D6) ; 

(  xchg 

dh, dl ) 

Function  DictionaryBytes (MaxKeys  :  Longlnt;  BitsPerKey  :  Byte)  :  Longlnt; 
Begin 

DictionaryBytes  :=  Round (MaxKeys  *  BitsPerKey  /  (-Ln(0.5)  *  8)); 

End; 

Function  DictHash(Var  Data;  Len  :  Word)  :  Longlnt; 

Begin 

DictHash  :=  Hash (Hash (HashSeed,  Data,  Len),  Data,  Len); 

End; 

Constructor  Dictionary. Init (MaxKeys  :  Word;  BitsPerKey  :  Byte); 

Var 

DictBytes  :  Longlnt; 

Begin 

DictBytes  :=  DictionaryBytes (MaxKeys,  BitsPerKey); 

(continued  on  page  1 12) 
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Listing  One  (Listing  continued,  text  begins  on  page  20.) 

If  DictBytes  >  $FFF0  Then  Begin 

WriteLn (DictBytes,  '  bytes  optimal  for  dictionary,  but  ',  $FFF0, 

'  is  maximum  size  dictionary.  Using  max  size.'); 

DictBytes  :=  $FFF0; 

End  Else  If  DictBytes  >  MaxAvail  Then  Begin 

WriteLn (DictBytes,  '  bytes  optimal  for  dictionary,  but  only  ',  MaxAvail, 
'  bytes  are  available.  Using  ',  MaxAvail); 

DictBytes  :=  MaxAvail; 

End  Else  If  DictBytes  <  16  Then  DictBytes  :=  16; 

DictSize  :=  DictBytes; 

GetMem(DictArray,  DictSize); 

FillChar (DictArrayA,  DictSize,  0) ; 

DictCount  :=  0; 

DictBits  :=  BitsPerKey; 

End; 

Constructor  Dictionary . RestoreDictionary (FileName  :  String); 

Var 

Header  :  SaveFileHeader; 

DictBytes  :  Longlnt; 
f  :  File; 

OldMode  :  Byte; 

Begin 

OldMode  :=  FileMode; 

FileMode  :=  $40; 

Assign (f,  FileName); 

Reset (f,  1); 

BlockRead(f,  Header,  SizeOf (Header) ) ; 

With  Header  Do  Begin 

Magic  :=  LongSwap (Magic) ; 

Size  :=  Swap (Size); 

DictBytes  :=  FileSize(f)  -  SizeOf (Header) ; 

If  (Magic  <>  MagicNumber)  Or  (Size  <>  DictBytes)  Or  (Size  <  16) 

Or  (Size  >  $FFF0)  Then  Begin 

WriteLn ('File  ',  FileName,  '  is  not  a  dictionary  save  file.'); 

Halt  (1) ; 

End; 

DictSize  :=  Size; 

DictBits  :=  BitsCount  And  $FF; 

DictCount  :=  LongSwap (BitsCount  And  $FFFFFF00); 

GetMem(DictArray,  DictSize); 

BlockRead(f,  DictArrayA,  DictSize); 

Close (f ) ; 

FileMode  :=  OldMode; 

End; 

End; 

Destructor  Dictionary. Done; 

Begin 

FreeMem (DictArray,  DictSize); 

DictArray  :=  Nil; 

DictSize  :=  0; 

DictBits  :=  0; 


DictCount  :=  0; 

End; 

Function  Dictionary .DictionarySize  :  Word; 

Begin 

DictionarySize  :=  DictSize  +  SizeOf (SaveFileHeader) ; 

End; 

Function  Dictionary . Insertstring (Var  s  :  String)  :  Boolean; 

Begin 

Insertstring  :=  InsertBlock (s [1J ,  Length (s)); 

End; 

Function  Dictionary .StringlnDictionary (Var  s  :  String)  :  Boolean; 

Begin 

StringlnDictionary  ;=  BlocklnDictionary (s [ 1 ] ,  Length(s)); 

End; 

Function  Dictionary . InsertBlock (Var  Data;  Len  :  Word)  :  Boolean; 

Begin 

InsertBlock  :=  InsertHash (DictHash (Data,  Len)); 

End; 

Function  Dictionary. BlocklnDictionary (Var  Data;  Len  :  Word)  :  Boolean; 

Begin 

BlocklnDictionary  :=  HashlnDictionary (DictHash (Data,  Len)); 

End; 

Function  Dictionary . InsertHash (Hash  :  Longlnt)  :  Boolean; 

Var 

i  :  Byte; 

InDict  :  Boolean; 

Begin 

InDict  :=  True; 

RandSeed  :=  Hash; 

Shuffle; 

For  i  :=  1  To  DictBits  Do 

If  Not  SetBit (DictArrayA,  DictSize,  SIRand)  Then  InDict  :=  False; 

If  Not  InDict  Then  Inc (DictCount) ; 

InsertHash  :=  InDict; 

End; 

Function  Dictionary .HashlnDictionary (Hash  :  Longlnt)  :  Boolean; 

Var 

i  :  Byte; 

InDict  ;  Boolean; 

Begin 

InDict  :=  True; 

RandSeed  :=  Hash; 

Shuffle; 
i  :=  0; 

While  (i  <  DictBits)  And  InDict  Do  Begin 

If  Not  TestBit (DictArrayA,  DictSize,  SIRand)  Then  InDict  :=  False; 

Inc  (i) ; 

End;  f 

HashlnDictionary  :=  InDict; 

End; 

Procedure  Dictionary. SaveDictionary (FileName  :  String); 

Var 

Header  :  SaveFileHeader; 
f  :  File; 

Begin 

Assign (f,  FileName); 

Rewrite (f,  1); 

With  Header  Do  Begin 

Magic  :=  LongSwap (MagicNumber) ; 

Size  :=  Swap (DictSize) ; 

BitsCount  :=  LongSwap (DictCount)  +  DictBits; 

End; 

BlockWrite (f ,  Header,  SizeOf (Header) ) ; 

BlockWrite (f ,  DictArrayA,  DictSize); 

Close (f) ; 

End; 

Function  Dictionary .EstError  :  Real; 

Begin 

EstError  :=  Exp (Ln (1 . 0-Exp (- (DictCount *DictBits) / (DictSize* 8 . 0) ) ) *DictBits) ; 
End; 

Function  Dictionary .ActError  :  Real; 

Var 

AllBits,  BitsOn,  i  :  Longlnt; 

Begin 

AllBits  :=  Longlnt (DictSize)  *  8; 

BitsOn  :=  0; 

For  i  :=  0  To  Pred (AllBits)  Do 

If  TestBit (DictArrayA,  DictSize,  i)  Then  Inc (BitsOn); 

ActError  :=  Exp (Ln (BitsOn  /  AllBits)  *  DictBits); 

End; 

End. 


End  Listing 


112 
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Listing  One  (Text  begins  on  page  36.) 

•ifndef  STRING_H 
•define  STRING  H 


Listing  Two 

♦include  <stream.h> 
♦include  "String. h" 


♦include  <string.h> 

♦include  <memory.h> 

♦include  <malloc.h> 

♦ifdef  NULL 
♦  undef  NULL 
♦endif 

♦define  NULL  0 

typedef  enum  (  False,  True  |  Boolean; 

//a  String  is  a  simple  implementation  of  a  C++  string  class 
class  String 
{ 

char  *s;  //  actual  pointer  to  text 

public: 

String  (void)  (  s  =  strdupC'");  } 

String (char  *c)  {  s  =  strdup(c);  ) 

String(char  *c,  int  n)  (  s  =  new  char(n+l);  memcpy (s, c, n) ;  s[n]=0;  ) 

String (String  &ss,  char  *c)  {  s  =  malloc(strlen(ss.s)+strlen(c)+l); 

strcpy (s, ss.s) ;  strcat(s,c);  ) 

String (String  &ss)  (  s  =  strdup(ss.s) ;  ) 

“String (void)  {  delete  s;  ) 

operator  char  ‘(void)  (  return  s;  ) 

Strings  operator  +(char  *c)  {  String  *a  -  new  String (‘this, c) ;  return  *a; } 

Strings  operator  +=(char  *c)  (  ‘this  =  ‘this  +  c;  return  ‘this;  ) 

Strings  operator  =(char  *c)  (  delete  s;  s  =  strdup(c);  return  ‘this;  ) 

Strings  operator  “(Strings  a) {  delete  s;  s  =  strdup(a.s);  return  ‘this;  ) 

operator  ==(char  *c)  const; 
operator  == (String  *c)  const; 

♦ifdef  DEBUG 

void  dump()  const; 

Boolean  verify ()  const; 

♦endif  /‘DEBUG*/ 

}; 


int  main  (int,  char  *()) 

{ 

String  a ("Hello  "); 

String  *b  =  new  String ("world. ") ; 
String  c; 

c  =  a  +  *b  +  "\n"; 


cout  «  "a  +  b  =  "  «  (char  *)c; 
cout  «  "a  =  "  «  (char  *)a  «  "\n"; 
cout  «  "b  =  "  «  (char  *)*b  «  "\n"; 

StringList  1(a); 

1  +=  *b; 


1 . dump ( ) ; 

} 


Listing  Three 

♦ifndef  ASSERT_HDR 
♦define  ASSERT_HDR 

♦ifdef  DEBUG 

extern  void  _assertRtn (char  *,  int); 

♦  define  assert (condition)  \ 

if  (condition)  ;  else  _assertRtn( _ FILE _ , _ LINE — 

♦else  /‘ifndef  DEBUG*/ 


//a  StringListElement  is  a  single  item  in  a  StringList 
class  StringListElement 
I 

String  s;  //  this  String  in  the  list 

StringListElement  ‘next;  //  pointer  to  next  element  in  list 
public: 

StringListElement (void)  :  next (NULL) ,  s("")  () 

StringListElement (char  *c)  :  next (NULL) ,  s(c)  {) 

StringListElement (char  *c,  int  n)  :  next (NULL) ,  s(c,n)  f) 
StringListElement (String  &ss)  :  next (NULL) ,  s(ss)  (} 

“StringListElement (void)  (  if  (next)  delete  next;  next=NULL;  ) 
friend  class  StringList; 
friend  class  StringListlterator; 

♦ifdef  DEBUG 

void  duropO  const;  # 

Boolean  verify ()  const; 

♦endif  /‘DEBUG*/ 


//  a  StringList  is  a  simple  single-linked  list  of  strings 
class  StringList 
( 

StringListElement  ‘head;  //  first  String  in  list 
StringListElement  ‘tail;  //  last  String  in  list 
public: 

StringList (void)  :  head(NULL),  tail (NULL)  () 

StringList (Strings  ss)  {  head  =  tail  =  new  StringListElement (ss) ;  ) 

StringList (char  *ss)  (  head  =  tail  =  new  StringListElement (ss) ;  } 

“StringList (void)  (  if  (head)  (  delete  head;  head=NULL;  )  ) 

Strings  find (char  *s)  const; 

void  clear (void)  {  delete  head;  head  =  tail  =  NULL;  ) 

StringListS  operator  += (StringListS  xx); 

StringListS  operator  +=(char  *ss); 

StringListS  operator  +=(StringS  ss); 

StringListS  operator  “(StringListS  xx) ; 
operator  int ( ) ; 

friend  class  StringListlterator; 

♦ifdef  DEBUG 

void  dump!)  const; 

Boolean  verify ()  const; 

♦endif  /‘DEBUG*/ 

}; 


//a  StringListlterator  is  a  method  of  traversing  a  list  of  strings 
class  StringListlterator 


//  StringList  to  be  traversed 
//  current  String  in  StringList 


const  StringList  ‘list; 

StringListElement  *nxt; 
public: 

StringListlterator (void)  :  list (NULL),  nxt (NULL)  {) 
StringListlterator (const  StringList  *1)  :  list(l),  nxt(l->head)  {} 
String  ‘next (void); 

void  reset ()  (  nxt  =  (list  !  =  NULL)  ?  list->head:  NULL;  ) 

int  anymore ()  const  (  return  (nxt  !=  NULL);  ) 

StringListlterators  operator  “(const  StringListS  ss); 

♦ifdef  DEBUG 

void  dump()  const; 

Boolean  verify ()  const; 

♦endif  /‘DEBUG*/ 

}; 

♦endif  //  STRING  H 


End  Listing  One 


♦  define  assert (condition) 
♦endif 

♦endif  /*ASSERT_HDR*/ 


Listing  Four 

♦include  <stream.h> 

♦ifdef  DEBUG 

void  _assertRtn (char  ‘file,  int  line) 

1 

cerr  «  "\nAssertion  Failure  in  file  ' "  «  file 

«  line  "  «  line  «  "\n" 
line  =  0;  line  /=  line;  //  force  core  dump 

) 

♦endif 


Listing  Five 

♦include  "String. h" 

♦include  "Assert. h" 

♦ifdef  DEBUG 
♦  include  <stream.h> 

♦endif 

/“*“  String  class  ******/ 

//  String  comparison  operator 
String: : operator  ==(char  *c)  const 
{ 

assert (this->verify ( ) ) ; 

//  compare  String  to  char  array 
return  strcmp(s,c)  ==  0; 

} 

//  String  comparison  operator 
String: : operator  ““(String  *c)  const 
( 

assert (this->verify () ) ; 

//  compare  String  to  String 
return  strcmp (s, (char  * ) c )  ==  0; 

} 

♦ifdef  DEBUG 

void  String: : dump (void)  const 

I 

assert (this->verify () ) ; 

cerr  «  "String (\""  «  s  <<  "\")"; 

} 

Boolean  String: :verify (void)  const 

{ 

//  Strings  must  always  point  to  something, 
if  (s  ==  NULL)  return  False; 
return  True; 

) 


End  Listing  Two 


End  Listing  Three 


End  Listing  Four 
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#endif 


/******  StringList  class  (and  StringListElement)  ******/ 
StringListS  StringList : :operator  += (Strings  ss) 

{ 

assert (this->verify () ) ; 
if  (tail) 

{ 

tail->next  =  new  StringListElement (ss) ; 
tail  =  tail->next; 


else 

head  =  tail  =  new  StringListElement (ss) ; 
return  *this; 

) 

StringListS  StringList :  .’operator  +=(char  *ss) 

( 

assert (this->verify () ) ; 
if  (tail) 

( 

tail->next  =  new  StringListElement (ss) ; 
tail  =  tail->next; 

} 

else 

head  =  tail  =  new  StringListElement (ss) ; 
return  ‘this; 

> 

StringListS  StringList: : operator  += (StringListS  xx) 

{ 

assert (this->verify () ) ; 

//  add  new  list  to  old  list  item  by  item 

for  (StringListElement  *le=xx.head;  le;  le=le->next) 

*this  +=  le->s; 
return  *this; 

) 

//  StringList  assignment  operator  (performs  deep  copy) 

StringListS  StringList: : operator  = (StringListS  xx) 

( 

assert (this->verify () ) ; 

//  get  rid  of  old  list 
clear () ; 

//  add  new  list  to  (clear)  old  list  item  by  item 
for  (StringListElement  *le=xx.head;  le;  le=le->next) 

*this  +=  le->s? 

//  return  new  copy  of  old  list 
return  ‘this; 

} 

//  (int) (StringList)  cast  returns  number  of  strings  in  list 
StringList: : operator  int() 

{ 

int  count  =  0; 

StringListlterator  11 (this); 

assert (this->verify () ) ; 
while  ( 11. next ()  !=  NULL) 
count++; 
return  count; 

} 

#ifdef  DEBUG 

// 

//  dump()  -  display  instance  in  format  "StringList (...) " 

// 

void  StringList : :dump (void)  const 

{ 

//  check  consistancy 
assert (this->verify {) ) ; 

//  print  header 
cerr  «  "StringList ("; 

//  use  StringListElement: : dump ()  to  recursively  display  all  members 
if  (head  !=  NULL)  head->dump () ; 

//  print  trailer 
cerr  «  ")\n"; 

} 

Boolean  StringList :: verify (void)  const 

{ 

//  if  there  are  elements  in  this  list,  ensure  they  are  valid. 

//  (note  that  head->verify ()  ensures  the  entire  list  is  valid.) 
if  ( (head!=NULL)  &&  ! head->verify () )  return  False; 

//  Both  the  head  and  tail  must  either  be  null  or  non-null, 
if  ( (head!=NULL)  &&  (tail==NULL) )  return  False; 
if  ( (head==NULL)  &&  (tail ! =NULL) )  return  False; 

return  True; 

) 

fendif  /*DEBUG*/ 
fifdef  DEBUG 

void  StringListElement :: dump (void)  const 

{ 

assert (this->verify () ) ; 
s . dump ( ) ; 
if  (next  ! =  NULL) 

{ 

cerr  «  ' , ' ; 
next->dump() ; 

) 

) 

Boolean  StringListElement :: verify (void)  const 

( 

//An  element  of  a  list  of  Strings  must  point  to  a  valid  String, 
if  ((char  *)  (s)  ==  NULL)  return  False; 
if  (!s. verify () )  return  False; 

//If  there  is  another  element  within  this  list,  it  must  be  valid, 
if  ( (next ! =NULL)  &&  ! next->verify () )  return  False; 

return  True; 

} 

#endif 

/******  StringListlterator  class  ******/ 


//  assignment  operator 

StringListlteratorS  StringListlterator : :operator  =(const  StringListS  ss) 
{ 

assert (this->verif y ( ) ) ; 
list  =  &ss; 
nxt  =  ss.head; 
return  ‘this; 

) 

//  get  next  item  in  list  of  strings  pointed  to  by  iterator 
String  ‘StringListlterator: :next (void) 

{ 


assert (this->verif y ( ) ) ; 
if  (list  ==  NULL)  return  NULL; 
if  (nxt  ==  NULL)  return  NULL; 
String  *aa  =  & (nxt->s) ; 
nxt  =  nxt->next; 
return  aa; 

) 

#ifdef  DEBUG 

Boolean  StringListlterator: :verify 


//  no  StringList,  so  no  next  item 
//  at  end  of  list,  so  no  next  item 
//  save  pointer  to  String 
//  point  to  next  item  in  list 
//  return  pointer  to  String 


const 


//  if  there  is  a  list  available,  verify  it. 
if  ( ! list->verify () )  return  False; 


//  if  we  haven't  reached  the  end  of  the  list, 

//  verify  the  next  element 

if  (nxt  !=  NULL  &&  ! nxt->verify ( ) )  return  False; 


//  everything  appears  correct 
return  True; 

#endif  /‘debug*/  End  Listing  Five 


Listing  Six 

cc  -  cc 

CFLAGS  =  -DDEBUG 


prog  :  main.o  String. o  lib.o 

$ (CC)  main.o  String. o  lib.o  -o  prog 

String. o  :  String. C  String. h 
$(CC)  -c  $ (CFLAGS)  String. C 

main.o  :  main.C  String. h 

$(CC)  -c  $ (CFLAGS)  main.C 


lib.o  :  lib.C 

$(CC)  -c  $ (CFLAGS)  lib.C 

clean  : 

rm  -f  *.o  a. out  core 


clobber  :  clean 
rm  -f  prog 


End  Listings 
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Listing  One  (Text  begins  on  page  44.) 

/**  CTrace.h  —  Definitions  for  using  the  Trace  class  “/ 
♦define  H_CTrace 


/*  System/library  header  files 
♦include  <Commands . h> 

♦include  <oops.h> 

♦include  <stdarg.h> 

♦include  <CDesktop.h> 

♦include  <CBartender .h> 
♦include  <CDataFile.h> 

♦include  <CApplication.h> 
♦include  <CDocument . h> 

♦include  <Constants.h> 


*/ 

/*  standard  menu  command  definition  */ 

/*  standard  OOP  definitions  */ 

/*  varg  macro  definitions  */ 

/*  definitions  for  desktop  class  */ 

/*  definitions  for  menu  bar  manager  */ 

/*  definitions  for  data  file  class  */ 

/*  definitions  for  the  application  class  */ 
/*  definitions  for  parent  class  */ 

/*  miscellaneous  environment  constants  */ 


/*  Local  header  files  */ 

♦include  "CLogPanorama.h"  /*  definitions  for  logging  panorama  class  */ 


/*  Resource  numbers  */ 

♦define  TRACE_MENU_ID  (2000) 

♦define  TRACE_MENU_SHOW  (2000L) 

♦define  TRACE_MENU_MASK  (2001L) 

♦define  TRACE_WINDOW_ID  (2000) 

♦define  TRACE_MASK_DIALOG  (2000) 

♦define  FIRST_MASK  (3) 

♦define  LAST_MASK  (34) 

♦define  UNH I L I TE_CONTROL  (255) 

♦define  OKAY_BUTTON_ITEM  (1) 


♦define  CANCEL_BUTTON_ITEM  (2) 


/*  menu  resource  ID  */ 

/*  menu  command  for  show/hide  log  */ 

/*  menu  command  for  log  masking  */ 

/*  main  window  resource  ID  */ 

/*  resource  ID  for  dialog  box  */ 

/*  item  ♦  of  first  checkbox  in  dialog  */ 
/*  item  ♦  of  last  checkbox  in  dialog  */ 
/*  magic  part  ♦  for  disabling  control  */ 
/*  item  ♦  for  the  'okay'  button  */ 

/*  item  ♦  for  the  'cancel'  button  */ 


/*  Standard  trace  categories  */ 
♦define  T_ERROR  (0x00000001) 

♦define  T_WARNING  (0x00000002) 

♦define  T_INFO  (0x00000004) 

♦define  T_FUNC_IN  (0x00000008) 

♦define  T_FUNC_0UT  (0x00000010) 


/*  serious  error  */ 

/*  mildly  serious  problem  */ 
/*  news  you  can  use  */ 

/*  function  entry  */ 

/*  function  exit  */ 


/*  Other  constants  */ 

♦define  MAX_USER_BUFF  (MAX_LOGREC_CHAR-19+l)  /*  max  length  of  user  message  */ 
♦define  TRACE_DEFAULT_MASK  (0L)  /*  initial  trace  mask  */ 


/*  External  references  */ 
extern  CDesktop  ‘gDesktop; 

extern  CApplication  ‘gApplication; 

extern  CBartender  ‘gBartender; 

extern  OSType  gSignature; 

struct  CTrace  :  CDocument 


/*  the  whole  desktop  view  */ 
/*  the  application  object  */ 
/*  the  menu  bar  object  */ 

/*  application  signature  */ 


( 

/*  local  instance  variables  */ 

CLogPanorama  *itsLogPanorama;  /*  panorama  for  trace  messages  */ 

unsigned  long  currMask;  /*  currently  enabled  trace  categories  */ 

/*  local  class  methods  */ 

void  ITrace (short  records); 

void  ToggleTraceWindow (void) ; 

void  SetTraceMask  (void) ; 

void  Trace  (unsigned  long  mask,  char  ‘format,  ...)• 

Boolean  IsItVisible (void) ; 

/*  inherited  methods  overriden  */ 
void  UpdateMenus  (void) ; 

Boolean  DoSaveAs  (SFReply  ‘macSFReply) ; 

Boolean  Close  (Boolean  quitting) ; 

}; 


End  Listing  One 


Listing  Two 

/“  CTrace. c  —  Methods  for  the  trace  document  class.  **/ 

♦include  "CTrace.h"  /*  trace  class  parameters  */ 

/**  Global  declaration  “/ 

CTrace 

‘gTrace;  /*  the  one  instance  of  this  class  */ 

/**  ITrace {)  —  Initializes  trace  document  object.  **/ 
void  CTrace: : ITrace 
( 

short  records  /*  number  of  records  before  wrap  */ 

) 


Rect 

frameRect;  /*  window  frame  */ 

CDocument :: IDocument  (gApplication,  TRUE); 
itsWindow  =  new  (CWindow) ; 

itsWindow->IWindow  (TRACE_WINDOW_ID,  FALSE,  gDesktop,  this); 
itsWindow->GetFrame  (&frameRect) ; 

itsWindow->Move  (gDesktop->bounds . right  -  frameRect . right  -  R I GHT_SMARG I N , 
gDesktop->bounds.top  +  TOP_SMARGIN) ; 
itsLogPanorama  =  new  (CLogPanorama) ; 
itsLogPanorama->ILogPane  (records,  this,  itsWindow); 
itsMainPane  =  itsLogPanorama; 
currMask  =  TRACE_DEFAULT_MASK; 
gTrace  =  this; 

I 


/**  ToggleTraceWindow ( )  --  Toggles  visibility  of  trace  window.  **/ 
void  CTrace: : ToggleTraceWindow (void) 

{ 

if  (itsWindow->visible) 

itsWindow->Hide  (); 

else 

I 

itsWindow->Show  (); 
itsWindow->Select  (); 


/**  Close ()  —  Overrides  normal  document  method  by  closing  trace  window.  **/ 
Boolean  CTrace : :Close 
( 


Boolean  quitting  /*  ignored  */ 

) 

( 

itsWindow->Hide  (); 
return  (TRUE); 

} 


/“  SetTraceMask  —  Allows  user  to  set/clear  defined  trace  masks.**/ 
void  CTrace:  .-SetTraceMask  (void) 

{ 

int 


bitNum, 

/* 

bit  number  within  the  trace  mask  */ 

checkBoxState, 

/* 

state  of  a  checkbox  (0=unset, l=set)  */ 

item, 

/* 

loop  counter  */ 

itemType, 

/* 

item  type  (4=button,  5=checkbox)  */ 

whichltem; 

/* 

item  number  selected  by  user  */ 

Handle 

itemStuff; 

/* 

handle  to  dialog  item  parameters  */ 

Boolean 

done; 

/* 

loop-termination  flag  */ 

Str255 

title; 

/* 

text  associated  with  a  dialog  item  */ 

Rect 

itemRect ; 

DialogPtr 

/* 

rectangle  surrounding  a  control  */ 

maskDialog; 

/* 

structure  for  dialog  box  */ 

/*  Pull  up  the  mask  dialog  box  out  of  the  resource  fork  */ 
maskDialog  =  GetNewDialog  ( TRACE_MASK_D I ALOG ,  NULL,  (Ptr) (-1) ) ; 

/*  Run  through  checkboxes  */ 
for  (item=FIRST_MASK,  bitNum=0; 

item<=LAST_MASK;  item++, 
bitNum++) 

{ 

GetDItem  (maskDialog,  item,  SitemType,  &itemStuff,  SitemRect); 
GetCTitle  (  (ControlHandle) itemStuff ,  title); 

PtoCstr  ( (char*) title) ; 

if  (strcmp( (char*) title,  "Undefined")'!3  0) 

{ 

checkBoxState  =  ( (currMasxS  (lL«bitNum) )  ==  0L)  ?  0  :  1; 
SetCtlValue  (  (ControlHandle)  itemStuff,  checkBoxState) ; 

) 

else 

HiliteControl  (itemStuff,  UNHILITE  CONTROL); 

) 

/*  The  default  button  (^l)  is  the  oxay  button,  draw  outline  around  it.  */ 
GetDItem  (maskDialog,  OKAY_BUTTON_ITEM,  SitemType,  iitemStuff,  SitemRect); 
SetPort  (maskDialog) ; 

PenSize  (3,  3); 

InsetRect  (SitemRect,  -4,  -4); 

FrameRoundRect  (fiitemRect,  16,  16); 

/*  Get  events  from  dialog  manager  and  process  accordingly  */ 
done  =  FALSE; 
while  (!done) 

( 

ModalDialog  (NULL,  fiwhichltem) ; 

GetDItem  (maskDialog,  whichltem,  SitemType,  SitemStuff,  SitemRect); 
switch  (itemType) 

{ 

case  ctrlltem  +  btnCtrl  :  /*  CANCEL  or  OKAY  */ 

if  (whichltem  ==  OKAY  BUTTON  ITEM) 

{ 

currMask  =  0L; 

for  (item=FIRST_MASK,  bitNum=0;  item<=LAST_MASK;  item++,  bitNum++) 

( 

GetDItem  (maskDialog,  item,  SitemType,  SitemStuff,  SitemRect); 
checkBoxState  =  GetCtlValue  (  (ControlHandle)  itemStuff); 
currMask  :=  (checkBoxState==0)  ?  0L  :  (lL«bitNum)  ; 

) 

done  =  TRUE; 

} 

else  if  (whichltem  ==  CANCE L_BUTTON_I TEM ) 

done  =  TRUE; 

break; 

case  ctrlltem  +  chkCtrl  :  /*  a  category  checkbox  */ 

checkBoxState  =  GetCtlValue  (  (ControlHandle)  itemStuff); 

if  (checkBoxState  ==  0) 

SetCtlValue  (  (ControlHandle)  itemStuff,  1); 
else 

SetCtlValue  (  (ControlHandle)  itemStuff,  0); 
break; 

default : 

break; 


/*  On  exit,  trash  dialog  record  and  controls  */ 
DisposDialog  (maskDialog) ; 


/**  Trace ()  —  Checks  current  mask 
void  CTrace: : Trace 


unsigned  long  mask, 
char  ‘format, 


) 


/*  severity  of  message  */ 

/*  format  for  user's  arguments  */ 
/*  arguments  to  format  (varg)  */ 


/*  string  that  will  be  added  to  log  */ 
/*  user's  contribution  to  log  record  */ 
/*  date+time  string  */ 


{ 

static  char 

traceBuf f [ MAX_LOGREC_C H AR ] , 
userBuf f [MAX_LOGREC_CHAR*2] , 
prefix[40]  ; 
int 

maxUserBuff;  /*  maximum  length  of  formatted  user  string  */ 

long 

timeSecs;  /*  current  time /date  */ 

DateTimeRec 

dateRec;  /*  time/date  in  MM/DD/YY  HH:MM:SS  components  */ 

/*  Should  the  message  get  added  to  the  trace  log?  */ 
if  (  (currMask  &  mask)  !=  0) 

1 

/*  format  the  user's  portion  of  the  message  */ 
vsprintf  (userBuff,  format,  _ va (format)); 

(continued  on  page  118) 
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Listing  Two  (Listing  continued,  text  begins  on  page  44.) 

/*  make  sure  the  entire  record  will  fit  into  traceBuff  */ 
if  (strlen  (userBuff)  >  MAX_USER_BUFF) 
userBuf f [MAX_USER_BUFF]  =  NULL; 

/*  build  log  message  and  add  it  to  the  log  */ 

GetDateTime  (&timeSecs); 

Secs2Date  (timeSecs,  SdateRec) ; 

sprintf  (traceBuff,  "%02d/%02d/%02d— %02d: %02d: %02d  %s", 

dateRec .month,  dateRec.day,  dateRec. year-1900, 
dateRec .hour,  dateRec. minute,  dateRec. second, 
userBuff) ; 

itsLogPanorama->AddString  (traceBuff) ; 


/**  IsItVisible ()  —  Returns  'visible'  flag  to  update  menu  bar  entries.  **/ 
Boolean  CTrace: : IsItVisible (void) 

{ 

return  (itsWindow->visible) ; 


/**  UpdateMenus ( )  —  Disables  Save  and  Revert  entries  **/ 
void  CTrace: : UpdateMenus (void) 

{ 

inherited: : UpdateMenus  ();; 
gBartender->DisableCmd  (cmdSave) ; 
gBartender->DisableCmd  (cmdRevert) ; 


/**  DoSaveAsO  —  Writes  out  contents  of  itsLogList  to  indicated  file.  **/ 
Boolean  CTrace: :DoSaveAs 


short 


SFReply  *macSFReply 
) 


logRecBuf f [ MAX_LOGREC_C H AR ] ; 


/*  the  user's  choice  of  file  */ 


/*  buffer  for  log  entry  */ 


number  of  records  in  LogList  */ 
byte  offset  to  end  of  log  entry 
loop  counter  */ 


maxRec, 
offsetToNull, 
rec; 

/*  Dispose  of  the  data  used  for  the  old  file  record 
if  (itsFile  !=  NULL) 

itsFile->Dispose  (); 

/*  Set  up  the  new  data  file  (no  error  checking!)  */ 
itsFile  =  new  (CDataFile) ; 

( (CDataFile  *) itsFile) ->IDataFile  (); 
itsFile->SFSpecify  (macSFReply) ; 
itsFile->CreateNew  (gSignature,  'TEXT'); 
itsFile->Open  (fsRdWrPerm) ; 

/*  Write  out  all  records  in  list  (add  carriage  return  to  end  of  each  line).*/ 
maxRec  =  (short) (itsLogPanorama->itsLogList) ->GetNumItems () ; 
for  (rec=l;  rec<=maxRec;  rec++) 

( 

(itsLogPanorama->itsLogList) ->GetString  (rec,  logRecBuff); 
offsetToNull  =  strlen  (logRecBuff); 
logRecBuf f [of fsetToNull]  =  '\r'; 

( (CDataFile*) itsFile) ->WriteSome  (logRecBuff,  offsetToNull+1) ; 

} 

return  (TRUE); 


End  Listing  Two 


Listing  Three 

/**  CLogPanarama.h  —  Definitions  for  using  the  LogPanorama  class  **/ 
♦define  _H_CLogPanorama 

/*  System/library  headers  */ 

♦include  <CPanorama .h>  / 

♦include  <CScrollPane.h>  / 

♦include  <CWindow.h>  / 

♦include  coops. h>  / 

♦include  <Constants.h>  / 

♦include  <Limits.h>  / 


definitions  for  superclass  Panorama  */ 
definitions  for  ScrollPane  class  */ 
definitions  for  Window  class  */ 
standard  OOP  definitions  */ 
miscellaneous  look-n-feel  paramaters  */ 
numeric  extrema  */ 


/*  Local  headers  */ 

♦include  "CLogList.h" 

♦define  LOGPANEJWT  (monaco) 
♦define  LOGP ANE_F ONT_S I Z E  (9) 

♦define  LOGPANE_HORZ_SCROLL  (5) 

♦define  LOGPANE_VERT_SCROLL  (1) 

♦define  LOGPANE_INSET  (4) 

/*  Externals  referenced  */ 
extern  RgnHandle 
gUtilRgn; 

struct  CLogPanorama  :  CPanorama 


/*  definitions  for  LogList  class  */ 

/*  font  family  of  text  in  the  log  window 
/*  size  of  text  in  the  log  window  */ 

/*  units  per  horizontal  scroll  */ 

/*  units  per  vertical  scroll  */ 

/*  left  margin  for  start  of  text  */ 


/*  drawing  region  */ 


/*  local  class  instance  data  */ 
CLogList  *itsLogList; 

/*  local  class  methods  */ 
void  ILogPane  (short  records, 


/*  the  buffer  for  logged  data  */ 


CBureaucrat  *aSupervisor, 

CWindow  *anEnclosure) ; 

void  AddString  (char  *theString) ; 

/*  inherited  methods  overriden  */ 
void  Draw  (Rect  *theRect) ; 

); 


End  Listing  Three 


Listing  Four 


/**  CLogPanorama. c  —  Methods  for  a  CLogPanorama  class  object.  **/ 

♦include  "CLogPanorama. h"  /*  defines  log  class  */ 

/**  ILogPanorama  —  Initializes  an  instance  of  the  log  panorama  class.  **/ 


number  of  records  in  LogList  */ 
in-charge  for  this  panorama  */ 
window  object  to  place  pane  into  */ 


/*  paramaters  of  selected  font  */ 

/*  pixels  per  line  */ 

/*  pixels  per  widest  character  */ 

/*  maximum  growth  of  log  window  */ 

/*  inside  margins  of  viewable  area  */ 

/*  pane  associated  with  panorama  */ 


void  CLogPanorama: : ILogPane 
( 

short  records, 

CBureaucrat  *aSupervisor, 

CWindow  *aWindow 
) 

{ 

Fontlnfo 

fontParms; 

short 

lineSpace, 
charSpace; 

Rect 

maxWindowRect , 
marginRect; 

CSc roll Pane 

*theScrollPane; 

/*  Set  drawing  parameters  and  adjust  record  size,  if  necessary.  **/ 
aWindow->Prepare  (); 

TextFont  ( LOGP ANE_FONT ) ; 

TextSize  ( LOGP ANE_FONT_S I ZE ) ; 

GetFontlnfo  (&fontParms) ; 

lineSpace  =  fontParms .ascent+fontParms .descent +fontParms .leading ; 
charSpace  =  fontParms .widMax; 

if  (  ( (long) records* (long) lineSpace)  >  (long) INT_MAX) 
records  =  INT_MAX  /  lineSpace; 

SetRect  (SmaxWindowRect,  MIN_WSIZE,  MIN_WSIZE, 

(MAX_LOGREC_CHAR  *  charSpace)  +  SBARSIZE, 

(records  *  lineSpace)  +  SBARSIZE); 
aWindow->SetSizeRect  (SmaxWindowRect) ; 

/*  Initialize  Panorama's  ScrollPane,  set  scroll  units  to  the  defaulted 
**  values,  and  attach  the  Panorama  to  the  ScrollPane.  */ 
theScrollPane  =  new  (CScrollPane) ; 
theScrollPane->IScrollPane (aWindow,  this,  0,  0,  0,  0, 

sizELASTIC,  sizELASTIC, TRUE,  TRUE,  TRUE) ; 
theScrollPane->FitToEnclFrame  (TRUE,  TRUE) ; 

theScrollPane->Set Steps  (LOGPANE_HORZ_SCROLL,  LOGPANE_VERT_SCROLL) ; 

/*  Initialize  Panarama  to  include  maximum  chars  wide  and  maximum  records  tall, 
**  set  the  Panarama  units  to  one  char  wide  and  one  char  tall.  */ 

CPanorama: : IPanorama (theScrollPane,  aSupervisor,  MAX_LOGREC_CHAR, 
records,  0,  0,  sizELASTIC,  sizELASTIC) ; 

SetScales  (charSpace,  lineSpace) ; 

FitToEnclosure  (TRUE,  TRUE) ; 
theScrollPane->InstallPanorama  (this) ; 

/*  Create  the  LogList  and  initialize.  */ 
itsLogList  =  new  (CLogList); 
itsLogList->ILogList  (records); 

} 

/**  Draw()  —  Refreshes  the  visible  portion  of  the  window.  **/ 
void  CLogPanorama: : Draw 


Rect 

) 


/*  portion  of  window  to  refresh  */ 


I 

short 


/*  record  number  of  first  visible  line  */ 
/*  how  many  pixels  wide  is  a  character?  */ 
/*  record  number  of  last  line  */ 

/*  total  number  of  records  in  LogList  */ 

/*  how  many  pixels  tall  is  a  line?  */ 

/*  window  coordinates  of  current  row  */ 

/*  loop  counter  */ 


firstRec, 
hScale, 
lastRec, 
totalRec, 
vScale; 
register  short 
currRow, 
rec; 

char 

buff [MAX_LOGREC_CHAR] ;  /*  buffer  for  fetching  log  records  */ 

/*  First,  translate  draw  rectangle  to  records.  **/ 

GetScales  (shScale,  SvScale); 

totalRec  =  (short) itsLogList->GetNumItems  (); 

firstRec  =  (drawRect->top  /  vScale); 

if  (firstRec  ==  0) 

firstRec  =  1; 

lastRec  =  (drawRect->bottom  /  vScale)  +  1; 
if  (lastRec  >  totalRec) 

lastRec  =  totalRec; 

/*  Refresh  all  of  visible  lines.  **/ 

Prepare  (); 

for  (rec=f irstRec,  currRow=firstRec*vScale; 
rec<=lastRec; 
rec++,  currRow+=vScale) 

{ 

itsLogList->GetString  (rec,  buff) ; 

MoveTo  (LOGPANE_INSET,  currRow) ; 

Drawstring  (CtoPstr (buf f ) ) ; 

) 


/**  AddString ()  —  Adds  a  new  string  to  panorama, 
void  CLogPanorama: : AddString 
( 


char  *theString 
) 


/*  null-terminated  string  to  add  */ 


frameRect; 

listLimits, 

hSpan, 

vSpan, 

hScale, 

vScale; 

topRecord, 

bottomRecord, 

newRecord, 

currPosition, 

recPosition; 


/*  interior  of  current  frame  */ 


/* 
/* 
/* 
/* 
/* 

/* 
/* 
/* 
/* 
/* 

/*  Add  the  record  to  the  LogList. 


maximum  the  LogList  will  hold  */ 
the  horizontal  span  of  frame  */ 
the  vertical  span  of  frame  */ 
horizontal  pixels  in  panarama  unit  */ 
vertical  pixels  in  panarama  unit  */ 

LogList  record  number  of  top  row  */ 
LogList  record  number  of  bottom  row  */ 
LogList  record  number  of  new  row  */ 
panorama  coordinates  of  top/left  frame  */ 
panorama  coordinates  of  new  string  */ 

*/ 


(continued  on  page  120) 
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CTRACE 


Listing  Four  (Listing  continued,  text  begins  on  page  44.) 

itsLogList->AddString  (theString) ; 

/*  Get  coordinates  of  current  frame  and  calculate  tentative  coordinates  for 
newly  added  record.  */ 

GetPosition  (icurrPosition) ; 

GetFrameSpan  (ShSpan,  fivSpan) ; 

GetScales  (ShScale,  svScale); 
topRecord.v  =  currPosition.v  +  1; 
bottomRecord.v  =  topRecord.v  +  vSpan  -  1; 
newRecord.v  =  (short) itsLogList->GetNumItems  (); 
newRecord.h  =  currPosition.h; 


EraseRect  {& f rameRect) ; 

) 

} 

Draw  (SframeRect) ; 
itsScrollPane->Calibrate () ; 

} 

End  Listing  Four 

Listing  Five 

/“  CLogList.h  —  Definitions  for  a  LogList  object.  “/ 

♦define  _H_CLogList 


/*  Determine  where  we  are  in  reference  to  bottom  of  screen  and  of  list.  “/ 
if  (newRecord.v  >  (bottomRecord.v+1)  ) 

{ 

/*  bottom  record  isn't  visible  */ 
currPosition.v  =  newRecord.v  -  vSpan; 

ScrollTo  (currPosition,  FALSE) ; 

Getlnterior  ( &f rameRect ) ; 

Prepare  (); 

EraseRect  (&f rameRect) ; 

) 

else 

{ 

/*  bottom  record  is  visible  */ 

listLimits  ■  itsLogList->GetMaxRecordCount  (); 

if  (bottomRecord.v  <  listLimits) 

{ 

/*  room  in  list — create  blank  line  if  necessary  */ 
if  (newRecord.v  ■■  (bottomRecord.v  +1)  ) 

{ 

Scroll  (0,  1,  TRUE); 

SetRect  (SframeRect,  newRecord.h*hScale,  (newRecord.v-1) ‘vScale, 
(newRecord.h+hSpan) ‘hScale,  (newRecord.v) ‘vScale) ; 

) 

else 

SetRect  (SframeRect,  newRecord.h*hScale,  (newRecord.v-1) *vScale, 
(newRecord.h+hSpan-1) *hScale,  (newRecord.v) *vScale) ; 

} 

else  if  (bottomRecord.v  >  listLimits) 

currPosition.v  =  newRecord.v  -  vSpan; 

ScrollTo  (currPosition,  FALSE); 

Getlnterior  (&f rameRect) ; 

Prepare  (); 

EraseRect  (&frameRect) ; 

) 

else 

{ 

/*  bottom  of  pane=limit  of  list,  so  do  our  own  scrolling  */ 

Prepare  (); 

Getlnterior  (SframeRect) ; 

ScrollRect  (SframeRect,  0,  -vScale,  gUtilRgn) ; 

SetRect  (fiframeRect,  bottomRecord.h*hScale,  (bottomRecord.v-1) *vScale, 
(bottomRecord.h+hSpan-1) *hScale,  (bottomRecord.v) ‘vScale) ; 


♦include  <CList.h> 
♦include  <oops.h> 
♦include  <string.h> 


/*  definitions  for  superclass  */ 

/*  standard  OOP  definitions  */ 

/*  miscellaneous  string  definitions  */ 


♦define  MAX_LOGREC_CHAR  (200L)  /*  size  of  longest  entry  (inc  NULL)  */ 


struct  CLogList  :  CList 

( 

/*  internal  instance  data  */ 

short  maxRec;  /*  maximum  number  of  records  ■*/ 

/*  local  class  methods  */ 

void  ILogList  (short  records); 

void  AddString  (char  *theString); 

void  GetString  (short  which,  char  *theString) ; 

short  GetMaxRecordCount  (void) ; 

/*  inherited  methods  overriden  */ 
void  Dispose  (void) ; 

}; 

End  Listing  Five 


Listing  Six 


/**  CLogList. c  —  Methods  for  a  LogList  object.  **/ 


♦include  "CLogList.h"  /*  definitions  for  LogList  class  */ 

/**  ILogList  —  Initializes  a  LogList  for  the  indicated  number  of  entries.  **/ 
void  CLogList: : ILogList 
( 

short  records  /*  maximum  number  of  entries  */ 

) 

{ 

CList ::IList  (); 
maxRec  -  records; 

) 


/**  Dispose  —  Frees  all  records  (and  their  handles)  in  the  list  **/ 
void  CLogList: :Dispose  (void) 

{ 

short 

i;  /*  loop  counter  */ 

Handle 

record;  /*  handle  to  list  record  */ 

while  (GetNumltems ()  >  0) 

( 

record  =  (Handle) Firstltem () ; 

Remove  ( (COb ject*) record) ; 

DisposHandle  (record); 

} 


) 


/**  AddString  —  Adds  a  string  to  LogList.  **/ 
void  CLogList: : AddString 
( 

char  *theString  /*  pointer  to  null-terminated  string  */ 

) 

( 

Handle 

record;  /*  handle  for  a  list  entry  */ 

if  (strlen (theString) +1  <  MAX_LOGREC_CHAR) 

{ 

record  =  NewHandle  (strlen (theString) +1) ; 
strcpy  (‘record,  theString); 

) 

else 

( 

record  =  NewHandle  (MAX_LOGREC_CHAR) ; 
strncpy  {‘record,  theString,  MAX_LOGREC_CHAR); 

*  record [MAX_LOGREC_CHAR-l]  =  NULL; 

) 

Append  ( (COb ject*) record) ; 
if  (GetNumltems  ()  >  maxRec) 

( 

record  =  (Handle) Firstltem  (); 

Remove  ( (COb ject*) record) ; 

DisposHandle  (record) ; 

) 

} 


/“  GetString  —  Grabs  requested  entry  and  copies  it  to  user's  buffer.  “/ 
void  CLogList :: GetString 
( 

short  which,  /*  record  number  to  return  */ 

char  ‘theString  /*  point  to  destination  buffer  */ 

) 


Handle 

record;  /*  handle  for  a  list  entry  */ 

if  (  (record* (Handle) Nthltem (which) )  !=  NULL) 
strcpy  (theString,  ‘record) ; 

else 

theString [0]  =  0; 

} 

/“  GetMaxRecordCount  —  Returns  max. number  of  records  available  in  LogList  “/ 
short  CLogList :: GetMaxRecordCount  (void) 

{ 

return  (maxRec) ; 

)  End  Listings 
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DOS  EXTENDER 


Listing  Four  (Text  begins  on  page  74.) 


PROT  -  A  386  protected  mode  DOS  extender 
Copyright  (C)  1989,  by  A1  Williams  All  rights  reserved. 
Permission  is  granted  for  non-commercial  use  of  this  software 
subject  to  certain  conditions  (see  PROT. ASM) . 

This  file  is:  STACKS. INC,  which  contains  all  the  stack  segments. 

16  bit  stack  segment  (for  CODE16) 

SSEG  SEGMENT  PARA  STACK  'STACK'  USE16 

SSEGO  DB  DOSSTACK  DUP  (?) 

SSEG1  EQU  $ 

SSEG  ENDS 

;  16  bit  stack  segment  for  vm86  int  (both  hardware  &  INT  30) 

SSINT  SEGMENT  PARA  STACK  'STACK'  USE16 

SSINTO  DB  VM86STACK  DUP  (?) 

SSINT1  EQU  $ 

SSINT  ENDS 

;  private  stack  for  default  critical  error  handler  dos  calls 
CSTACK  SEGMENT  PARA  STACK  'STACK'  USE16 

DB  CRITSTACK  DUP  (?) 

CSTACK  ENDS 


32  bit  stack  segment 


SS32 
SSEG32 
SSEG321 
SS32 


SEGMENT  PARA  PUBLIC 
DB  PMSTACK  DUP 
EQU  $ 

ENDS 


'  STACK' 
(?) 


End  Listing  Four 


Listing  Five 


PROT  -  A  386  protected  mode  DOS  extender 
Copyright  (C)  1989,  by  A1  Williams  All  rights  reserved. 
Permission  is  granted  for  non-commercial  use  of  this  software 
subject  to  certain  conditions  (see  PROT. ASM) . 

This  file  is:  INT386.INC 


Peculiarities:  1.  We  don't  emulate  lock,  IRETD,  PUSHFD,  POPFD  yet;  2.  When 
calling  INT  25  or  INT  26  from  protected  mode  flags  are  destroyed  (not  left 
on  stack  as  'in  VM86,  real  mode);  3.  For  now  I  don't  support  adding  offsets 
to  the  return  address  on  your  vm86  stack  to  change  where  IRET  goes  to. 

That  could  be  fixed,  but  I  don't  know  of  any  PC  software  that  does  that 


;  fake  segment  for  far  ret  interrupts  (this  has  no  descriptor 

in 

GDT/LDT) 

QISR 

SEGMENT 

PARA  PUBLIC  ' 

C0DE16'  USE16 

ASSUME 

CS :QISR 

;  push  sacrifical  words  for  IRET  to 

i  eat  —  PLO  stack  controls 

return  anyway 

QIRET: 

PUSH 

0 

PUSH 

0 

PUSH 

0 

IRET 

QISR 

ENDS 

;  IDT  segment 

IDTABLE 

SEGMENT 

PARA  PUBLIC  ' 

DATA32'  USE32 

IDTBEG 

EQU 

$ 

DQ 

T0PINT+1  DUP 

(0) 

IDTEND 

EQU 

$ 

IDTABLE 

ENDS 

;ISR  segment 

DEFINT 

MACRO 

N 

INT&N 

LABEL 

FAR 

PUSH 

&N 

JMP 

NEAR  PTR  INTDUMP 

ENDM 

ISR 

SEGMENT 

PARA  PUBLIC  ' 

CODE32'  USE32 

ASSUME 

CS : ISR 

ISRBEG 

EQU 

$ 

;  Defines  interrupt  handlers  from  0 

to  TOPINT  (TOPINT  defined 

in 

EQUMAC .INC) 

INTNO 

= 

0 

REPT 

T0PINT+1 

DEFINT 

% INTNO 

INTNO 

= 

INTNO  +  1 

ENDM 

;  Debug  dump 

messages 

MESSAREA 

DB 

' INT=' , 0 

STKM 

DB 

'Stack  Dump:' 

,0 

TASKM 

DB 

'  TR=',0 

RTABLE 

DB 

'G' 

DB 

'F' 

DB 

'D' 

DB 

'E' 

GTABLE 

DB 

' DISIBPSPBXDXCXAX' 

MEMMESS 

DB 

'Memory  Dump: 

',0 

;  All  interrupts  come  here.  We  check  for  the  interrupt  #  pushed  on  the  stack 
;  and  vector.  Adds  interrupt  latency,  but  simplifies  IDT  construction. 
INTDUMP  LABEL  NEAR 

;  check  for  GP  error 

CMP  BYTE  PTR  [ESP],QDH 

JZ  NEAR  PTR  INT13H 


NOT13 : 

;  check  for  vm86  psuedo-int 

CMP  BYTE  PTR  [ESP],30H 

JZ  NEAR  PTR  INT30H 

;  hardware  interrupt? 

CMP  BYTE  PTR  [ESP], 2 OH 


JB 

SHORT  NOTIO 

IF 

ATCLASS 

CMP 

BYTE  PTR  [ESP] , 2FH 

ELSE 

CMP 

BYTE  PTR  [ESP] , 27H 

END  IF 

JA 

SHORT  NOTIO 

JMP 

NEAR  PTR  HWINT 

NOTIO: 

;  An  unexpected  interrupt;  crank  out  a  debug  dump,  exit  to  dos 


PUSHAD 

PUSH 

GS 

PUSH 

FS 

PUSH 

DS 

PUSH 

ES 

MOV 

AX, SEL  VIDEO 

MOV 

ES,  AX 

MOV 

AX,  CS 

MOV 

DS,  AX 

;  do  dump 

MOV 

ECX,  4 

INTL1 : 

MOV 

AL, [ RTABLE- 1+ECX] 

CALL32F 

SEL  CODE32, OUCH 

MOV 

AL,  'S' 

CALL32F 

SEL  CODE32,OUCH 

MOV 

AL, '=' 

CALL32F 

SEL  CODE32, OUCH 

POP 

EAX 

CALL32F 

SEL  CODE32, HEXOUT2 

PUSH 

ECX 

MOV 

ECX,  6 

LSP1 : 

MOV 

AL,  '  ' 

CALL32F 

SEL  CODE32, OUCH 

LOOP 

LSP1 

POP 

ECX 

LOOP 

INTL1 

CALL32F 

SEL  CODE32, CRLF 

XOR 

ECX, ECX 

INTL2: 

CMP 

CL,  5 

JNZ 

SHORT  NOCRINT 

CALL32F 

SEL_CODE32, CRLF 

NOCRINT: 

MOV 

AL, 'E' 

CALL32F 

SEL  CODE32, OUCH 

MOV 

AL,  [GTABLE+ECX*2] 

CALL32F 

SEL  CODE32,OUCH 

MOV 

AL, [GTABLE+1+ECX*2 ] 

CALL32F 

SEL  CODE32, OUCH 

MOV 

AL,  '=' 

CALL32F 

SEL  CODE32,OUCH 

POP 

EAX 

CALL32F 

SEL  CODE 32, HEXOUT4 

MOV 

AL,  '  ' 

CALL32F 

SEL  CODE32,OUCH 

INC 

CL 

CMP 

CL,  8 

JNE 

SHORT  INTL2 

MOV 

EBX, OFFSET  MESSAREA 

CALL32F 

SEL  CODE32 , MESSOUT 

POP 

EAX 

CALL32F 

SEL  CODE32, HEXOUT 

MOV 

EBX, OFFSET  TASKM 

CALL32F 

SEL  CODE32, MESSOUT 

STR 

AX 

CALL32F 

SEL  CODE32, HEXOUT2 

CALL32F 

SEL_CODE32 , CRLF 

;  stack  dump 

XOR 

EAX, EAX 

MOV 

AX,  SS 

LSL 

EDX, EAX 

JNZ 

SHORT  INTABT 

MOV 

EBX, OFFSET  STKM 

CALL32F 

SEL  CODE32, MESSOUT 

XOR 

CL,  CL 

INTL3 : 

CMP 

ESP, EDX 

JAE 

SHORT  INTABT 

TEST 

CL,  7 

JNZ 

SHORT  NOSCR 

CALL32F 

SEL  CODE32, CRLF 

NOSCR : 

POP 

EAX 

CALL32F 

SEL  CODE32, HEXOUT4 

INC 

CL 

MOV 

AL,  '  ' 

CALL32F 

SEL  CODE32,OUCH 

JMP 

SHORT  INTL3 

INTABT: 

;  Check  for  memory  dump  request 

MOV 

AX, SEL  DATA 

MOV 

DS,  AX 

ASSUME 

DS :DAT32 

MOV 

AX, WORD  PTR  DUMP  SEG 

OR 

AX,  AX 

JZ 

SHORT  NOMEMDUMP 

;  come  here  • 

to  do  memory  dump 

CALL32F 

SEL  CODE 3 2, CRLF 

PUSH 

DS 

PUSH 

CS 

POP 

DS 

MOV 

EBX, OFFSET  MEMMESS 

CALL32F 

SEL  CODE32, MESSOUT 

CALL32F 

SEL  CODE32, CRLF 

POP 

DS 

MOV 

AX, WORD  PTR  DUMP  SEG 

MOV 

ES,  AX 

CALL32F 

SEL  CODE32 , HEXOUT2 

MOV 

AL, '  :' 

CALL32F 

SEL  CODE 3 2, OUCH 

MOV 

EDX, DUMP  OFF 
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FSET: 
INLOOP : 


scan  for  instructions 


MOV 

EAX, EDX 

CALL32F 

SEL  CODE32, HEX0UT4 

MOV 

ECX , DUMP_CNT 

MOV 

AL,  '  ' 

CALL32F 

SEL  CODE32, OUCH 

MOV 

EAX, ES: [EDX]  ; 

get  word 

CALL32F 

SEL  CODE32 , HEX0UT4 

ADD 

EDX,  4 

SUB 

ECX,  4 

JA 

SHORT  DUMP LOOP 

CALL32F 

SEL_CODE32, CRLF 

MOV 

ATCLASS 

AL, 20H 

Send  EOI  signal 

OUT 

OAOH, AL 

OUT 

20H, AL 

just  in  case  hardware  did  it 

MOV 

BACK2D0S 

AL, 7FH 

return  7f  to  DOS 

GP  fault. 

If  mode  isn't 

VM86,  do  debug  dump.  Otherwise 

instruction.  If  instruction  isn't  known,  do  debug  dump. 

ADD 

ESP,  4 

balance  stack  (remove  intno) 

TEST 

[ESP+12] , 20000H 

JZ 

SHORT  SIM13A  ; 

wasn't  a  vm86  interrupt! 

ADD 

ESP,  4 

remove  error  code 

PUSH 

EAX 

PUSH 

EBX 

PUSH 

DS 

PUSH 

EBP 

MOV 

EBP, ESP 

point  to  stack  frame 

ADD 

EBP, 10H 

MOV 

AX, SEL  DATAO 

MOV 

DS,  AX 

MOV 

EBX, [EBP+4]  ; 

get  cs 

AND 

EBX, OFFFFH 

SHL 

EBX,  4 

ADD 

EBX, [EBP] 

get  eip 

XOR 

EAX, EAX 

al  =  OPCODE  byte 
ah  =  #  of  bytes  skipped  over 
bit  31  of  eax=l  if  OPSIZ  prefix 
encountered 

JMP 

SHORT  INLOOP 

it  of  eax 

if  OPSIZ 

OR 

EAX, 80000000H 

MOV 

AL,  [EBX] 

INC 

AH 

INC 

EBX 

CMP 

AL, 66H 

opsize  prefix 

JZ 

SHORT  FSET 

CMP 

AL, 9DH 

JZ 

SHORT  DOPOPF 

CMP 

AL, 9CH 

JZ 

SHORT  DOPUSHF 

CMP 

AL, OF AH 

JZ 

NEAR  PTR 

DOC  LI 

CMP 

AL, OFBH 

JZ 

NEAR  PTR 

DOSTI 

CMP 

AL, OCDH 

JZ 

NEAR  PTR 

DOINTNN 

CMP 

AL, OCFH 

JZ 

NEAR  PTR 

DO I RET 

CMP 

AL, OFOH 

JZ 

NEAR  PTR 

DOLOCK 

Whoops!  What  the  $#$%$#!  is  that? 


POP 

EBP 

POP 

DS 

POP 

EBX 

POP 

EAX 

PUSH 

0 

;  simulate  error 

PUSH 

13 

;  simulate  errno 

JMP32S 

N0T13 

The  following  routines  emulate  VM86  instructions.  Entry  conditions: 

eax[31]=l  iff  opsiz  preceeded  instruction 

ah=count  to  adjust  eip  on  stack 

al=instruction 

[EBX]  next  opcode  byte 

ds:  zerobase  segment 

;  This  routine  emulates  a  popf 
DOPOPF: 


MOV 

ADD 

ADC 

MOV 


BX,  [EBP] 
BL,  AH 
BH,  0 
[EBP] ,BX 


get  ss*10H,  add  esp  fetch  top  of  stack 


MOVZX 

SHL 

ADD 

MOVZX 

MOV 

AND 

AND 

OR 

MOV 

MOV 

ADD 

MOV 

AND 

POP 

POP 

POP 


EBX, WORD  PTR  [EBP+10H] 
EBX,  4 

EBX, [EBP+OCH] 

E AX , WORD  PTR  [EBX] 


EBX, [EBP+8] 

BX, 07000H 
AX, 08FFFH 
EAX, EBX 
[ EBP+8 ],EAX  ; 
EBX,  2 

[EBP+OCH], EBX 

EBX, OFFFEFFFFH 

[EBP+8] , EBX 

EBP 

DS 

EBX 


get  his  real  flags 
only  preserve  NT, IOPL 
wipe  NT, IOPL  in  new  flags 

save  his  real  flag  image 


(continued  on  page  124) 
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Listing  Five  (Listing  continued ,  text  begins  on  page  74.) 

POP  EAX 

I  RETD 

;  Routine  to  emulate  pushf 
DOPUSHF: 

MOV  BX,  [EBP]  ;  Fix  ip 

ADD  BL, AH 

ADC  BH, 0 

MOV  [EBP] , BX 

MOV  EAX, [EBP+8]  ;  get  his  flags 

;  get  ss,  add  esp  and  "push"  flags 

MOVZX  EBX, WORD  PTR  [EBP+10H] 

SHL  EBX, 4 

ADD  EBX,  [EBP+OCH] 

MOV  [EBX— 2 ] , AX 

MOV  EBX, 2 

;  adjust  stack 

SUB  [EBP+OCH] , EBX 

;  mask  out  flag  bits 

MOV  EBX, OFFFEFFFFH 

AND  [EBP +8], EBX 

POP  EBP 

POP  DS 

POP  EBX 

POP  EAX 

IRETD 

;  Emulate  CLI 
DOCL'I : 

MOV  BX,  [EBP]  ;  Fix  ip 

ADD  BL, AH 

ADC  BH, 0 

MOV  [EBP] , BX 

MOV  EAX, [EBP+8]  ;  get  flags 

OR  EAX,  20000H  ;  set  vm,  clr  RF  4  IOPL 

AND  EAX,  OFFFECDFFH 

MOV  [EBP+8], EAX  ;  replace  flags 

POP  EBP 

POP  DS 

POP  EBX 

POP  EAX 

IRETD 

;  Emulate  STI 
DOST I: 

MOV  BX,  [EBP]  ;  Fix  ip 

ADD  BL, AH 

ADC  BH, 0 

MOV  [EBP] , BX 

MOV  EAX, [EBP+8]  ;  get  flags 

OR  EAX, 20200H  ;  set  vm,  clr  RF  4  IOPL 

AND  EAX, OFFFECFFFH 

MOV  [EBP+8], EAX  ;  replace  flags 

POP  EBP 

POP  DS 

POP  EBX 

POP  EAX 

IRETD 

;  This  routine  emulates  an  INT  nn  instruction 
DOINTNN : 

PUSH  EDX 

PUSH  ECX 

;  get  ss 

MOVZX  EDX, WORD  PTR  [EBP+10H] 

SHL  EDX, 4 

;  add  esp 

ADD  EDX, [EBP+OCH] 

;  move  flags,  qsir  address  to  vm86  stack  4  correct  esp 
;  ...  flags 

MOV  CX,  [EBP+08H] 

MOV  [EDX-2] , CX 

MOV  WORD  PTR  [EDX-4],SEG  QIRET 

MOV  WORD  PTR  [EDX-6] , OFFSET  QIRET 

SUB  DWORD  PTR  [EBP+OCH] ,6 

MOV  CX,  [EBP]  ;  ip 

INC  AH  ;  adjust  ip  by  #  of  bytes  to  skip 

ADD  CL, AH 

ADC  CH,  0 

MOV  [EBP] ,CX 

;  get  tss  alias  (always  directly  above  TSS  in  GDT) 

STR  DX  ;  get  our  task  # 

SUB  DX,8  ;  alias  is  one  above 

MOV  ES, DX 

MOV  DX,SEL_DATA 

MOV  DS, DX 

ASSUME  DS :DAT32 

;  get  plO  esp  from  TSS  4  push  to  local  stack 
MOV  EDX, INTSP 

SUB  EDX, 4 

MOV  INTSP, EDX 

MOV  ECX,ES: [4]  ;  espO 

MOV  [EDX], ECX 

;  get  int  vector 

MOV  DX, SEL_DATA0 

MOV  DS, DX 

MOV  ECX, ESP  ;  adjust  stack  for  int  30H 

ADD  ECX, 60 

MOV  ES : [ 4 ] , ECX 

;  test  for  zero;  if  so  called  from  int  30H 
OR  AH, AH 

MOVZX  EDX, AL 

JZ  SHORT  FROM30 

;  otherwise  get  int  vector  from  CS:EIP  stream 
MOVZX  EDX, BYTE  PTR  [EBX] 

MOV  ECX, ESP 

ADD  ECX,  24 

MOV  ES:[4],ECX  ;  adjust  stack  for  non-int  30H 

FROM30: 

;  interrupt  vector* 4  =  VM86  interrupt  vector  address 
SHL  EDX, 2 

;  try  to  clean  up  mess  on  stack 

MOV  AX, SEL_DATA 


MOV  DS,  AX 

MOV  ST02 , EDX 

POP  ECX 

POP  EDX 

XCHG  ST02 , EDX 

MOV  STOl, ECX 

MOV  ST03, EBP 

POP  EBP 

XCHG  ST03, EBP 

POP  ECX 

MOV  BX, SEL_DATA 

MOV  DS, BX 

MOV  ST04 , ECX 

POP  EBX 

POP  EAX 

MOV  CX, SEL_DATA0 

MOV  DS, CX 

;  copy  segment  registers  4  esp  for  vm86  int 
PUSH  [EBP+20H] 

PUSH  [EBP+1CH] 

PUSH  [EBP+18H] 

PUSH  [EBP+14H] 

PUSH  [EBP+10H] 

PUSH  [EBP+OCH] 

MOV  ECX, [EBP+08] 

;  push  flags  (with  vm=l, iopl=0) , cs,  eip,  rf=0 
OR  ECX, 20000H 

;  clear  iopl,  rf,  tf,  if  and  push  flags 
AND  ECX, OFFFECCFFH 

PUSH  ECX 

;  read  new  cs/ip  from  8086  idt 

;  ...  push  CS 

MOVZX  ECX, WORD  PTR  [EDX+2] 
PUSH  ECX 


MOVZX  ECX, ' 

PUSH  ECX 

;  ...  push  IP 

MOVZX  ECX,' 

PUSH  ECX 

MOV  CX,  S! 

mov  ds,  c: 

PUSH  ST04 

MOV  ECX, , 

MOV  EDX, , 

MOV  EBP,. 

POP  DS 

IRETD 

;  Emulate  IRET  instruction 
DOIRET: 

;  vm86  stack 

MOVZX  EAX,  I 

SHL  EAX,  ■ 

ADD  EAX, 

MOV  EBX, 


ECX, WORD  PTR  [EDX] 
ECX 

CX, SEL_DATA 
DS,  CX 
ST04 

ECX, STOl 
EDX, ST02 
EBP, ST03 
DS 


;  go  on  to  vm86  land 


MOVZX  EAX, WORD  PTR [ EBP +1 OH] 

SHL  EAX, 4 

ADD  EAX, [EBP+OCH] 

MOV  EBX, [EAX]  ;  get  cs:ip 

If  top  of  stack=0:0  than  a  RETF  or  RETF  2  was  detected 

OR  EBX, EBX 

JZ  SHORT  FARRETINT 

PUSH  ECX 

XOR  ECX, ECX 

compare  return  address  with  QIRET 
MOV  CX,  SEG  QIRET 

SHL  ECX, 16 

MOV  CX, OFFSET  QIRET 

CMP  EBX, ECX 

POP  ECX 

if  equal  than  '‘normal"  IRET 

JZ  SHORT  NORMIRET 

Not  equal  then  that  vm86  jerk  is  "faking"  an  IRET  to  pass  control 
We  must  build  a  "fake"  plO  frame 
adjust  sp 

ADD  DWORD  PTR  [EBP+OCH] , 6 

get  ip 

MOVZX  EBX, WORD  PTR  [EAX] 

MOV  [EBP], EBX 

get  cs 

MOVZX  EBX, WORD  PTR  [EAX+2] 

MOV  [EBP+4] , EBX 

get  new  flags 

MOVZX  EBX, WORD  PTR  [EAX+4] 

OR  EBX, 20000H  ;  set  vm,  clr  RF  4  IOPL 

AND  EBX, OFFFECFFFH 

MOV  [EBP+8], EBX 

POP  EBP 

POP  DS 

POP  EBX 

POP  EAX 

IRETD  ;  go  on 


EBX, WORD  PTR  [EAX+2] 
[EBP+4] , EBX 


MOVZX  EBX, WORD  PTR  [EAX+4] 

OR  EBX, 20000H  ;  set  vm,  clr  RF  4  IOPL 

AND  EBX, OFFFECFFFH 

MOV  [EBP+8], EBX 

POP  EBP 

POP  DS 

POP  EBX 

POP  EAX 

IRETD  ;  go  on 

;  this  means  qiret  caught  a  FAR  RET  instead  of  an  IRET;  preserve  current  flags 
FARRETINT: 

MOV  EAX, EBP 

POP  EBP 

POP  DS 

PUSH  EBP 

PUSH  EAX 

MOV  BX, DS 

MOV  AX, SEL_DATA 

MOV  DS,  AX 

MOV  ST03, EBX 

POP  EBP  ;  I SR's  ebp 

MOV  EAX, [EBP+OCH] 

ADD  EAX, 6  ;  skip  pushes  from  qiret 

MOV  ST04, EAX 

;  get  flags 

MOV  EAX, [EBP+0 

MOV  ST02 , EAX 

JMP  SHORT  NIRE1 

;  This  handles  the  "normal"  case 
NORMIRET: 

MOV  BX, [EAX+4] 

MOV  EAX, EBP 

POP  EBP 

POP  DS 


EAX, [EBP+08H] 
ST02 , EAX 
SHORT  NIRET 
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PUSH  EBP 

PUSH  EAX 

MOV  AX, BX 

MOV  BX, DS 

PUSH  SEL_DATA 

POP  DS 

MOV  ST02 , EAX 

MOV  ST03, EBX 

POP  EBP  ;  ISR' s  ebp 

XOR  EAX, EAX 

MOV  ST04 , EAX 

NIRET: 

PUSH  ESI 

XOR  ESI, ESI 

OR  DWORD  PTR  [EBP+28H],0 

;  if  CS=0  then  int  30H  asked  for  segment  save 
JNZ  SHORT  V86IRET 

MOV  EAX, [EBP+14H] 

MOV  SAV_ES, EAX 

MOV  EAX, [EBP+18H] 

MOV  SAV_DS , EAX 

MOV  EAX, (EBP+1CH] 

MOV  SAV_FS, EAX 

MOV  EAX, (EBP+20H] 

MOV  S AV_GS , EAX 

MOV  ESI, 8 

V86IRET: 

MOV  AX, ES 

MOV  STOl, EAX 

POP  EBP 

XCHG  EBP, [ESP] 

;  get  tss  alias 

STR  AX 

SUB  AX, 8 

MOV  ES, AX 

ASSUME  DS :DAT32 

MOV  EAX,ES:[4]  ;  get  our  current  stack  begin 

;  see  if  we  have  to  balance  the  VM86  stack 
TEST  SS : [EAX+ESI+8] ,  20000H 

JZ  SHORT  STKADJD 

MOV  EBX, ST04 

OR  EBX, EBX 

JZ  SHORT  ADJSTK 

;  balance  vm86  stack 

MOV  SS: [EAX+ESI+OCH] ,  EBX 

JMP  SHORT  STKADJD 

ADJSTK:  ADD  DWORD  PTR  SS: (EAX+ESI+OCH] , 6 

STKADJD: 

;  get  quasi  flags 

MOV  EBX, ST02 

;  get  real  flags 

PUSH  SS: [EAX+ESI+8] 

;  preserve  flags 

MOV  DWORD  PTR  SS: [EAX+ESI+8] , EBX 

LEAVEFLAGS : 

;  only  let  8086  part  of  flags  stay 

AND  DWORD  PTR  SS: [EAX+ESI+08] , 01FFFH 

POP  EBX  ;  load  real  flags  into  ebx 

;  save  386  portion  of  old  flags  (AND  IP) 

AND  EBX, 0FFFFE200H 

OR  SS: [EAX+ESI+8],  EBX 

POP  ESI 

XCHG  EAX, [ESP] 

PUSH  EAX  ;  stack  =  ebx,  new  sp 

MOV  EBX, INTSP 

;  get  prior  plO  esp  from  local  stack 
MOV  EAX, [EBX] 

ADD  EBX, 4 

MOV  INTSP, EBX 

MOV  ES : [ 4 ] , EAX  ;  restore  to  TSS 

;  restore  registers 

POP  EBX 

MOV  ES, WORD  PTR  STOl 

MOV  DS, WORD  PTR  ST03 

POP  EAX  ;  restore  "real"  eax 

XCHG  EAX, [ESP] 

POP  ESP  ;  set  up  new  top  stack 

XCHG  EAX, [ESP+4] 

OR  EAX, EAX  ;  test  cs 

XCHG  EAX, [ESP+4] 

JNZ  SHORT  GOIRET 

ADD  ESP, 8  ;  skip  fake  CS/IP  from  INT  30H 

GOIRET: 

;  reset  resume  flag 

AND  DWORD  PTR  [ESP+8] , OFFFECFFFH 

IRETD 

;  Emulate  lock  prefix 
DOLOCK: 

POP  EBP 

POP  DS 

POP  EBX 

POP  EAX 

PUSH  OFFFFH 

PUSH  13  ;  simulate  errno 

JMP32S  NOT 13 

;  This  is  interface  routine  for  protected  mode  program  call  VM86  interrupts. 

;  Call  with  es:ebx  pointing  to  a  parameter  block 

;  +00  flag  -  if  1  then  resave  ES,  DS,  FS  &  GS  into  parameter  block  after  call 
;  +04  int  number  (0-255)  (required) 

;  +08  eflags 

;  +12  vm86  esp  (required) 

;  +16  vm86  ss  (required) 

;  +20  vm86  es 

;  +24  vm86  ds 

;  +28  vm86  fs 

;  +32  vm86  gs 

;  +36  vm86  ebp  (  to  replace  that  used  in  call  ) 

;  +40  vm86  ebx  (  to  replace  that  used  in  call  ) 

( continued  on  page  126) 
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Listing  Five  (Listing  continued,  text  begins  on  page  74.) 


;  All  other  registers  will  be  passed  to  vm86  routine 
;  This  routine  depends  on  the  dointnn  routine 


INT30H: 

ADD  ESP, 4  ;  remove  intno 

CMP  BYTE  PTR  ES:[EBX],0 

JZ  SHORT  NOSEGSAV 

;  dummy  CS/IP  to  signal  IRET  to  save  segments 
PUSH  0 

PUSH  0 


NOSEGSAV: 

PUSH  ES: [EBX+32]  ;  stack  up  registers 

PUSH  ES: [EBX+28] 

PUSH  ES: [EBX+24] 

PUSH  ES: [EBX+20] 

PUSH  ES: [EBX+16) 

PUSH  ES: [EBX+12] 

;  force  VM86=1  in  EFLAGS 


XCHG 

EAX, ES: [EBX+8] 

OR 

EAX,  20000H 

AND 

EAX, OFFFECFFFH 

PUSH 

EAX 

XCHG 

EAX, ES : [EBX+8] 

PUSH 

0 

don't  care 

cs 

PUSH 

0 

don't  care 

eip 

MOV 

EBP, ESP 

PUSH 

EAX 

PUSH 

ES: [EBX+40]  ; 

vm86  ebx 

PUSH 

DS 

PUSH 

ES: [EBX+36]  ; 

vm86  ebp 

MOV 

AX, SEL  DATAO 

MOV 

DS,  AX 

get 

user' s  intno 

MOV 

AL, ES: [EBX+4] 

set 

flag  to  dointnn 

not  to  check  cs:ip  for  int 

# 

MOV 

AH, OFFH 

;  go  ahead....  make  my  interrupt 
JMP32S  DOINTNN 


;  Handle  hardware  int!  This  routine  uses  INT  30  to  handle  HW  interrupts 
;  If  interrupted  in  protected  mode,  a  special  stack 
;  is  used.  If  in  VM86  mode,  the  current  VM86  stack  is  used 
HWINT: 


XCHG 

EAX, [ESP] 

PUSH 

DS 

PUSH 

ES 

PUSH 

EBX 

MOV 

BX, SEL  DATA 

MOV 

DS,  BX 

MOV 

ES,  BX 

CMP 

EAX, 28H 

JB 

SHORT  IRQ07 

ADD 

EAX, 48H 

JMP 

SHORT  IRQSET 

swap  eax  &  int  # 


vector  IRQ8-F  to  INT  70-77 


IRQ07: 


SUB 

EAX, 24  ;  vector  IRQO-7  to 

INT  8-OF 

IRQSET: 

set  up 

special  interrupt  frame 

MOV 

H I NTFRAME . VM I NT , E AX 

MOV 

HINTFRAME . VMEBP , EBP 

POP 

EBX 

MOV 

HINTFRAME. VMEBX, EBX 

PUSH 

EBX 

MOV 

EAX,020000H  ;  model  flags 

MOV 

HINTFRAME . VMFLAGS , EAX 

MOV 

EAX, OFFSET  SSINT1 

MOV 

HINTFRAME . VMESP , EAX 

MOV 

AX, SEG  SSINT1 

MOV 

HINTFRAME. VMSS, EAX 

MOV 

EAX, [ESP+24]  ;  get  flags 

TEST 

EAX, 20000H  ;  check  vm 

JZ 

SHORT  NOTVMHW 

MOV 

EAX, [ESP+28]  ;  get  vm86's  esp 

MOV 

HINTFRAME. VMESP, EAX 

MOV 

EAX, [ESP+32] 

MOV 

HINTFRAME. VMSS, EAX 

NOTVMHW : 

MOV 

EBX, OFFSET  HINTFRAME 

PUSH 

FS 

PUSH 

GS 

INT 

30H  ;  Do  interrupt 

POP 

GS 

POP 

FS 

POP 

EBX 

POP 

ES 

POP 

DS 

POP 

IRETD 

EAX 

ISREND 

EQU 

$ 

ISR 

ENDS 

End  Listing  Five 

Listing  Six 

*  PROT  -  A  386  protected  mode  DOS  extender  * 

"  Copyright  (C)  1989,  by  A1  Williams.  All  rights  reserved.  * 

"  Permission  is  granted  for  non-commercial  use  of  this  software  * 
k  subject  to  certain  conditions  (see  PROT. ASM) .  * 

*  This  file  is:  TSS.INC,  the  Task  State  Segment  definitions.  * 

Define  TSS  structure.  For  more  details  refer  to  the  Intel  documentation. 


Remember,  defined  values  are  only  defaults,  and  can  be  changed  when 


;  a  value  is 

defined 

TSSBLK 

STRUC 

BLINK 

DD 

0 

ESPPO 

DD 

OFFSET  SSEG321 

SSPO 

DD 

SEL  STACK 

ESPP1 

DD 

0 

SSP1 

DD 

SEL  STACK 

ESPP2 

DD 

0 

SSP2 

DD 

SEL  STACK 

CR31 

DD 

0 

EIP1 

DD 

OFFSET  USER 

EF1 

DD 

200H 

EAX1 

DD 

0 

ECX1 

DD 

0 

EDX1 

DD 

0 

EBX1 

DD 

0 

ESP1 

DD 

OFFSET  SSEG321 

EBP1 

DD 

0 

ESI1 

DD 

0 

EDI1 

DD 

0 

ESI 

DD 

SEL  DATA 

CS1 

DD 

SEL  UCODE 

SSI 

DD 

SEL  STACK 

DS1 

DD 

SEL  UDATA 

FS1 

DD 

SEL  DATAO 

GS1 

DD 

SEL  VIDEO 

LDT1 

DD 

0 

DW 

0 

IOT 

DW 

S+2-OFFSET  BLINK 

I  OP 

DB 

8192  DUP  (0) 

DB 

OFFH 

TSSBLK 

ENDS 

TSSSEG 

SEGMENT 

PARA  PUBLIC  ' DATA32'  USE16 

ORG 

0 

;  Dummy  TSS  that  stores  the  original  machine  state 

TSSOBEG 

TSSBLK 

<> 

TSSOEND 

EQU 

$ 

;  TSS  to  run 

the  USER 

task 

TSS1BEG 

TSSBLK 

<> 

TSS1END 

EQU 

$ 

’’’SSSEG 

ENDS 

End  Listing  Six 
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Listing  Seven 


PROT  -  A  386  protected  mode  DOS  extender 
Copyright  (C)  1989,  by  A1  Williams 
All  rights  reserved. 

Permission  is  granted  for  non-commercial  use  of  this  software 
subject  to  certain  conditions  (see  PROT. ASM) . 

This  file  is:  C0DE16.INC,  the  16  bit  DOS  entry/exit  code. 


CSEG 

SEGMENT 

ASSUME 

PARA  PUBLIC  ' C0DE16'  USE16 

CS :CSEG,  DSrCSEG 

BEG16 

EQU 

$ 

IDTSAV 

DF 

0  ;  space  to  save 

old  real  mode  IDT 

XZRO 

DF 

0  ;  Zero  constant 

for  inhibiting  IDT 

TEMP 

EQU 

THIS  FWORD  ;  Space  to  load 

GDT 

TLIM 

DW 

(GDTEND-GDT) -1 

TEMD 

DD 

0 

;  area  to 

save  stack 

pointer 

SOFFSAV 

DW 

0 

SSEGSAV 

DW 

0 

;  old  keyboard  interrupt  vector  —  we  have  to  catch 

reboot  requests 

KEYCHAIN 

EQU 

THIS  DWORD 

KEYOFF 

DW 

? 

KEYSEG 

DW 

? 

INTM 

IF 

DB 

ATCLASS 

0  ;  interrupt  mask 

-  pic  1 

INTMAT 

ENDIF 

DB 

0  ;  interrupt  mask 

-  pic  2  (AT  ONLY) 

MOV 

PSP, AX  ;  save  PSP 

MOV 

BX, DAT32 

MOV 

ES,  BX 

MOV 

ES:_PSP, AX 

;  check  to 

see  if  we 

are  running  on  a  386/486 

XOR 

AX,  AX 

PUSH 

AX 

POPF 

PUSHF 

POP 

AX 

AND 

AX, 0F000H 

CMP 

AX, 0F000H 

JNZ 

SHORT  NOT86 

NOT386 : 

MOV 

DX,  OFFSET  NOT386M 

NOT386EXIT: 

MOV 

AH,  9 

INT 

21H 

MOV 

AX, 4C80H 

INT 

21H  ;  exit 

NOT86 : 

MOV 

AX, 0F000H 

PUSH 

AX 

POPF 

PUSHF 

POP 

AX 

AND 

AX, OFOOOH 

JZ 

SHORT  NOT386 

;  If  we  got  here  we  are  on  an  80386.  Check  PM  flag 
SMSW  AX 

AND  AX, 1  ;  are  we  in  protected  mode? 

MOV  DX, OFFSET  VM86M 

JNZ  SHORT  NOT386EXIT 


PSP 

DW 

0 

MOV 

AX, 3509H 

INT 

21H 

;  error 

messages 

MOV 

AX,  ES 

NOT386M 

DB 

'Error:  this  program  requires  an  80386  or  80486' 

MOV 

KEYSEG, AX 

DB 

'  processor .',  13, 10, '  $' 

MOV 

KEYOFF, BX 

VM86M 

DB 

'Error:  this  program  will  not  execute  ' 

MOV 

AX, 2509H 

DB 

'in  VM86  mode.' 

MOV 

DX, OFFSET 

REBOOT 

DB 

13,10,'$' 

INT 

21H 

MOV 

AX, 2523H 

;  16  bit 

ss/sp  for  return  to  real  mode 

MOV 

DX, OFFSET 

CTRLC 

LOAD 16 

DD 

OFFSET  SSEG1-1 

INT 

21H 

DW 

SEL_RDATA 

MOV 

AX, 2524H 

MOV 

DX, OFFSET 

CRITERR 

;****** 

Begin  program 

INT 

21H 

ENTRY 

LABEL 

FAR 

;  *  Create  segments 

START 

PROC 

NEAR 

PUSH 

GDTSEG 

PUSH 

CS  ;  set  up  DS  segment,  save  PSP 

POP 

ES 

POP 

DS 

MOV 

AX,  ES 

OK.,  clear  to  proceed.  Set  up  new  AC, 


keyboard  and  Critical  error  handlers 


( continued  on  page  128) 
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Listing  Seven  (Listing  continued,  text  begins  on  page  74.) 

MOV 

EDX,  OFFSET  GDT 

SHL 

EBX,  4 

MOV 

EBX, CS 

MOV 

ECX, (DAT32END-DAT32BEG) -1 

SHL 

EBX,  4 

calc  segment  base  address 

MOV 

AH,  RW  DATA 

MOV 

ECX,  OFFFFH 

64  K  limit  (don't  change) 

MOV 

AL,  1 

MOV 

AH,  ER  CODE 

read/exec  code  seg 

MOV 

SI,  SEL  DATA 

XOR 

AL,  AL 

size 

CALL 

MAKE  DESC 

PUSH 

GDTSEG 

XOR 

EBX, EBX 

POP 

ES 

MOV 

BX, IDTABLE 

MOV 

EDX,  OFFSET  GDT 

SHL 

EBX,  4 

MOV 

SI, SEL  CODE 16 

MOV 

ECX, ( IDTEND-IDTBEG)  -1 

CALL 

MAKE  DESC 

make  code  seg  (16  bit /real) 

MOV 

AH, RW  DATA 

MOV 

ECX, OFFFFFH 

MOV 

AL,  1 

XOR 

EBX, EBX 

MOV 

SI,  SEL  IDT 

MOV 

SI,  SEL  DATAO 

CALL 

MAKE  DESC 

XOR 

ECX, ECX 

XOR 

EBX, EBX 

DEC 

ECX 

ecx=ffffffff 

MOV 

BX, ISR 

MOV 

AL,  1 

SHL 

EBX,  4 

MOV 

AH,  RW  DATA 

MOV 

ECX, (ISREND-ISRBEG) -1 

CALL 

MAKE  DESC 

make  data  (  4G  @  zero  base  ) 

MOV 

AH, ER  CODE 

XOR 

EAX, EAX 

MOV 

AL,  1 

INT 

12H 

MOV 

SI, SEL  ICODE 

MOVZX 

ECX,  AX 

CALL 

MAKE  DESC 

SHL 

ECX, 10 

XOR 

EBX, EBX 

LOADFREE 

BX 

get  free  memory  segment 

MOV 

BX, TSSSEG 

SUB 

ECX, EBX 

SHL 

DEC 

ECX 

;  compute  TSS  length 

MOV 

SI,  SEL  FREE 

MOV 

ECX, (TSSOEND-TSSOBEG) -1 

MOV 

AL,  1 

MOV 

AH, RW  DATA 

MOV 

AH, RW  DATA 

MOV 

AL,  1 

CALL 

MAKE  DESC 

MOV 

SI, SEL  TSSO 

XOR 

EAX,  EAX 

CALL 

MAKE  DESC 

MOV 

AH, 88H 

get  top  of  extended  memory 

MOV 

AH, TSS  DESC 

INT 

15H 

MOV 

SI, TSSO 

SHL 

EAX, 10 

*  1024 

CALL 

MAKE  DESC 

OR 

EAX, EAX 

any  extended  present? 

ADD 

EBX, OFFSET  TSS1BEG 

MOV 

ECX, EAX 

MOV 

SI, TSS1 

JNZ 

SHORT  EXTPRES 

;  compute 

TSS  length 

MOV 

ECX,  1 

MOV 

ECX, (TSS1END-TSS1BEG) -1 

EXTPRES : 

CALL 

MAKE  DESC 

DEC 

ECX 

MOV 

SI, SEL  TSS1 

MOV 

EBX, 100000H 

MOV 

AH, RW  DATA 

MOV 

SI, SEL  EXT 

0  limit  segment  if  no  ext. 

CALL 

MAKE  DESC 

MOV 

AL,  1 

MOVZX 

EBX, PSP 

MOV 

AH, RW  DATA 

SHL 

EBX,  4 

CALL 

MAKE  DESC 

MOV 

ECX, 255 

XOR 

EBX, EBX 

MOV 

AH, RW  DATA 

MOV 

BX, SEG  SEG32ENT 

MOV 

AL,  1 

SHL 

EBX,  4 

MOV 

SI, SEL  PSP 

MOV 

ECX,  (SEG32END- 

SEG32BEG) -1 

CALL 

MAKE  DESC 

MOV 

AH, ER  CODE 

PUSH 

ES 

MOV 

AL,  1 

MOV 

AX, PSP 

MOV 

SI, SEL  CODE32 

MOV 

ES,  AX 

CALL 

MAKE  DESC 

32  bit  code  segment 

XOR 

EBX, EBX 

XOR 

EBX, EBX 

MOV 

BX, ES: [2CH] 

MOV 

BX, USERCODE 

MOV 

AX,  BX 

SHL 

EBX,  4 

SHL 

EBX,  4 

MOV 

ECX, (USERCODEEND-USERCODEBEG) -1 

DEC 

AX 

MOV 

AH, ER  CODE 

MOV 

ES,  AX 

MOV 

AL,  1 

XOR 

ECX, ECX 

MOV 

SI, SEL  UCODE 

MOV 

CX, ES : [3] 

CALL 

MAKE  DESC 

SHL 

ECX,  4 

XOR 

EBX, EBX 

DEC 

ECX  ;  get  limit 

MOV 

BX, USERDATA 

MOV 

SI, SEL  ENV 

SHL 

EBX,  4 

POP 

ES 

MOV 

ECX, (USERDATAEND-USERDATABEG) -1 

MOV 

AL,  1 

MOV 

AH, RW  DATA 

MOV 

AH, RW  DATA 

MOV 

AL,  1 

CALL 

MAKE  DESC  ;  make  envrioment  segment 

MOV 

SI, SEL  UDATA 

;  turn 

on 

A20 

CALL 

MAKE  DESC 

MOV 

AL,  1 

XOR 

EBX, EBX 

CALL 

SETA20 

MOV 

BX, SS32 

CLI 

;  no  interrupts 

until  prot  mode 

SHL 

EBX,  4 

always  para  align  stacks! 

MOV 

SSEGSAV, SS 

MOV 

ECX, (SSEG321-SSEG32) -1 

;  save 

sp  for  triumphant  return  to  r/m 

MOV 

AH, RW  DATA 

stack  seg  is  data  type 

MOV 

SOFFSAV, SP 

MOV 

AL,  1 

SIDT 

IDTSAV 

MOV 

SI, SEL  STACK 

LIDT 

XZRO  ;  save  and  load 

IDT 

CALL 

MAKE  DESC 

XOR 

EBX, EBX 

XOR 

EBX, EBX 

MOV 

BX, SEG  GDT 

MOV 

BX,  SSEG 

SHL 

EBX,  4 

SHL 

EBX,  4 

ADD 

EBX, OFFSET  GDT 

MOV 

ECX, OFFFFH 

real  mode  limit  (don't  change) 

MOV 

TEMD, EBX 

XOR 

AL,  AL 

LGDT 

TEMP  ;  set  up  GDT 

MOV 

AH, RW  DATA 

MOV 

EAX, CRO 

MOV 

SI, SEL  RDATA 

OR 

EAX, 1  ;  switch  to  prot 

mode! 

CALL 

MAKE  DESC 

16  bit  data  for  return  to  r/m 

MOV 

CRO, EAX 

XOR 

EBX, EBX 

;  iump 

to 

load  CS  and 

flush  prefetch 

MOV 

BX, SEG  GDT 

JMPABS 

SEL  CODE16, PROT1 

SHL 

EBX,  4 

PROT1 : 

ADD 

EBX, OFFSET  GDT 

OPSIZ 

MOV 

ECX, (GDTEND-GDT) -1 

JMPABS32 

SEL  CODE32, SEG32ENT 

MOV 

AL,  1 

MOV 

AH, RW  DATA 

MOV 

SI, SEL  GDT 

;  Jump  here  to  return 

to  real  mode  DOS. 

CALL 

MAKE  DESC 

;  If  desired  AL  can  be  set  a  to  DOS  exit  code 

MOV 

AX, 500H 

set  video  to  page  0 

BACK 16 

LABEL 

FAR 

INT 

10H 

MOV 

BL,AL  ?  save  exit  code 

MOV 

AH, OFH 

CLI 

INT 

10H 

get  mode 

XOR 

EAX, EAX 

MOV 

EBX, OBOOOOH  ; 

monochrome 

MOV 

DR7 , EAX  ;  turn  off  debug 

(just  in  case) 

CMP 

AL,  7  ; 

check  for  mono 

JZ 

SHORT  VIDEOCONT 

LSS 

ESP , FWORD  PTR  CS:LOAD16 

MOV 

EBX, OB8000H 

MOV 

AX, SEL  RDATA 

VIDEOCONT : 

MOV 

DS,  AX 

MOV 

ECX, 3999 

limit  for  text  page 

MOV 

ES,  AX 

MOV 

AL,  1 

MOV 

FS,  AX 

MOV 

AH, RW  DATA 

MOV 

GS,  AX 

MOV 

SI, SEL  VIDEO 

MOV 

EAX, CRO 

CALL 

MAKE  DESC 

make  video  segment 

XOR 

MOV 

EBX, EBX 

BX, DAT32 

(cotitinued  on  page  130) 
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Listing  Seven  ( Listing  continued,  text  begins  on  page  74.) 

;  return  to  real  mode 

MOV 

AL, ODFH 

AND 

EAX, 07FFFFFF2H 

JNZ 

A20SET 

MOV 

CRO , EAX 

MOV 

AL, ODDH 

;  jump  to 

load  CS  and 

clear  prefetch 

A20SET: 

OUT 

60H, AL 

JMPABS 

CSEG, NEXTREAL 

OR 

AL,  AL  ;  make  sure  ZF  is  set  for 

NEXTREAL 

LABEL 

FAR 

RET 

;  compatibilty  with  AT  routines 

MOV 

AX,  CS 

SETA20 

ENDP 

MOV 

DS,  AX 

ENDIF 

LIDT 

IDTSAV 

restore 

old  IDT  0(3ff) 

IN 

AL, 21H 

;  This  routine  makes 

a  descriptor;  ebx=base;  ecx=limit  in  bytes;  es:edx=GDT 

MOV 

INTM, AL 

;  address; 

al=  size 

(0=16bit  l=32bit);  ah=AR  byte;  SI=descriptor  (TI  &  DPL 

;  reprogram  PIC's 

;  not  important ! ) .  Auto  sets  and  calculates  G  and  limit 

IF 

ATCLASS 

MAKE  DESC 

PROC 

NEAR 

IN 

AL, 0A1H 

PUSHAD 

MOV 

INTMAT, AL 

MOVZX 

ESI, SI 

MOV 

AL, 11H 

SHR 

SI, 3  ;  adjust  to  slot  # 

OUT 

OAOH, AL 

SHL 

AL,6  ;  shift  size  to  right  bit  position 

OUT 

20H, AL 

CMP 

ECX, OFFFFFH  ;  see  if  you  need  to  set  G  bit 

IDELAY 

JBE 

SHORT  OKLIMR 

MOV 

AL, 70H 

SHR 

ECX, 12  ;  div  by  4096 

OUT 

0A1H, AL 

OR 

AL,80H  ;  set  G  bit 

MOV 

AL,  8 

OKLIMR: 

MOV 

ES: [EDX+ESI *8 ] , CX 

OUT 

21H, AL 

SHR 

ECX, 16 

IDELAY 

OR 

CL,  AL 

MOV 

AL,  2 

MOV 

ES: [EDX+ESI*8+6] , CL 

OUT 

0A1H, AL 

MOV 

ES: [EDX+ESI *8+2] , BX 

MOV 

AL,  4 

SHR 

EBX, 16 

OUT 

21H, AL 

MOV 

ES: [EDX+ESI*8+4]  ,  BL 

IDELAY 

MOV 

ES: [EDX+ESI*8+5] , AH 

MOV 

AL,  1 

MOV 

ES: [EDX+ESI*8+7] ,  BH 

OUT 

0A1H, AL 

POPAD 

OUT 

21H, AL 

RET 

IDELAY 

MOV 

AL, INTMAT 

MAKE_DESC 

ENDP 

OUT 

0A1H, AL 

;  This  is 

the  routine  that  disables  AC  interrupts.  You  could  place  your  own 

MOV 

AL, INTM 

;  code  here  if  desired.  NOTE:  THIS  IS  VM86  CODE! 

OUT 

21H, AL 

CTRLC 

PROC 

FAR 

ELSE 

PUSH 

DS 

MOV 

AL, 13H 

PUSH 

AX 

OUT 

20H, AL 

MOV 

AX, DAT 3 2 

MOV 

AL,  8 

MOV 

DS,  AX 

OUT 

21H, AL 

ASSUME 

DS : DAT32 

INC 

AL 

MOV 

AL,  1 

OUT 

21H, AL 

MOV 

BREAKKEY, AL  ;  set  flag 

MOV 

AL, INTM 

POP 

AX 

OUT 

21H, AL 

POP 

DS 

END  IF 

IRET 

;  clean  up 

to  go  back 

to  DOS 

CTRLC 

ENDP 

LSS 

SP, DWORD  PTR  SOFFSAV 

;  Reboot  handler  (VM86  code) 

STI 

; 

resume 

interupt  handling 

REBOOT 

PROC 

FAR 

;  turn  a2C 

back  off 

STI 

XOR 

AL,  AL 

PUSH 

AX 

CALL 

SETA20 

IN 

AL, 60H 

;  restore 

keyboard  interrupt 

CMP 

AL, 53H  ;  delete  key? 

MOV 

DX, KEYOFF 

JNZ 

SHORT  NOREBOOT 

MOV 

AX, KEYSEG 

XOR 

AX,  AX 

PUSH 

DS 

PUSH 

DS 

MOV 

DS,  AX 

MOV 

DS,  AX 

MOV 

AX, 2509H 

MOV 

AL,DS:[417H]  ;  get  shift  status 

INT 

21H 

POP 

DS 

POP 

DS 

TEST 

AL, 8  ;  check  for  cntl/alt 

MOV 

AH, 4CH 

blow  this  joint! 

JZ 

SHORT  NOREBOOT 

MOV 

AL,  BL 

get  return  code 

TEST 

AL,  4 

INT 

21H 

return 

to  the  planet  of  MSDOS 

JZ 

SHORT  NOREBOOT 

START 

ENDP 

;  If  detected  a  'ALT 

-DEL  then  eat  it  and  return 

A20  on  (enable) .  AL=0  to  turn  A20 

IN 

AL, 61H 

;  Routine 

to  control  A20  line.  AL=1  to  turn 

MOV 

AH,  AL 

;  off  (disable) .  Returns  ZF=1  if  error;  AX  destroyed 

OR 

AL, 80H 

IF 

ATCLASS 

OUT 

61H, AL 

SETA20 

PROC 

NEAR 

MOV 

AL,  AH 

PUSH 

CX 

OUT 

61H, AL 

MOV 

AH, ODFH 

A20  On 

MOV 

AL, 20H 

OR 

AL,  AL 

OUT 

20H, AL 

JNZ 

SHORT  A20WAIT1 

POP 

AX 

MOV 

AH, ODDH 

A20  Of] 

IRET 

A20WAIT1: 

;  not  a  'ALT-DEL,  resume  normal  keyboard  handler 

CALL 

KEYWAIT 

NOREBOOT : 

POP 

AX 

JZ 

SHORT  A20ERR 

JMP 

CS: [KEYCHAIN] 

MOV 

AL, 0D1H 

REBOOT 

ENDP 

OUT 

64H, AL 

;  Critical 

error  handler  (always  fail/ignore) 

CALL 

KEYWAIT 

CRITERR 

PROC 

FAR 

MOV 

AL,  AH 

PUSH 

DS 

OUT 

60H,  AL 

PUSH 

DAT  3  2 

CALL 

KEYWAIT 

POP 

DS 

JZ 

SHORT  A20ERR 

ASSUME 

DS :DAT32 

MOV 

AL, OFFH 

MOV 

CRITAX, AX 

OUT 

64H,  AL 

MOV 

AL,  1 

CALL 

KEYWAIT 

MOV 

CRITICAL,  AL 

A20ERR: 

POP 

CX 

MOV 

CRITDI,  DI 

RET 

MOV 

CRITBP, BP 

SETA20 

ENDP 

MOV 

CRITSI, SI 

IF 

DOS 

LT  3 

;  Wait  for  keyboard  controller  ready 

Returns  ZF=1  if  timeout;  destroys  CX  & 

XOR 

AL,  AL 

AL 

KEYWAIT 

PROC 

NEAR 

ELSE 

MOV 

AL,  3 

XOR 

CX,CX 

maximum 

time  out 

ENDIF 

KWAITLP : 

POP 

DS 

DEC 

CX 

IRET 

JZ 

SHORT  KEYEXIT 

CRITERR 

ENDP 

IN 

AL, 64H 

AND 

AL,  2 

LAST 16 

EQU 

$ 

JNZ 

KWAITLP 

CSEG 

ENDS 

KEYEXIT: 

OR 

RET 

CX,CX 

End  Listings 

KEYWAIT 

ENDP 

ELSE 

;  INBOARD 

PC  Code  for 

A20 

SETA20 

PROC 

NEAR 

OR 

AL,  AL 
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listing  One  (Text  begins  on  page  86.) 

Listing  Five 

/*  ROLO.H  */ 

/*  Main  window  of  Rolodex  ISAM  file  browser.  */!! 

/*  Menu  Constants  */ 

inherit (TextWindow,  fRoloWindow,  #(keysDict  /*  Dictionary  of  keys  */ 

#define  SEARCH  2000 

roloDB  /*  ISAM  manager  */ 

roloTable  /*  ISAM  rolodex  file  */)  ,  2,  nil)!! 

fdefine  PRIMARY  2011  /*  Index  popup  */ 

# define  ALTERNATE  2012 

now (class (RoloWindow) ) ! ! 

#define  NEXT  2020 

#define  PREV  2030 

now (RoloWindow) ! ! 

fdefine  INSERT  2040 

/*  Initiate  a  session  with  the  ISAM  manager.  Create  the  ISAM  file.  */ 

♦define  UPDATE  2050 

Def  createDB (self ) 

fdefine  DELETE  2060 

(  roloDB  :=  new (IsamManager) ; 
openManager (roloDB) ;  . 

if  checkError (roloDB) 

/*  Dialog  Constants  */ 

then  destroy (roloDB) ; 

fdefine  PHONE  101 

AroloDB  :=  nil; 

fdefine  PERSON  102 

fdefine  COMPANY  103 

End  Listing  One 

Listing  Two 

endif; 

roloTable  :=  new (RoloFile) ; 
setFilename (roloTable,  "rolo") ; 
setManager (roloTable,  roloDB); 
create (roloTable,  ISINOUT  +  ISMANULOCK) ; 
if  checkError (roloTable) 
then  destroy (roloTable) ; 

AroloTable  :=  nil; 

/*  Additional  methods  required  by  WinTrieve  Rolodex  Browser  sample  app.  */ 

endif; 

now (String) ; !  ! 

/*  Handles  input  dialog  processing  for  obtaining  search  title.  Returns  title 

/*  Returns  a  copy  of  the  receiver  from 

or  nil  if  user  cancels.  */ 

which  a  blank  characters  have  been  removed.  */ 

Def  getPerson (self  1  id  title) 

Def  removeBlanks (self  !  str) 

{  id  :=  new (InputDialog,  "Person  Key",  "Person:",  ""); 

{  str  := 

loop 

do (self , 

while  runModal(id,  INPUT  BOX,  self)  =  IDOK 

(using (c)  if  c  <>  '  '  then  str  :=  str  +  asString(c)  endif; 

title  :=  leftJustify (getText (id) ) ; 

}); 

if  size(title)  >  0 

Astr; 

} 

then  Atitle; 
endif; 

!  ! 

endLoop; 

now (class (CType) ) ! ! 

Anil; 

/*  Return  a  CType  object  by  looking  up  it's  name  in  type  dictionaries.  Same  as 

/*  Handles  input  dialog  processing  for  obtaining  phone  number.  Returns  phone 

findType  method  except  does  no  error  checking.  */ 

Def  getType (self ,  tName) 

number  or  nil  if  user  cancels.  */ 

(  A$CTypes [tName]  cor  SUserTypes [tName] ; 

Def  getPhone (self  :  id  str  val) 

)( 

End  Listing  Two 

(  id  :=  new (InputDialog,  "Primary  Key",  "Phone:",  ""); 
loop 

while  runModal(id,  INPUT  BOX,  self)  =  IDOK 

str  :=  removeBlanks (getText (id) ) ; 
if  size(str)  >  0  cand  (val  :=  aslnt(str,  10)) 
then  Aval; 

Listing  Three 

endif; 

endLoop; 

Anil; 

)( 

/*  Rolodex  browser.  */!! 

inherit (Application,  fRoloApp,  nil,  2,  nil)!! 

/*  Validate  record  dialog  input.  If  ok,  returns  dictionary  of  input  field 

now (class (RoloApp) ) ! ! 

values.  If  error  input  field,  displays  error  box  and  returns  nil.  */ 

Def  validatelnput (self ,  cVals  !  input) 

7*  Remove  unnecessary  classes.  */ 

{  input  :=  new (Dictionary,  10);  /*  Validate  input.  */ 

Def  removeExtra (self ) 

input [fphone]  :=  left Justify (removeBlanks (cVals [PHONE] )) ; 

{  do (f (EditWindow  WinEllipse  WinPolygon  Stopwatch 

if  size  (input [fphone] )  =  0 

Control  FileDialog  ReplaceDialog  RelFile), 

then  errorBox (caption,  "Invalid  Phone  field."); 

(using (g)  removeGlobal (self ,  g) ; 

else  input [fperson]  :=  leftJustify (cVals [PERSON] ) ; 

}); 

| 

if  size (input [fperson] )  =  0 

then  errorBox (caption,  "Invalid  Person  field."); 
else  input [f company]  :=  left Justify (cVals [COMPANY] ) ; 

if  size (input [fcompany] )  =  0 

now (RoloApp) ! ! 

then  errorBox (caption,  "Invalid  Company  field."); 
else  Ainput 

/*  Startup  the  Rolodex  browser.  */ 

endif; 

Def  init(self,  cmdStr) 

endif; 

(  init (self : ancestor,  cmdStr); 

endif; 

mainWindow  :=  newMain (RoloWindow,  nil,  "Rolodex  Browser",  nil); 

Anil; 

show (mainWindow,  CmdShow) ; 
if  not (createDB (mainWindow) ) 

)  !! 

/*  Close  the  database.  */ 

then  close (mainWindow) ; 

Def  closeDB(self) 

endif; 

) 

{  if  roloTable 
then  close (roloTable) ; 

'■  ! 

destroy (roloTable) ; 
roloTable  :=  nil; 

/*  Class  Initialization  */ 

endif; 

End  Listing  Three 

if  roloDB 

then  closeManager (roloDB) ; 

Listing  Four 

destroy (roloDB) ; 
roloDB  :=  nil; 

/*  A  Rolodex  file.  */!! 

inherit (IsamFile,  fRoloFile,  nil,  2,  nil)!! 

endif; 

}( 

/*  Closing  the  window  so  close  the  database.  */ 

now (RoloFileClass) ! ! 

Def  shouldClose (self ) 

(  closeDB (self ) ; 

now (RoloFile) ! ! 

}( 

/*  Init  Rolodex  file  record  type  and  key  defs.  */ 

/*  Initiate  a  session  with  the  ISAM  manager.  */ 

Def  init (self) 

Def  openDB(self) 

{  init (self :ancestor) ; 

(  roloDB  :=  new (IsamManager) ; 

def (UserType,  frolo,  #( 

openManager (roloDB) ; 

char  phone  30 

if  checkError (roloDB) 

char  person  30 

then  destroy (roloDB) ; 

char  company  30 

)); 

AroloDB  :=  nil; 
endif ; 

setRecType (self ,  frolo); 

roloTable  :=  new (RoloFile) ; 

addKeyDef (self ,  fprimary,  fNODUPS,  fphone); 
addKeyDef (self,  fperson,  fDUPS,  fperson); 

}!! 

setFilename (roloTable,  "rolo") ; 

End  Listing  Four 

(continued  on  page  134) 
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Listing  Five  (Listing  continued,  text  begins  on  page  86.) 


setManager (roloTable,  roloDB) ; 
open (roloTable,  ISINOUT  +  ISMANULOCK) ; 
if  checkError (roloTable) 
then  destroy (roloTable) ; 

A roloTable  :=  nil; 
endif; 


/*  Display  the  current  record  in  the  window.  */ 

Def  printRecord(self) 

{  els (self); 

printstring (self,  "Phone:  "); 

printString(self,  asString (getField (roloTable,  #phone) ) ) ; 
eol (self) ; 

printstring (self ,  "Person:  "); 

printstring (self,  asString (getField (roloTable,  #person) ) ) ; 
eol (self) ; 

printstring (self,  "Company:  "); 

printString(self ,  asString (getField (roloTable,  #company) ) ) ; 
eol (self) ; 

) 

;  ; 

/*  Build  a  record  dialog.  */ 

Def  recDlg(self,  dPhone,  dPerson,  dCompany  !  D) 

{  D  :=  new(DialogDesign) ; 
setSize (D,  808,  1850120); 

/* 

addItem(D,  newStatic (Dlgltem,  "Phone:",  100,  5010,  40010,  0 ) ) ; 
addItem(D,  newEdit (Dlgltem,  dPhone,  PHONE,  50010,  35012,  0)); 
addItem(D,  newStatic (Dlgltem,  "Person:",  100,  5025,  40010,  0)); 
addItem(D,  newEdit (Dlgltem,  dPerson,  PERSON,  50025,  125012,  0) ) ; 
addItem(D,  newStatic (Dlgltem,  "Company:",  100,  5040,  40010,  0)); 
addItem(D,  newEdit (Dlgltem,  dCompany,  COMPANY,  50040,  35012,  0)); 

*/ 

addItem(D,  newStatic (Dlgltem,  "Phone:",  100,  5010,  40@10,  0)); 
addItem(D,  newEdit (Dlgltem,  dPhone,  PHONE,  50010,  125012,  0)); 
addItem(D,  newStatic (Dlgltem,  "Person:",  100,  5025,  40010,  0)); 
addItem(D,  newEdit (Dlgltem,  dPerson,  PERSON,  50025,  125012,  0)); 
addItem(D,  newStatic (Dlgltem,  "Company:",  100,  5040,  40010,  0)); 
addItem(D,  newEdit (Dlgltem,  dCompany,  COMPANY,  50040,  125012,  0)); 
addItem(D,  newButton (Dlgltem,  "Cancel",  IDCANCEL,  115095,  40014,  0)) 
AD; 

} 

i  ; 

/*  Search  for  a  record  based  on  current  index  order.  */ 

Def  searchRec (self ,  wp  !  val) 

{  select 

case  currentlndex (roloTable)  =  #primary 
is  val  :=  getPhone (self ) ; 
if  not (val) 
then  Anil; 
endif; 

putField(roloTable,  val,  #phone); 
endCase 

case  currentlndex (roloTable)  =  Iperson 
is  val  :=  getPerson (self ) ; 
if  not (val) 
then  Anil; 
endif; 

putField (roloTable,  val,  #person) ; 
endCase 
endSelect; 

if  not (read (roloTable,  ISEQUAL)) 
then  checkError (roloTable) ; 

Anil; 

endif; 

printRecord(self)  ; 


/*  Read  the  previous  record  and  display  it.  */ 
Def  prevRec (self,  wp) 

(  if  read (roloTable,  ISPREV) 
then  printRecord(self)  ; 
else  checkError (roloTable) ; 

els (self) ; 
endif; 

) 

;  ; 

/*  Read  the  next  record  and  display  it.  */ 

Def  nextRec (self ,  wp) 

{  if  read (roloTable,  ISNEXT) 
then  printRecord(self) ; 
else  checkError (roloTable) ; 

els (self) ; 
endif; 


/*  Insert  a  record.  */ 

Def  insertRec(self,  wp  \  rDlg  cVals  iVals) 

{  rDlg  :=  recDlg(self,  "",  "",  ""); 
loop 

while  runModal (rDlg,  nil,  self)  <>  0 
cVals  :=  controlValues (rDlg) ; 
if  iVals  :=  validatelnput (self ,  cVals) 
then  putField (roloTable,  iVals [fphone] ,  #phone) ; 
putField (roloTable,  iVals [#person) ,  fperson) ; 
putField (roloTable,  iVals ( #company] ,  # company ) ; 
if  not (insertCurrent (roloTable) ) 
then  checkError (roloTable) ; 
else  printRecord(self) ; 
endif; 

Aself ; 
endi f ; 

rDlg  :=  recDlg(self,  cVals [PHONE] ,  cVals [PERSON] ,  cVals [COMPANY] ) ; 
endLoop; 
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/*  Change  to  selected  index  and  display  first  record  in  new  index  ordering.  */ 
Def  changelndex (self ,  wp  !  key  oldKey) 

{  key  :=  keyAt (keysDict,  wp) ; 
oldKey  :=  current Index { roloTable ) ; 
if  key  =  oldKey 
then  Aself; 
endif ; 

if  selectRecord (roloTable,  key,  0,  ISFIRST) 
then  read (roloTable,  ISNEXT) ; 
unCheckMenuItem(menu,  keysDict [oldKey] ) ; 
checkMenuItem(menu,  wp) ; 
endif; 

if  not (checkError (roloTable) ) 
then  printRecord(self) ; 
endif; 


/*  Delete  the  current  record.  */ 
Def  deleteRec (self ,  wp) 

{  if  not (deleteCur rent (roloTable) ) 
then  checkError (roloTable) ; 
else  els (self); 
endif; 


/*  Update  a  record.  */ 

Def  updateRec (self ,  wp  !  rDlg  cVals  iVals) 

(  if  not (read (roloTable,  ISCURR) ) 
then  checkError (roloTable) ; 

Aself ; 
endif; 

rDlg  recDlg(self, 

asString(getField (roloTable,  fphone) ) , 
getField (roloTable,  fperson), 
asString (getField( roloTable,  #company) ) ) ; 
loop 

while  runModal (rDlg,  nil,  self)  <>  0 
cVals  :=  controlValues (rDlg) ; 
if  iVals  :=  validatelnput (self ,  cVals) 
then  putField (roloTable,  iVals [#phone] ,  #phone) ; 
putField (roloTable,  iVals [fperson] ,  fperson); 
putField (roloTable,  iVals [f company ] ,  f company) ; 
if  not (updateCur rent (roloTable) ) 
then  checkError (roloTable) ; 
else  printRecord(self) ; 
endif; 

Aself ; 
endif; 

rDlg  :=  recDlg(self,  cVals [PHONE] ,  cVal s[ PERSON ] ,  cVals [COMPANY] ) ; 
endLoop; 

}!  ! 

/*  Respond  to  the  menu  events. 

The  wp  argument  gives  the  selected  menu  ID. 

Get  a  message  symbol  from  the  menu  object.  */ 

Def  command (self,  wp,  lp  !  msg) 

{  if  msg  :=  action (menu,  wp) 
then  Aperform(self,  wp,  msg) 
endif; 

}!! 

/*  Setup  the  menu  bar.  */ 

Def  createMenu(self) 

{  createMenu (self ; ancestor) ; 
menu  :=  init (new (Menu) ) ; 
setHandle (menu,  hMenu) ; 

topMenu (menu,  "SSearch!",  SEARCH,  fsearchRec) ; 
keysDict  :=  new(OrderedDictionary,  4); 
keysDict [fprimary]  :=  PRIMARY; 
keysDict [fperson]  :=  ALTERNATE; 
popupMenu (menu,  "& Index", 
tuple ("phone",  "person"), 
tuple (PRIMARY,  ALTERNATE),  f changelndex) ; 
checkMenuItem(menu,  PRIMARY); 
topMenu (menu,  "&Next!",  NEXT,  fnextRec) ; 
topMenu (menu,  "&Prev!",  PREV,  fprevRec) ; 
topMenu (menu,  "&Insert!",  INSERT,  finsertRec) ; 
topMenu (menu,  "SUpdate!",  UPDATE,  fupdateRec) ; 
topMenu (menu,  "SDelete!",  DELETE,  fdeleteRec) ; 
drawMenu (self) ; 


/*  Initialize  the  window.  Create  menu  and  About  to  control  menu.  */ 
Def  init (self) 

(  init (self : ancestor) ; 
createMenu (self) ; 
addAbout (self) ; 


/*  Class  Initialization  */ 


End  Listings 
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Listing  One  (Text  begins  on  page  92.) 

member  account  by  strAccountCode; 

) 

....................................... . 

set  payor_accounttypecode  ( 
order  ascending; 
owner  payor; 

*  FILE:  chekmate. ddl 

member  account  by  cAccountType,  strAccountCode; 

*  DESCRIPTION:  db  Vista  database  definition  language  schema 

} 

*****.*************.***,.*».******,„******,», 

******»*****/ 

set  payor  accountname  ( 

database  chekmate  { 

order  ascending; 
owner  payor; 

/*  File  definition  section  */ 

member  account  by  strAccountName; 

data  file  checksl  =  "chekmate. dOl"  contains  system,  payor,  payee, 

) 

tranPayee,  account; 

/*  Sets  with  account  as  parent  */ 

data  file  checks2  =  "chekmate. d02"  contains  transaction,  actual; 

set  account  budget  { 

data  file  checks3  =  "chekmate. d03"  contains  budget,  distribution; 

order  ascending; 

key  file  checkKey  =  "chekmate. kOl"  contains  strPayorName,  strAccountName, 

owner  account; 

member  budget  by  nBudgetMonth; 

strAccountCode,  strPayeeCode, 

1 

StrPayeeName; 

set  account  actual  ( 

/*  Ewcord  definition  section  */ 

order  ascending; 

record  payor  { 

owner  account; 

unique  key  char  strPayorName  [35]; 

member  actual  by  nActualMonth; 

char  strPayorAddrl  [35];/*  single  element  fields  */ 

) 

char  strPayorAddr2  [35];/*  are  easier  in  toolbook  */ 

set  account  distribution  { 

char  strPayorCity  [20] ; 

order  next; 

char  strPayorState  [3] 

owner  account; 

char  strPayorZip  [10]; 

member  distribution; 

char  strPayorCtry  [10] ; 

} 

/*  account  payee  implements  default  distribution  account  for  payees.  */ 

char  strPayorTel  [15] ; 

char  cPayorRegAdd;  /* 

values  are  (a)D(d)  and  */ 

set  account  payee  ( 

char  cPayorAccAdd;  /*  (a) S (k)  on  exception  processing  */ 

order  next; 

char  cPayorPayeeAdd; 

owner  account; 

char  cPayorAccess;  /* 

values  are  C(ode)  and  N(ame)  */ 

member  payee; 

int  nPayorYear; 

) 

/*  sets  with  payee  as  owner  */ 

db  addr  dbaPayorCurrBank; 

int  nPayorNextRecur; 

set  payee  transaction  ( 

1 

order  next; 

/*  Account  covers  both  balance  sheet  and 

income  statement  accounts.  */ 

owner  payee; 
member  transaction; 

record  account  ( 

> 

key  char  strAccountName  [35] 

/*  sets  with  actual  as  owner.  */ 

key  char  strAccountCode  [15] 

set  actual  transaction  date  ( 

char  strAccountNumber  [15] 

order  ascending; 

char  cAccountType; 

/*  A  L  E  I  E  */ 

owner  actual; 

int  bAccountTax; 

/*  T=  tax  related  */ 

member  transaction  by  ITranDate; 

int  bAccountlsRegister; 

) 

} 

set  actual  transaction  number  ( 

/*  Payee  */ 

order  ascending; 

record  payee  { 

owner  actual; 

key  char  strPayeeName  [35] 

member  transaction  by  nTranNumber; 

key  char  strPayeeCode  [15] 

I 

char  strPayeeAddrl  [35] 

set  actual  transaction  type  { 

char  strFayeeAddr2  [35] 

order  ascending; 

char  strPayeeCity  [20] 

owner  actual; 

char  strPayeeState  [3] ; 

member  transaction  by  cTranType,  ITranDate; 

char  strPayeeZip  [10] 

} 

char  strPayeeCtry  [10] 

set  actual  distribution  ( 

char  strPayeeTel  [15] 

order  next; 

/*  default  account  is  a  set  */ 

owner  actual; 

char  strPayeeMemo  [35] 

member  distribution; 

char  strPayeeType  [10] 

) 

/*  sets  with  transaction  as  owner  */ 

] 

/*  Budget  records  are  owned  by  the  account.  */ 

set  transaction  distribution  { 

record  budget  ( 

order  next; 

int  nBudgetMonth; 

/*  number  from  1  to  12  */ 

owner  transaction; 

long  lBudget Amount; 

member  distribution; 

/*  Actuals  are  maintained  in  order;  speeds  process  of  updating  register.*/ 

set  transaction  tranPayee  { 

record  actual  { 

order  next; 

int  nActualMonth; 

owner  transaction; 

long  lActualAmount; 

member  tranPayee; 

/*  Transactions  are  headers  for  distributions.  */ 

End  Listing  One 

char  cTranType; 

/*  check,  deposit,  etc  */ 

char  strTranMemo  [35]; 

int  bTranClear; 

/*  T  =  cleared  */ 

int  nTranNumber; 

/*  Check  number  */ 

Listing  Two 

long  ITranDate; 

/*  Transaction  date  as  a 

long  ITranAmount; 

} 

"COBOL"  date:  ccyymmdd  */ 

to  handle  LINKDLLS 

/*  Distributions  are  the  balancing  entries 

for  transactions.  */ 

record  distribution  ( 

—  use  the  Windows  kernel  for  memory  management 

long  lDistrAmount; 

) 

linkdll  "kernel.exe" 

word  globalAlloc  (word,dword) 

/*  Set  definition  section  —  Sets  with  system  as  parent  */ 

word  globalFree  (word) 

set  system  payor  ( 

pointer  globalLock  (word) 

order  ascending; 

word  globalReAlloc (word, dword, word) 

owner  system; 

dword  globalSize (word) 

member  payor  by  strPayorName; 

word  globalUnlock (word) 

) 

end 

set  system  payeecode  { 

— use  ToolBook's  file  dll  for  file  system  access 

order  ascending; 

linkdll  "tbkfile.dll" 

owner  system; 

string  getCurrentDirectory (string) 

member  payee  by  strPayeeCode; 

string  getCurrentDrive ( ) 

1 

end 

set  system_payeename  ( 

order  ascending; 

--  use  Raima's  db  VISTA  dll  for  database  functionality 

owner  system; 

linkdll  "vista.dll" 

member  payee  by  strPayeeName; 

— except  for  close, closetask,  and  opentask,  functions  are  as 

) 

— in  the  db  vista  docs  (dt  =  d  ).  The  last  args  are  *currenttask, dbn 

set  system_lastData  ( 
order  next; 

int  dt  close  (pointer) 

owner  system; 

int  dt  closetask (pointer) 

member  lastData; 

int  dt  connect  (int, pointer, int) 

} 

int  dt  crget  (pointer, pointer, int) 

/*  Sets  with  payor  as  parent  */ 

set  payor  accountcode  ( 

— other  calls  ommitted  here 

order  ascending; 
owner  payor; 

(continued  on  page  138) 
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Listing  Two  (Listing  continued,  text  begins  on  page  92.) 

int  dt_setro  (int, pointer, int) 

end 


— chekmate.dll  is  the  helper  dll  for  the  checking  account  system 
linkdll  "chekmate.dll" 

— other  calls  ommitted  here 

word  dbv_EditRegister  (word, int, long, int, word, int) 
word  dbv_GetReqister  (word, int, word) 

end 


set  retval  to  -1 
conditions 

when  char  1  of  fField  is  "h"  — handles 

set  retval  to  pointerWord (vOf f set, svPtrControl) 
when  chars  1  to  3  of  fField  is  "dba"  — db_addrs 

set  retval  to  pointerlong (vOffset, svPtrControl) 
when  char  1  of  fField  is  "n" 

set  retval  to  pointerint (vOffset, svPtrControl) 

end 

return  retval 


end 


End  Listing  Two 

Listing  Three 

to  handle  InitGlobals 

system  svhControl,  svPtrControl 
system  svhDBBuffer,  svPtrDBBuf fer 
system  svhCurrTask,  svPtrCurrTask 

set  svhControl  to  GlobalAlloc  (66,64)  --GHND  is  66,  size  is  64  bytes 
set  svhDBBuffer  to  GlobalAlloc  (66,256) 
set  svhCurrTask  to  GlobalAlloc  (66,64) 

if  svhControl  <=  0  or  svhDBBuffer  <=  0  or  svhCurrTask  <=  0 
— clean  up,  since  allocation  failed 
send  FreeGlobals 

send  Exit  —  shutdown  the  system 

else 

--get  pointers 

set  svPtrControl  to  GlobalLock  (svhControl) 

set  svPtrDBBuf fer  to  GlobalLock  (svhDBBuffer) 

set  svPtrCurrTask  to  GlobalLock  (svhCurrTask) 

end 

end 

to  handle  FreeGlobals 

system  svhControl,  svPtrControl 
system  svhDBBuffer,  svPtrDBBuf fer 
system  svhCurrTask,  svPtrCurrTask 
if  svhControl  is  not  null  and  svhControl  >  0 
get  GlobalUnlock  (svhControl) 
get  GlobalFree  (svhControl) 

end 

if  svhDBBuffer  is  not  null  and  svhDBBuffer  >  0 
get  GlobalUnlock  (svhDBBuffer) 
get  GlobalFree  (svhDBBuffer) 

end 

if  svhCurrTask  is  not  null  and  svhCurrTask  >  0 
get  GlobalUnlock  (svhCurrTask) 
get  GlobalFree  (svhCurrTask) 

end 

— clean  up  globals  to  make  ToolBook  suspend  rather  than  GP  Fault 

set  svhControl  to  null 

set  svhDBBuffer  to  null 

set  svhCurrTask  to  null 

set  svPtrControl  to  null 

set  svPtrDBBuf fer  to  null 

set  svPtrCurrTAsk  to  null 


End  Listing  Three 


Listing  Four 


typedef  struct  Control  ( 

HANDLE  hCurrentTask;  //current  task  structure  (DB_TASK) 

HANDLE  hDataBaseBuf fer;  //db_Vista's  control  buffer 


//  Offscreen  image  /  database  address  pairs 

HANDLE  hRegisterlmage;  //offscreen  image  of  the  register  field 

HANDLE  hRegisterDBAArray;  //array  of  database  addresses,  1  for  each  line 
//in  the  register  image 


//  Selector  fields  storage 
HANDLE  hPayeeCodeArray; 
HANDLE  hPayeeCodeDBAArray; 
HANDLE  hPayeeNameArray; 
HANDLE  hPayeeNameDBAArray; 
HANDLE  hAccountCodeArray; 
HANDLE  hAccountCodeDBAArray; 
HANDLE  hAccountNameArray; 
HANDLE  hAccountNameDBAArray; 
HANDLE  hRegisterNumbers; 


//offscreen  image  of  the  payee  selector  field 
//array  of  database  addresses  -  payee  selector 
//offscreen  image  of  the  payee  selector  field 
//array  of  database  addresses  -  payee  selector 
//offscreen  image  of  account  selector  field 
//array  of  database  addresses  -  accts.  selector 
//offscreen  image  of  account  selector  field 
//array  of  database  addresses  -  accts  selector 
//array  of  deposit,  payments,  balances 


//  Database  addresses  for  active  records 

DB_ADDR  dbaCurrPayor;  //address  of  the  current  payor  record 

DB~ADDR  dbaCurrRegister;  //address  of  the  current  active  register  record 

DB~ADDR  dbaCurrRegisterActual;  //address  of  current  month's  register 


//  Database  number  for  concurrency  operations 
int  nDatabaseNumber;  //normally  0 
)  CONTROL; 


End  Listing  Four 


Listing  Five 


—CONTROL  BLOCK  ACCESSOR— 


to  get  hControl  fField 
system  svPtrControl 
set  vOffset  to  ControlOf fset (fField) 


to  set  hControl  fField  to  fVal 
system  svPtrControl 
set  vOffset  to  ControlOf fset (fField) 
conditions 

when  char  1  of  fField  is  "h"  --handles 

get  pointerWord (vOffset, svPtrControl, fVal) 
when  chars  1  to  3  of  fField  is  "dba"  — db_addrs 
get  pointerlong (vOffset, svPtrControl,  fVal) 
when  char  1  of  fField  is  "n" 

get  pointerint (vOffset, svPtrControl, fVal) 
end 

end 

to  get  ControlOf fset  fField 
conditions 

when  char  1  of  fField  is  "h"  — handies 
conditions 

when  fField  is  hCurrentTask 
set  vOffset  to  0 
when  fField  is  hDatabaseBuf fer 
set  vOffset  to  1 
when  fField  is  hRegisterlmage 
set  vOffset  to  2 

when  fField  is  hRegisterDBAArray 
set  vOffset  to  3 

when  fField  is  hRegisterCodeArray 
set  vOffset  to  4 

when  fField  is  hRegisterCodeDBAArray 
set  vOffset  to  5 

when  fField  is  hRegisterNameArray 
set  vOffset  to  6 

when  fField  is  hRegisterNameDBAArray 
set  vOffset  to  7 
when  fField  is  hPayeeCodeArray 
set  vOffset  to  8 

when  fField  is  hPayeeCodeDBAArray 
set  vOffset  to  9 
when  fField  is  hPayeeNameArray 
set  vOffset  to  10 
when  fField  is  hPayeeNameDBAArray 
set  vOffset  to  11 
when  fField  is  hAccountCodeArray 
set  vOffset  to  12 

when  fField  is  hAccountCodeDBAArray 
set  vOffset  to  13 
when  fField  is  hAccountNameArray 
set  vOffset  to  14 

when  fField  is  hAccountNameDBAArray 
set  vOffset  to  15 
when  fField  is  hRegisterNumbers 
set  vOffset  to  16 

end 

return  vOffset *2 

when  chars  1  to  3  of  fField  is  "dba"  — db_addrs 
set  -vbase  to  34  --  max (vOf fset*2) +2 
conditions 

when  fField  is  dbaCurrPayor 
set  vOffset  to  0 
when  fField  is  dbaCurrRegister 
set  vOffset  to  1 

when  fField  is  dbaCurrRegisterActual 
set  vOffset  to  2 
end 

return  vbase+vOf fset*4 
when  char  1  of  fField  is  "n" 

set  vbase  to  46  — vbase  +  dbaentries  *  4 
conditions 

when  fField  is  "nDatabaseNumber" 
set  vOffset  to  0 

end 

return  vbase+vOf fset*2 

end 

end 

End  listing  Five 


Listing  Six 

—  Fill  selector  loads  selector  text  from  global  memory  into  selector  field 

to  handle  FILLSELECTOR  fComboName, fOb jectName 
set  vCurdba  to  dbv_current record () 
set  vHText  to  hControl ("h"  &  fComboName  &  "Array") 
if  vhText  =  0 

get  createSelectorList  (fComboName) 
set  vHText  to  hControl ("h"  &  fComboName  &  "Array") 
end 

get  globalLock  (vHText) 
if  fObjectName  is  null 

set  fObjectName  to  fComboName 
end 

set  text  of  (pListID  of  group  fObjectName)  to\ 
pointerstring (0,  it) 
get  globalUnLock  (vHText) 
set  dbv_currentrecord()  to  vCurdba 

end 

—  createSelectorList  loads  global  memory  block  with  values  from  appropriate 

—  set  member  fields 

to  get  createSelectorList  fArray 
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system  svPtrDbBuf fer,  svPtrCurrTask 
—  first  determine  what  all  the  database  constants  are 
conditions 

when  fArray  is  "RegisterName" 

get  dt_findfm(20000, svPtrCurrTask,  0) 
set  vSet  to  20006 

get  dt_setom(vSet, 20000, svPtrCurrTask,  0) 
set  vField  to  1000 

—  cases  for  "RegisterCode",  "PayeeCode",  "PayeeName",  "AccountCode", 

—  and  "AccountName"  are  similar 
else 

return  false 
end 

set  vArray  to  "h"  &  fArray 

— check  if  the  memory  is  already  allocated 
if  hControl (vArray  &  "Array")  =  0 
set  vhTextBuffer  to  globalAlloc (66, 1000) 
set  vhDBABuffer  to  globalAlloc (66, 500) 
set  hControl (vArray  &  "Array")  to  vhTextBuffer 
set  hControl (vArray  &  "DBAArray")  to  vhDBABuffer 

else 

set  vhTextBuffer  to  hControl (vArray  &  "Array") 
set  vhDBABuffer  to  hControl (vArray  &  "DBAArray") 
end 

set  vPtrTextBuffer  to  globalLock (vhTextBuffer) 
set  vPtrDBABuffer  to  globalLock (vhDBABuffer) 
set  vDBAOffset  to  0 
set  vcharCount  to  0 
get  dt_findfm(vSet,  svPtrCurrTask,  0) 
while  it  =  0 
— build  the  text  buffer 

get  dt^crreadfvField, svPtrDbBuf fer, svPtrCurrTask, 0) 
set  vlihe  to  pointerstring (0, svPtrDbBuf fer) 
put  CRLF  after  vLine 

get  pointerstring (vCharCount, vPtrTextBuffer, vLine) 
increment  vCharCount  by  charcount (vLine) 

--build  the  db_addr  buffer 
get  dt_crget (svPtrDbBuffer, svPtrCurrTask,  0) 
get  pojnterlong(0, svPtrDbBuf fer) 
get  pointerlong (vDBAOffset, vPtrDBABuffer, it) 
increment  vDBAOffset  by  4  —  because  DBAs  are  longs 
— get  next  record 

get  dt  findnm(vSet, svPtrCurrTask, 0) 

end 

return  true 

get  globalunLock (vhTextBuffer) 
get  globalunLock (vhDBABuffer) 
end 

End  Listing  Six 


Listing  Seven 


DB_TASK  DB_FAR  *lpTask,  //  database  task 

int  nDatabase)  //  database  number 


int 

iError— 1; 

// 

error  return  code 

int 

nDBA=0; 

// 

number  of  DBA' s 

int 

nMaxDBA=0; 

// 

maximum  number  of  DBA' s  used 

int 

nMaxBytes=0; 

// 

maximum  bytes  allowed 

LPSTR 

lpText =NULL; 

// 

current  text  line 

DB  ADDR  FAR 

*lpDBA=NULL; 

// 

database  address  value 

HANDLE 

hMem; 

// 

handle  to  reallocated  memory  block 

DB  ADDR 

lCurDBA; 

// 

current  database  record 

//  save  the  current  database  record 

dt_crget  ( (DB_ADDR  FAR  *) &lCurDBA, lpTask, nDatabase) ; 

//  initialize  the  text  and  DBA  memory  blocks, 
if  (*lphListText  ==  NULL) 

{ 

‘lphListText  =  GlobalAlloc  (DLL  ALLOC, SELECTOR  TEXT  SIZE); 

}  -  -  _ 
if  ( *lphListDBA  ==  NULL) 

{ 

*lphListDBA  =  GlobalAlloc  (DLL_ALLOC,  (LONG)  ( SE LECTOR_DBA_COUNT * s i zeo f 

(DB  ADDR) ) ) ; 

) 

if  (*lphListText  ==  NULL  ! I  *lphListDBA  ==  NULL) 

{ 

goto  Cleanup; 

) 

//  initial  allocations  to  set  the  maximum  values  and  lock  the  memory  blocks. 
nMaxDBA  =  GlobalSize  (‘lphListDBA)  /  sizeof (DB_ADDR) ; 
nMaxBytes  =  GlobalSize  (‘lphListText); 

lpText  =  GlobalLock  (‘lphListText); 

lpDBA  =  (DB_ADDR  FAR  *)  GlobalLock  (‘lphListDBA) ; 

//  read  the  database  and  fill  in  the  text  values 
for  (iError  =  dt_findfm  (nSetID, lpTask, nDatabase) ; 
iError==S_OKAY; 

iError  =  dt_findnm  (nSetID, lpTask, nDatabase) ) 

( 

if  (nMaxBytes<=MIN_SELECTOR  TEXT  SIZE) 

{ 

//  need  to  allocate  more  text  memory. 
lpText  =  NULL; 

GlobalUnlock  (‘lphListText); 
hMem  =  GlobalReAlloc  (‘lphListText, 

GlobalSize (‘lphListText) +SELECTOR_TEXT_SIZE, 
GMEM_ZEROINIT) ; 

if  (hMem==NULL) 

{ 

iError  =  -2; 

goto  Cleanup;  //  not  enough  memory 

) 


*  dbv_CreateSelectorList — Purpose:  Obtains  list  of  available  selections  for 

*  a  particular  chekmate  field  and  save  them  along  with  database  addresses 

*  in  the  chekmate  control  block. 

*  Parameters:  hControl,  HANDLE  to  the  database  control  block;  nSetID,  numeric 

*  identifier  for  set  containing  selection  list;  lField,  LONG  database  field 

*  number;  nHandleOf fset,  integer  offset  into  the  Control  block  of  handle  for 

*  memory  where  data  should  be  stored. 

*  Return  Value:  0,  if  no  errors;  -n,  if  errors  reading  database 

extern  WORD  FAR  PASCAL  dbv_CreateSelectorList ( 

HANDLE  hControl,  //  Control  Block 

int  nSetID,  //  database  set  identifier 

LONG  lField,  //  database  field  number 

int  hHandleOf fset)  //  offset  in  Control  Block  for  memory  handle 


int  i; 

int  iError— 1; 

LPCONTROL  lpControl=NULL; 

DB_TASK  DB_FAR  *lpTask=NULL; 

LP HANDLE  lpHandle; 

if  (NULL==hCont rol ) 


//  error  return  code 
//  control  block 
//  task  pointer 
//  handle  pointer 


return  -1;  //  control  block  not  initialized 


//  Lock  control  block  so  task  block  can  be  locked  for  database  call. 
lpControl  =  (LPCONTROL)  GlobalLock  (hControl); 

lpTask  =  (DB_TASK  DB_FAR  *)  GlobalLock  (lpControl->hCurrentTask) ; 


//  point  to  handle  in  control  block  for  list  text. 

lpHandle  =  ((LPHANDLE)  lpControl)  +  hHandleOf fset; 

iError  =  LoadSelectorList  (lpHandle, lpHandle+1, nSetID, lField, lpTask, 

lpControl->nDatabaseNumber) ; 

Cleanup: 

GlobalUnlock  (lpControl->hCurrentTask) ; 

GlobalUnlock  (hControl) ; 
return  (iError); 


*  LoadSelectorList — Purpose:  Reads  database  for  specified  set  and  transfer 

*  data  from  lField  into  text  buffer.  Each  record  a  separate  text  line  in 

*  buffer  and  database  addresses  for  each  record  will  also  be  saved. 

*  Parameters:  lphListText,  handle  to  memory  for  list  text;  lphListDBA,  handle 

*  to  memory  for  list  database  addresses;  nSetID,  numeric  identifier  for 

*  database  set  containing  the  selection  list;  lField,  LONG  database  field 

*  number;  lpTask,  pointer  to  database  task;  nDatabase,  database  number 

*  Return  Value:  0,  if  no  errors;  -n,  if  errors  reading  database 


*/ 


int  PASCAL  LoadSelectorList  ( 

LPHANDLE  lphListText, 
LPHANDLE  lphListDBA, 

int  nSetID, 

LONG  lField, 


//  handle  to  memory  for  list  text 
//  memory  handle  for  list  database  adr. 
//  database  set  ID 

//  database  field  number  for  list  text 


‘lphListText  =  hMem;  //  new  handle 

lpText  =  GlobalLock  (‘lphListText); 

nMaxBytes  =  GlobalSize (‘lphListText)  -  lstrlen  (lpText); 

lpText  +=  lstrlen (lpText) ; 

} 

//  read  the  field  contents  into  the  text  buffer 
dt_crread (lField,  lpText, lpTask,  nDatabase) ; 
lstrcat  (lpText, "\r\n") ; 
lpText  +=  lstrlen (lpText) ; 

//  save  the  DBA  of  the  record 
if  (nDBA  >=  nMaxDBA) 

( 

//  need  to  allocate  more  DBA  memory. 
lpDBA  =  NULL; 

GlobalUnlock  (‘lphListDBA); 
hMem  =  GlobalReAlloc  (‘lphListDBA, 

GlobalSize (‘lphListDBA) +SELECTOR_DBA_COUNT*sizeof (DB_ADDR) , 

GMEM_Z  ERO I NI T ) ; 

if  (hMem==NULL) 

{ 

iError  =  -2; 

goto  Cleanup;  //  not  enough  memory 

) 

‘lphListDBA  =  hMem;  //  new  handle 

lpDBA  =  (DB_ADDR  DB_FAR  *)GlobalLock  (‘lphListDBA); 

nMaxDBA  =  GlobalSize (‘lphListDBA)  -  nDBA; 

lpDBA  +=  nDBA; 

} 

dt_crget  (lpDBA, lpTask, nDatabase) ; 

lpDBA++; 

nDBA++; 

} 

Cleanup: 

//  restore  the  address  of  the  current  record 
dt_crset  ( (DB_ADDR  far  *) SlCurDBA, lpTask, nDatabase) ; 
if  (lpText !=NULL) 

{ 

GlobalUnlock  (‘lphListText); 

) 

if  ( lpDBA !=NULL) 

{ 

GlobalUnlock  (‘lphListDBA); 

) 

if  ( iError==S_EOS ) 

I 

iError  =  S_OKAY; 

) 

return  (iError) ; 

) 


End  Listings 
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Neural  Nets:  A 
Cautionary  View 


The  September  issue  of  Byte  maga¬ 
zine  brought  together  some  com¬ 
puter  industry  experts  to  discuss, 
among  other  things,  the  staying 
power  of  some  new  or  newly  popular 
technologies.  The  expert  opinion  was 
divided  on  whether  or  not  neural  nets 
are  a  flash  in  the  pan.  With  all  due 
respect  to  the  experts,  neural  nets  have 
already  demonstrated  their  usefulness 
in  several  areas.  If  nothing  else,  they 
have  a  place  in  multidimensional  pat¬ 
tern  recognition. 

Neural  nets  are  a  useful  tool  for  solv¬ 
ing  certain  kinds  of  problems.  This  col¬ 
umn  is  about  what  they  are  not. 

The  New  Connectionism 

One  thing  neural  nets  are  not  is  just 
another  programming  methodology. 
Neural  nets,  along  with  Parallel  Distrib¬ 
uted  Processing,  is  part  of  a  movement 
in  cognitive  and  computer  science  called 
the  “New  Connectionism.” 

Parallel  Distributed  Processing  (PDP) 
is  on  the  cognitive  side  of  the  fence. 
According  to  David  Rumelhart  and 
James  McClelland,  whose  book  Paral¬ 
lel  Distributed  Processing  (MIT  Press, 
1986)  defined  the  discipline,  PDP  mod¬ 
els  “assume  that  information  processing 


Michael  Swaine 


takes  place  through  the  interactions  of 
a  large  number  of  simple  processing 
elements  called  units,  each  sending  ex¬ 
citatory  and  inhibitory  signals  to  other 
units.  In  some  cases,  the  units  stand  for 
possible  hypotheses  about  such  things 
as  the  letters  in  a  particular  display  or 
the  syntactic  roles  of  the  words  in  a 
particular  sentence.” 

That  sounds  like  a  description  of 


neural  nets,  and  in  fact  neural  nets 
more  or  less  represent  the  computer 
science  and  engineering  side  of  the 
New  Connectionism.  Generally,  a  neu¬ 
ral  net  implementation  for,  say,  picking 
tanks  out  of  the  foliage  in  grainy  pho¬ 
tographs,  looks  like  a  PDP  system,  but 
the  goals  of  the  implementors  are  dif¬ 
ferent.  Neural  nets  are  built  to  get  some¬ 
thing  practical  done,  rather  than  to 
model  the  mind. 

There  exists  today  an  intricate  weav¬ 
ing  between  cognitive  and  computer 
science.  This  column  attempts  to  fol¬ 
low  some  of  the  threads  of  that  com¬ 
mon  fabric. 

The  New  Connectionism  is  a  recent 
revival,  with  differences,  of  an  old  idea. 
Connectionism  in  this  new  form  has  a 
strong  attraction  for  many  computer 
and  cognitive  scientists.  Jerry  Fodor  and 
Zenon  Pylyshin  examine  both  the  at¬ 
tractions  and  the  assumptions  of  the 
New  Connectionism  in  “Connection¬ 
ism  and  Cognitive  Architecture:  A  Criti¬ 
cal  Analysis”  in  Connections  and  Sym¬ 
bols,  eds.  Steven  Pinker  and  Jacques 
Mehler  (MIT  Press,  1988).  “On  the  com¬ 
puter  science  side,”  they  say,  “connec¬ 
tionism  appeals  to  theorists  who  think 
that  serial  machines  are  too  weak  and 
must  be  replaced  with  radically  new 
parallel  machines,  while  on  the  bio¬ 
logical  side  it  appeals  to  those  who 
believe  that  cognition  can  only  be  un¬ 
derstood  if  we  study  it  as  neuros¬ 
cience.  ...  It  also  appeals  to  many 
young  cognitive  scientists  who  view 
the  approach  as  not  only  anti-estab¬ 
lishment  (and  therefore  desirable)  but 
also  rigorous  and  mathematical.” 

I  intend  to  present  here  Fodor  and 
Pylyshin’s  critique  of  the  New  Connec¬ 
tionism.  Their  critique  evaluates  the  New 
Connectionism  as  a  model  of  cognitive 


architecture;  that’s  their  interest,  and 
the  approach  of  philosophy,  psychol¬ 
ogy,  and  linguistics.  Why  should  this 
interest  us  as  programmers  or  com¬ 
puter  scientists?  Because  it  is  very  rele¬ 
vant  to  understanding  the  potential  of 
neural  nets  as  a  programming  tool.  If 
the  New  Connectionism  is  fundamen¬ 
tally  incapable  of  modeling  cognitive 
architecture,  then  neural  nets  are  far 
less  powerful  than  many  neural  net 
proponents  believe. 

It  may  not  be  obvious  how  close 
cognitive  science  and  computer  sci¬ 
ence  have  grown  in  recent  years.  Even 
the  competitors  of  the  PDP  model  in 
cognitive  science  on  the  one  hand,  and 
the  competitors  of  neural  nets  in  com¬ 
puter  science  on  the  other  are  the  same 
these  days.  The  Classical  models  that 
Fodor  and  Pylyshin  set  against  the  New 
Connectionism  were  derived  from  the 
structure  of  Turing  and  Von  Neumann 
machines. 

Psychological  theory  today  shapes 
up  largely  as  a  battle  between  cogni¬ 
tive  neural  nets  and  cognitive  Turing 
machines. 

Rocks  Regarded  as  Real 

Fodor  and  Pylyshin  begin  by  showing 
that  both  Connectionist  models  and  Clas¬ 
sical  models  want  to  operate  at  the 
same  level  of  explanation.  This  is  not 
a  trivial  point  in  their  domain.  Psychol¬ 
ogy  has  a  long  tradition  of  reduction- 
ism  that  has  spawned  several  distinct 
schools. 

One  such  school,  Behaviorism,  was 
founded  in  1913  in  a  fiery  essay  by  a 
relatively  unknown  young  psycholo¬ 
gist  named  John  Watson.  Watson  called 
for  a  purely  objective  science  of  psy¬ 
chology,  jettisoning  all  the  fuzzy-headed 
introspection  of  the  day.  There  was  a 
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lot  to  jettison,  and  so  welcome  was  his 
argument  that  not  long  after  this  Wat¬ 
son  was  elected  president  of  the  main 
association  of  psychologists.  Watson 
subsequently  left  academia  to  become 
an  advertising  agency  executive,  per¬ 
haps  perceiving  better  than  his  follow¬ 
ers  the  true  mission  of  Behaviorism. 

Behaviorism’s  most  charismatic  mod¬ 
ern  spokesperson  was  B.F.  Skinner.  In 
his  autobigraphy,  The  Shaping  of  a  Be¬ 
haviorism  Skinner  characterized  his  in¬ 
terest  as  radical  behaviorism,  in  which 
the  existence  of  subjective  entities  is 
denied.  Skinner  died  this  year,  and  just 
weeks  before  his  death  he  told  a  re¬ 
porter  that  his  greatest  regret  was  that 
he  was  not  understood  by  his  contem¬ 
poraries.  It’s  true;  psychology  has  moved 
away  from  Behaviorist  models,  and  the 
focus  is  now  on  cognitive  models  that 
do  take  things  such  as  thoughts  and 
ideas  and  mental  representations  seri¬ 
ously.  The  reductionism  of  the  Behav¬ 
iorist  school,  which  may  have  served 
a  purpose  in  bringing  some  rigor  to  the 
field  70-odd  years  ago,  now  looks  deliber¬ 
ately  obtuse  to  most  psychologists. 

Another  reductionist  trend  of  psy¬ 
chology  has  focused  on  neural  con¬ 
nections.  The  mind,  it  maintains,  is  to 
be  understood  in  terms  of  what  neu¬ 
rons  do:  Psychology  is  neurology,  pe¬ 
riod.  This  is  also  not  a  powerful  force 
in  psychology  today,  and  it  is  impor¬ 
tant  to  realize  that  the  New  Connec- 
tionist  models  do  not,  by  and  large, 
subscribe  to  this  view.  Rumelhart  and 
McClelland,  in  particular,  say  that  new 
and  useful  concepts  emerge  at  differ¬ 
ent  levels  of  organization. 

Fodor  and  Pylyshin  contend  that  nei¬ 
ther  the  New  Connectionist  models  nor 
the  Classical  models  are  reductionist, 
and  that  both  want  to  work  at  a  cogni¬ 
tive  level  of  organization;  and  they  ex¬ 
plain  what  they  mean  by  cognitive. 

The  world,  they  argue,  has  a  causal 
structure  at  many  levels  of  analysis. 
There  is  a  scientific  story  to  be  told 
about  quarks,  and  there  is  a  scientific 
story  to  be  told  about  atoms,  and  about 
molecules.  There  is  a  legitimate  sci¬ 
ence  of  geology,  which  legitimately  con¬ 
siders  such  entities  as  rocks  and  tec¬ 
tonic  plates.  While  we  certainly  hope 
that  all  these  stories  will  be  consistent, 
we  don’t  call  quantum  physics  a  new 
theory  of  geology,  and  deny  to  geolo¬ 
gists  the  reality  of  rocks.  Different  mod¬ 
els  of  explanation  are  appropriate  at 
different  levels  of  observation. 

Fodor  and  Pylyshin  maintain,  con¬ 
vincingly  and  apparently  uncontrover- 
sially,  that  the  appropriate  level  of  ex¬ 
planation  for  any  account  of  cognitive 
architecture  (such  as  the  Connectionist 
or  Classical  models)  is  the  representa¬ 


tional  states  of  the  organism. 

In  other  words,  symbols. 

This  is  an  important  point  for  cogni¬ 
tive  science  because  it  defines  the  goals 
of  these  two  approaches  and  gives  them 
common  observations  to  examine.  Be¬ 
cause  it  defines  techniques,  it  is  just  as 
important  but  far  less  contentious  in 
computer  science.  Everyone  would 

There  exists  today  an 
intricate  weaving 
between  cognitive  and 
computer  science 


agree  that  you  could  make  a  large  sys¬ 
tem  maximally  fast  and  efficient  by  treat¬ 
ing  it  as  one  entity  and  coding  in  ma¬ 
chine  language.  No  one  would  work 
this  way.  Divide-and-conquer  is  one 
of  the  most  fundamental  paradigms  of 
programming.  Large  programs  need  in¬ 
termediate  structure,  and  we  would  not 
generally  consider  it  an  improvement 
to  strip  the  objects  out  of  an  object- 
oriented  design,  the  structure  from  a 
structured  program,  the  subroutines 
from  a  system. 

So  Connectionist  and  Classical  cog¬ 
nitive  science  agree  about  the  desired 
level  of  explanation;  and  developers 
of  neural  nets  and  Turing  machines 
agree  about  the  need  for  intermediate 
structures.  All  disputants  agree  on  the 
need  for  symbolic  processing,  although 
we  haven’t  yet  defined  what  symbols 
are  and  how  they  are  to  be  processed. 

So  what  is  the  nature  of  the  disagree¬ 
ment  between  the  Classical  and  Con¬ 
nectionist  approaches,  which  Fodor  and 
Pylyshin  say  is  serious? 

It's  Not  Who  You  Know,  It's  How  You 
Know  Them 

The  difference  is  in  what  symbols  are 
and  in  how  the  system  is  allowed  to 
operate  on  them. 

For  Classical  mental  models,  seman¬ 
tic  content  is  assigned  to  expressions. 


(a)  (A  &  B) 

/  \ 

A  B 


(b)  (A  &  B) 

[  (P  &  Q)  -4  P  ;  (P  &  Q)  ->  Q  ] 


Figure  1:  Connectionist  vs.  Turing 
machine 


For  Connectionist  models,  it’s  assigned 
to  nodes.  These  are  the  symbols,  the 
things  that  represent  something,  in  the 
two  approaches. 

The  two  approaches  also  differ  in 
the  kinds  of  primitive  operations  that 
can  be  applied  to  these  content-bear¬ 
ing  entities.  Connectionist  models  only 
allow  causal  connections  as  primitive 
relations  among  the  nodes:  When  you 
know  how  activation  and  inhibition 
flow  among  them,  you  know  every¬ 
thing  there  is  to  know  about  how  the 
nodes  in  a  network  are  related,  claim 
Fodor  and  Pylyshin. 

Classical  models,  on  the  other  hand, 
allow  various  relations  among  their  con¬ 
tent-bearing  entities,  including,  particu¬ 
larly,  the  relation  of  constituency.  Here 
is  what  that  implies:  Classical  models 
are  committed  to  what  Fodor  and 
Pylyshin  call  “symbol  structures.”  That 
is,  not  all  symbols  are  atomic  symbols; 
some  are  made  up  of  other  symbols. 
As  they  put  it,  some  content-bearing 
entities  must  have  constituents  that  are 
also  content-bearing,  and  the  content 
of  the  composite  entity  must  be  a  func¬ 
tion  of  the  contents  of  the  constituents. 

This  is  crucial  to  the  Classical  ap¬ 
proach;  in  particular,  it  allows  the  pro¬ 
cesses  of  a  Classical  model  to  operate 
on  an  entity  in  terms  of  its  structure, 
so  that  the  same  process  that  converts 
(P  &  Q)  into  P  can  also  convert  ((X  & 
Y  &  Z)  &  (A  &  B  &  C))  into  (X  &  Y  &  Z). 

Consider  Figure  1(a)  and  how  a  Con¬ 
nectionist  machine  such  as  a  neural 
net  might  interpret  it.  To  the  Connec¬ 
tionist  machine,  the  paths  in  the  dia¬ 
gram  indicate  the  possible  paths  along 
which  excitation  and  inhibition  can  flow. 
When  the  Connectionist  machine  draws 
the  inference  from  (A  &  B)  to  A,  what 
happens  is  that  node  (A  &  B)  being 
excited  causes  node  A  to  be  excited. 

Now  consider  a  Turing  machine  draw¬ 
ing  the  inference  from  (A  &  B)  to  A;  see 
Figure  1(b).  The  Turing  machine  con¬ 
tains  a  program  that  lets  it  replace  any 
(P  &  Q)  that  it  finds  on  its  tape  with  a 
corresponding  P.  It  reads  (A  &  B),  in¬ 
terprets  that  as  a  (P  &  Q)  instance, 
extracts  the  P  part,  which  is  the  A,  and 
puts  it  on  the  tape. 

Both  approaches  involve  the  use  of 
symbols.  In  the  Connectionist  machine, 
the  nodes  (A  &  B)  and  A  can  represent 
propositions  like  Bill  loves  Mary  and 
Mary  drives  a  Jeep,  and  Bill  loves  Mary. 
In  the  Turing  machine,  the  expressions 
on  the  tape  can  represent  the  same 
propositions.  But  the  symbols  in  the 
Connectionist  machine  are  all  atomic, 
while  the  symbols  in  the  Turing  ma¬ 
chine  can  have  structure. 

So  the  architectural  difference  be- 
(continued  on  page  145) 
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(continued  from  page  142) 
tween  the  models  is  this:  In  the  Classi¬ 
cal  machine,  the  objects  to  which  the 
content  A  &  B  is  ascribed  literally  con¬ 
tain,  as  proper  parts,  objects  to  which 
the  content  A  is  ascribed.  Real-world 
constituency  is  modeled  in  the  con¬ 
stituency  relations  of  the  Classical  ma¬ 
chine’s  objects.  But  in  the  Connection- 
ist  machine,  none  of  this  is  true;  the 
object  to  which  the  content  A  &  B  is 
ascribed  is  causally  connected  to  the 
object  to  which  the  content  A  is  as¬ 
cribed;  but  there  is  no  structural  (part/ 
whole)  relation  that  holds  between  them. 
Although  the  label  attached  to  the  node 
(A  &  B)  makes  it  look  like  it  has  struc¬ 
ture,  it  does  not. 

Here’s  how  Fodor  and  Pylyshin  char¬ 
acterize  the  disagreement:  Classical  and 
Connectionist  theories  disagree  about 
the  nature  of  mental  representations; 
for  the  former,  but  not  for  the  latter, 
mental  representations  characteristi¬ 
cally  exhibit  a  combinatorial  constitu¬ 
ent  structure  and  combinatorial  seman¬ 
tics.  Classical  and  Connectionist  theo¬ 
ries  also  disagree  about  the  nature  of 
mental  processes;  for  the  former,  but 
not  for  the  latter,  mental  processes  are 
characteristically  sensitive  to  the  com¬ 
binatorial  structure  of  the  representa¬ 
tions  on  which  they  operate. 

Fodor  and  Pylyshin  claim  that  Con¬ 
nectionist  models  are  wrong  on  both 
counts. 

A  Competency  Hearing  for  Connectionism 

Fodor  and  Pylyshin  argue  in  psycho¬ 
logical  terms,  but  there  are  different 
ways  to  test  theories  and  models  against 
human  behavior.  You  can  look  at  ac¬ 
tual  performance  or  you  can  look  at 
competence.  Fodor  and  Pylyshin  ar¬ 
gue  in  terms  of  the  latter,  in  terms  of 
human  capacities.  The  form  of  the  ar¬ 
gument  is:  For  any  system  to  be  able 
to  do  such-and-such  a  thing  that  peo¬ 
ple  are  able  to  do,  it  must  have  such-and- 
such  a  form.  There  is  an  analogous 
argument  on  the  computer  science  side: 
Any  system  that  doesn’t  have  such-and- 
such  a  form  can’t  do  such-and-such 
interesting  things. 

Fodor  and  Pylyshin  argue  in  terms 
of  the  productivity  of  thought,  the  sys- 
tematicity  and  compositionality  of  cog¬ 
nitive  representations,  and  the  systema- 
ticity  of  inference. 

Productivity.  There  is  a  classic  argu¬ 
ment,  most  notably  articulated  by  Noam 
Chomsky,  that  purports  to  prove  that 
certain  kinds  of  mental  models  can’t 
account  for  human  linguistic  compe¬ 
tence.  Fodor  and  Pylyshin  extend  the 
argument  from  language  to  thought. 
Their  argument  runs  something  like 
this:  Human  beings  are  capable  of  think- 
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ing  an  unbounded  variety  of  thoughts. 
This  unbounded  competence  must  be 
produced  by  finite  means;  there  are 
only  a  finite  number  of  neurons  in  the 
brain.  To  get  unbounded  competence 
by  finite  means,  you  need  to  treat  the 
system  of  representations  as  consisting 
of  expressions  belonging  to  a  [recur¬ 
sively]  generated  set.  This  works  only 
when  an  unbounded  number  of  the 
expressions  are  nonatomic.  And  this  is 
just  what  can’t  happen  in  a  Connec¬ 
tionist  model.  So,  Fodor  and  Pylyshin 
conclude,  the  mind  cannot  be  a  PDP. 

There  is  a  counterargument  to  the 
productivity  argument:  That  humans 
can’t  really  think  infinitely  many 


thoughts.  It’s  unconvincing,  but  hard 
to  refute.  The  argument  from  the  sys- 
tematicity  and  compositionality  of  cog¬ 
nitive  representations  makes  it  unnec¬ 
essary  to  refute  it.  That  argument  goes 
like  this: 

The  ability  to  think  certain  thoughts 
is  intrinsically  related  to  the  ability  to 
think  certain  other  thoughts.  This  makes 
sense  only  if  the  thoughts  are  made 
up  of  the  same  parts.  It’s  not  that  you 
couldn’t  train  a  neural  net  to  make  the 
right  associations  between  thoughts; 
it’s  just  that  there  is  nothing  in  connec¬ 
tionist  structure  that  supports  these  as¬ 
sociations.  These  associations  are  cru¬ 
cial;  they  are  the  very  stuff  of  which 
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thought  is  made,  and  Connectionist  mod¬ 
els  have  no  explanation  for  them. 

Finally,  there’s  the  argument  from 
the  systematicity  of  inference.  A  neural 
net  model  can  be  constructed  to  draw 
the  inference  A  from  (A  &  B),  and  to 
draw  the  inference  B  from  (A  &  B).  But 
a  neural  net  can  just  as  easily  be  con¬ 
structed  to  make  one  of  these  infer¬ 
ences  but  not  the  other.  -We  never  see 
such  lopsided  mental  ability  in  human 
beings.  Why  not?  Connectionist  mod¬ 
els  don’t  know. 

This  would  seem  to  imply  the  fol¬ 
lowing:  If  you  want  to  build  an  infer¬ 
ence  engine  that  reasons  properly,  it 
can’t  be  merely  Connectionist. 

Fodor  and  Pylyshin  conclude  from 
this  sequence  of  arguments  that  some¬ 
thing  is  deeply  wrong  with  Connec¬ 
tionist  architecture.  This  is  what’s  wrong: 
Because  Connectionist  architecture  de¬ 
nies  syntactic  and  semantic  structure 
in  mental  representations,  it  is  forced 
to  accept,  as  possible  minds,  systems 
that  are  arbitrarily  unsystematic.  This 
is  blatantly  contrary  to  observation. 
Consequently,  Connectionist  architec¬ 
ture  is  inadequate  to  explain  the  basic 
data  in  its  domain. 

Furthermore,  it’s  not  enough  for  a 
Connectionist  to  agree  that  all  minds 
are  systematic;  he  must  also  explain 
how  nature  contrives  to  produce  only 
systematic  minds.  That,  apparently,  the 
Connectionist  can’t  do  without  recourse 
to  the  only  existing  approach  that  does 
predict  pervasive  systematicity:  The  Clas¬ 
sical  approach. 

This  seems  to  me  a  fairly  damning 
critique  of  Connectionism  as  a  cogni¬ 
tive  architecture,  and  it  seems  to  have 
some  implications  for  Connectionist  com¬ 
puter  programming,  as  well.  For  neural 
nets  as  programming  tools,  Fodor  and 
Pylyshin’s  conclusions  would  appear 
to  imply  at  least  the  following  limita¬ 
tion:  A  neural  net,  viewed  theoretically 
as  a  computational  system,  is  the  equal 
of  a  Turing  machine.  Both  are  general- 
purpose  computing  machines,  and  both 
can  achieve  anything  a  general-pur¬ 
pose  computing  machine  can  achieve. 
But  for  tasks  requiring  operations  on 
symbol  structures,  neural  nets  alone 
are  apparently  not  enough;  for  that, 
you  need  something  like  a  Turing  ma¬ 
chine.  Neural  nets  may  suffice  for  the 
low-level  implementation  of  an  infer¬ 
ence  engine,  but  only  if  you  use  the 
neural  net  to  implement  a  Turing  ma¬ 
chine  or  other  conventional  architec¬ 
ture,  and  implement  the  inference  en¬ 
gine  using  that. 
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DES  Revisited  and 
the  Shaft 


DATELINE  NOVEMBER,  2012:  After  22 
years  of  shuffling  from  court  to  court, 
venue  to  venue,  jurisdiction  to  jurisdic¬ 
tion,  the  case  of  FoobarSoft  vs.  Stevens 
has  finally  been  settled  by  the  United  States 
Supreme  Court.  It  seems  that  in  the  year 
1990,  the  time  of  the  landmark  decision 
where  a  columnist's  opinion  was  no  longer 
protected  from  claims  of  libel,  Stevens 
was  a  victim  of  the  common  columnist’s 
malady  known  as  “pub  lag.”  Unaware  of 
the  impending  abridgement  of  the  rights 
of  columnists,  and  working  with  the  col¬ 
umnist's  usual  four-month  lead  time,  Ste¬ 
vens  dutifully  reported  to  his  devoted  read¬ 
ership  that  FoobarSoft’s  new  Foobar  C++ 
compiler  had  a  small  bug  where  the  Foobar 
C++  Programmer’s  Chaise  Lounge  failed 
to  allow  the  programmer  to  assign  pre¬ 
ferred  ratios  to  the  ingredients  of  the 
vodka_martini class.  As  a  result,  program¬ 
mers  were  forced  to  overload,  encapsulate, 
and  polymorphize  under  the  influence  of 
two-parts  vodka  to  one-part  vermouth. 
Stevens  went  on  to  say  that  he  was  unable 
to  maintain  mental  track  of  class  hierar¬ 
chies  and  networks  with  more  than  3500 
derived  classes  while  under  the  influence 
of  instantiated  objects  of  the  vodka_martini 


class.  He  expressed  his  strong  opinion 
that  programmers  should  be  allowed  to 
define  drier  martinis  to  taste,  and  he  con¬ 
cluded  that  FoobarSoft  C++  had  a  defi¬ 
ciency. 

After  the  column  was  “in  the  can,” 
as  we  say,  but  before  the  issue  was  in  the 
hands  of  readers,  the  Supreme  Court  made 
their  ruling.  If  the  opinion  of  a  columnist 
causes  harm  to  someone  and  the  opinion 
is  not  clearly  factual,  that  person  has  been 
libeled  and  is  entitled  to  redress. 

Billy  Ghoats,  FoobarSoft 's  president, 
heard  from  a  programmer  in  Bangor,  Maine 
who  said  that  because  of  Stevens’s  re¬ 
marks,  the  programmer  would  delay  his 
paradigm  shift  until  all  the  compilers  got 
all  their  ingredients  right.  Ghoats  con¬ 
sulted  his  legal  staff  who  advised  him  to 
sue  Stevens  for  $195.53,  the  profits  that 
FoobarSoft  realize  on  each  sale  of  the 
$200  C++  package.  Wanting  satisfaction 
as  well  as  compensation,  Ghoats  also  pe¬ 
titioned  the  court  to  allow  him  to  scratch 
“C++”  across  Stevens’s  chest  as  punitive 
damages. 

Now,  after  22  years,  the  case  has 
finally  been  settled.  The  many  delays  were 
a  result  of  the  court’s  heavy  calendar  which 


included  the  7,532  lawsuits  that  were  filed 
against  Andy  Rooney  by  food,  soap,  and 
cosmetic  manufacturers  immediately  after 
the  1990  landmark  ruling.  The  decision 
in  the  Stevens  case  was  rendered  by  al¬ 
most  the  same  Supreme  Court  that  made 
the  original  ruling.  Chief  Justice  Wapner, 
who  was  appointed  by  President  Quayle 
in  1998,  read  the  opinion.  The  court  unani¬ 
mously  ruled  that  Stevens’s  report  of  the 
FoobarSoft  C++  behavior  did  not  consti¬ 
tute  libel  because  it  was  factual.  However, 
calling  the  behavior  a  bug  and  a  defi¬ 
ciency  was,  in  the  court’s  opinion,  non- 
factual  and  damaging  to  FoobarSoft,  and 
so  the  plaintiff  received  an  award  in  the 
amount  originally  requested.  The  puni¬ 
tive  damages  were  waived  because  Ste¬ 
vens,  now  72  and  retired,  wears  only  T- 
shirts  collected  over  the  years  from  soft¬ 
ware  conferences  and  vendor-supplied  re¬ 
viewer’s  packages,  and  Ghoats  was  afraid 
Stevens  would  insist  on  wearing  the  rare 
and  now-collectible  “Foobar  ’til  your 
pointer  drops!”  edition  given  out  at  the 
1995  FoobarSoft- Woodstock  Grog  and  Gra¬ 
nola  Festival  and  subsequently  banned 
in  Berkeley. 


The  indulgence  to  which  I  just  sub¬ 
jected  you  is  not  as  far-fetched 
as  it  seems.  The  Supreme  Court 
ruling  really  happened.  We  col¬ 
umnists  and  product  reviewers  better 


Al  Stevens 


watch  our  step.  How  far  can  this  new 
attitude  reach?  If  I  discuss  a  compiler, 
editor,  or  debugger  in  this  column  and 
do  not  like  it,  my  opinion  becomes 
lawyer  fodder.  If  the  program  lacks 
features,  is  my  opinion  that  the  lack 
constitutes  a  deficiency  factual  or  is  it 
libel?  Who  will  be  the  first  to  test  it? 

How  far  do  the  implications  of  this 
decision  reach?  Is  this  opinionated  ti- 
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rade  of  mine  libelous  to  the  Supreme 
Court  itself?  Wow!  How’d  you  like  to 
be  sued  by  a  bunch  of  Supreme  Court 
justices? 

DES  Revisited 

In  September  I  published  a  C  implemen¬ 
tation  of  the  Data  Encryption  Standard 
(DES)  algorithm.  I  built  it  from  the  Na¬ 
tional  Bureau  of  Standards  FIPS  PUB 
46  document  which  describes  the  algo¬ 
rithm.  I  lamented  the  lack  of  a  valida¬ 
tion  suite  of  data  that  would  allow  me 
to  determine  if  the  algorithm  would 
comply  with  the  specification.  Without 
one  I  plodded  ahead  anyway.  The  pro¬ 
grams  seemed  to  work.  They  did  a 
dandy  job  of  mangling  a  file  beyond 
recognition  and  putting  it  back  in  a 


usable  format  again. 

Richard  Feezel,  a  reader,  sent  me  a 
message  on  CompuServe  saying  that 
he  had  compared  the  output  from  my 
programs  with  that  of  a  hardware  board 
that  implemented  DES,  and  the  results 
were  different.  He  spent  a  good  bit  of 
time  looking  at  the  code  and  pointed 
out  some  likely  problems.  Richard  did 
not  have  the  DES  document,  so  he 
couldn’t  tell  where  the  code  was  going 
astray  or  if  the  board  and  my  programs 
were  just  different  implementations. 
Later  he  told  me  that  he  found  public 
domain  DES  code  and  validation  data 
on  CompuServe.  The  DES  hardware 
he  was  using  passed  the  tests  provided 
by  the  validation  data. 

That  was  good  news.  I  really  needed 
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a  validation  data  file.  The  DES  code  in 
the  download  was  a  bonus  that  turned 
out  to  be  a  life  saver.  You  will  remem¬ 
ber  that  the  DES  algorithm  involves  a 
lot  of  loops  of  permutations  of  bit  pat¬ 
terns.  An  implementor  needs  a  sequence 
of  data  blocks  that  represent  the  in¬ 
terim  steps  that  the  algorithm  takes. 
The  input  and  output  examples  were 
helpful  but  only  to  tell  if  the  program 
was  working  or  failing.  Nothing  really 
points  you  to  the  particular  place  in  the 
procedure  where  the  first  failure  oc¬ 
curs.  The  DES  algorithm  goes  into  a 
loop  where  halves  of  a  64-bit  data  block 
are  permuted,  swapped,  and  mangled 
with  a  value  derived  from  the  key.  The 
first  error,  no  matter  how  small,  is  go¬ 
ing  to  spread  like  a  mushroom. 

The  big  help  came  from  the  program 
that  the  validation  data  file  accompa¬ 
nied.  It  is  a  public  domain  C  program 
first  implemented  by  James  Gillogly  and 
later  modified  by  Phil  Karn.  You  can 
find  it  on  CompuServe  as  file  DES. ARC 
in  Data  Library  3  of  the  IBMPRO  forum. 
It  is  no  doubt  available  on  other  BBSs 
and  online  services.  The  program,  which 
was  written  some  time  ago,  does  not 
use  ANSI  C  conventions  but  the  authors 
have  included  a  version  that  compiles 
with  Turbo  C,  warnings  and  all. 

By  following  the  progress  of  the  Gil- 


logly/Karn  program  and  comparing  its 
results  to  those  of  my  program,  I  was 
able  to  correct  the  problems.  Because 
of  the  data  permutations  in  DES,  I  was 

The  DES  specification 
says  that  the  least 
significant  bit  of  each 
byte  of  the  key  may  be 
for  a  parity  bit  or 
whatever  you  want 
it  to  be 


sure  that  my  implementation  of  the 
staicture  of  the  algorithm  was  sound. 
It  was  encrypting  and  decrypting  large 
files  without  losing  any  data.  The  prob¬ 
lems  had  to  do  with  the  internal  repre¬ 
sentations  of  data  blocks  causing  the 
programs  to  permute  differently  than 
they  should.  And  so  they  were,  most 
of  them.  I  cleared  up  most  problems 
by  using  a  swapbyte  function  that 


changes  the  byte  order  of  a  long  inte¬ 
ger  from  aabbccdd  to  ddccbbaa.  The 
Gillogly/Karn  program  uses  such  a  func¬ 
tion  but  only  in  the  Turbo  C  version. 
Apparently  the  byte/word  architecture 
of  the  original  machine  does  not  order 
the  bytes  in  the  backward  view  of  8- 
and  16-bit  machines  that  has  plagued 
me  ever  since  I  first  saw  a  PDP-11. 

There  were  a  few  other  problems.  I 
was  not  rotating  the  key  schedule  out¬ 
put  correctly.  That  was  a  bug  that  did 
not  prevent  the  programs  from  encrypt¬ 
ing  and  decrypting,  but  the  encrypted 
data  blocks  were  not  compatible  with 
the  DES  specification  and  probably  not 
as  secure. 

David  Dunthorn  of  Oak  Ridge,  Ten¬ 
nessee  wrote  that  my  observation  about 
the  8-bit  value  being  preserved  in  the 
encrypted  file  means  that  my  DES  code 
was  not  working  correctly.  How  true. 
The  behavior  I  saw  was  a  byproduct 
of  the  other  problems  and  led  me  to  a 
false  conclusion.  Mr.  Dunthorn  pro¬ 
vided  data  examples  which  can  serve 
to  test  a  DES  implementation.  Example 
1  provides  three  of  the  examples  he 
sent.  The  code  in  this  month’s  column 
correctly  processes  these  examples  as 
well  as  that  in  the  downloaded  valida¬ 
tion  data  and  the  other  examples  from 
Mr.  Dunthorn. 
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Mr.  Dunthorn  continues: 

The  algorithm  for  DES  is  so  intercon¬ 
nected  that  if  a  program  does  even  a  few 
examples  correctly,  it  has  a  very  high 
probability  of  being  correct.  A  one  bit 
change  anywhere  will  yield  an  entirely 
different  result,  not  something  that  is 
just  a  little  bit  off.  ...  It  is  something  of 
a  challenge  to  get  DES  operating  cor¬ 
rectly  even  when  working  from  the  speci¬ 
fication. 

I’ll  say. 

The  DES  specification  says  that  the 
least  significant  bit  of  each  byte  of  the 
key  may  be  for  a  parity  bit  or  whatever 
you  want  it  to  be,  and  so  the  algorithm 
ignores  the  least  significant  bit  of  the 
key.  When  my  program’s  output  did 
not  match  the  output  from  the  Gillogly/ 
Karn  program,  I  found  that  they  were 
using  the  most  significant  bit  for  parity 
and  I  was  not.  The  DES  specification 
is  not  concerned  with  the  implementa¬ 
tion  problems  associated  with  such 
things  as  files  and  key  parity.  The  speci¬ 
fication  addresses  how  you  encrypt  and 
decrypt  8-byte  blocks  of  data  with  an 
8-byte  key.  The  parity  code  in  the  Gil- 
logly/Karn  program  is  in  an  outer  shell 
that  manages  the  files  and  key  and  calls 
the  inner  encryption  and  decryption 
code.  The  inner  algorithms  comply  with 
the  DES  specification.  From  this  I  real¬ 
ized  that  different  complying  DES  pro¬ 
grams  that  encrypt  and  decrypt  data 
files  will  not  always  be  compatible.  I 
added  the  odd  parity  logic  to  my  pro¬ 
gram  so  that  I  could  encrypt  and  de¬ 
crypt  files  interchangeably  between  my 
program  and  the  downloaded  one  to 
test  the  algorithm. 

The  documentation  that  came  with 
the  Gillogly/Karn  program  identified 
the  DES  Cipher  Block  Chaining  (CBC) 
mode,  something  that  is  not  addressed 
in  the  NBS  1977  FIPS  PUB  DES  specifi¬ 
cation,  although  the  program  uses  the 
CBC  mode  as  a  default.  That  had  me 
going  for  a  while.  In  the  CBC  mode, 
the  previous  ciphered  block  of  8  bytes 
is  exclusive-orred  with  the  current  un¬ 
encrypted  block  before  the  program 
encrypts  the  current  block.  The  other 
mode,  which  bypasses  the  extra  en¬ 
cryption,  is  the  Electronic  Code  Book 
mode.  That  is  the  mode  supported  by 
my  programs.  The  Gillogly/Karn  pro¬ 
gram  implements  the  CBC  mode  out¬ 
side  of  the  DES  code,  so  that  is  another 
area  where  implementations  will  differ. 

I  mentioned  in  September  that  the 


DES  algorithm  has  a  shortcoming.  Be¬ 
cause  it  encrypts  blocks  of  8  bytes  by 
mangling  and  scattering  the  bits  all  over 
the  block,  an  encrypted  file  must  nec¬ 
essarily  have  a  length  that  is  a  multiple 
of  8  bytes.  The  DES  algorithm  has  no 
way  to  know  the  actual  length  of  that 
last  block.  In  some  applications  the 
precise  end-of-file  location  is  critical 
to  the  use  of  the  file.  The  Gillogly/Karn 
program  records  the  length  of  the  last 
block  in  the  last  byte  of  the  file.  If  the 
file  is  an  even  multiple  of  8  bytes,  the 
algorithm  adds  a  block  with  that  infor¬ 
mation  in  it.  This  approach  solves  the 
problem,  but  it  is  not  a  part  of  the  DES 
specification.  As  with  the  other  exter¬ 
nal  extensions,  this  solution  produces 
a  file  format  that  would  not  be  compat¬ 
ible  with  other  implementations. 

Probably  the  most  significant  differ¬ 
ence  between  the  two  implementations 
is  in  their  execution  speed.  The  Gillogly/ 
Karn  program  is  faster.  They  do  not 
implement  all  the  permutations  by  us¬ 
ing  tables  the  way  I  did.  Rather,  to 
improve  performance,  they  use  certain 
characteristics  of  the  table  values  to 
code  some  of  the  permutations  with 
shifts  and  masks.  The  cost  for  those 
performance  improvements  is  that  the 
code  is  difficult  to  understand  in  places. 
Often  I  could  not  compare  their  in¬ 
terim  results  with  mine  because  our 
approaches  were  different  enough  that 
there  were  no  corresponding  data  pat¬ 
terns  to  compare. 

The  “C  Programming”  column  is  as 
much  about  C  code  as  it  is  about  algo¬ 
rithms,  so  I  did  not  attempt  to  incorpo¬ 
rate  any  of  the  Gillogly/Karn  perfor¬ 
mance  improvements.  If  I  were  using 
DES  in  a  small  file  environment,  such 
as  an  electronic  mail  application,  I 
would  probably  use  my  programs  be¬ 
cause  they  would  be  easier  for  me  to 
understand  and  maintain.  For  applica¬ 
tions  involving  large  files  I  would  adapt 
the  Gillogly/Karn  algorithm  to  gain  its 
performance  benefits.  Or  I  would  search 
out  some  of  the  assembly  language 
implementations  that  are  even  faster. 

I  changed  the  structure  of  the  pro¬ 
grams  to  isolate  the  DES  algorithms 
from  the  code  that  manages  the  key 
and  the  files.  You  will  find  the  cor¬ 
rected  and  modified  DES  programs  here 
in  Listing  One,  des.h  (page  164),  List¬ 
ing  Two,  main.c  (page  164),  Listing 
Three,  des.c  (page  164),  and  Listing 
Four,  tables. c  (page  165).  Compile  and 
link  everything  into  an  executable  pro- 


Key:  D123456789A3CDEF  0123456789A8CDEF  0123456789ABCDEF 
Text:  4E6F772069732074  68652074696D6520  666F722061 6C6C20 
Encr:  3FA40E8A984D4815  6A271787AB8883F9  893D51EC4B563B53 


Example  1:  Data  examples  for  DES  testing 
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gram  named  “des.exe.”  Instead  of  sepa¬ 
rate  encrypt  and  decrypt  programs,  such 
as  we  had  in  September,  the  des  pro¬ 
gram  handles  both  functions.  You  spec¬ 
ify  -e  or  -d  as  the  first  command  line 
parameter  to  tell  the  program  which 
operation  to  perform.  The  second  pa- 

The  crypto  program  was 
like  a  bicycle  lock.  It 
would  deter  the  casual 
interloper ;  but  the 
serious  thief  has  the  tools 
and  skills  to  get  past  it 

rameter  is  the  8-byte  key  and  the  third 
and  fourth  parameters  are  the  input 
and  output  filenames. 

You  can  incorporate  the  DES  func¬ 
tions  into  your  own  programs  by  in¬ 
cluding  des.h  and  linking  to  des.c  and 
tables. c.  Call  the  initkey  function  with 
the  address  of  your  8-byte  key  as  an 
argument.  Then  call  either  the  encrypt 
or  decrypt  function  once  for  each  8- 
byte  block  in  the  data  you  want  to 
encrypt  or  decrypt.  Both  functions  ac¬ 
cept  a  pointer  to  the  8-byte  block  where 
the  input  to  and  output  from  the  algo¬ 
rithm  will  go. 

The  CRYPTO  Program 

A  reader  named  Dave  called  to  say  that 
crypto. c,  my  first  example  of  a  simple 
encryption/decryption  algorithm  was 
not  very  good.  It  seems  that  he  en¬ 
crypted  a  file  that  had  long  strings  of 
zero  bytes.  The  crypto  program  en¬ 
crypts  and  decrypts  by  simply  exclusive- 
orring  the  8-byte  key  with  each  succes¬ 
sive  8-byte  block  of  the  data  file.  When 
the  file  has  strings  of  zero  bytes,  the 
encrypted  value  is  the  key  itself. 

I  designed  crypto.c  to  encrypt  ASCII 
electronic  mail  message  text,  which 
never  has  strings  of  zero-value  bytes.  I 
should  have  warned  you  about  that 
particular  behavior,  however. 

Another  reader,  Roberto  Quijalvo  of 
Plantation,  Florida  wrote  to  point  out 
that  if  your  ASCII  text  file  has  strings 
of  spaces  and  the  key  is  also  ASCII  text, 
the  exclusive-or  inserts  the  key  into  the 
text  with  a  case  change.  That  one  never 
bit  me  because  my  ASCII  files  go 
through  a  run-length  encoder,  which 
truncates  trailing  white  space  from  lines 
and  compresses  other  runs  of  charac¬ 
ters  into  escape  sequences  prior  to  en¬ 
cryption.  That  process  was  not  for  en¬ 


cryption,  though,  but  for  compression 
minimize  transmission  time. 

Mr.  Quijalvo  contributed  some  code 
+to  internally  mangle  the  key.  He  says 

A  slight  alteration  in  [the]  code  would 
make  it  more  difficult  to  discover  the 
key: 

/*  original  code  segment  */ 
while  (*cpl  &&  cpl  <  argv[l]  +8) 
*cp2++  “=  *cpl++; 

/*  altered  code  segment  */ 
while  (*cpl  &&  cpl  <  argv[l]  +8) 
*cp2++  “= 

(*cpl<0x41 ?  *cpl++  : 

*cpl++  -  0x40  )  ; 

By  checking  the  key  for  a  character 
greater  than  0x40  C@’)  and  changing 
any  alpha  character  to  a  non-alpha  char¬ 
acter  before  using  it,  the  key  can  be 
saved  from  experiencing  such  embar¬ 
rassingly  blatant  exposure. 

Francis  Rocks  of  Berwyn,  Pennsylva¬ 
nia  reported  the  same  problem  and 
offered  a  different  solution.  Francis  says, 

A  solution  would  be  to  eliminate  hex 
20  (blank)  encoding  with  the  following 
code  replacing  your  second  “while”  con¬ 
struct: 

while  (*cpl  && cpl  <  argv [  1]  +8)  { 
if  (*cp2  ! =  0x20)  { 

*cp2++  ~=  *cpl++; 

1 

else  { 

*cp2++; 

*cpl++; 

1 

1 

All  three  readers  thought  that  crypto.c 
was  less  secure  than  it  ought  to  be, 
which  it  is  if  you  use  it  outside  of  a 
controlled  data  environment  such  as 
the  one  I  built  the  algorithm  for. 

These  modifications  are,  of  course, 
merely  moves  to  beef  up  a  simple  algo¬ 
rithm  whose  original  intent  was  only 
to  momentarily  divert  the  merely  curi¬ 
ous,  which  is  the  cause  for  encryption 
for  most  of  us.  In  more  hostile  sur¬ 
roundings  if  the  invader  knows  that  the 
text  is  encrypted,  he  or  she  must  dis¬ 
cover  the  algorithm  as  well  as  the  key. 
Because  the  exclusive-or  algorithm  is 
a  common  one,  the  appearance  of  any 
repeated  pattern,  even  the  mangled  key, 
would  tend  to  alert  the  spy  to  the  pos¬ 
sibility  of  exclusive -orring  the  entire 
message  with  different  permutations  of 
that  pattern  to  see  what  would  happen. 
Rocks’s  solution  works  only  for  the 
strings  of  spaces.  But  if  a  file  has  re7 
peated  strings  of  other  values,  fixed 
permutations  of  the  key  are  going  to 
be  in  there,  and  a  codebreaker  will 
exploit  the  patterns. 
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The  crypto  program  was  like  a  bicy¬ 
cle  lock.  It  would  deter  the  casual  in¬ 
terloper,  but  the  serious  thief  has  the 
tools  and  skills  to  get  past  it.  If  you 
need  to  be  that  secure,  you  need  some¬ 
thing  other  than  crypto. 

Listing  Five,  page  166,  and  Listing 
Six,  page  166,  are  encrypto.c  and  de- 
crypto.c,  two  programs  that  eliminate 
the  exposed  key  problems  that  crypto. c 
has  with  text  files.  I  combined  the  run- 
length  encoding  algorithm  of  my  text 
compresser  and  the  encryption  of  the 
crypto. c  program  into  these  two  pro¬ 
grams.  Besides  encrypting  and  decrypt¬ 
ing,  they  compress  runs  of  duplicate 
characters  into  a  simple  escape  se¬ 
quence.  The  programs  work  only  with 
ASCII  text  files. 

The  encrypto.c  program  translates 
any  run  of  two  or  more  duplicated 
characters  into  2  bytes.  The  first  byte 
is  the  count  of  the  run  with  the  most 
significant  bit  set  on.  The  second  byte 
is  the  duplicated  character.  Because 
the  algorithm  uses  the  most  significant 
bit  to  identify  a  run-length  counter,  it 
works  only  with  7-bit  ASCII  files  and 
will  terminate  if  it  finds  a  most  signifi¬ 
cant  bit  set  in  the  input  file.  After  en¬ 
crypto.c  compresses  the  text,  it  encrypts 
it  in  blocks  with  lengths  equal  to  that 
of  the  key’s  length.  The  compression 
and  encryption  are  done  in  one  pass 
of  the  file. 

The  decrypto.c  program  reverses  the 
compression/encryption  process.  It  de¬ 
crypts  the  characters  and  then  decom¬ 
presses  them. 

The  crypto. c  program  in  September 
used  a  fixed-length  key  of  8  bytes,  en¬ 
crypto.c  and  decrypto.c  take  the  key 
length  that  is  entered  and  encrypt/ 
decrypt  blocks  of  that  length. 

I  considered  writing  an  identifying 
signature  at  the  front  of  the  encrypted 
file  so  that  the  decrypto.c  program  could 
verify  that  it  was  being  asked  to  decrypt 
a  properly  encrypted  file.  I  rejected  this 
idea  because  an  outsider  who  inter¬ 
cepted  the  file  might  then  know  which 
program  encrypted  it.  I  then  consid¬ 
ered  encrypting  the  signature.  I  rejected 
that  idea  as  well.  A  codebreaker  who 
already  knew  the  algorithm  would  then 
have  a  known  data  value  from  which 
to  reverse-engineer  the  key. 

While  not  immune  to  the  attacks  of 
a  persistent  codebreaker,  the  algorithms 
in  encrypto.c  and  decrypto.c  are  more 
secure  than  those  of  the  simpler  crypto. c 
program  from  September  and  far  less 
complex  than  those  of  DES. 

DDJ 

(Listings  begin  on  page  164.) 
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Ice  Cubes  in  the 
Swimming  Pool 


e  careful  what  you  ask  for,  chil¬ 
dren:  You  might  get  it. 

Consider:  It’s  hot  out  here  in 
North  Phoenix,  so  hot  that  by 
August  the  swimming  pools  have  be¬ 
come  too  warm  to  be  refreshing.  The 
best  you  can  do  is  jump  in  and  jump 
immediately  out  again  in  the  hope  that 
the  single-digit  humidity  will  cool  you 
off  by  rapid  evaporation.  If  you  have  a 
solar  pool-heating  system,  you  can  cool 
the  water  by  running  it  at  night,  so  that 
the  hot  water  warms  the  panels  and 
radiates  heat  into  the  clear  desert  mid¬ 
night  sky. 

No  such  luck  here  until  we  move 
into  our  new  house,  and  by  then  sum¬ 
mer  will  be  little  more  than  a  memory 
with  smoke  wafting  off  of  it.  So  when 
I  mailed  invitations  to  one  of  our  regu¬ 
lar  parties,  I  made  it  plain  to  our  guests: 
The  pool  temperature  had  gone  over 
90  degrees,  and  if  it  got  any  hotter  I’d 
have  to  throw  some  ice  cubes  into  it. 

It  was  105  degrees  the  afternoon  of 
the  party,  and  no  one  was  in  the  pool. 
Come  seven  PM,  we  had  finished  din¬ 
ner  and  were  talking  hacker-talk  out 
on  the  patio.  The  wind  was  rising 
sharply,  and  we  saw  the  flashes  of  dis¬ 
tant  lightning  in  the  north.  Low  clouds 
rolled  over  the  sun,  and  behind  them 
came  roiling  clouds  of  red  dust  from 


Jeff  Duntemann,  KI6RA/7 


the  desert  just  north  of  town. 

The  storm  hit  like  a  hammer,  taking 
the  temperature  from  105  down  to  75 
almost  instantly,  with  continuous  light¬ 
ning  and  winds  gusting  to  70  miles  per 
hour  amidst  torrential  rain.  Then,  as 
though  that  weren’t  enough,  it  started 
to  hail. 

Big  chunks  of  ice  riding  a  70  mph 
wind  are  lethal  missiles.  We  tumbled 


inside  and  watched  in  amazement  as 
the  storm  poured  wave  after  wave  of 
hailstones,  some  rivaling  golf  balls,  into 
the  yard.  Ten  minutes  later,  there  were 
hailstone  drifts  three  inches  deep  be¬ 
side  the  fence,  and  a  thick  layer  of 
hailstones  bobbed  steaming  in  our  pool. 

Out  in  front,  10th  Avenue  was  a  river, 
carrying  broken  tree  branches  and  frag¬ 
ments  of  redwood  fence.  Power  was 
out  for  most  of  the  night. 

But  I  had  managed  to  get  some  ice 
into  the  pool. 

Modulus  Vobiscum 

Similarly,  I  got  what  I  asked  for  —  and 
then  some  —  when  I  swore  up  and 
down  that  I  would  figure  out  what  was 
eating  my  day-of-the-week  function, 
CalcDayO/Week.  Part  of  that  adven¬ 
ture  was  detailed  last  month,  in  my 
recreation  of  a  Pascal  and  Modula-2 
implementation  of  Zeller’s  Congruence 
from  the  original  source,  a  scholarly 
paper  that  Zeller  published  in  1887. 
(Zeller’s  Congruence,  in  case  you’re 
just  tuning  in,  is  an  algorithm  that  cal¬ 
culates  the  day  of  the  week,  given  the 
year,  month,  and  day.) 

I  left  you  with  an  implementation 
that  worked  fine.  There  was  a  worm 
in  it,  though:  In  order  to  make  the 
algorithm  return  correct  dates  in  all 
cases,  I  had  to  ensure  that  Turbo  Pas¬ 
cal’s  MOD  operator  never  acted  upon 
a  negative  quantity.  In  other  words, 
rather  than  evaluate  -17  MOD  7,  I 
added  7  repeatedly  to  -17  until  the 
sum  surfaced  on  the  plus  side  of  zero. 
That  quantity  then  became  the  first  op¬ 
erand  of  the  MOD  operator.  (See  last 
month’s  code  listings  if  you  don’t  quite 
see  what  I  mean.)  This  is  a  kluge  by  the 
classic  definition,  which  is  to  say,  some¬ 
thing  that  works  right  for  all  the  wrong 
reasons.  (And  the  wrongest  reason  of 
all  is  not  having  any  idea  whatsoever 


why  it  works  right!) 

I’d  heard  whispers  for  years  that 
Turbo  Pascal’s  X  MOD  Y  operator  wasn’t 
quite  kosher,  but  nobody  I  knew  could 
define  just  what  was  wrong  with  it.  All 
my  tests  indicated  that  it  did  just  what 
the  modulus  operation  was  supposed 
to  do:  Calculate  an  integer  division  of 
the  first  operand  by  the  second,  then 
return  the  remainder  of  that  division. 
The  dividend  is  thrown  away  unused. 
(That’s  what  the  X  DIV  Y  operator  is 
for.)  No  matter  what  combination  of 
positive  and  negative  integers  I  used, 
every  calculation  agreed  with  my  pains¬ 
taking  pencil-and-paper  work.  (How 
many  pocket  calculators  will  show  you 
a  remainder?  Not  mine  .  .  .  .)  I  began 
to  consign  those  rumors  of  MOD’S  in¬ 
competence  to  base  canards,  but  then 
a  disturbing  possibility  turned  up  out 
of  a  conversation  in  the  mathematics 
conference  on  BIX:  That  the  way  Turbo 
Pascal  and  I  understood  the  modulus 
operator  was  subtly  but  ruinously  dif¬ 
ferent  from  the  way  the  mathematics 
community  —  and  hence  Zeller  him¬ 
self  —  understood  it. 

Which  Way  is  the  Floor? 

My  head  first  started  to  spin  when  some¬ 
one  known  to  me  only  as  “seba”  posted 
the  following  definition  for  the  modu¬ 
lus  operator: 

X  MOD  Y  =  X-Y1X/Y] 

where  [X/Y]  is  the  greatest  integer  less 
than  or  equal  to  X/Y.  This  sure  didn’t 
look  like  taking  the  remainder  and  toss¬ 
ing  the  dividend,  and  it  sure  wasn’t.  I 
first  implemented  this  equation  the  fol¬ 
lowing  way: 

X-(Y*Trunc(X/Y)) 

This,  again,  worked  for  positive  values 
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of  Abut  not  for  negative  values.  After 
considerable  head  scratching,  I  real¬ 
ized  that  truncating  a  real  number  value 
such  as  that  produced  by  X/Y  always 
moves  the  value  toward  zero  on  the 
number  line.  This  is  fine  for  positive 
values,  but  for  negative  values,  moving 
toward  zero  makes  the  value  greater 
than  X/Y  rather  than  less.  Implement¬ 
ing  the  equation  for  negative  values 
has  to  be  done  this  way: 

X-  (Y*Trunc((X/Y)  -1)) 

Decrementing  the  value  of  the  expres¬ 
sion  X/Y  by  one  ensures  that  truncating 
the  expression  returns  the  largest  inte¬ 
ger  less  than  X/Y. 

Combining  the  two  cases  into  one 
Modulus  function  is  easy,  and  the  re¬ 
sult  is  the  function  given  in  Listing  One 
(page  167). 

Modulus  Roulette 

If  you  have  yet  to  grok  the  fullness  of 
this  new  equation  describing  the  modu¬ 
lus  operator,  have  faith  —  I  trust  it 
because  it  works,  not  because  it’s  “obvi¬ 
ous”  to  me.  For  it  to  become  obvious, 

I  have  to  look  to  a  graphical  interpreta¬ 
tion  of  the  modulus  operator,  some¬ 
thing  I  learned  in  eighth  grade  during 
a  brief  brush  with  the  New  Math  Mon¬ 
ster  and  haven’t  thought  about  since 
1966.  To  implement  the  modulus  op¬ 
erator  graphically,  follow  the  example 
shown  in  Figure  1.  To  take  At  modulus 
Y,  draw  a  circle  of  digits  starting  from 
Oand  running  to  Y-l.  In  Figure  1,  I’m 
setting  up  the  circle  to  take  At  modulus 
7,  as  required  by  Zeller’s  Congruence. 

With  the  circle  in  place,  start  at  0  and 
count  around  the  circle  by  At  positions. 
(Tap  each  digit  with  a  pencil  eraser  if 
you  have  to  —  I  did,  and  I  won’t  laugh 


if  you  do  too.)  Here’s  the  kicker:  If  N 
is  positive,  move  around  the  circle  in  a 
clockwise  direction.  If  N  is  negative, 
move  around  the  circle  in  a  counter¬ 
clockwise  direction.  Try  it  right  now 
with  the  numbers  1 7  (clockwise)  and 

I’d  heard  whispers  for 
years  that  Turbo 
Pascal’s  X  MOD  Y 
operator  wasn’t  quite 
kosher,  but  nobody  I 
knew  could  define  just 
what  was  wrong  with  it 


-17 ('counterclockwise. )  Your  answers 
should  be: 

17  modulus  7  =  3 

-17  modulus  7  =  4. 

Note  that  I  didn’t  call  the  operator 
MOD.  By  now  it  was  clear  to  me  that 
MOD  and  modulus  are  two  different 
operators.  Turbo  Pascal  and  Turbo  C++ 
calculate  17  modulus  7  =  3  but  -17 
modulus  7  =  - 3 ■  In  all  cases,  -N  MOD 
Y  is  simply  -  (1 V  MOD  Y),  which  is 
what  you  would  expect  if  MOD  returns 
the  remainder  of  a  simple  division. 
Unfortunately,  what  we  call  MOD  Zeller 
would  have  called  the  remainder  func¬ 
tion.  And  that  in  a  nutshell  was  what 
was  wrong  with  CalcDayOfWeek.  (The 
final  implementation  of  CalcDayOfWeek 


using  Zeller’s  Congruence  is  given  in 
Listing  Two,  page  167.)  It  wasn’t  really 
a  bug  in  Turbo  Pascal.  What  TP  calls 
MOD  is  really  the  remainder  function, 
and  if  what  you  need  is  the  remainder 
function  it  will  work  without  a  hitch 
every  time. 

However,  if  you’ve  ever  implemented 
an  algorithm  from  the  literature  of  mathe¬ 
matics  that  calls  for  the  modulus  opera¬ 
tor  and  used  MOD,  your  algorithm  will 
go  wonky  any  time  the  first  operand 
of  modulus  goes  negative.  Check  it 
out.  Now.  I  suspect  the  problem  may 
be  present  in  many  more  compilers 
than  Borland’s.  If  you’re  not  using  Turbo 
Pascal,  bring  up  your  compiler  and 
evaluate  -17  MOD  7.  If  you  get  any¬ 
thing  but  4,  you’ve  got  remainder  or 
something  else,  not  true  modulus. 

Thus  ends  the  tale  of  what  is  cer¬ 
tainly  the  most  amazing  single  bug  in 
my  very  full  notebook  of  bug  hunts. 

BGI  Hardcopy 

Sometimes  you  wonder  why  it  takes 
as  long  as  it  does  for  certain  new  prod¬ 
ucts  to  appear.  Ever  since  Borland  first 
released  the  BGI  with  Turbo  Pascal 
4.0,  there’s  been  this  gaping  hole  in 
BGI  functionality:  hardcopy.  While  nu¬ 
merous  utilities  exist  to  zip  a  displayed 
graphics  screen  out  to  the  printer,  this 
requires  that  the  graphics  image  first 
appear  on  the  screen.  If  you  want  to 
use  the  screen  for  something  else,  you’re 
simply  out  of  luck. 

Enter  Graf/Drive  Plus  from  Fleming 
Software.  The  notion  is  elegant:  A  BGI 
driver  that  sends  BGI  output  to  a 
hardcopy  device  rather  than  a  video 
device.  In  other  words,  rather  than  load 
a  driver  for  the  EGA  or  Hercules  graph¬ 
ics  adapters,  you  load  a  driver  for  the 
Epson  or  LaserJet  printers  or  one  of  the 
supported  HP  plotters.  Then,  when  you 
execute  a  standard  BGI  statement  such 
as  Circle  or  OutTextXY,  the  graphics 
go  to  paper  rather  than  to  the  screen. 

All  BGI  functions  that  make  sense 
for  hardcopy  are  supported.  (Those  that 
don’t  are  things  such  as  Getlmage,  Put- 
Image ,  and  palette  control  routines.) 
The  package  works  with  Turbo  Pascal 
(5.x),  Turbo  C  2.0,  and  Turbo  C++  1.0. 
Printers  currently  supported  are  the  HP 
LaserJet  series,  Epson  MX/FX  80  and 
compatibles,  the  Epson  LQ1500  and 
compatibles,  and  the  HP  7470A  and 
747 5A  pen  plotters.  Several  new  print¬ 
ers  will  be  supported  by  the  time  you 
read  this,  including  PostScript,  the  HP 
PaintJet,  the  HP7585  plotter,  and  the 
Toshiba  and  IBM  QuietWriter  printers. 

Graf/Drive  Plus  does  exactly  what  it 
says  it  does.  I’ve  had  no  trouble  mak¬ 
ing  it  work  and  can  trace  no  crashes 
(continued  on  page  1 59) 


Figure  1:  A  graphical  interpretation  of  the  modulus  operator 
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(continued  from  page  156) 
or  other  bugs  to  its  use.  The  individual 
drivers  are  fairly  small  (less  than  16K) 
and  can  be  linked  into  your  .EXE  im¬ 
age  just  as  any  BGI  driver  can  be.  The 
hacking-around  license  is  $149;  if  you 
purchase  a  developers’  license  ($299) 
you  can  distribute  the  drivers  with  your 
application  without  further  royalty  ob¬ 
ligations. 

Lord  knows,  something  like  this 
should  have  been  done  years  ago. 
Highly  recommended. 

Comdex  Approaches 

A  lot  of  developers  don’t  go  to  Comdex 
anymore.  They  say,  rightfully,  that  it’s 
a  hardware  show,  but  that’s  all  the  more 
reason  to  hock  your  firstborn  and  truck 
on  out  there.  For  the  little  guy,  it’s  a 
niche-filler’s  game  these  days,  and  you 
have  to  remember  that  a  software  niche 
is  an  idea  delimited  by  available  hard¬ 
ware.  And  the  one  thing  a  lone  wolf 
can  do  better  than  all  the  armies  of  IBM 
is  have  ideas. 

It  happens  to  me  every  year:  I  prowl 
the  aisles  (especially  in  the  third-tier 
hotels  where  the  weird  stuff  ends  up) 
and  wait  for  the  hardware  on  display 
to  suggest  new  applications  to  me.  I’m 
in  the  magazine  business  rather  than 
the  software  business  these  days,  but 
the  ideas  come  nonetheless.  And  some¬ 
times  the  triggering  products  are  not 
even  “hardware”  in  the  familiar  sense: 
Last  year  I  saw  a  firm  dealing  in  custom- 
perfed  sheets  of  paper  for  computer 
printed  tear-out  coupons,  and  I  had 
this  notion  that  I  could  create  custom 
sheets  punched  and  perfed  to  tear  down 
into  pages  for  the  smallest  standard 
pocket  memo  book,  which  is  some¬ 
thing  only  a  little  larger  than  your  aver¬ 
age  business  card.  Feed  10  or  12  sheets 
through  your  laser  printer  with  the 
proper  software  interface  to  your  con¬ 
tacts  database  (including  an  eight-point 
font)  and  bang!  A  little  little  black  book! 

The  problem  of  marketing  your  soft¬ 
ware  still  remains  (looming  larger  than 
ever,  in  fact)  but  having  ideas  that  no¬ 
body  else  has  had  is  often  no  harder 
than  getting  out  and  exposing  yourself 
to  large  quantities  of  the  stuff  of  which 
our  industry  is  made. 


After  all,  lots  of  people  find  that  pac¬ 
ing  around  the  room  helps  shake  ideas 
loose.  At  Comdex,  you  can  pace  around 
some  of  the  largest  rooms  in  the  civi¬ 
lized  universe,  (in  fact,  to  see  it  all 
you’d  better  pace  at  something  close 
to  a  dead  run)  surrounded  by  the  larg¬ 
est  concentration  of  computer  stuff  that 
ever  happens  anywhere. 

If  you  can’t  get  ideas  there,  you  might 
as  well  go  back  to  selling  shower  cur¬ 
tains. 

Source  Code  Availability 

As  a  service  to  our  readers,  all  source 
code  is  available  on  a  single  disk  and 
online.  To  order  the  disk,  send  $14.95 


Products  Mentioned 

Graf/Drive  Plus 
Fleming  Software 
P.O.  Box  528 
Oakton,  VA  22124 
703-591-6451 
Personal  license.-  $149 
Developers’  license:  $299 


(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal,  501  Galveston  Drive, 
Redwood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Specify  issue  number  and 
disk  format.  Code  is  also  available 
through  M&T’s  Telepath  online  service 
(via  TYMNET)  and  through  the  DDJ  Fo¬ 
rum  on  CompuServe  (type  GO  DDJ). 

DDJ 

(Listings  begin  on  page  167.) 
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Object-Oriented 
Software  Development: 
Reality  Sets  In 


With  so  many  books  now  avail¬ 
able  on  particular  object-ori¬ 
ented  programming  langu¬ 
ages,  it  is  surprising  that  there 
aren’t  more  books  available  to  explain 
what  object-oriented  means.  Books  on 
C++  or  Smalltalk  tell  you  how  to  use 
these  languages  to  implement  a  sys¬ 
tem,  but  they  don’t  tell  you  much  about 
the  object-oriented  approach  to  design¬ 
ing  that  system  in  the  first  place. 

Those  books  which  have  been  writ¬ 
ten  on  object-oriented  design,  tend  to 
be  one-sided  using  Fred  Brooks’  pro¬ 
nouncements  to  describe  the  pitfalls 
and  tar  pits  of  traditional  software  de¬ 
velopment,  but  without  much  under¬ 
standing  of  the  potential  pitfalls  that 
object-oriented  design,  like  any  design 
principle,  is  bound  to  have. 

Grady  Booch’s  Object-Oriented  De¬ 
sign  with  Applications  isn’t  like  this.  It 
has  a  strong  sense  of  the  real-world 
issues  involved  with  adopting  and  us¬ 
ing  the  object-oriented  paradigm.  If  you 


Andrew  Schulman 


are  looking  for  a  magic  solution  to  the 
problems  of  software  development,  you 
will  probably  find  this  book  irritating. 
But  for  a  balanced  assessment  of  the 
pros  and  cons  of  object-oriented  soft¬ 
ware  development,  this  is  a  fine  place 
to  start. 

Towards  the  beginning  of  the  book, 
Booch  says  that  it  is  good  practice  to 
write  programs  “so  that  they  don’t  care 


Object-Oriented 
Design  with 
Applications 

Grady  Booch 
Redwood  City,  Calif.: 

The  Benjamin/Cummings 
Publishing  Co.,  1991 
580  pp„  $38.75 
ISBN  0-8053-0091-0. 

Object-Oriented 
Software 
Construction 

I  Bertrand  Meyer 
New  York,  N.Y.:  Prentice  Hall,  1988 
534  pp.,  $41.00 
ISBN  0-13-629049-3. 

about  the  physical  representation  of 
data.”  How  many  times  have  we  heard 
this  from  the  advocates  of  object-ori¬ 
ented  design?  How  many  times  can 
you  actually  write  non-trivial  programs 
that  are  in  fact  agnostic  as  to  the  physi¬ 
cal  representation  of  data? 

Well,  unlike  more  amateurish  books 
on  object-oriented  software  develop¬ 
ment,  Booch  doesn’t  sweep  these  is¬ 
sues  under  the  rug.  Chapter  7  (entitled 
“Pragmatics”)  is  particularly  good  at 
describing  the  potential  performance 
risks  of  object-oriented  design.  For  ex¬ 
ample,  Booch  plainly  states  that  object- 
oriented  software  rarely  has  “locality 
of  reference,”  so  that  special  measures 
must  be  taken  for  it  to  behave  on  sys¬ 


tems  with  paged  virtual  memory.  If  we 
care  about  performance  (!),  we  often 
must  care  about  the  physical  represen¬ 
tation  of  data  too.  And  while  object- 
oriented  software  can  actually  give  bet¬ 
ter  performance,  because,  for  exam¬ 
ple,  virtual  functions  eliminate  the  need 
for  some  explicit  type  checking,  on  the 
other  hand  it  can  often  result  in  code 
bloat.  Thus,  Booch  points  out  that  so¬ 
phisticated  compilers  and  linkers  with 
dead-code  elimination  are  needed  to 
fulfill  some  of  the  promise  of  object- 
oriented  software  development. 

Booch  also  shows  a  grave  concern 
with  “performance”  in  software  devel¬ 
opment  time.  Several  passages  are  de¬ 
voted  to  design  issues  that  affect  re¬ 
compilation.  “A  change  in  a  single  mod¬ 
ule  interface  might  result  in  many  hours 
of  recompilation.  Obviously,  a  man¬ 
ager  cannot  often  afford  to  allow  this” 
(p.  52).  “In  the  extreme,  recompilation 
costs  may  be  so  high  as  to  inhibit  de¬ 
velopers  from  making  changes  that  are 
reasonable  improvements”  (p.  205). 
Thus,  to  be  practical,  object-oriented 
software  development  also  cries  out 
for  incremental  compilers. 

Booch  discusses  the  key  issue  of  how 
an  organization  makes  the  transition 
to  object-oriented  software  develop¬ 
ment.  One  section  describes  the  “dark 
side”  of  start-up  costs;  Booch  makes 
the  reasonable  recommendation  that 
one  start  using  object-oriented  design 
in  a  low-risk  project  first.  The  book 
also  discusses  possible  organizational 
obstacles:  “Object-oriented  design 
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makes  it  possible  to  use  smaller  devel¬ 
opment  teams  ....  Unfortunately,  try¬ 
ing  to  staff  a  project  with  fewer  people 
than  traditional  folklore  suggests  are 
needed  may  produce  resistance.  Such 
an  approach  jeopardizes  the  attempts 
of  some  managers  to  build  empires” 

(p.  208). 

While  Booch’s  understanding  that  ev¬ 
ery  benefit  has  an  associated  cost  makes 
this  an  excellent  introduction  to  object- 
oriented  software  development,  I  found 
the  actual  discussions  of  design  less 
useful.  There  is  a  big  build-up  to  the 
chapter  on  “Classification”:  Presented 
with  a  problem,  how  do  you  find 
“where  the  objects  are”?  Somewhere 
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Booch  makes  the  central  point  that  not 
everything  is  an  object,  and  that  here, 
as  elsewhere,  there  is  no  prescription 
for  turning  a  problem  into  a  neat  bun¬ 
dle  of  classes  and  objects. 

But  the  chapter  on  “Classification” 
was  disappointing.  Booch  writes  here 
that  “To  the  developer  in  the  trenches 
fighting  changing  requirements  amidst 
limited  resources  and  tight  schedules, 
our  discussion  [of  classification  phi¬ 
losophy,  such  as  Wittgenstein  on  cate¬ 
gories!]  may  seem  to  be  far  removed 
from  the  battlefields  of  reality.  Actu¬ 
ally,  these  approaches  to  classification 
have  direct  application  to  object-ori¬ 
ented  design”  (p.  140).  Unfortunately, 


the  connection  is  never  really  made, 
making  this  chapter  the  book’s  one 
disappointment. 

The  entire  second  half  of  Object- 
Oriented  Design  With  Applications  con¬ 
tains  five  applications  in  five  languages: 
A  home  heating  system  in  Smalltalk,  a 
geometrical  optics  construction  kit  in 
Object  Pascal  (MacApp),  a  software 
house-bug  reporting  system  in  C++  (a 

Execution  of  an  Eiffel 
system  may  be  viewed 
as  a  cooperative 
race  between  two 
coroutines 


good  example  of  a  useful,  yet  low-risk 
project  for  an  organization  making  the 
transition  to  object-oriented  develop¬ 
ment  to  cut  its  teeth  on),  a  cryptanaly¬ 
sis  program  in  the  Common  LISP  Ob¬ 
ject  System  (CLOS),  and  a  traffic  man¬ 
agement  system  in  Ada  (Booch  is  well 
known  for  his  work  on  Ada). 

Booch  states  that  object-oriented  has 
emerged  as  a  “unifying  theme”  in  “di¬ 
verse  segments  of  the  computer  sci¬ 
ences.”  Apparently  this  theme  can  be 
useful  in  any  area  where  it  is  desirable 
to  close  the  “semantic  gap,”  and  he 
cites  several  examples  of  “object-ori¬ 
ented  operating  systems”  and  even  “ob¬ 
ject-oriented  hardware,”  including  the 
Intel  432  and  its  iMAX  operating  sys¬ 
tem.  On  the  other  hand,  the  RISC  para¬ 
digm  in  computer  architecture  asserts 
that  there  is  nothing  intrinsically  wrong 
with  the  “semantic  gap;”  object-oriented 
hardware  indeed  sounds  like  a  bad 
idea.  Still,  since  I  work  at  a  company 
which  produces  system  software  (Phar 
Lap,  makers  of  386 1  DOS-Extender), 
Booch’s  book  had  me  wonder  about 
the  possible  applicability  of  the  object- 
oriented  paradigm  to  low-level  soft¬ 
ware  such  as  ours.  Recently,  Microsoft 
has  been  talking  about  “object-oriented 
operating  systems.”  Frankly,  I’m  not 
convinced. 


While  reading  the  new  book  by  Grady 
Booch,  I  had  the  pleasure  of 
rereading,  for  the  third  time,  Bertrand 
Meyer’s  Object-Oriented  Software 
Construction.  This  is  still  the  standard 
work  on  the  topic,  and  the  best  expla¬ 
nation  of  what  all  the  object-oriented 
fuss  is  about. 

Meyer’s  book  describes  the  Eiffel  lan- 
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guage,  so  you  might  think  it  is  useless 
if  you  don’t  have  access  to  Eiffel.  But, 
by  using  a  programming  language  to 
which  the  reader  probably  doesn’t  have 
access,  Object-Oriented  Software  Con¬ 
struction  makes  you  concentrate  on  de¬ 
sign  issues,  not  on  the  peculiarities  of 
language  syntax. 

The  opening  sentence  of  the  book 
states  that  “The  principal  aim  of  soft¬ 
ware  engineering  is  to  help  produce 
quality  software.”  Yet,  “quality  in  soft¬ 
ware  is  best  viewed  as  a  tradeoff.”  Meyer 
also  emphasizes  the  importance  of  soft¬ 
ware  maintenance,  stating  that  it  is  “the 
hidden  part,  the  side  of  the  profession 
which  is  not  usually  highlighted  in  pro¬ 
gramming  courses.”  In  fact,  an  aware¬ 
ness  of  the  importance  of  maintenance 
has  been  one  of  the  driving  forces  be¬ 
hind  the  object-oriented  movement. 

Much  of  the  book  is  concerned  with 
issues  of  writing  correct  and  robust  soft¬ 
ware,  and  of  dealing  with  errors,  excep¬ 
tions,  failures,  and  abnormal  conditions. 
Some  of  this  material  appears  in  “Writ¬ 
ing  Correct  Software  with  Eiffel,”  by 
Bertrand  Meyer.  (See  either  DDJ,  De¬ 
cember  1989  or  DDJ  bound  volume 
14.)  A  glance  at  the  book’s  index  under 
the  entries  “exception”  and  “failure” 
will  point  you  to  several  lengthy  discus¬ 
sions  of  these  often-neglected  issues. 
The  sections  “Coping  with  Failure”  (pp. 
144-155)  and  “Dealing  with  Abnormal 
Cases”  (pp.  199-203)  are  superb. 

One  of  Meyer’s  key  techniques  for 
error  handling  is  the  assertion,  which 
he  refers  to  a  way  to  “include  specifica¬ 
tion  elements  within  the  implementa¬ 
tions  themselves”  (p.  112).  Meyer  in¬ 
troduces  a  “class  invariants”  notation 
which  is,  it  seems,  far  more  under¬ 
standable  than  notations  which  have 
appeared  in  books  such  as  Barbara 
Liskov  and  John  Guttag’s  Abstraction 
and  Specification  in  Program.  Develop¬ 
ment. 

Meyer  devotes  an  entire  chapter  to 
object-oriented  memory  management. 
The  chapter  begins  with  the  statement 
“It  would  be  so  nice  to  forget  about 
memory”  (p.  352),  but  Meyer  has  no 
illusions  on  that  score.  Meyer  shows 
the  problem  with  the  traditional  ap¬ 
proaches  to  memory  management,  in¬ 
cluding  what  he  calls  “programmer- 
controlled  deallocation,”  which  turns 
the  programmer  into  a  bookkeeper. 
What  then  characterizes  object-oriented 
memory  management?  Obviously  some 
form  of  “automatic”  memory  manage¬ 
ment.  “Unfortunately,  reference  count¬ 
ing  is  not  a  realistic  technique”  (p.  365), 
and  garbage  collection  “is  unaccept¬ 
able  for  real-time  applications”  (p.  366). 

The  Eiffel  approach  to  storage  man¬ 
agement  is  essentially  a  garbage-col- 
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lection  coroutine:  “Execution  of  an  Eif¬ 
fel  system  may  be  viewed  as  a  coop¬ 
erative  race  between  two  coroutines: 
The  application,  which  creates  objects 
as  it  goes,  and  renders  some  dead;  and 
the  collector,  which  chases  after  the 
application,  collects  all  the  dead  ob¬ 
jects  it  can  find,  and  makes  them  avail¬ 
able  again  to  the  application”  (p.  367). 

Throughout,  Object-Oriented  Soft¬ 
ware  Construction  provides  insights  into 
the  necessary  object-oriented  “mind¬ 
set.”  This  mindset  has  a  “more  neutral 
attitude  toward  ordering.”  “Real  sys¬ 
tems  have  no  top”  (p.  47).  Instead, 
object-oriented  systems  have  a  “shop¬ 
ping  list  approach.”  Always  try  to  pass 
the  buck:  “Better  later  than  sooner,  says 
object-oriented  wisdom”  (p.  50).  Meyer 
argues  that  looser  systems  will  be  more 
robust,  extendible,  reusable,  and  main¬ 
tainable  than  current  systems:  “decen¬ 
tralization  is  the  key  to  flexible  archi¬ 
tectures”  (p.  43D-  The  object-oriented 
approach  might  be  caricatured  as  noth¬ 
ing  more  than  “lighten  up,  dude.”  Meyer 
shows  how  the  looser,  bottom-up,  top¬ 
less  approach  really  can  result  in  better 
quality  software. 

In  short,  while  Booch’s  new  book  is 
more  tempered  by  knowledge  of  the 
costs  and  possible  downsides  of  object- 
oriented  software  development,  Meyer’s 
classic  work  is  a  better  introduction  to 
object-oriented  thinking.  The  two  books 
complement  each  other  well,  and  are 
recommended  to  anyone  trying  to  un¬ 
derstand  what  it  means  to  be  object 
oriented. 

DDJ 
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Listing  One  ( Text  begins  on  page  149.) 


/*  - des.h - */ 

/*  Header  file  for  Data  Encryption  Standard  algorithms  */ 

/*  - prototypes - */' 

void  initkey(char  *key) ; 
void  encrypt (char  *blk) ; 
void  decrypt (char  *blk); 


/* 

extern 

extern 

extern 

extern 

extern 

extern 

extern 

extern 


tables 


unsigned  char 
unsigned  char 
unsigned  char 
unsigned  char 
unsigned  char 
unsigned  char 
unsigned  char 
unsigned  char 


Pmask ( ] ; 

IPtbl ( ] ; 

Etbl [ ] ; 

Ptbl ( ] ; 

stbl [8] [4]  (16]  ; 
PCltbl ( ] ; 

PC2tbl ( ] ; 
ex6 [8] [2]  [4] ; 


/ 


End  Listing  One 


Listing  Two 


/*  Data  Encryption  Standard  front  end 
*  Usage:  des  [-e  -d]  keyvalue  infile  outfile 
*/ 


♦include  <stdio.H> 

#include  <string.h> 

♦include  "des.h" 

static  void  setparity (char  *key); 

void  main(int  argc,  char  *argv[]) 

( 

FILE  *f i,  *fo; 
char  key [9] ; 
char  blk [8] ; 

if  (argc  >  4)  ( 

strncpy(key,  argv[2],  8); 
key  [8]  =  '\0\- 
setparity (key) ; 

initkey (key) ; 

if  ( ( f i  =  fopen (argv{3] ,  "rb"))  !=  NULL)  ( 

if  ((fo  =  fopen (argv [4] ,  "wb"))  !=  NULL)  { 
while  (!feof(fi))  ( 
memset(blk,  0,  8); 
if  (f  read  (blk,  1,  8,  fi)  !=  0)  { 

if  (stricmp(argv(l] ,  "-e")  ==  0) 
encrypt (blk) ; 

else 

decrypt (blk) ; 
fwrite(blk,  1,  8,  fo) ; 

) 

) 

f close (fo) ; 

> 

fclose (fi) ; 

) 

) 

else 

printf ("\nUsage :  des  [-e  -d]  keyvalue  infile  outfile"); 

} 


/* - make  a  character  odd  parity - */ 

static  unsigned  char  oddparity (unsigned  char  s) 

{ 

unsigned  char  c  =  s  !  0x80; 
while  (s)  { 

if  (s  &  1) 

c  A=  0x80; 

s  =  (s  »  1)  &  0x7 f; 

‘  } 

return  c; 


/* - make  a  key  odd  parity - */ 

void  setparity (char  *key) 

( 

int  i; 

for  (i  =  0;  i  <  8;  i++) 

*(key+i)  =  oddparity (* (key+i) ) ; 

) 

End  Listing  Two 


static  void  rotate (unsigned  char  *c,  int  n); 
static  int  fourbits (struct  ks,  int  s); 
static  int  sixbits (struct  ks,  int  s)  ; 

static  void  inverse_permute (long  *op, long  *ip,long  *tbl,int  n) ; 
static  void  permute (long  *op,  long  *ip,  long  *tbl,  int  n) ; 
static  long  f(long  blk,  struct  ks  ky) ; 
static  struct  ks  KS(int  n,  char  *key) ; 
static  void  swapbyte (long  *1); 

/* - initialize  the  key - */ 

void  initkey (char  *key) 

( 

int  i; 

for  (i  =  0;  i  <  16;  i++) 
keys [i]  =  KS(i,  key) ; 

} 


/* - encrypt  an  8-byte  block - */ 

void  encrypt (char  *blk) 

{ 

struct  LR  ip,  op; 
long  temp; 
int  n; 

memcpyUip,  blk,  sizeof  (struct  LR) )  ; 

/* - initial  permuation - */ 

permute (Sop.L,  iip.L,  (long  *) IPtbl,  64); 
swapbyte (&op.L) ; 
swapbyte (&op.R) ; 

/* - swap  and  key  iterations - */ 

for  (n  =  0;  n  <  16;  n++)  ( 

temp  =  op.R; 

op.R  =  op.L  A  f(op.R,  keys[n]); 
op.L  =  temp; 

} 

ip.R  =  op.L; 
ip.L  =  op.R; 
swapbyte (Sip. L) ; 
swapbyte (& ip.R) ; 

/*  -  inverse  initial  permutation  -  */ 

inverse_permute (Sop.L,  Sip.L, 

(long  *) IPtbl,  64); 
memcpy(blk,  &op,  sizeof (struct  LR) ) ; 


/* - decrypt  an  8 -byte  block - */ 

void  decrypt (char  *blk) 

{ 

struct  LR  ip,  op; 
long  temp; 
int  n; 

memcpy(&ip,  blk,  sizeof (struct  LR) ) ; 

/* - - initial  permuation - */ 

permute (&op.L,  Sip.L,  (long  *) IPtbl,  64); 

swapbyte (&op.L) ; 

swapbyte (&op.R) ; 

ip.R  =  op.L; 

ip.L  =  op.R; 

/* - swap  and  key  iterations - */ 

for  (n  =  15;  n  >=  0;  — n)  { 

temp  =  ip.L; 

ip.L  =  ip.R  A  f(ip.L,  keys[n]); 
ip.R  =  temp; 

} 

swapbyte (& ip.L) ; 
swapbyte (Sip. R) ; 

/*  -  inverse  initial  permuation  -  */ 

inverse_permute (&op.L,  Sip.L, 

(long  *) IPtbl,  64); 
memcpy(blk,  &op,  sizeof (struct  LR) ) ; 


/*  -  inverse  permute  a  64-bit  string  -  */ 

static  void  inverse_permute (long  *op,long  *ip,long  *tbl,int  n) 

{ 

int  i; 

long  *pt  =  (long  *) Pmask; 

*op  =  *(op+l)  =  0; 

for  (i  =  0;  i  <  n;  i++)  { 

if  ( (*ip  &  *pt)  I!  (* (ip+1)  &  *(pt+l)))  ( 

*op  !=  *tbl; 

*(op+l)  !=  *(tbl+l); 

} 

tbl  +=  2; 
pt  +=  2; 

} 

) 


Listing  Three 

/*  - des.c - */ 

/*  Functions  and  tables  for  DES  encryption  and  decryption 
*/ 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  "des.h" 

/* - 48-bit  key  permutation - */ 

struct  ks  { 
char  ki [6] ; 

}  ; 

/* - tw0  halves  of  a  64-bit  data  block - */ 

struct  LR  { 
long  L; 
long  R; 


static  struct  ks  keys [16]; 


/* - permute  a  64-bit  string - */ 

static  void  permute (long  *op,  long  *ip,  long  *tbl,  int  n) 

( 

int  i; 

long  *pt  =  (long  *) Pmask; 

*op  =  * (op+1 )  =  0; 

for  (i  =0;  i  <  n;  i++)  [ 

if  ( (*ip  4  *tbl)  ::  (* (ip+1)  &  * (tbl+1) ) )  { 

*op  :=  *pt; 

* (op+1 )  :=  * (pt+l) ; 

} 

tbl  +=  2; 
pt  +=  2; 

) 


/*  -  Key  dependent  computation  function  f(R,K)  -  */ 

static  long  f(long  blk,  struct  ks  key) 

struct  LR  in¬ 
struct  LR  or; 
int  i; 
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union  ( 

struct  LR  f; 
struct  ks  kn; 

}  tr  =  {0,0},  kr  =  {0,0}; 

ir.L  =  blk; 
ir.R  =  0; 

kr.kn  =  key; 

swapbyte (&ir .L)  ; 
swapbyte ( & i r . R )  ; 

permute (&tr. f .L,  &ir.L,  (long  *)Etbl,  48); 

tr.f.L  A=  kr.f.L; 
tr.f.R  A=  kr.f.R; 

/*  the  DES  S  function:  ir.L  =  S(tr.kn);  */ 
ir.L  =  0; 

for  (i  =  0;  i  <  8;  i++)  { 

long  four  =  fourbits (tr .kn,  i); 
ir.L  !=  four  «  ( ( 7— i )  *  4); 

) 

swapbyte (&ir.L) ; 
ir.R  =  or.R  =  0; 

permute (&or . L,  fiir.L,  (long  *)Ptbl,  32); 

swapbyte (Sor.L)  ; 
swapbyte (&or . R) ; 

return  or.L; 


/* - extract  a  4-bit  stream  from  the  block/key - */ 

static  int  fourbits (struct  ks  k,  int  s) 

{ 

int  i  =  sixbits(k,  s) ; 
int  row,  col; 

row  =  ( ( i  »  4)  &  2)  !  (i  &  1); 
col  =  (i  »  1)  &  Oxf; 
return  stbl [s] (row] [col] ; 

} 


/*  -  extract  6-bit  stream  fr  pos  s  of  the  block/key  -  */ 

static  int  sixbits  (struct  ks  k,  int  s) 

( 

int  op  =  0; 

int  n  =  (s) ; 

int  i; 

for  (i  =  0;  i  <  2;  i++)  { 

int  off  =  ex6[n] [i] [0] ; 
unsigned  char  c  =  k.ki[off]; 
c  »=  ex6  [n]  [i]  [1]  ; 
c  «=  ex6  in]  [ i  j  [2] ; 
c  &=  ex6  fn] [ i ]  E 3 ] ; 
op  ! =  c ; 

} 

return  op; 


/* - DES  Key  Schedule  (KS)  function - */ 

static  struct  ks  KS(int  n,  char  *key) 

{ 

static  unsigned  char  cd[8]; 

static  int  its [ ]  =  {1, 1,2, 2, 2, 2, 2,2, 1,2, 2, 2, 2, 2,2,1}; 
union  { 

struct  ks  kn; 
struct  LR  filler; 

}  result; 

if  (n  ==  0) 

permute ( (long  *)cd,  (long  *)  key,  (long  *)PCltbl,  64); 

rotate (cd,  its [n] ) ; 
rotate (cd+4,  its [n ] ) ; 

permute (Sresult . filler .L,  (long  *)cd,  (long  *)PC2tbl,  48); 
return  result. kn; 


/*  rotate  a  4-byte  string  n  (1  or  2)  positions  to  the  left  */ 
static  void  rotate (unsigned  char  *c,  int  n) 

{ 

int  i; 

unsigned  j,  k; 

k  =  ( ( *c)  &  255)  »  (8  -  n); 
for  (i  =  3;  i  >=  0;  — i)  { 
j  =  ( (*  (c+i)  «  n)  +  k)  ; 
k  =  (j  »  8)  &  255; 

*(c+i)  =  j  &  255; 

) 

if  (n  ==  2) 

* (c+3)  =  (* (c+3)  &  OxcO)  I  ( (*  (c+3)  «  4)  &  0x30); 
else 

*  (c+3)  =  ( * (c+3)  &  OxeO)  I  ( (* (c+3)  «  4)  &  0x10); 


/* - swap  bytes  in  a  long  integer - */ 

static  void  swapbyte (long  *1) 

{ 

char  *cp  =  (char  *)  1; 
char  t  =  * (cp+3) ; 

* (cp+3)  =  *cp; 

*cp  =  t; 
t  =  * (cp+2) ; 

* (cp+2)  =  * (cp+1) ; 

* (cp+1)  =  t; 


End  Listing  Three 


Listing  Four 

/*  - tables. c - */ 

/*  tables  for  the  DES  algorithm 
*/ 


/* - macros 

#define  ps(n) 

#def ine  b (n, r) 
#define  p(n) 

(fdefine  q(n) 


to  define  a  permutation  table  - 

((unsigned  char) (0x80  »  (n— 1 ) ) ) 

( (n>r! ln<r-7)?0:ps(n-(r-8) ) ) 
b (n,  8),b(n,16),b(n,24),b(n,32),\ 
b(n,40),b(n,48) , b (n, 56) , b (n, 64) 
p(  (n ) +4 ) 


/* - permutation  masks - */ 

unsigned  char  Pmask[]  =  { 

p(  l),p(  2)  ,  p  (  3) ,  p  (  4 ) ,  p  (  5)  ,  p  (  6) ,  p  (  7) ,  p  (  8), 
p(  9),p(10),p(ll),p(12),p(13),p(14),p(15),p(16), 
p(17),p(18),p(19),p(20),p(21) ,p(22),p(23) ,p(24), 
p(25),p(26),p(27),p(28),p(29),p(30),p(31),p(32), 
p(33),p(34),p(35),p(36),p(37),p(38),p(39),p(40), 
p(41),p(42),p(43),p(44),p(45),p(46),p(47),p(48), 
p(49),p(50),p(51),p(52),p(53),p(54),p(55),p(56), 
p(57),p(58),p(59),p(60),p(61),p(62),p(63),p(64) 

}; 


/*  -  initial  and  inverse-initial  permutation 

unsigned  char  IPtbl[]  =  { 

p(58),p(50),p(42),p(34),p(26),p(18),p(10),p( 
p(60),p(52),p(44),p(36),p(28),p(20),p(12),p( 
p(62) , p (54 ) ,p(46) , p ( 38 ) , p ( 30 ) , p (22 ) ,p(14)  ,p( 
P ( 64 )  ,p(56) ,  p ( 4 8 )  ,p(40) ,  p ( 32 )  , p ( 2 4 )  , p ( 1 6 )  ,p( 
P(57)  ,p(49)  ,  p ( 4 1 )  ,p(33) ,  p ( 2 5 )  ,p(17)  ,p(  9) , p ( 
P ( 59)  ,p(51) , p ( 4 3 )  ,p(35) ,  p ( 2 7 )  ,p(19)  ,p(ll)  ,p( 
p(61),p(53),p(45),p(37)/p(29),p(21),p(13),p( 
p(63),p(55),p(47),p(39),p(31),p(23),p(15),p( 

}  ; 


table  - 


2), 

4) , 
6), 
8), 
1), 
3), 

5) , 
7) 


/* - permutation  table  E  for  f  function - */ 

unsigned  char  Etbl[]  =  { 

P ( 32 ) ,p(  1) , p (  2) , p (  3) , p (  4 ) , p (  5), 
p(  4) , p (  5) , p (  6) , p (  7) , p (  8) , p (  9), 

P(  8) ,p (  9),p(10),p(ll),p(12),p(13), 
p(12),p(13),p(14),p(15),p(16),p(17), 
p(16),p(17),p(18},p(19),p(20),p(21), 
p(20),p(21),p(22),p(23),p(24),p(25), 
p(24),p(25),p(26),p(27),p(28),p(29), 
p(28),p(29),p(30),p(31),p(32),p(  1) 

}; 


/* - permutation  table  P  for  f  function - */ 

unsigned  char  Ptbl [ ]  =  { 

P (16) ,p {  7),p(20),p(21),p(29),p(12),p(28),p(17), 
p(  1) ,p(15) ,p(23) , p (26) ,p(  5) , p (18) , p (31) , p (10) , 
p(  2)  ,p  (  8) ,  p  ( 2  4 )  ,  p  ( 1 4 ) ,  p  ( 32 )  ,p(27)  ,p(  3) ,  p  (  9), 
p (19) ,p (13) , p (30) , p (  6) , p (22) , p (11) , p (  4) , p (25) 

}; 


/*  —  table  for  converting  six-bit  to  four-bit  stream  —  */ 
unsigned  char  stbl [8] [4] (16]  =  { 

/* - si  -  */ 

14,4,13,1,2,15,11,8,3,10,6,12,5,9,0,7, 

0,15,7,4,14,2,13,1,10,6,12,11,9,5,3,8, 

4,1,14,8,13,6,2,11,15,12,9,7,3,10,5,0, 

15,12,8,2,4,9,1,7,5,11,3,14,10,0,6,13, 

/* - s2  -  */ 

15,1,8,14,6,11,3,4,9,7,2,13,12,0,5,10, 

3,13,4,7,15,2,8,14,12,0,1,10,6,9,11,5, 

0,14,7,11,10,4,13,1,5,8,12,6,9,3,2,15, 

13,8,10,1,3,15,4,2,11,6,7,12,0,5,14,9, 

/* - s3 -  */ 

10,0,9,14,6,3,15,5,1,13,12,7,11,4,2,8, 

13,7,0,9,3,4,6,10,2,8,5,14,12,11,15,1, 

13,6,4,9,8,15,3,0,11,1,2,12,5,10,14,7, 

I, 10,13,0,6,9,8,7,4,15,14,3,11,5,2,12, 

/* - s4  */ 

7,13,14,3,0,6,9,10, 1,2,8,5,11,12,4,15, 

13,8,11,5, 6, 15,0,3, 4,7,2, 12,1, 10, 14, 9, 
10,6,9,0,12,11,7,13,15,1,3,14,5,2,8,4, 
3,15,0,6,10,1,13,8,9,4,5,11,12,7,2,14, 

/* - s5 -  */ 

2,12,4,1,7,10,11,6,8,5,3,15,13,0,14,9, 

14,11,2,12,4,7,13,1,5,0,15,10,3,9,8,6, 

4,2,1,11,10,13,7,8,15,9,12,5,6,3,0,14, 

II, 8,12,7,1,14,2,13,6,15,0,9,10,4,5,3, 

/* - s6 -  */ 

12,1,10,15,9,2,6,8,0,13,3,4,14,7,5,11, 

10,15,4,2,7,12,9,5,6,1,13,14,0,11,3,8, 

9,14,15,5,2,8,12,3,7,0,4,10,1,13,11,6, 

4,3,2,12,9,5,15,10,11,14,1,7,6,0,8,13, 

/* - s7 -  */ 

4,11,2,14,15,0,8, 13,3,12,9,7,5,10,6, 1, 
13,0,11,7,4,9,1,10,14,3,5,12,2,15,8,6, 
1,4,11,13,12,3,7,14,10,15,6,8,0,5,9,2, 
6,11,13,8,1,4,10,7,9,5,0,15,14,2,3,12, 

/* - s8  -  */ 

13,2,8,4,6,15,11,1,10,9,3,14,5,0,12,7, 

1,15,13,8,10,3,7,4,12,5,6,11,0,14,9,2, 

7,11,4,1,9,12,14,2,0,6,10,13,15,3,5,8, 

2,1,14,7,4,10,8,13,15,12,9,0,3,5,6,11 


/*  -  Permuted  Choice  1  for  Key  Schedule  calculation  -  */ 

unsigned  char  PCltbl [ ]  =  { 

p(57),p(49),p(41),p(33),p(25),p(17),p(  9), 
p(  l),p(58),p(50),p(42),p(34),p(26),p(18), 
p(10),p(  2),p(59),p(51),p(43),p(35),p(27), 
p(19),p(ll),p(  3),p(60),p(52),p(44),p(36), 

P(0),p(0),p(0),p(0), 

p(63),p(55),p(47),p(39),p(31),p(23),p(15), 
p(  7)  ,p(62)  ,p(54)  ,p(46) ,  p  ( 38 )  ,p(30)  ,p(22) , 

(continued  on  page  166) 
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Listing  Tour  (Listing  continued,  text  begins  on  page  149.) 

p (14) , p (  6),p(61)/P(53),p(45),p(37),p(29), 
p  <  2 1 ) ,  p  (13)  ,p(  5),p(28),p(20),p(12),p(  4), 
p(0)  ,P(0)  ,P(0)  ,p(0) 


/*  -  Permuted  Choice  2  for  Key  Schedule  calculation  -  */ 

unsigned  char  PC2tbl[]  =  { 

p(14),p(17),p(ll),p(24),p(  l),p(  5) ,  p  (  3)  ,p  (28) , 
p (15) , p (  6),p(21),p(10),p(23),p(19),p(12),p(  4), 
p  (26) ,  p  (  8)  ,p(16)  ,p(  7),p(27),p(20),p(13),p(  2), 

q(41),q(52),q(31),q(37),q(47),q(55),q(30),q(40), 

q(51),q(45),q(33),q(48),q(44),q(49),q(39),q(56), 

q(34),q(53),q(46),q(42)/q(50),q(36),q(29)/q(32) 

}; 

/*  -  For  extracting  6-bit  strings  from  64-bit  string  -  */ 

unsigned  char  ex6 [8] [2] (4]  =  { 

/*  byte,  »,  «,  &  */ 

/* - s  =  8  */ 

0,2,0, 0x3f, 

0,2,0, 0x3f , 

/* - s  =  7  */ 

0,0,4,0x30, 

1,4,0, OxOf, 

/* - s  =  6  - */ 

1,0,2,0x3c, 

2,6,0,0x03, 

/* - s  =  5  - */ 

2,0,0, 0x3f , 

2,0,0, 0x3f , 

/* - s  =  4 - */ 

3,2,0, 0x3f , 

3,2,0, 0x3f , 

/* - s  =  3 - */ 

3,0,4,0x30, 

4,4,0, OxOf , 

/* - s  =  2 - */ 

4,0,2,  0x3c, 

5,6,0,0x03, 

/* - s  =  1 - */ 

5, 0, 0, 0x3f, 

5, 0, 0, 0x3f 

}; 

End  Listing  Four 


Listing  Five 

/*  - encrypto.c -  */ 

/*  Single  key  text  file  encryption 
*  Usage:  encrypto  keyvalue  infile  outfile 
*/ 

#include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦define  FALSE  0 
♦define  TRUE  ! FALSE 

static  void  charout(FILE  *fo,  char  prev,  int  runct,  int  last); 
static  void  encrypt (FILE  *fo,  char  ch,  int  last); 

static  char  *key  =  NULL; 
static  int  keylen; 
static  char  *cipher  =  NULL; 
static  int  clen  =  0; 

void  main (int  argc,  char  *argv[]) 

{ 

FILE  *fi,  *fo; 
char  ch,  prev  =  0; 
int  runct  =  0; 

if  (argc  >  3)  { 

/*  —  alloc  memory  for  the  key  and  cipher  blocks  —  */ 

keylen  =  strlen (argv[l] ) ; 

cipher  =  malloc (keylen+1) ; 

key  =  malloc (keylen+1) ; 

strcpy(key,  argv[l]); 

if  (cipher  !=  NULL  &&  key  !=  NULL  && 

(fi  =  fopen (argv[2] ,  "rb”))  !=  NULL)  { 

if  ( (fo  =  fopen (argv[3] ,  "wb"))  !=  NULL)  { 
while  ( (ch  =  fgetc(fi))  !=  EOF)  { 

/* - validate  ASCII  input - */ 

if  (ch  &  128)  { 

fprintf  (stde.rr,  "%s  is  not  ASCII", 
argv[2] ) ; 

fclose (fi) ; 
fclose (fo) ; 
remove (argv[3] ) ; 
free (cipher) ; 
free (key) ; 
exit ( 1 ) ; 

) 

/*  —  test  for  duplicate  bytes  —  */ 
if  (ch  ==  prev  &&  runct  <  127) 
runct++; 
else  { 

charout(fo,  prev,  runct,  FALSE); 
prev  =  ch; 
runct  =0; 

} 

1 

charout(fo,  prev,  runct,  TRUE); 
fclose (fo) ; 


} 

fclose (fi) ; 

} 

if  (cipher) 

free (cipher) ; 
if  (key) 

free (key) ; 

} 

) 

/* - send  an  encrypted  byte  to  the  output  file - */ 

static  void  charout(FILE  *fo,  char  prev,  int  runct,  int  last) 

{ 

if  (runct) 

encrypt (fo,  (runct+1)  !  0x80,  last); 
if  (prev) 

encrypt (fo,  prev,  last) ; 


/* - encrypt  a  byte  and  write  it - */ 

static  void  encrypt (FILE  *fo,  char  ch,  int  last) 

{ 

* (cipher+clen)  =  ch  A  * (key+clen) ; 
clen++; 

if  (last  ! !  clen  ==  keylen)  { 

/* - cipher  buffer  full  or  last  buffer - */ 

int  i; 

for  (i  =0;  i  <  clen;  i++) 
fputc (* (cipher+i) ,  fo) ; 
clen  =  0; 

} 

) 

End  Listing  Five 

Listing  Six 

/*  - decrypto.c -  */ 

/*  Single  key  text  file  decryption 
*  Usage:  decrypto  keyvalue  infile  outfile 
*/ 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  <stdlib.h> 

♦include  <process.h> 
static  char  decrypt (FILE  *); 

static  char  *key  =  NULL; 
static  int  keylen; 
static  char  ‘cipher  =  NULL; 
static  int  clen  =  0,  coff  =  0; 

void  main (int  argc,  char  *argv[]) 

( 

FILE  *fi,  *fo; 
char  ch; 
int  runct  =  0; 

if  (argc  >  3)  { 

/*  -  alloc  memory  for  the  key  and  cipher  blocks  -  */ 

keylen  =  strlen (argv(l) ) ; 
cipher  =  malloc (keylen+1) ; 
key  =  malloc (keylen+1)  ; 
strcpy(key,  argv[l]); 

if  (cipher  !=  NULL  &&  key  !=  NULL  && 

(fi  =  fopen (argv[2) ,  "rb"))  !=  NULL)  ( 

if  ((fo  =  fopen (argv(3) ,  "wb"))  !=  NULL)  ( 

while  ( (ch  =  decrypt (fi))  !=  EOF)  ( 

/*  —  test  for  run  length  counter  —  */ 
if  (ch  &  0x80) 

runct  =  ch  &  0x7 f; 
else  ( 

if  (runct) 

/*  —  run  count:  dup  the  byte  —  */ 
while  ( — runct) 
fputc (ch,  fo) ; 
fputc (ch,  fo) ; 

} 

) 

fclose (fo) ; 

} 

fclose (fi) ; 

} 

if  (cipher) 

free (cipher) ; 
if  (key) 

free (key) ; 

} 

) 

/*  -  decryption  function:  returns  decrypted  byte  -  */ 

static  char  decrypt (FILE  *fi) 

{ 

char  ch  =  EOF; 
if  (clen  ==  0)  ( 

/*  -  read  a  block  of  encrypted  bytes  -  */ 

clen  =  fread(cipher,  1,  keylen,  fi); 
coff  =  0; 

} 

if  (clen  >  0)  { 

/*  -  decrypt  the  next  byte  in  the  input  block  -  */ 

ch  =  * (cipher+cof f )  A  *(key+coff); 
coff++; 

— clen; 

) 

return  ch; 


End  Listings 
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Listing  One  ( Text  begins  on  page  155.) 

FUNCTION  Modulus {X,Y  :  Integer)  :  Integer; 

VAR 

R  :  Real; 

BEGIN 

R  :=  X/Y; 

IF  R  <  0  THEN 

Modulus  :=  X-(Y*Trunc(R-l) ) 

ELSE 

Modulus  :=  X- (Y*Trunc(R) ) ; 

END; 


Listing  Two 

PROGRAM  ZelTest2;  {  From  DDJ  11/90  ) 


End  Listing  One 


CONST 

DayStrings  :  ARRAY [0.. 6]  OF  STRING  = 

{'Sunday' ,  'Monday' ,  'Tuesday' , 'Wednesday' , 'Thursday' , 'Friday' , 'Saturday' ) ; 


VAR 

Month,  Day,  Year  :  Integer; 

{  This  function  implements  true  modulus,  rather  than  ) 

{  the  remainder  function  as  implemented  in  MOD.  ) 

FUNCTION  Modulus (X,Y  ;  Integer)  :  Integer; 

VAR 

R  :  Real; 

BEGIN 

R  ;=  X/Y; 

IF  R  <  0  THEN 

Modulus  :«  X- (Y*Trunc (R-l) ) 

ELSE 

Modulus  : -  X- ( Y*Trunc (R) ) ; 

END; 

FUNCTION  CalcDayOfWeek {Year, Month, Day  :  Integer)  :  Integer; 

VAR 

Century, Holder  :  Integer; 

BEGIN 

{  First  test  for  error  conditions  on  input  values:  } 

IF  (Year  <  0)  OR 

(Month  <  1)  OR  (Month  >12)  OR 
(Day  <  1)  OR  (Day  >  31)  THEN 

CalcDayOfWeek  :»■  -1  {  Return  -1  to  indicate  an  error  ) 

ELSE 

(  Do  the  Zeller's  Congruence  calculation  as  Zeller  himself  } 

(  described  it  in  "Acta  Mathematica"  #7,  Stockhold,  1887.  } 

BEGIN 

{  First  we  separate  out  the  year  and  the  century  figures:  ) 

Century  :=  Year  DIV  100; 

Year  :=  Year  MOD  100; 

{  Next  we  adjust  the  month  such  that  March  remains  month  #3,  ) 

{  but  that  January  and  February  are  months  #13  and  #14,  ) 

{  *but  of  the  previous  year*:  ) 

IF  Month  <  3  THEN 
BEGIN 

Inc (Month, 12); 

IF  Year  >  0  THEN  Dec (Year, 1)  {  The  year  before  2000  is  } 

ELSE  {  1999,  not  20-1...  } 

BEGIN 

Year  :=  99; 

Dec (Century) ; 

END 

END; 

{  Here's  Zeller's  seminal  black  magic:  }• 

Holder  :=  Day;  {  Start  with  the  day  of  month  } 

Holder  :=  Holder  +  (((Month+1)  *  26)  DIV  10);  {  Calc  the  increment  } 
Holder  :=  Holder  +  Year;  (  Add  in  the  year  } 

Holder  :=  Holder  +  (Year  DIV  4);  (  Correct  for  leap  years  } 

Holder  :=  Holder  +  (Century  DIV  4);  {  Correct  for  century  years  ) 

Holder  :=  Holder  -  Century  -  Century;  {  DON'T  KNOW  WHY  HE  DID  THIS!  } 

Holder  :=  Modulus (Holder, 7) ;  {  Take  Holder  modulus  7  } 

{  Here  we  "wrap"  Saturday  around  to  be  the  last  day:  } 

IF  Holder  =  0  THEN  Holder  :=  7; 

{  Zeller  kept  the  Sunday  =  1  origin;  computer  weenies  prefer  to  ) 

{  start  everything  with  0,  so  here's  a  20th  century  kludge:  j 

Dec (Holder) ; 

CalcDayOfWeek  :=  Holder;  (  Return  the  end  product!  } 

END; 

END; 


BEGIN 

Write('Month  (1-12):  ');  Readln (Month) ; 

Write ('Day  (1-31):  ');  Readln (Day); 

Write ('Year  :  ');  Readln (Year) ; 

Writeln('The  day  of  the  week  is  ', 

DayStrings [CalcDayOfWeek (Year, Month, Day) ] ) ; 

Readln; 

END. 

End  Listings 
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The  MVC  Paradigm  in 

Smalltalk/V 

Model-View-Controller  becomes  Object-Pane  Dispatcher 


Kenneth  E.  Ayers 


My  recent  efforts  at  unraveling 
more  of  Smalltalk’s  myster¬ 
ies  centered  around  the  win¬ 
dowing  system.  After  creat¬ 
ing  a  few  applications  and 
spending  many,  many  hours  browsing 
through  the  source  code  (thank  heav¬ 
en  for  the  source  code!),  I  finally  began 
to  form  a  mental  picture  of  how  the 
windowing  system  behaves.  The  pic¬ 
ture  is  not  a  simple  one.  For  instance, 
the  example  code  presented  in  this  ar¬ 
ticle  was  extracted  from  the  six  pages 
of  code  involved  just  in  opening  a  win¬ 
dow. 

I’ll  begin  by  describing  the  Model- 
View-Controller  (MVC)  paradigm  as  im¬ 
plemented  in  classic  Smalltalk.  Secondly, 
I’ll  describe  how  the  architecture  under 
Smalltalk/V286  differs  from  the  classic 
paradigm.  Finally,  I’ll  focus  in  more 
detail  on  the  mechanisms  of  creating, 
opening,  and  framing  a  window. 

The  MVC  Paradigm 

The  classic  Smalltalk  system,  as  de¬ 
signed  at  Xerox  PARC  in  the  1970s,  is 
based  on  the  Model-View-Controller 
paradigm,  the  conceptual  framework 
of  which  was  discussed  in  “Informa- 
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IDT  in  Westerville,  Ohio.  He  is  involved 
in  the  design  of  real-time  software  for 
industrial  graphic  workstations.  He  also 
works  part  time  as  a  consultant,  spe¬ 
cializing  in  prototyping  custom-software 
systems  and  applications.  Ken  can  be 
contacted  at  7825 Larchwood  St.,  Dub¬ 
lin,  OH  43017. 


tion  Models,  Views,  and  Controllers,” 
by  Adele  Goldberg  ( DDJ ,  July  1990). 

An  application  in  Smalltalk-80  con¬ 
sists  of  three  components:  A  model 
that  produces  the  information,  a  view 
that  displays  it,  and  a  controller  that 
manages  input  events. 

The  model  is  in  some  sense  the  core 
of  the  application,  the  data  structures 
that  represent  what  the  application  is 
trying  to  accomplish.  A  view  is  an  ob¬ 
ject  that  actually  presents  the  informa¬ 
tion  contained  in  a  model  on  the  dis¬ 
play  screen.  Various  types  of  view  ob¬ 
jects  are  provided  by  the  system,  each 
designed  to  display  specific  types  of 
information.  For  example,  one  kind  of 


view  can  display  data  as  a  scrollable 
list,  while  another  presents  text  so  it 
can  be  edited. 

Controllers  exist  to  process  input  from 
the  keyboard  and  mouse.  Generally 
speaking,  for  each  type  of  view  there 
is  a  corresponding  type  of  controller. 
For  example,  a  list  controller  recog¬ 
nizes  particular  input  events  as  indicat¬ 
ing  a  selection  from  the  displayed  list 
of  items.  The  text  editor’s  controller 
handles  specific  events  for  marking, 
cutting,  or  pasting  a  block  of  text  or  for 
scrolling  a  page. 

In  the  Smalltalk-80  implementation, 
the  MVC  architecture  is  embodied  in 
the  hierarchies  for  the  classes  Model, 
View,  and  Controller.  The  implemen¬ 
tors  of  Digitalk’s  Smalltalk/V286  con¬ 
centrated  the  functionality  of  the  MVC 
paradigm  into  a  smaller  set  of  more 
complex  classes.  The  mechanisms  are 
different  enough  that  the  two  platforms 
are  largely  incompatible  at  the  applica¬ 
tion  level  (even  though  the  language 
implementations  are  almost  identical 
at  the  syntactic  level). 

How  Smalltalk/V  and  Smalltalk-80  Differ 

The  most  obvious  difference  between 
Smalltalk/V  and  Smalltalk-80  is  in  the 
class  names.  First  of  all,  class  Model  is 
gone!  This  isn’t  a  serious  problem.  Ulti¬ 
mately,  the  application  is  the  model; 
and  the  dependent  notification  mecha¬ 
nisms  are  available  anyway  —  through 
class  Object. 

In  Smalltalk/V286,  a  view  object  is 
an  instance  of  class  Pane  or  one  of  its 
subclasses.  Figure  1  shows  the  basic 
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(continued  from  page  168)  patcher ;  which  is  detailed  in  Figure  2 

hierarchy  for  class  Pane  and  Table  1  and  Table  2. 

describes  its  principal  classes.  Similarly,  Smalltalk/V286  has  several  classes  and 
controllers  are  derived  from  class  Dis-  global  objects  that  provide  high-level 


Figure  1:  The  hierarchy  for  Vane  pro-  Figure  2:  The  hierarchy  for  Dispatcher 
vides  protocols  for  displaying  infor-  provides  protocols  for  handling  input 

mation  within  a  window.  events  directed  to  a  window. 


Pane 

Provides  the  common  instance  variables  and  the  default  behaviors  for  its 
subclasses,  such  as  drawing  borders  and  popping  up  menus. 

TopPane 

Represents  the  window  itself,  embodied  by  the  border  and  the  title  bar. 

SubPane 

Represents  independent  regions  within  a  window.  SubPane  provides  the  com¬ 
mon  behaviors  such  as  reframing  for  its  subclasses. 

TextPane 

Provides  methods  for  scrolling  text  and  notifying  the  model  when  its  contents 
change  or  are  saved. 

ListPane 

Supports  scrolling  and  displaying  data  in  the  form  of  a  list  of  individual  items; 
provides  methods  to  visually  indicate  the  current  selection. 

GraphPane 

A  generalized  "canvas"  for  graphic  drawing. 

Table  1:  Description  of  the  principal  Pane  classes 


management  functions  for  the  window 
system.  One  of  these  is  the  global  vari¬ 
able  Display —  the  only  instance  of  class 
DisplayScreen.  Display  represents  the 
physical  display  and  provides  access 
to  the  screen  as  a  bitmap. 

Another  major  player  is  the  global 
object  Scheduler.  The  only  allowable 
instance  of  class  DispatchManager , 
Scheduler  maintains  a  list  of  all  the 
windows  on  the  screen  and  manages 
their  activation  and  deactivation. 

The  subpane’s 
dispatcher  enters  its 
own  control  loop  to 
monitor  input  events 

The  global  variable  Processor  is  the 
only  instance  of  class  ProcessScheduler, 
whose  responsibility  it  is  to  manage 
the  various  processes  that  might  be 
active  in  the  system  at  any  given  time. 
Among  these  is  the  user  interface  pro¬ 
cess  that  fields  interrupts  from  the  key¬ 
board  and  the  mouse  and  translates 
them  into  suitable  input  events. 

Raw  input  is  handed  off  to  the  global 
object  Terminal  —  an  instance  of  class 
TerminalStream.  Terminal  takes  care 
of  the  housekeeping  associated  with 
the  input  stream.  Internally,  its  state 
machine  maps  multistage  input  events 
(mouse  movements,  button  clicks,  key 
scan  codes,  and  so  on)  into  a  set  of 
global  event  function  codes  (which  are 
defined  in  the  pool  dictionary  Function- 
Keys ). 

Finally,  the  global  variable  Transcript 
is  an  instance  of  class  TextEditor.  Tran¬ 
script  is  used  much  like  a  console  win¬ 
dow  to  relay  error  or  status  informa¬ 
tion.  However,  being  a  generic  text 
editor,  Transcript  is  also  available  for 
use  in  evaluating  any  Smalltalk  expres¬ 
sion,  via  the  “do  it”  or  “show  it”  menu 
selections. 

The  Chain  of  Command 

Each  of  the  application’s  panes,  includ¬ 
ing  the  top  pane,  has  a  Dispatcher  as¬ 
sociated  with  it  for  handling  input 
events.  Input  comes  into  the  applica¬ 
tion  via  the  active  dispatcher.  How  is 
this  dispatcher  activated? 

First,  let’s  assume  that  the  cursor  is 
initially  positioned  on  the  background 
screen,  outside  any  window.  Under 
these  conditions,  the  system  scheduler 
{Scheduler)  is  calling  the  shots.  Basi¬ 
cally,  Scheduler  sits  in  a  loop  and  steps 
through  its  list  of  windows,  sending 
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(continued  from  page  1 70) 
each  one  the  message  isControlWan- 
ted  (which,  by  default,  merely  tests  to 
see  if  the  cursor  is  positioned  within 
the  window’s  borders). 


The  first  window  that  answers  “yes” 
becomes  the  active  window.  Scheduler 
puts  that  window  at  the  head  of  its  list 
and  sends  its  dispatcher  (usually  a  TopDis - 
patchef)  the  message  activateWindow. 


DispatchManager 

Manages  all  of  the  windows  on  the  screen.  There  is  only  one  instance 
of  this  class:  the  global  variable  Scheduler. 

Dispatcher 

Provides  the  default  behaviors  for  processing  input  from  the  mouse  or 
keyboard. 

TopDispatcher 

Provides  methods  to  process  inputs,  including  cursor  positioning  and 
menu  activation,  directed  at  the  window  itself. 

ScrollDispatcher 

Provides  the  default  behavior  for  processing  input  related  to  scrolling 
the  image  in  a  pane. 

TextEditor 

Processes  input  for  its  associated  TextPane. 

ListSelector 

Processes  input  for  its  associated  ListPane. 

GraphDispatcher 

Processes  input  directed  to  a  GraphPane. 

Table  2:  Description  of  the  principal  Dispatcher  classes 


reframePaneraPane 

Sent  by  a  GraphPane  when  the  size  or  position  of  a  window 
is  changed.  The  model  should  implement  this  message  if 
there  is  more  than  one  GraphPane  in  a  window,  because  it 
provides  the  identity  of  the  pane  being  reframed.  The  actual 
frame  can  be  determined  by  the  message  aPane  frame. 

reframeraRectangle 

Also  sent  by  a  GraphPane  when  the  window  is  reframed.  The 
model  should  implement  this  message  when  there  is  only  one 

GraphPane  in  the  window. 

showWindow 

Sent  by  the  TopPane  when  the  window's  contents  must  be 
refreshed  for  any  reason.  Serves  as  an  indication  that  the 
window  is  being  displayed  and  that  any  application  informa¬ 
tion  should  be  prepared  for  presentation. 

activatePane 

Sent  by  a  GraphPane  when  the  cursor  enters  its  frame.  This 
message  can  be  used,  for  example,  to  change  the  cursor’s 
shape  so  that  the  user  receives  a  visual  indication  that  the 
cursor  has  entered  a  particular  region. 

deactivatePane 

Sent  by  a  GraphPane  when  the  cursor  leaves  its  frame. 

close 

Sent  when  the  window  is  being  closed.  This  is  useful  for 
saving  any  unfinished  business  before  the  window  disap¬ 
pears! 

label 

Sent  when  the  model  is  expected  to  answer  the  string  that  will 
be  used  for  the  window’s  label. 

collapsed  Label 

Sent  when  the  model  should  answer  the  string  that  it  wants 
used  to  label  the  collapsed  window.  Receipt  of  this  message 
can  also  indicate  that  the  window  is  in  the  process  of  being 
collapsed. 

InitWindowSize 

Sent  by  the  open  method  in  class  Dispatcher.  This  message 
gives  the  model  an  opportunity  to  specify  the  initial  size  of  the 
window. 

Table  3:  Methods  optionally  implemented  by  Model-to-Handle  user-generated 
events 


closelt 

Closes  the  window. 

zoom 

Normally  applies  only  to  instances  of  class  TextPane,  which  will  then  expand  to  the 
full  screen-size.  If  window  contains  no  text  panes,  the  zoom  message  will  be  sent 
to  the  model. 

reframe 

Indicates  that  the  user  wishes  to  change  the  size  of  the  window. 

collapse 

Causes  the  window  to  collapse  to  an  iconic  form  (an  abbreviated  title  bar  contain¬ 
ing  only  the  window's  label). 

Table  4:  Methods  optionally  implemented  by  Model-to-Handle  icon  button 
events 


Once  a  TopDispatcher  acquires  con¬ 
trol,  it  enters  its  own  control  loop.  Here, 
the  TopDispatcher  polls  the  dispatch¬ 
ers  associated  with  each  of  the  win¬ 
dow’s  subpanes,  asking  if  one  of  them 
wants  control.  The  pane  that  contains 
the  cursor  is  then  marked  as  the  active 
pane  and  its  dispatcher  assumes  con¬ 
trol  of  the  input  stream. 

When  the  dispatcher  for  a  subpane 
gains  control,  it  goes  through  an  acti¬ 
vation  sequence  which,  in  the  case  of 
a  GraphPane ,  for  instance,  includes 
sending  the  message  activatePane  to 
its  model. 

Finally,  the  subpane’s  dispatcher  en¬ 
ters  its  own  control  loop  to  monitor 
input  events.  The  specific  type  of  dis¬ 
patcher  that  ultimately  gets  control  de¬ 
termines  the  nature  of  the  system’s  re¬ 
action  to  input  events. 

Keeping  Everybody  Informed 

Much  of  the  power  (and  the  complex¬ 
ity)  of  the  Smalltalk/V286  windowing 
system  is  a  result  of  the  dialogue  be¬ 
tween  a  window  (the  pane  and/or  dis¬ 
patcher)  and  its  model.  For  almost  every 
type  of  event  that  a  user  can  generate, 
there  is  a  mechanism  for  notifying  the 
model  about  potential  changes.  Some 
events  are  handled  transparently  by  the 
pane  or  its  dispatcher,  so  they  don’t 
“bother”  the  application.  However,  from 
the  viewpoint  of  a  model’s  implementa¬ 
tion,  these  event  response  capabilities 
are  considered  optional.  Consequently, 
in  most  cases,  the  pane  or  dispatcher 
“asks”  the  model  about  its  implemen¬ 
tation,  using  a  sequence  of  statements 
similar  to  that  in  F.xample  1(a). 

The  methods  that  a  model  may  im¬ 
plement  to  handle  window  related 
events  are  listed  in  Table  3. 

In  addition  to  the  messages  described 
in  Table  3,  still  other  messages  may  be 
sent  to  the  model  by  selecting  one  of 
the  iconic  “buttons”  that  appear  in  a 
window’s  title  bar.  The  actions  associ¬ 
ated  with  these  buttons,  such  as  clos¬ 
ing,  collapsing,  moving,  or  resizing,  are 
directly  related  to  the  behavior  of  win¬ 
dow.  However,  these  same  actions  may 
also  affect  the  way  the  model  carries 
out  its  internal  operations. 

Therefore,  when  the  top  dispatcher 
detects  a  left  mouse  button  click  with 
the  cursor  positioned  inside  one  of  these 
buttons,  it  fetches  the  name  of  the  icon 
(a  Symbol)  from  a  class  variable.  The 
icon’s  name  is  actually  the  name  of  a 
method  that  is  supposed  to  perform 
the  action.  If  the  model  is  capable  of 
responding  to  the  message,  it  will  be 
sent;  otherwise,  the  top  dispatcher  per¬ 
forms  some  default  operation.  These 
messages  are  described  in  Table  4. 

All  of  the  messages  mentioned  in 
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Tables  3  and  4  are  sent  to  the  model 
by  the  window  —  typically  as  the  re¬ 
sult  of  a  user-initiated  event.  There  are 
also  many  ways  in  which  the  model 
can  influence  the  configuration  and 
operation  of  its  windows.  In  fact,  much 
of  the  public  protocol  for  the  Dispatcher 
and  Pane  class  hierarchies  is  available 
for  just  this  purpose.  Some  of  the  more 
important  messages  involved  in  these 
operations  are  given  in  Table  5. 

Constructing  a  Window 

The  first  step  in  constructing  an  appli¬ 
cation  window  at  runtime  is  to  create 
the  top  pane  for  the  window.  This  step, 
illustrated  by  the  open  method  found 
in  Listing  One  (page  175),  is  marked 
by  the  line:  topPane  .  =  TopPane  new. 
Following  this  is  a  series  of  cascaded 
messages,  directed  at  the  newly  cre¬ 
ated  topPane ,  that  specify  the  initial 
setup  for  the  window  (its  associated 
model,  label,  menu,  and  so  on). 

Once  the  topPane  has  been  taken  care 
of,  the  subpanes  can  be  created  and 
added  to  the  topPane  as  in  Example 
1(b).  Here  the  cascaded  messages  pro¬ 
vide  setup  information  to  the  subpane. 

Notice  that  in  Listing  One  there  are 
three  subpanes  created  and  added  to 
the  topPane.  One  of  these  is  a  List- 
Pane f,  while  the  other  two  are  Graph- 
phPanes.  Also  notice  that  each  sub¬ 
pane  is  assigned  a  “name”  by  the  state¬ 
ment:  name:<  aSymbol> ; 

This  can  be  confusing,  because  the 
name  given  is  not  really  the  “name”  of 
the  subpane.  It  is,  in  fact,  the  name  of 
a  method  selector  that  will  be  sent  to 
the  model  during  the  process  of  open¬ 
ing  the  window.  This  method  is  sup¬ 
posed  to  perform  application-specific 
initialization  for  the  pane.  In  the  case 
of  the  ListPane,  the  method  should  an¬ 
swer  an  array  containing  the  list  of 
items  to  be  displayed.  For  a  GraphPane , 
the  initialization  method  is  expected 
to  answer  a  Form  (bitmap)  whose  size 
is  the  same  as  the  pane’s  frame  (the 
frame  is  passed  as  an  argument  to  the 
message). 

Framing  a  Window 

Framing  a  window  is  one  of  the  more 
obscure  parts  of  creating  a  window 
application  in  Smalltalk/V286.  Each  sub¬ 
pane  must  possess  a  means  of  deter¬ 
mining  its  position  and  size  relative  to 

(a)  (model  respondsTo : #activatePane) 

ifTrue: [model  perform: tactivatePane] . 

(b)  topPane  addSubPane: 

(aPane  :=  GraphPane  new 
ccascaded  messages>; 
yourself) . 

Example  1:  Creating  and  adding 
subpanes 


label  :aString 

Sent  to  a  TopPane  to  specify  the  label  which  should  appear 
at  the  top  of  the  window. 

model  :anObject 

Notifies  a  Pane  that  its  controlling  model  is  anObject. 

name:aSymbol 

Tells  a  Pane  that  aSymbol  is  the  name  of  the  method,  imple¬ 
mented  in  the  model  class,  that  provides  initialization  for  the 
pane.  The  specified  method  may  or  may  not  be  expected  to 
accept  an  argument,  depending  upon  the  type  of  pane.  For 
example,  a  rectangle  (the  pane’s  frame)  will  be  passed  as  an 
argument  to  the  “name”  method  associated  with  a  GraphPane. 

menu:aSymbol 

Supplies  a  Pane  with  the  name  of  a  method  that  will  answer  a 
Menu  substituted  for  the  pane’s  default  menu. 

change:aSymbol 

Here,  aSymbol  is  the  name  of  a  single-argument  method  that 
handles  user-initiated  selections  (such  as  pressing  the  left 
mouse  button)  within  the  pane. 

selectllp:aSymbol 

For  GraphPane  only,  aSymbol  is  the  name  of  a  message  that 
is  sent  when  the  left  mouse  button  is  released. 

framingRatio:aRectangle 

Used  to  specify  the  region  of  the  window’s  display  that  the 
subpane  will  occupy. 

framlngBlock:aBlock 

Used  to  specify,  more  precisely,  the  position  and  size  of  a 
subpane  within  the  window. 

Table  5:  Messages  optionally  sent  by  the  Model  to  configure  a  window 
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the  window  as  a  whole.  The  calcula¬ 
tions  must  be  such,  that  if  the  win¬ 
dow’s  position  or  size  is  allowed  to 
change,  the  position  and  size  of  each 
subpane  can  be  adjusted  to  accommo¬ 
date  the  new  frame. 

There  are  two  ways  of  framing  sub¬ 
panes.  Either  of  the  messages  framing¬ 
Ratio:  aRectangle  or  framingBlock: 
aBlock  can  be  used,  depending  upon 
the  level  of  precision  required.  If  the 
absolute  position  or  size  of  the  sub¬ 
panes  is  not  critical,  framingRatio:  is 
far  easier  to  use.  This  message  speci¬ 
fies  the  position  and  size  of  a  subpane 
as  fractions  of  the  whole  window.  For 
example,  framingRatio: (0  @  (3/4)  ex- 
tent:l/4  @  (1/4));  tells  a  subpane  that 
it  will  be  positioned  at  the  left  edge  of 
the  window  and  three  quarters  of  the 
way  down  from  the  top.  The  subpane’s 
size  will  be  one  quarter  of  the  width 
of  the  window  and  one  quarter  of  its 
height.  In  other  words,  it  will  occupy 
the  lower  left-hand  corner  of  the  par¬ 
ent  window. 

However,  in  those  cases  when  an 
application  demands  that  one  or  more 
of  its  subpanes  be  located  in  a  specific 
position  or  be  framed  to  a  certain  abso¬ 
lute  size,  the  procedure  becomes  a  bit 
more  complicated.  Listing  Two  (page 
175)  is  a  modified  version  of  the  open 
method  in  which  the  list  pane  is  con¬ 
strained  to  be  ten  characters  wide  and 
ten  lines  high.  Here  the  message 
framingBlock:  is  sent  to  each  subpane 
with  a  block  of  code  as  its  argument. 
The  block  of  code  is  not  evaluated  at 
the  time  this  message  is  sent  to  the 
subpane,  but  when  the  window  is 
opened  or  reframed.  At  that  time,  it  is 
passed  a  single  argument  —  a  rectan¬ 
gle  defining  the  the  window’s  interior 
frame.  The  block  should  answer  a  new 
rectangle  —  the  frame  of  the  subpane. 

Any  variables  local  to  the  open 
method  that  are  referenced  within  the 
framing  block,  will  have  the  values  they 
had  when  the  open  method  completed. 
Be  careful  with  this  one  —  don’t  try  to 
calculate  the  dimensions  of  the  sub¬ 
pane  frames  incrementally,  using  one 
set  of  variables.  The  results  will  not  be 
what  you  expect! 

Wrapping  Up 

There’s  no  doubt  that  Smalltalk  is  a  big 
and  complex  system  and  that  the  pow¬ 
erful  array  of  features  it  offers  can  be 
quite  intimidating.  Fortunately,  the  en¬ 
vironment  provides  the  kinds  of  tools 
that  make  exploration  considerably  less 
difficult. 

DDJ 

(Listings  begin  on  page  1750 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  16. 
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Listing  One  (Text  begins  on  page  168.) 

open 


!  frame  ! 

appName 

:=  String  new. 

saved 

:=  true. 

editorPen 

:=  Pen  new. 

imagePen 

:=  Pen  new. 

frame 

:=  (Display  boundingBox  extent  //  6) 

extent : (Display  boundingBox  extent  *  2 
topPane  :=  TopPane  new 
model: self; 
label: self  label; 
menu : twindowMenu; 
minimumSize: frame  extent; 
yourself. 

topPane  addSubpane: 

(listPane  :=  ListPane  new 
model: self; 
name : fappList; 
change : #appSelection : ; 
returnlndex: false; 
menu: flistMenu; 

framingRatio: (0  @  0  extent: 1/4  @  (2/3)); 
yourself) . 
topPane  addSubpane: 

(imagePane  :=  GraphPane  new 
model : self ; 
name : #init Image : ; 
menu: #noMenu; 

framingRatio: (0  @  (2/3)  extent:l/4  @  (1/3)); 
yourself) . 
topPane  addSubpane: 

(editorPane  :=  GraphPane  new 
model : self; 
name:#initEditor: ; 
menu:#editorMenu; 
change :#edit Icon : ; 

framingRatio: (1/4  @  0  extent:3/4  @  1); 
yourself) . 

topPane  reframe: frame. 

topPane  dispatcher  openWindow  scheduleWindow. 


End  Listing  One 


Listing  Two 

open 


I  frame  listWid  listHgt  ! 

saved  :=  true. 
editorPen  :=  Pen  new. 
imagePen  :=  Pen  new. 

frame  :=  (Display  boundingBox  extent  //  6) 

extent: (Display  boundingBox  extent  *2  11 

listWid  :=  SysFont  width  *  10. 
listHgt  :=  SysFont  height  *  10. 


topPane  :=  TopPane  new 
label: self  label; 
model : self; 
menu : #windowMenu ; 
minimumSize: frame  extent; 
yourself. 

topPane  addSubpane: 

(listPane  :=  ListPane  new 
model: self; 
name: iappList; 
change : #appSelection : ; 
returnlndex: false; 
menu: #listMenu; 
f ramingBlock : [ : aFrame  ! 
aFrame  origin 

extent: listWid  @  listHgt]; 
yourself) . 
topPane  addSubpane: 

(imagePane  :=  GraphPane  new 
model : self ; 
name : # init Image : ; 
menu:#noMenu; 
f ramingBlock : [ : aFrame ! 

aFrame  origin  +  (0  @  listHgt) 

extent: (listWid 

@  (aFrame  height  -  listHgt))] 

yourself) . 
topPane  addSubpane: 

(editorPane  :=  GraphPane  new 
model : self; 
name : #initEditor : ; 
menu : #editorMenu; 
change : feditlcon: ; 
f ramingBlock: (: aFrame! 

aFrame  origin  +  (listWid  @  0) 

extent :( (aFrame  width  -  listWid) 

@  aFrame  height)]; 

yourself) . 

topPane  ref r ame : f r ame . 

topPane  dispatcher  openWindow  scheduleWindow. 


End  Listings 
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Phase  One  is  a  C  engine  that  re¬ 
places  Borland’s  Paradox  C  Engine.  TSR 
Systems  claims  that  Phase  One  is  four 
to  ten  times  faster  than  any  other  cur¬ 
rently  available  Paradox  C  engine.  En¬ 
hanced  memory  management  routines 
and  file  management  algorithms  are 
the  basis  for  Phase  One. 

DDJ  spoke  with  a  TSR  consultant, 
Dennis  Young,  who’s  using  the  engine 
to  develop  a  report  writer.  He  described 
the  engine  as  “a  way  station  —  these 
functions  are  things  we  needed  in  or¬ 
der  to  compile  PAL  scripts.  The  engine 
kind  of  fell  out  of  the  development  of 
the  compiler,  and  wound  up  being 
much  faster  than  the  Paradox  Engine.” 

The  DOS  version  requires  a  Micro¬ 
soft  C-compatible  compiler  or  Borland’s 
Turbo  C  or  Turbo  C++.  The  DLL  for 
Windows  3.0  should  now  be  available, 
also.  The  engine  contains  both  the  DOS 
and  Windows  libraries  and  retails  for 
$495,  though  any  owner  of  a  com¬ 
petitive  Paradox  C  engine  can  upgrade 
for  $149.  Reader  service  no.  20. 

TSR  Systems  Limited 
116  Oakland  Ave. 

Port  Jefferson,  NY  11777 
516-331-6336 

The  Spinnaker  PLUS  Software  Slot  De¬ 
veloper’s  Kit  for  the  Macintosh  has  been 
released  by  Spinnaker  Software.  With 
it  you  can  create  customized  exten¬ 
sions  to  the  PLUS  development  envi¬ 
ronment.  With  Spinnaker  PLUS  you  can 
develop  applications  that  look  and  run 
the  same,  without  modification,  across 
Windows  3.0,  OS/2  Presentation  Man¬ 
ager,  and  Macintosh  operating  systems. 

With  Software  Slots,  PLUS  can  ac¬ 
cept  new  object  classes  and  scripting 
language  extensions.  Commands  and 
functions  similar  to  external  commands 
and  functions  extend  the  PLUS  pro¬ 
gramming  language  and  allow  an  un¬ 
limited  number  of  arguments  and  cus¬ 
tomized  syntax.  External  draw  objects 


add  new  object  types  such  as  a  clock, 
a  digital  instrument  display,  a  bar  graph, 
a  3-D  chart,  and  other  data  representa¬ 
tions.  The  Kit  is  available  for  $695. 
Reader  service  no.  26. 

Spinnaker  Software 
201  Broadway 
Cambridge,  MA  02139-1901 
617-494-1200 

A  development  tool  for  Windows  comes 
from  EdenSoft.  Resource  Workshop 
includes  such  resources  as  menus,  icons, 
fonts,  cursors,  bitmaps,  string  tables, 
accelerators,  and  dialogs. 

DDJ  spoke  with  David  Rowley  of 
Varian  Associates,  developers  of  Win¬ 
dows-compatible  products,  who’s  been 
involved  in  the  beta  test  since  the  be¬ 
ginning.  Rowley  claims  “It’s  better  than 
any  tool  Microsoft  provides  for  their 
software  developers;  it  allows  quick 
prototyping  of  resources  for  an  appli¬ 
cation  —  you  can  use  it  as  a  develop¬ 
ment  tool  without  having  to  edit  the 
resource  script  file.  You  can  even  edit 
from  within  EXE  files.” 

Other  features  are  a  Project  View 
with  all  related  files  and  resources,  in¬ 
cremental  compilation,  full  source  code 
preservation,  language  extensions,  mul¬ 
tiple  undo  and  redo  commands,  the 
ability  to  edit  resources  as  text  or  graphi¬ 
cally,  extensive  support  of  #defines, 
automatic  usage  cross  reference,  and 
support  for  both  Windows  2  and  3 
resources.  And  Resource  Workshop  is 
compatible  with  older  tools.  It  sells  for 
$295.  Reader  service  no.  22. 

EdenSoft 

2980  College,  Suite  7 
Berkeley,  CA  95705 
415-548-3554 

SATVU,  a  satellite  propagation  and  field- 
of-view  simulation  software  package 
for  PCs,  is  new  from  Applied  Research. 
SATVU  animates  the  field-of-view  seen 
from  a  satellite,  ground  station,  rocket 
trajectory,  or  point  in  inertial  space. 
From  any  of  these  points  you  can  see 
other  satellites,  the  Earth,  sun,  moon, 
planets,  and  more  than  1700  stars  and 
deep-sky  objects. 

DDJ  spoke  with  Harold  Fears,  the 
senior  engineer  on  the  project,  who 
told  us  he  wrote  the  time-critical  rou¬ 
tines  in  assembler,  the  menus  in  Turbo 
C,  and  debugged  with  the  Turbo  De¬ 
bugger.  “We  adapted  this  program  from 
a  larger  one  we  developed  for  the  De¬ 
fense  Department,  and  are  targeting  a 
smaller  market,  such  as  ham  operators, 
amateur  astronomers,  and  anyone  in¬ 
terested  in  satellites,  planets,  and  stars. 
It’s  all  menu-driven,  though  you  can 
use  a  mouse,  and  it  only  takes  about 
15  minutes  to  learn.” 


You  need  an  AT  or  386  compatible 
with  math  coprocessor,  hard  disk,  and 
EGA  or  VGA  graphics.  The  animation 
update  rate  is  approximately  one  screen 
per  second  on  a  20-MHz  386.  Applied 
Research  can  customize  a  version  for 
you  —  they  have  different  subroutines 
and  modules  that  they  can  add  to  the 
product.  As  is,  SATVU  sells  for  $200. 
Reader  service  no.  25. 

Applied  Research  Inc. 

5025  Bradford  Blvd. 

Cummings  Research  Park 
Huntsville,  AL  35805 
205-837-8600 

Objectworks\C++  Release  2  from 
ParcPlace  Systems  is  now  available 
for  the  Sun-3  and  SPARCstation  plat¬ 
forms.  An  integrated  development  sys¬ 
tem  designed  to  help  C++  program¬ 
mers  take  better  advantage  of  object- 
oriented  programming  by  creating  and 
reusing  C++  code.  New  features  let  you 
work  with  Objectworks\C++  in  con¬ 
junction  with  traditional  Unix  tools.  The 
product  supports  large  system  devel¬ 
opment  and  incorporates  AT&T  C++ 
Language  System,  Release  2.1.  C++  class 
libraries  allow  for  code  reuse. 

The  open  environment  of  Ob- 
jectworks\C++  lets  you  use  your  favor¬ 
ite  C  preprocessor,  C  compiler,  and 
linker  to  customize  your  program.  It  is 
also  compatible  with  third  party  source 
code  control  systems,  profilers,  and  de¬ 
buggers.  The  source-level  process  in¬ 
spector  allows  debugging  of  C  as  well 
as  C++  code.  Integration  into  a  single, 
window-based  environment  means  you 
no  longer  have  to  switch  between  edi¬ 
tors,  grep,  compilers,  linkers,  and  de¬ 
buggers,  making  code  development 
faster.  Objectworks\C++  costs  $3000, 
and  ObjectKit\C++,  a  collection  of  re¬ 
usable  class  libraries,  costs  $500.  Reader 
service  no.  24. 

ParcPlace  Systems 
1550  Plymouth  St. 

Mountain  View,  CA  94043 
415-691-6700 

ED  the  Programmer’s  Editor,  from  the 
Australian  company  Soft  As  It  Gets, 
was  designed  to  simplify  and  speed 
up  program  writing  and  development. 
A  virtual  memory,  text-editing  engine 
with  a  full  C  extension  language  allows 
you  to  extend  the  editor’s  capabilities. 
A  C  interpreter  and  companion  com¬ 
piler  are  built  in,  and  ED  supports  both 
C  and  C++.  ED  includes  such  features 
as  fast  look-up  of  functions  and  meth¬ 
ods,  smart  indenting  and  templates,  di¬ 
rect  access  to  include  files,  a  C  function 
browser,  and  full  undo/redo. 

ED  is  fully  configurable,  including 
( continued  on  page  182) 
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(continued  from  page  1 77) 
keys  for  initiating  commands,  window 
colors,  and  user-defined  menus.  ED 
was  designed  to  support  programming 
teams,  and  includes  LAN  multiuser  lock¬ 
ing,  which  allows  one  user  to  edit  a  file 
while  others  view  it.  Multiprogrammer 
support  allows  each  user  to  have  their 
own  menus,  configuration  information, 
and  keyboard  bindings.  ED  fits  into 
128K  of  memory,  and  can  swap  to  disk 
or  EMS  if  necessary.  Contact  the  com¬ 
pany  for  pricing.  Reader  service  no.  23. 
Soft  As  It  Gets 
3  Pullman  Ct. 

East  St.  Kilda 

3183  Victoria,  Australia 

Cedar  Software  has  released  Fractal 
Grafics,  for  creating  complex  images 
with  fractal  geometry  and  a  visual  pro¬ 
gramming  language.  You  design  a  tem¬ 
plate  and  the  program  continues  your 
pattern  automatically.  If,  for  example, 
you  draw  the  trunk  and  first  few 
branches  of  a  tree,  the  program  will 
draw  the  rest.  You  can  load  and  save 
images  in  PCX  format  or  as  highly  com¬ 
pressed  fractal  templates. 

With  either  a  mouse  or  a  keyboard 
you  can  spin,  skew,  grow,  shrink, 
stretch,  squish,  and  rearrange  parts  of 
any  shape  without  losing  texture  or 
detail.  Changes  can  then  be  reflected 
through  all  levels.  The  program  fea¬ 
tures  an  online  interactive  tutorial,  point 
and  click  menus,  and  full  color  control. 
The  guidebook  extensively  explains  and 
illustrates  the  background  of  fractals 
as  well  as  all  formulae  and  algorithms. 
Full  source  code  is  available,  and  the 
package  sells  for  $79.  Reader  service 
no.  31- 

Cedar  Software 
RR1,  Box  5140 
Morrisville,  VT  05661-5140 
802-888-5275 

A  comprehensive  user  interface  devel¬ 
opment  package  for  Smalltalk/V  286  is 
available  from  Acumen  Software.  Wid- 
gets/V  286  is  an  interactive  editor  for 
point  and  click  development,  and  an 
extensive  user  interface  object  library 
for  building  block  reusability.  To  build 
an  interface,  you  move,  size,  and  edit 
the  widgets  directly  on  the  screen.  You 
can  switch  back  and  forth  between 
designing  and  testing  with  the  editor’s 
run  mode,  for  rapid  prototyping. 

DDJ  spoke  with  Eric  Langjahr,  presi¬ 
dent  of  Impeccable  Software  and  beta 
tester  for  Widgets,  who  said,  “Widgets 
provides  a  very  large  class  library  for 
building  user  interfaces  that  are  more 
modern  than  any  available  for  PCs  — 
similar  to  the  NextStep,  with  three- 
dimensional  images  and  the  like.  You 


build  visually  and  put  the  program¬ 
matic  pieces  in  later.  It’s  unique  to  any¬ 
thing  available  now.” 

The  object  library  includes  a  broad 
spectrum  of  common  visual  objects  for 
use  in  graphical  user  interfaces,  such 
as  various  window  styles,  hierarchical 
pop-up  and  pull-down  menus,  list 
boxes,  text  editor,  scrolling  pages,  ra¬ 
dio  buttons,  and  palettes  of  forms.  A 
set  of  intrinsics  is  provided  for  creating 
customized  widgets.  Widgets/V  is  sell¬ 
ing  for  $99-  Reader  service  no.  29. 
Acumen  Software 
851  Lytton 
Palo  Alto,  CA  94301 
415-328-3816 

Another  product  available  for  Smalltalk 
users  is  MathPacl/V  from  Knowledge 
Systems.  MathPacl/V  lets  you  perform 
advanced  mathematical  operations 
within  Smalltalk  applications.  The  abil¬ 
ity  to  work  within  the  same  develop¬ 
ment  environment  instead  of  using  an¬ 
other  language  should  reduce  devel¬ 
opment  time. 

MathPacl/V  features  vectors,  two- 
dimensional  matrices,  N-dimensional  ma¬ 
trices,  complex  numbers,  long-cycle  ran¬ 
dom  number  generation,  beta  function, 
incomplete  beta  function,  in  of  gama 
function,  binomial  coefficient,  and  string 
asFloat.  MathPacl/V  is  priced  at  $199. 
Reader  service  no.  30. 

Knowledge  Systems  Corp. 

1 14  MacKenan  Dr.,  Ste.  100 
Cary,  NC  27511-6446 
919-481-4000 

GEOGRAF  Level  One  from  GEOCOMP 
is  a  graphics  library  of  subroutines  and 
functions  for  creating  custom  graphs 
and  charts.  For  use  with  most  Microsoft 
and  Borland  compilers,  GEOGRAF  Level 
One  enables  you  to  add  graphics  to 
programs  without  having  to  develop 
complex  graphics  device  drivers  for 
each  device  you  wish  to  support,  and 
you  can  output  your  graphics  to  any 
output  device.  Because  GEOGRAF  Level 
One  uses  the  same  library  structure  as 
most  of  the  Microsoft  and  Borland  com¬ 
pilers,  you  can  use  similar  graphics  calls 
with  different  languages  and  compilers. 
Device  drivers  can  be  changed  at  any 
time  without  changing  the  software. 

DDJ  spoke  with  Doug  McGary,  pro¬ 
ject  engineer  at  TMA  Technologies  and 
beta  tester  for  GEOGRAF  Level  One. 
“I’m  involved  in  image  processing  [and] 
needed  to  be  able  to  detect  defects  in 
a  special  plastic  material  used  for  cor¬ 
nea  replacement.  I  figured  out  the  sub¬ 
routine  calls  I  needed  to  make  and 
wrote  the  code  and  had  it  debugged 
in  three  days.  GEOGRAF  saved  me  three 
man-weeks  of  software  writing  —  it’s 


well  documented  and  easy  to  use.” 

GEOGRAF  Level  One  sells  for  $149 
and  comes  with  a  30-day  money-back 
guarantee.  Reader  service  no.  27. 
GEOCOMP  Corporation 
66  Commonwealth  Ave. 

Concord,  MA  01742 
800-822-2669 

A  conference  examining  the  latest  in 
technological  tools  for  creating  visuals, 
sound,  live  performance,  and  integrated 
media  experiences  took  place  at  Cy- 
berArts  International  in  Los  Angeles 
in  September.  CyberArts  was  a  show¬ 
case  of  artists,  programmers,  musicians, 
special  effects  technicians,  and  multi- 
media  gurus  combining  technologies 
in  film,  music,  and  art  production.  The 
three-day  affair  consisted  of  concerts 
and  performances,  workshops,  presen¬ 
tations,  exhibits,  and  an  art  gallery. 

The  list  of  speakers  was  a  who’s  who 
in  this  eclectic,  interconnected,  emerg¬ 
ing  field.  Jeff  Rona  and  Chris  Meyer 
demonstrated  “The  Music  Cognition 
Link,”  a  HyperCard  application  built 
on  inference  engines  created  through 
Lisp.  Based  on  a  spinoff  of  neural  nets 
with  back  propagation,  this  program 
accepts  input  from  a  keyboard  and  re¬ 
sponds  in  kind.  The  level  of  the  com¬ 
puter’s  response  was  surprisingly  avant- 
garde —  at  times  it  seemed  as  if  the 
computer  was  more  creative  than  its 
human  counterparts. 

In  other  presentations  Jaron  Lanier 
discussed  virtual  reality,  Marc  Canter 
answered  the  question  “What  the  Heck 
Is  Multimedia?”,  Bill  Buxton  blasted  the 
distinction  between  artists  and  tech¬ 
nologists,  Allen  Adkins  discussed  the 
impact  of  the  CD  David  Zicarelli  dem¬ 
onstrated  the  basics  of  interactive  crea¬ 
tivity,  Carl  Rodendahl  presented  “live” 
animation  (digital  puppet  techniques), 
and  Kit  Galloway  and  Sherrie  Rabi- 
nowitz  of  the  Electronic  Cafe  talked  about 
“composite-image  performances,”  which 
they  make  possible  through  a  satellite 
link.  Other  presentations  demonstrated 
interactive  toys,  hyperinstruments,  and 
desktop  computer  animation. 

Next  year’s  conference,  also  to  be 
sponsored  by  Keyboard  magazine  and 
Miller  Freeman,  is  scheduled  for  August 
22-25,  again  in  Los  Angeles. 
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How  To  Succeed  In  the  Window  Business 
Without  Really  Trying 

Software  author  and  Windows  developer  Alan  Cooper  recently  asked  me  to  appear  on  a 
Software  Entrepreneur’s  Forum  panel  whose  mission  was  to  discuss  making  money  with 
Windows  3.0.  It  proved  impossible  for  me  to  attend,  but  I  prepared  some  remarks  anyway.  For 
what  they're  worth,  here  are  my  thoughts  on  making  money  with  Windows  3.0.  You  are  welcome 
to  disagree  with  them,  as  a  whole  or  individually. 

Windows  3-0  is  being  marketed  as  a  new  platform.  Given  that,  all  the  new-platform  truisms 
apply;  in  particular,  the  get-there-first  truism.  The  first  Windows  3.0  applications  will  get  more 
press  —  and  be  judged  less  critically  —  than  will  comparable  later  products.  Be  the  first. 

This  advice  may  seem  not  only  obvious  but  also  useless,  because  a  couple  dozen  Windows 
applications  were  announced  six  months  ago  at  the  Windows  rollout.  But  the  get-there-first  truism 
also  seems  to  work  on  a  niche-by-niche  basis.  I  modify  my  advice.  Be  the  first  at  something. 

For  any  new  platform,  two  hot  markets  are  developers  and  early  adopters  of  new  technology. 
Particularly  for  these  groups,  a  think-globally-act-locally  truism  applies,  if  you  happen  to  live  in  the 
San  Francisco  Bay  Area  or  in  the  Boston  area.  Consider  keeping  costs  low  by  spending  most  of 
your  marketing  budget  locally.  Check  the  ad  rates  in  the  regional  computer  publications.  Talk  to 
the  local  papers. 

Consider  the  home  market.  This  was  what  IBM  and  a  lot  of  others  companies  did,  to  their  chagrin, 
in  the  early  80s,  and  they’re  at  it  again.  Maybe  this  time  they’re  right.  According  to  the  September  10 
Business  Week  story  on  the  home  market,  3.7  million  computers  a  year  are  bought  to  be  used  in 
the  home,  and  20  percent  of  the  PS/2s  sold  are  being  used  at  home. 

Does  all  of  this  actually  constitute  a  distinct  market  for  home  software?  Beats  me.  I  don’t  think 
Tandy  has  the  answer  with  the  recipe  program  that  it’s  including  with  its  new  home  machine 
(which,  incidentally,  won’t  run  Windows).  The  Business  Week  piece  suggests  that  home  applications 
aren’t  much  different  from  work  applications:  word  processing,  accounting,  budgeting.  But  if  you 
have  a  brilliant  idea  for  a  home  product,  you  should  know  that  IBM,  Apple,  Tandy,  and  a  lot  of 
other  hardware  companies  are  going  to  be  pushing  computers  for  the  home  very  hard.  Since  the 
early  80’s  snafu  almost  certainly  had  to  do  with  ease  of  use,  your  Windows  application  might  do 
very  well. 

Don’t  overlook  Asymetrix  ToolBook  as  a  prototyping  tool.  Here’s  a  scenario:  You  write  a  design 
prototype  using  ToolBook.  You  add  core  functionality  in  DLL  functions  to  produce  a  working 
prototype.  Now  you  write  the  real  application  around  the  same  DLL  functions.  At  this  point  you 
actually  have  two  products  under  development:  A  full  high-performance  version,  and  a  stripped- 
down,  slower,  but  not  unacceptable  ToolBook  version.  This  gives  you  not  just  a  product  but  a  (sort 
of)  product  line  from  (sort  of)  one  development  cycle. 

You  evolve  these  two  products  away  from  one  another  as  you  develop  them,  adding  functionality 
to  one  (removing  it  from  the  other)  to  differentiate  them.  You  put  the  ToolBook  version  out  first, 
staking  out  your  market  niche,  arousing  customer  and  press  interest,  and  getting  cash  flowing  in 
earlier  than  you  could  if  you  waited  to  get  a  real  application  done. 

This  buys  you  two  legitimate  occasions  to  talk  to  the  press  about  your  product  because  you  will 
have  two  product  announcements.  And  when  you  later  release  the  non -ToolBook  professional 
edition ,  the  press  and  users  already  understand  the  concept  of  the  product  and  the  basic 
functionality,  so  their  attention  is  naturally  drawn  to  what  is  different  about  this  product:  Improved 
performance  and  niftier  features. 

When  considering  maintaining  Windows  2.1  compatibility,  keep  in  mind  that  Microsoft  is 
marketing  Windows  3-0  primarily  against  Windows  2.1.  The  success  of  Windows  3.0  will,  to  some 
extent,  depend  on  how  much  users  disliked  Windows  2.1. 

When  considering  whether  or  not  to  develop  simultaneously  for  Windows  and  PM,  consider  the 
cost  of  delaying  your  Windows  release  against  the  size  of  the  OS/2  market  in  the  near  future.  In  the 
not-so-near  future,  you  can  always  port  a  stable  Windows  version  to  OS/2.  And  consider  that 
developing  simultaneously  for  Windows  and  PM  requires  that  you  care  about  Microsoft’s  relationship 
with  IBM,  whatever  that  may  be  this  week. 


Michael  Swaine 
editor-at-large 
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SOURCE  CODE  AVAILABILITY 

As  a  service  to  our  readers,  all  source  code 
is  available  on  a  single  disk  and  online.  To 
order  the  disk,  send  $14.95  (Calif,  residents 
add  sales  tax)  to  Dr.  Dobb's Journal,  501 
Galveston  Dr.,  Redwood  City,  CA  94063, 
or  call  800-356-2002  (inside  Calif.)  or  800- 
533-4372  (outside  Calif.).  Specify  issue  num¬ 
ber  and  disk  format.  Code  is  also  available 
through  the  DDJ  Forum  on  CompuServe 
(type  GO  DDJ)  and  through  M&T’s  Telepath 
Conferencing  system. 


NEXT  ISSUE _ 

Happy  Birthday  to  the  Doctor!  January  1991 
is. our  15th  anniversary  issue  and,  along 
with  a  look  at  software  design,  we’ll  exam¬ 
ine  topics  important  to  the  past  and  future 
of  computer  programming. 
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EDITORIAL 

Conferences  and 
Contests 


Technical  editor  Ray  Valdes  recently  spent  a  week  in  sunny  New  Jersey  attending  the 
“C++  at  Work”  conference  sponsored  by  the  Wang  Institute  of  Boston  University  and 
the  C++  Report.  What  follows  is  the  short  version  of  his  report: 

Now  that  some  of  the  initial  hype  has  subsided,  where  does  C++  stand  today?  What  are  its 
prospects?  Should  you  switch  from  whatever  language  you’re  using  now,  or  wait  and  see? 

These  were  some  of  the  questions  raised  at  the  “C++  at  Work”  conference  held  in  Secaucus, 
New  Jersey.  The  principal  advantage  of  the  conference  location  was  its  proximity  to  Bell  Labs, 
cradle  of  both  the  C  language  and  its  object-oriented  descendant.  Human  languages  have  a 
strong  cultural  component,  programming  languages  much  less  so.  But  the  C++  language  is 
complex  and  subtle  enough  that  an  immersion  into  the  native  culture  of  that  language  is 
necessary  in  order  to  use  this  tool  effectively.  And  there  were  enough  native  speakers  from 
Bell  Labs  at  this  C++  conference  to  make  the  visit  worthwhile. 

One  realization,  for  me,  was  how  large  and  complex  the  language  is  in  comparison  to  C. 
For  PC  programmers  moving  to  C  from  other  languages,  making  the  transition  to  C++  will  be 
an  equally  large  step.  It  is  paradoxical  that,  on  one  hand,  you  must  be  both  well  grounded  in 
the  culture  of  C  (pointers,  pre-  and  postoperators,  casts,  and  so  on)  to  fully  understand  C++. 
On  the  other  hand,  you  must  be  willing  to  throw  out  the  “bad”  procedural-language  mind-set 
in  favor  of  “good”  object-oriented  worldview. 

The  clarity  of  the  object-oriented  view  is  sullied  by  real-world  considerations  of  performance 
and  efficiency.  These  considerations  burden  the  language  with  multiple  alternative  techniques 
(six  different  kinds  of  inheritance,  for  example)  and  a  need  to  always  keep  the  underlying 
machinery  in  mind.  For  example,  it  is  hard  to  read  or  debug  a  program  without  knowing  the 
entire  context  of  a  class’s  ancestors  (such  as  any  overloaded  operators  or  overriden  methods), 
as  well  as  knowing  how  the  compiler  creates  temporaries  when  it  evaluates  an  expression 
(for  example,  which  constructors  will  be  invoked). 

(As  an  aside  for  those  who  find  the  language  cumbersome  or  wordy,  consider  a  tour  I 
recently  took  through  a  very  large  software  system,  composed  of  hundreds  of  thousands  of 
lines  of  C  and  many  megabytes  of  executable.  In  the  course  of  making  this  system  manageable, 
the  developers  had  to  concoct  many  of  the  object-oriented  mechanisms  offered  by  the  C++ 
language.  Because  these  were  implemented  as  stylistic  conventions  and  preprocessor  macros, 
the  resulting  system  is  both  harder  to  read  and  less- reliable  than  a  C++  equivalent  would  be.) 

Despite  these  difficulties,  it  is  clear  that  the  language  will  be  the  mainstream  development 
vehicle  of  the  90s.  Not  wishing  to  start  any  religious  wars,  I  believe  that  Smalltalk  is  simpler, 
cleaner,  more  powerful,  and  can  exist  in  a  fast  enough  implementation.  Yet  C++  will  prevail, 
for  reasons  that  are  as  much  cultural,  historical,  and  business  oriented  as  they  are  technological. 

As  evidence,  some  of  the  speakers  at  the  conference  were  emigres  from  Lisp  (Dick  Gabriel, 
of  Lucid  Inc.)  and  Smalltalk  (Ted  Goldstein,  formerly  of  ParcPlace  Systems).  They  are 
presently  immersed  in  bringing  to  C++  some  of  the  nifty  advanced  tools  currently  enjoyed 
only  by  users  of  those  languages. 

As  a  speaker  said  at  the  conference,  C++  is  a  language  invented  by  expert  programmers 
and  computer  scientists  to  make  their  work  easier  and  more  productive.  In  the  hands  of 
experts,  it  is  a  powerful  tool  that  makes  development  of  large  software  systems  manageable. 
In  less-skilled  or  inexperienced  hands,  it  can  prove  quite  dangerous. 

Bjarne  Stroustrop  had  some  useful  advice  near  the  end  of  the  week:  “Ease  yourself  into  the 
language.  Don’t  feel  you  have  to  use  all  of  the  features,  and  don’t  try  to  use  them  all  on  the 
first  day.” 

Calling  All  Student  Programmers 

Symantec,  makers  of  Think  C,  Think  Pascal,  and  a  passel  of  other  development  tools,  is 
sponsoring  a  programming  contest  for  high  school  and  college  students.  The  competition 
consists  of  programming  questions  and  problems.  Individual  students  or  entire  classes  can 
enter.  There’s  one  version  of  the  contest  for  high  school,  another  for  college. 

Two  grand  prizes  will  be  awarded  —  one  for  high  school  and  one  for  college  —  and 
they’re  not  bad.  Each  grand  prize  winner  will  get  a  $5,000  scholarship,  a  Macintosh  Ilci, 
and  a  lifetime  subscription  to  Dr.  Dobb’s Journal.  Four  runners  up  (two  from  high  school, 
two  from  college)  will  also  receive  prizes,  including  a  year’s  subscription  to  DDJ. 

Entries  will  be  accepted  through  March  1991,  with  prizes  awarded  in  June  1991;  judging 
will  be  by  Symantec  engineers.  To  register  or  find  out  more  information,  teachers  or 
students  should  call  Symantec  Contest  Hotline,  617-275-4800. 


Jonathan  Erickson 
editor-in-chief 
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LETTERS 


Porting  Fortran 

Dear  DDJ, 

The  article  “Porting  Fortran  Programs 
from  Minis  to  PCs,”  by  John  Bradberry 
(September  1990)  brought  back  memo¬ 
ries  of  the  most  thankless  task  1  have 
ever  undertaken.  .  .  porting  a  moderately 
sized  scientific  Fortran  program  to  a 
PC. 

I  can  still  recall  staring  aghast  at  the 
countless  travesties  in  style  and  prac¬ 
tice,  marveling  at  the  complete  lack  of 
structure.  Imagine  a  seemingly  endless 
printout  of  unindented,  line-numbered 
code  with  scores  of  undeclared  vari¬ 
ables  with  ingenious  names  like  dxyl5, 
ixxx,  ix,  ixx,  ixl,  ixy,  nrtsc,  iscalel,  etc. 
Every  eight  or  nine  vertical  inches  of 
code  would  be  interrupted  by  a  block 
of  seven  or  eight  consecutive  computed 
if  statements.  If  subroutines  perform¬ 
ing  multiple  tasks  are  a  Do  Not,  that  is 
still  better  than  a  huge  program  with 
no  subroutines  at  all  .  .  .  just  gotos  and 
if  statements  returning  control  some¬ 
where  depending  upon  the  value  of  a 
global  flag  defining  the  original  calling 
context. 

It  seemed  sad  somehow  that  a  very 
useful,  even  brilliant,  solution  to  an 
important  problem  found  expression 
in  such  an  ungainly  program.  On  the 
bright  side,  what  was  once  ugly  is  now 
beautiful,  and  what  was  once  Fortran 
is  now  C. 

Peter  Matsunaga 

Aiea,  Hawaii 

Dear  DDJ , 

It  was  a  real  pleasure  to  see  the  article 
“Porting  Fortran  Programs  from  Minis 
to  PCs,”  by  John  Bradberry  (September 
1990).  The  table  of  “Do’s  and  Don’ts” 
was  especially  interesting  to  a  veteran 
of  some  30  years  of  wrestling  with  For¬ 
tran  mysteries. 

But  on  to  the  bad  news:  The  listings 
accompanying  the  article  reveal  a  com¬ 
monly  made  mistake  in  dealing  with 
type  conversions  in  computed  or  re¬ 
placement  statements.  Consider,  for  ex¬ 


ample,  the  45th  line  of  the  listing,  shown 
on  page  80:  PI=3-14159265.  The  as¬ 
sumption  usually  made  is  that  the  in¬ 
formation  stored  in  variable  PI  will  be 
of  double  precision  since  PI  was  de¬ 
clared  as  type  REAL*8. 

Example  1  shows  that  this  is  not 
always  true.  Many  compilers,  includ¬ 
ing  the  Microsoft  Fortran  5.0  used  here, 
do  not  conform  to  the  assumption.  The 
value  actually  stored  in  PI  in  this  exam¬ 
ple  turned  out  to  be  3-1459274.  This  is 
nowhere  near  the  15  or  16  digits  of 
precision  expected. 

In  the  absence  of  cues  explicitly  des¬ 
ignating  the  right  side  of  a  statement 
as  double  precision,  the  compilers  ap¬ 
parently  evaluate  the  right  side  in  sin¬ 
gle  precision  registers.,  When  the  time 
comes  to  finally  replace  the  left  side 
variable,  the  right  side  result,  in  a  sin¬ 
gle  precision  register,  is  transferred  to 
a  double  precision  register  and  then 
to  the  double  precision  storage  loca¬ 
tion  of  the  variable. 

Having  found  several  instances  over 
the  years  where  taking  things  for  granted 
got  me  less  than  I  expected,  it  has 
become  my  practice  to  make  statements 
involving  type  conversion  as  “bullet¬ 
proof”  as  possible.  This  means  things 
like  explicitly  putting  in  the  SNGL  and 
DBLE  functions  wherever  those  effects 
are  actually  intended  to  be.  In  the  case 
of  constants,  such  as  3.1459265,  the 
only  way  to  make  constants  explicitly 
double  precision  is  to  always  include 
a  “D”  exponent.  For  example: 
PI=3.14159265D0. 

George  Zabriskie 

Huntsville,  Alabama 

John  responds:  Mr.  Zabriskie  correctly 
points  out  a  flaw  in  the  initialization 
of  double  precision  constants  in  the 
Fortran  listings.  Type  conversion  and 
mixed-mode  arithmetic  present  such 


Example  1 


potential  problems  (in  all  languages) 
and  were  not  adequately  addressed  in 
my  article  due  to  scope  and  space  limi¬ 
tations.  The  actual  use  of  the  constant(s) 
had  no  adverse  effect  on  the  demon¬ 
strated  application,  but  good  program¬ 
ming  practices  and  consistency  are  al¬ 
ways  worth  pointing  out. 

And  Porting  C 

Dear  DDJ, 

I  just  read  “Porting  C  Programs  to  386 
Protected  Mode,”  by  William  F.  Dud¬ 
ley,  Jr.  (August  1990)  and  am  writing 
in  response  to  the  statement: 

“Now  I  have  a  hairy  preprocessor 
macro  that  computes  the  size  of  a  ‘data 
element,’  which  is  really  the  biggest  of 
any  of  several  different  structs.”  (p.  17) 
This  may  not  be  a  complete  problem 
exposition,  but  it  would  be  unfortu¬ 
nate  if  such  a  mechanism  were  always 
required.  A  simple  solution  is  shown 
in  Example  2.  This  consumes  no  run¬ 
time  memory,  though  if  you  need  the 
size  of  a  data  element,  you  can  now 
index  more  efficiently,  as  in  Example  3- 
John  Deurbrouck 
Mountlake  Terrace,  Washington 

10-Key  Update 

Dear  DDJ, 

Although  I  found  Jeff  Duntemann’s  col¬ 
umn  in  the  August  1990  DDJ  interest¬ 
ing,  I  must  take  issue  with  his  choice 
of  user  interface.  Full-screen  editors 
with  mouse  control  have  their  place, 
but  entering  numbers  from  a  bingo 
card  is  not  that  place. 

Have  you  ever  seen  someone  use  a 
10-key  pad  such  as  the  one  on  the  right 
of  the  PC’s  keyboard?  A  skilled  opera¬ 
tor  has  two  important  qualities:  He  can 
operate  by  touch  and  he  can  do  so  very 
fast.  Requiring  a  10-key  operator  to 
move  his  attention  between  the  bingo 
(continued  on  page  12) 


C: \>TYPE  PIE. FOR 
PROGRAM  PIE 
REAL* 8  PI_0NE,  PI_TW0 
C 

PI_0NE=3. 14159265  (Common  method  -  without  exponent 

PI_TW0=3 . 14159265D0  ! Correct  method  -  with  D  exponent 

C 

WRITE  (*,100)  PI_0NE,  PI_0NE 

100  FORMAT ( '  This  is  PI  stored  without  a  ’  'D' '  designator:  ',F12.8,3X, 
Z16, /) 

WRITE  (*,110)  PI_TW0,  PI_TW0 

110  FORMAT!'  This  is  PI  stored  with  a  ' 'D' '  designator:  ',F12.8,3X, 
Z16,/) 

STOP 

END 

C:\PIE 

This  is  PI  stored  without  a  ' 'D"  designator:  3.1459274  400921FB60000000 
This  is  PI  stored  with  a  ”D"  designator:  3.14159265  400921FB53C8D4F1 

Stop  -  Program  terminated. 

C:\> 
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(continued  from  page  8) 
card  and  the  screen  is  inefficient;  to 
further  require  him  to  translate  a  num¬ 
ber  into  relative  screen  coordinates  (let’s 
see;  I’m  on  100  and  205  is  also  circled  — 
that’s  five  over  and  two  down)  is  dou¬ 
ble  so. 

Back  when  I  did  this  sort  of  thing  for 
a  living,  I  could  even  move  my  hands 
between  the  keypad  and  the  alpha  key¬ 
board  without  looking. 

Please  take  the  operator  into  account 
when  designing  user  interfaces.  Al¬ 
though  screen-oriented  editors  are 
flashy  and  fun  to  program,  I  believe 
that  Mr.  Duntemann’s  users  would  ap¬ 
preciate  a  simpler,  enter-the-number 
interface. 

Roger  Ivie 

Logan,  Utah 

And  More  on  AND 

Dear  DDJ, 

1  too  have  heard  about  the  unusual 
programming  language  Michael  Swaine 
discussed  at  the  end  of  his  January 
1990  “Programming  Paradigms”  column. 
There  were  several  things  about  this 
language  he  did  not  mention.  This  lan¬ 
guage  is  particularly  well-suited  for  pro¬ 
gramming  cellular  automatons.  In  ad¬ 
dition,  AND  programs  are  not  struc¬ 
tured  in  a  top-down  fashion,  but  form 
a  double  helix  instead. 

Even  though  there  are  many  millions 
of  different  kinds  of  programs  written 
in  AND,  current  research  is  trying  to 
take  parts  of  several  programs  and  re¬ 
combine  the  pieces  into  new  programs. 
You  would  think  that  with  all  the  pro¬ 
grams  written  in  AND  there  would  be 
one  that  would  fulfill  any  need.  Maybe 
we  conventional  programmers  can  learn 


Example  2 


Example  3 


Example  4 
12 


a  lesson  from  the  AND  researchers. 

AND  programs  are  susceptible  to  vi¬ 
ruses.  Strangely  enough,  some  kinds 
of  bugs  in  AND  programs  occasionally 
manifest  themselves  as  another  pro¬ 
gramming  language,  the  one  Swaine 
discussed  in  the  first  part  of  his  column 
[Lisp]. 

You  would  think  that  with  all  the 
AND  programs  around,  there  would 
be  a  debugger.  Maybe  there  are  some 
technical  problems  that  can’t  be  over¬ 
come,  like  the  problem  of  interpreting 
the  object  code.  But  with  only  three 
symbols  to  consider,  this  shouldn’t  be 
very  hard. 

At  any  rate,  this  is  what  I  know  about 
this  unusual  programming  language.  I 
look  forward  to  hearing  more  about 
AND.  And  please  find  out  the  correct 
name  of  this  language.  I’d  be  ever  so 
interested  to  know. 

Clifford  V.  Moravetz 

Gays  Mills,  Wisconsin 

Network  Detection 

Dear  DDJ , 

Regarding  Al  Stevens’s  column  about 
the  NetWare  API  (August  1990),  I  would 
like  to  share  a  method  I  use  for  detect¬ 
ing  a  network.  Whenever  you  call  Net¬ 
Ware’s  GetServerlnformation  function, 
the  file  server  name  will  be  zero  length 
if  no  server  can  be  found.  Since  I  am 
using  C++,  I  take  advantage  of  default 
parameters  to  let  you  pass  the  address 
of  a  FILE_SERVER_INFO  structure  (see 
Example  4)  if  you  so  desire,  which  will 
then  come  back  containing  informa¬ 
tion  on  the  default  server  (if  any).  I 
think  Al  will  agree  this  method  is  a 
whole  bunch  simpler. 

Now  that  I’ve  stopped  to  think  of 


what  this  function  does,  it’s  erroneous 
to  call  it  “loggedin,”  since  what  it  actu¬ 
ally  tells  you  is  whether  a  file  server  is 
detected.  Guess  I’ll  have  to  change  its 
name.  .  .  . 

Dave  Nelson 

Jet  Propulsion  Laboratory 

Pasadena,  California 


Memory  Allocation 

Dear  DDJ, 

I  thoroughly  enjoyed  Larry  Spencer’s 
article  “Debugging  Memory  Allocation 
Errors,”  (August  1990).  The  technical 
content  was  valuable,  and,  of  course, 
any  similarity  between  the  scenarios 
painted  by  him  and  the  life  of  “real 
programmers”  was  totally  unintentional! 

To  add  to  the  humor,  there  is  a  small 
unintentional  problem  in  the  mem_ 
Track_J'ree( )  function,  which  partly  de¬ 
feats  the  purpose  of  the  function.  The 
simplest  correction  is  to  include  an  ad¬ 
ditional  line,  rc  =  0,  at  the  very  end  of 
the  code  on  the  left  column  on  page 
179. 

To  those  who  did  not  use  Larry’s  code, 

I  suggest  you  keep  it  in  a  safe  place 
(that  is,  permanently  on  top  of  the  high¬ 
est  pile);  you  know  not  the  hour  .  .  . 

To  those  who  did,  make  the  above 
modification  and  check  your  program 
again.  Whooooopppppssss!!  But  the  pro¬ 
gram  was  perfect  yesterday!!  OK,  OK, 
OK  .  .  .  more  coffee  .  .  .  dammmn  .  .  . 
here  we  go  again  .  .  . 

Michael  Kennedy 

Dublin,  Ireland 

Dear  DDJ, 

In  the  August  1990  issue,  Lawrence 
Spencer  points  out  some  of  the  prob¬ 
lems  with  dynamic  memory  allocation 
in  a  C/Pascal-like  language:  “Maybe 
you  freed  a  pointer  that  you  never  allo¬ 
cated”  or  “Maybe  you  allocated  mem¬ 
ory  but  never  freed  it”  and  points  out 
that  even  veteran  programmers  are  li¬ 
able  to  make  mistakes  of  this  kind.  The 
results  are  frequently  disastrous,  as  he 
points  out  about  the  hypothetical  pro¬ 
gram  HIGHRISE:  “but  once  in  a  while 
it  locks  up  the  computer”  and  “Also, 
what  about  the  time  HIGHRISE  fore¬ 
casted  a  profit  of  $17,546,321.97  on  a 
$1,000  investment?  .  .  .  Please,  let  it 
have  been  a  hardware  error!”  He  then 
presents  some  practical  solutions  for 
handling  this  problem  in  C  (I  person¬ 
ally  have  always  tended  to  use  some¬ 
thing  like  the  solution  he  presents,  in 
my  larger  C  projects). 

But  there  are  other,  more  general 
solutions  to  the  problem,  albeit  outside 
the  context  of  the  article.  Use  of  an¬ 
other  language  —  a  language  like  Lisp, 
(continued  on  page  14) 
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union  checksize  ( 

struct  struct_l; 
struct  struct_2; 
struct  struct_3; 

}  ; 

♦define  DATA  ELEMENT  SIZE  sizeof (union  check. size) 


struct  struct_l  sl_init; 

union  check_size  aray  [40],  *ptr; 
int  x  ; 

ptr  =  array; 

for  (x=0;  x<40;  ptr++,  x++) ptr->struct_l  =  sl_init; 


♦include  <nit.h>  //  the  NetWare  API  header 

//  struct  FILE_SERVER_INFO  is  defined  in  nit.h 

typedef  char  bool; 

bool  loggedin (FILE_SERV_INFO  *  f  =  NULL) ( 

FILE_SERV_INFO  fs,  *  fp; 

fp  =  (f==NULL)?  Sfs  :  f;  //use  the  struct  passed,  if  any 

GetServerlnformation (sizeof (FILE_SERV_INFO) ,  fp) ; 
return  fp->serverName [0] ; 

) 
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(continued  from  page  12) 
for  instance.  Unfortunately,  the  mem¬ 
ory  management  of  Lisp  can  cause  per¬ 
formance  problems.  Not  to  mention 
that  the  venerable  Lisp  can  be  a  some¬ 
what  alien  experience  for  programmers 
steeped  in  the  C/Pascal  tradition. 

Somewhere  in  between  is  the  new 
language  Clu'  (“Klu-prime”)  we  pro¬ 
vide:  This  language  is  a  modern  ver¬ 
sion  of  MIT’s  CLU  language.  While  mem¬ 
ory  allocation  and  deallocation  is  han¬ 
dled  automatically  in  this  language,  the 
performance  of  this  allocation/dealloca¬ 
tion  is  for  the  most  part  similar  to  the 
programmer  making  malloc( )  and 
free()  calls  manually.  (This  however, 
is  not  the  primary  advantage  of  using 
Clu',  which  supports  abstract  data  types 
with  a  very  simplified  inheritance  facil¬ 
ity  as  well  as  other  simple  and  power¬ 
ful  concepts  such  as  iterators,  excep¬ 
tion  handling,  and  parametrization.) 

In  any  significantly  complex  task, 
dynamic  memory  allocation/dealloca¬ 
tion  tends  to  be  enough  of  a  sink  of 
programmer  time  and  effectiveness,  and 
enough  source  of  errors,  that  I  just  do 
not  see  it  remaining  under  manual  con¬ 
trol  in  the  programming  languages  and 
environments  of  the  future. 

Mukesh  Prasad 

Meta  Mind  Inc. 

East  Haven,  Connecticutt 

Bezier  Update 

Dear  DDJ, 

I  found  the  July  1990  article  “Drawing 
Character  Shapes  with  Bezier  Curves,” 
by  Todd  King  very  interesting.  Todd  is 
correct  in  pointing  out  that  the  Bezier 
curve  rendering  could  be  improved, 
especially  the  parametric  equation 
method.  Here  is  one  way  to  do  it. 

The  equation  used  for  determining 
the  x  coordinate  on  page  48  of  the  July 
issue  performs  fourteen  floating-point 
multiplications,  six  subtractions,  and 
three  additions,  plus  one  to  increment 
the  parameter  t.  Of  course,  the  six  subtrac¬ 
tions  can  be  reduced  to  a  single  sub¬ 
traction  by  storing  the  value  of  (1  -  t) 
in  a  variable,  Actually,  this  can  be  simpli¬ 
fied  further  by  realizing  that  the  pa¬ 
rameter  f  starts  at  0.0  and  is  incremented 
each  time  by  a  set  stepping  value.  This 
implies  that  a  separate  variable  can  be 
used  for  (1  -  t),  which  would  be  initial¬ 
ized  to  1.0  and  decremented  by  the 
stepping  value.  The  six  subtractions 
are  replaced  by  a  parameter  that  is 
decremented  by  a  constant  only  once 
per  iteration! 

The  equation  can  be  simplified  by 
reducing  the  number  of  floating-point 
multiplications,  using  Horner’s  rule: 

f(t)  =  [(at  +  b)t  +  c]t  +  d 


So  if  (1  -  t)’s  are  factored  out,  the  first 
equation  becomes: 

x(t)  =  [(Xj(l  - 1)  +  3tx2  )(1  -  t)  +  3t2x3] 

(1  - 1)  +  t3  x4 

This  equation  performs  eleven  multipli¬ 
cations,  three  subtractions,  and  three 
additions.  It  is  possible  to  factor  ts  in¬ 
stead  of  (1  -  f)  terms  if  that’s  more 
convenient.  In  any  case,  this  demon¬ 
strates  that  the  first  equation  is  not  mini¬ 
mal  and  can  be  improved  using  simple 
mathematics.  More  can  probably  be  done. 

Todd  has  a  procedure,  hull ,  that 
shows  the  convex  hull  of  the  four  con¬ 
trol  points.  This  procedure  is  incorrect, 
however.  I  made  a  similar  mistake  in 
one  of  my  computer  graphics  projects. 
For  example,  if  a  line  was  drawn  be¬ 
tween  the  first  and  the  last  control  point, 
and  the  second  control  point  was  placed 
on  one  side  of  that  line,  whereas  the 
third  control  point  was  placed  on  the 
other  side  of  the  line,  the  hull  that 
Todd’s  procedure  draws  would  not  be 
convex  and  would  not  contain  the  Be¬ 
zier  curve.  One  of  the  reasons  why 
folks  determine  convex  hulls  is  for  clip¬ 
ping.  If  the  convex  hull  of  a  curve  is 
inside  a  window,  then  the  whole  curve 
must  be  inside  the  window.  This  means 
that  each  of  the  points  on  the  curve 
does  not  need  to  be  checked  to  see  if 
it  is  inside  the  window,  and  that  only 
the  control  points  need  to  be  tested. 
Dr.  Sedgewick  devotes  a  whole  chap¬ 
ter  on  convex  hull  determination  in 
his  book  Algorithms  (Addison- Wesley, 
1988).  It’s  a  very  good  reference  on 
many  topics. 

Victor  J.  Duvanenko 

Knightdale,  North  Carolina 


We  welcome  your  comments  (and  sug¬ 
gestions).  Mail  your  letters  (include  disk 
if  your  letter  is  lengthy  or  contains  code) 
to  DDJ,  501  Galveston  Dr.,  Redwood 
City,  CA  94063,  or  send  them  electroni¬ 
cally  to  CompuServe  76704,50  or  via 
MCI  Mail,  c/o  DDJ.  Please  include  your 
name,  city,  and  state.  We  reserve  the 
right  to  edit  letters. 

DDJ 
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Controlling 

Background  Processes  Under 

Unix 

Here’s  a  system  that  “user-izes”  process  management 


Barr  E.  Bauer 


undertake  scientific  computing  using  a  number  of  net¬ 
worked  workstations,  compute  servers,  and  a  super¬ 
computer.  Typically,  problems  are  set  up  and  the  re¬ 
sults  are  analyzed  on  the  workstations,  while  the  actual 
number  crunching  activity  is  performed  on  the  more 
powerful  machines.  The  description  of  this  approach  is 
straightforward,  but  the  tools  necessary  to  manage  the  jobs 
that  originate  from  a  central  workstation,  and  are  then  run 
on  a  variety  of  remote  hosts  over  a  network,  are  not  gener¬ 
ally  available. 

For  . instance,  with  the  standard  available  Unix  System  V 
tools,  you  cannot  ask  user-oriented  questions,  such  as  “What 
applications  and  datasets  are  running  on  any  remote  host?” 
“Which  applications  are  pending?”  or  “What  is  the  status  of 
a  certain  job?”  without  resorting  to  Unix  commands  that 
oftentimes  do  not  look  like  the  user’s  actual  query. 

This  article  presents  a  system  designed  to  “user-ize”  the 
management  of  background  processes  that  run  both  locally 
and  across  a  network.  The  system,  which  I  call  “shepard,” 
includes  a  standardized  interface  that  utilizes  menus  where 
appropriate  to  reduce  the  management  of  processes  down 
to  the  essentials:  Tasks,  executable  scripts,  dataset  names, 
and  remote  host  names.  The  specifics  of  the  process  of 
executing,  monitoring,  and  retrieving  programs  that  run 
remotely  are  hidden  in  shell  scripts.  The  bulk  of  this  system 
is  written  in  Bourne  shell  script  and  is  reasonably  portable. 

System  Overview 

The  basic  idea  behind  this  system  is  to  use  a  series  of  scripts 
to  control  all  activities  that  occur  locally  or  on  a  remote  host, 
and  to  do  so  in  a  simple,  straightforward,  user-oriented 
manner.  Integral  to  this  activity  is  the  establishment  of  a 
queuing  system  to  handle  job  control,  simplify  the  selection 
of  the  host  and  programs,  invoke  the  programs,  move  the 


Barr  works  for  Schering-Plough  Research,  a  pharmaceuti¬ 
cal  company.  He  can  be  reached  at  60  Orange  Street, 
Bloomfield,  NJ  07003- 


data  files  over  a  network,  and  record  all  activities.  The  core 
of  the  system  consists  of  five  Bourne  shell  scripts  —  run , 
shepard ,  shepard_  queue ,  shepard_exec,  and  run_update 
—  and  a  number  of  application-specific  control  files  that 
contain  either  tables  or  control  scripts.  When  the  system 
runs  it  generates  a  number  of  status  files  to  show  the  jobs 
that  are  waiting,  running,  finished,  and  restartable  on  each 
remote  host.  The  system  also  generates  a  file  on  the  origin 
machine  to  show  the  status  and  location  of  all  jobs. 

I  have  commented  the  code  extensively  to  describe  its 
features  and  operation.  Descriptions  of  the  scripts  are  pre¬ 
sented  here  to  give  you  a  general  understanding  of  the  role 
of  each  script  in  the  overall  system.  For  specifics,  refer  to  the 
listings. 

The  script  run  is  a  menu-driven  task  manager  that  queries 
for  a  task,  a  script,  a  dataset,  and  the  host,  run  then  carries 
out  the  requested  task  by  invoking  shepard  on  the  selected 
host  through  a  remote  shell  ( rsh )  command,  run  maintains 
a  list  of  jobs  originating  from  the  origin  machine  as  well  as 
a  log  file,  and  serves  as  a  hub  that  coordinates  jobs  run  on 
several  machines.  Through  run,  the  user  knows  which 
programs  are  using  which  datasets  and  where  those  pro¬ 
grams  are  running.  The  tasks  managed  by  run  are  simple 
and  include  starting  and  stopping  the  execution  of  pro¬ 
grams,  determining  the  status  of  jobs  running  on  a  specific 
remote  host,  and  probing  running  jobs  for  intermediate 
results  or  status  information,  run  performs  all  of  its  work, 
including  the  generation  of  most  menus,  through  the  other 
scripts  across  the  network  by  use  of  rsh  calls. 

The  types  of  tasks  that  the  shepard  system  currently 
performs  include: 

•  Execute  a  job,  locally  or  over  a  network  by  a  remote  host 

•  Monitor  the  remote  host 

•  Probe  a  running  job  for  intermediate  results 

•  Kill  a  running  job  with  extreme  prejudice 

•  Halt  a  running  job  in  a  controlled  manner 

•  Restart  a  job 
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®  List  running,  waiting  (enqueued),  restartable,  and  finished 
jobs 

•  List  general  and  error  log  files 

The  script  shepard  performs  all  of  the  process  manage¬ 
ment  for  a  specific  host,  shepard  takes  as  its  arguments  the 
task,  the  script,  the  dataset,  the  origin  machine,  and  the 
dataset  directory.  Execution  is  handled  by  shepard_ 
queue.  The  process  of  updating  the  status  file  on  the  origin 
machine  is  performed  by  run_update,  and  all  other  activi¬ 
ties  are  conducted  directly  in  shepard.  Lists  of  running  and 
waiting  jobs,  as  well  as  an  execution  log  are  maintained  and 
displayed  when  requested  by  run.  The  process  of  adjusting 
the  control  files,  and  updating  the  status  file  on  the  origin 
machine  when  a  job  is  completed  is  also  handled  in  shepard. 

The  script  shepard_queue  maintains  a  FIFO  queuing  sys¬ 
tem  that  regulates  both  the  numbers  and  the  types  of  jobs 
allowed  to  execute  concurrently.  This  approach  is  a  good 
way  to  maintain  a  balance  between  throughput  and  maxi¬ 
mum  system  performance.  The  executing  task  is  started  by 
invoking  shepard_exec  as  a  background  task.  An  error  log 
is  maintained.  Instead  of  using  multiple  queue  files,  a  single 
queue  file  is  used  both  for  the  sake  of  simplicity  and  be¬ 
cause  the  queue  file  is  used  to  generate  a  menu. 

The  script  shepard_exec  has  embedded  in  it  the  specifics 
for  moving  data  into  the  execution  environment,  running 
the  selected  program,  moving  the  results  back,  and  calling 
shepard  to  update  the  control  files.  The  specifics  of  program 
invocation  —  the  process  of  copying  data  files  from  origin 
to  host,  executing  the  program,  and  transferring  the  result 


files  back  to  the  origin  machine  —  are  hidden  in  scripts. 
shepard_exec  needs  only  the  name  of  the  script  and  the 
specific  dataset  for  the  run;  all  else  is  controlled  by  the 
specifics  in  the  scripts. 

The  script  run_update  updates  the  status  file  on  the  origin 
machine  to  reflect  the  current  status  of  the  job.  run_update 
is  invoked  by  remote  shell  calls  from  both  shepard  and 
shepard_queue. 

Networking 

Three  types  of  data  transfer  are  supported:  remote,  nfs,  and 
server.  The  best  choice  depends  very  much  upon  your 
particular  environment  and  operating  preferences.  The  choice 
of  network  is  set  in  .shepard.ini. 

In  remote  mode,  the  data  is  copied  from  its  directory  on 
the  origin  machine  into  the  user’s  login  account  on  the 
selected  host  and  then  executed.  The  output  is  transferred 
back  to  the  origin.  The  input  and  the  output  exist  on  both 
machines.  This  approach  provides  a  more  robust  operating 
mode  when  the  network  is  unreliable,  but  it  is  not  the  best 
mode  to  use  with  very  large  datasets. 

In  nfs  mode,  the  data  is  accessed  through  remotely  mounted 
network  drives  by  using  Sun’s  NFS  Network  File  System,  and 
is  not  actually  moved.  The  output  in  nfs  mode  is  written 
directly  to  the  network  drive.  Only  one  copy  of  the  input 
and  the  output  is  generated.  This  mode  is  sensitive  to 
network  crashes. 

In  server  mode,  the  data  exists,  and  the  execution  is. 
performed,  entirely  on  the  compute  server.  Only  one  copy 
of  the  input  and  the  output  is  generated.  This  is  the  best 
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mode  to  use  with  large  datasets,  and  is  also  useful  when  the 
network  is  unreliable  because  the  data  never  moves  over 
the  network. 

I  generally  use  the  server  mode  through  an  NFS-mounted 
directory.  This  method  provides  the  benefits  of  direct  access 
to  data  without  having  to  move  it,  and  is  especially  benefi¬ 
cial  when  the  datasets  are  large. 

An  Example 

The  control  files  in  this  example  are  those  used  in  my 
working  environment,  and  they  reflect  both  the  machines 
and  the  programs  I  use  in  computational  medicinal  chemis¬ 
try.  The  application  example  is  for  a  version  of  BATCHM1N 
(Columbia  University),  which  is  the  premiere  program  for 
molecular  simulation.  The  application  is  dimensioned  to 
handle  protein-sized  problems,  and  is  run  only  on  a  Convex 
supercomputer.  The  problems  are  set  up  graphically  on  an 
Iris  workstation  and  then  are  transferred  to  the  Convex  for 
simulation.  (The  simulation  process  can  last  longer  than  a 
week  for  a  single  problem.)  The  application  script  is  called 
bmin31lv,  and  the  dataset  is  referred  to  as  bmintest. 

The  operation  of  the  user  interface  is  described  in  the 
comments.  The  selection  of  executable  scripts,  the  per¬ 
formance  of  status  queries  for  running  jobs  and  the  like,  and 
the  execution  of  available  tasks  are  all  menu-driven  ac¬ 
tivities.  I  have  included  niceties  such  as  the  listings  of 
completed  jobs  when  run  is  started,  plus  the  retention  of 
selected  values  for  scripts,  datasets,  and  hosts  as  defaults  for 
the  next  invocation  of  run. 

When  a  job  is  intended  for  launching,  run  passes  the 
selection  information  to  shepard  on  the  selected  host,  and 
then  adds  the  new  job  to  the  origin  machine’s  .current  file 
with  status  STARTED.  At  this  point  run  is  no  longer  involved 
with  the  process. 

When  it’s  invoked  by  run ,  shepard  creates  a  lock  file, 
.sbeplock.  .sheplock  forces  all  other  invocations  of  shepard 
to  wait  and  also  insures  sole  access  of  all  control  files  by 
shepard.  .sheploctts  control  extends  through  the  invocation 
of  shepard_queue.  shepard  passes  the  information  to 
shepard_queue ,  which  places  the  job  in  the  .waiting  file  and 
gives  the  job  the  highest  priority  value  for  that  script  so  that 
the  newly  submitted  job  will  be  the  last  one  to  execute.  The 
origin  machine’s  .current  file  is  updated  to  status  WATTING. 

sbepard_queue  checks  the  job  count  of  a  particular  script 
against  the  maximum  job  count  in  .limits  and  proceeds  to 
execution  if  below,  or  exits,  leaving  the  job  enqueued.  To 
execute  the  job,  the  script  shepard_exec  is  passed  all  the  * 
relevant  job  information  and  submitted  as  a  background 
process.  The  job  is  removed  from  .waiting  and  placed  in 
.running  with  the  process  ID  (pid)  by  shepard_exec.  If  the 
job  fails  it  is  placed  in  .restart.  The  .current file  on  the  origin 
machine  is  updated  to  status  RUNNING.  shepard_ 
queue  returns  to  shepard ,  removes  the  lock,  and  exits.  A  log 
of  all  activities  is  maintained  so  that  the  user  can  later 
determine  what  happened. 

shepard_queue sources  an  application-specific  file,  which 
in  this  case  is  bmin31lv. script.  This  file  defines  the  generic 
shell  variables  in  shepard_exec  for  the  specifics  of  the  appli¬ 
cation.  (The  use  of  shell  variables  to  represent  the  various 
file  extensions  makes  the  basic  shepard_exec  more  flex¬ 
ible.)  Data  is  moved  by  bmin31lv_getdata,  which  is  defined 
in  $getdata_script.  The  application  is  executed  with  the 
assumption  that  it  needs  a  standard  input,  and  generates 
output  to  standard  output  and  standard  error.  bmin31lv 
takes  its  command  input  via  the  standard  input  from  bmin¬ 
test. com,  and  generates  run  output  via  standard  output  to 
bmintest.log.  It  also  uses  bmintest.dat,  which  is  moved 
along  with  bmintest.com  into  the  execution  environment. 
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(continued  from  page  18) 

bmin31lv  also  generates  a  bmintest .out,  which  is  returned 
to  the  origin  machine.  The  output  files  are  moved  back 
across  the  network  using  the  script  bmin31lv.putdata,  which 
is  defined  in  $putdata_script.  From  the  user’s  point  of  view, 
all  of  the  requisite  files  are  named,  created,  and  moved 
based  only  on  the  application  script  and  the  dataset  name; 
the  specifics  are  buried  in  the  scripts. 

Upon  completion  of  this  process,  sbepard_exec  calls 
shepard  with  the  -z  option.  shepard_exec  may  have  to  wait 
while  other  processes  (such  as  run)  and  other  completing 
jobs  execute  shepard.  Once  in  control,  the  job  is  removed 
from  .running  and  placed  in  finished.  The  origin  machine’s 
.current  is  updated  to  DONE,  the  log  files  are  updated,  and 
the  job  passes  into  history.  shepard_queue  is  invoked  with 
the  -q  option  to  check  for  waiting  jobs,  and  launch  if 
possible.  The  final  act  is  to  remove  .sheplock. 

A  different  example  is  the  killing  of  a  running  job.  When 
the  kill  task  is  selected  in  run,  shepard  is  called  on  the 
selected  host.  Once  control  is  established,  a  menu  of  run¬ 
ning  jobs  is  generated  from  .running  and  control  is  returned 
to  run.  The  job  to  be  killed  is  selected  by  its  entry  number. 
shepard  is  again  invoked,  and  now  passes  the  selection 
number  of  the  job  as  the  fifth  argument,  shepard  looks  up 
the  pid  of  the  selected  job,  and  kills  the  script  associated 
with  that  pid.  The  process  listing  is  searched  for  child 
processes  (which  in  this  case  is  the  application)  and  the 
child  processes  are  also  killed.  The  job  is  removed  from 
.running  and  the  log  files  are  updated.  Control  passes  back 
to  run. 

From  the  user’s  point  of  view,  the  shepard  system  achieves 
its  goals  of  simplifying  the  network  management  of  jobs, 
and  tells  the  user  which  jobs  are  located  where,  based  upon 
what  is  important:  the  application  and  the  dataset.  A  benefit 
of  the  queue  system  is  that  numbers  of  jobs  can  be  left 
pending  (and  easily  managed)  without  fear  of  “choking”  the 
system  if  they’re  improperly  enqueued  or  if  they’re  blocking 
other  types  of  jobs. 

Control  Files  and  Menu  Generation 

The  control  files  are  doubly  useful  both  for  generating 
menus  and  building  tables  of  values  for  lookup.  In  fact,  the 
Unix  utility  program  Awk  is  handy  for  both  tasks.  I  provide 
code  examples  to  show  the  process  of  generating  “pick-an- 
item”  menus  and  lookup  of  values  based  upon  the  selected 
item  number.  Although,  the  code  examples  are  very  simple, 
I  have  never  seen  Awk  used  in  this  manner. 

The  control  files  use  space  separation  between  the  fields. 
Awk  has  the  flexibility  to  use  selected  fields  (words)  out  of 
a  single  record  (line).  This  flexibility  offers  the  option  to  use 
the  first  several  fields  on  a  line  as  lookup  values,  and  to  use 
the  rest  of  the  fields  on  the  line  as  information  displayed  in 
the  menu.  An  example  of  this  method  is  .hosts,  in  which  the 
first  word  on  each  line  represents  a  possible  host,  and  the 
remainder  of  the  line  describes  the  host. 


File 

Format 

.runscripts: 

hostname  script  (remainder  is  descriptive  comment) 

.hosts: 

hostname  (remainder  is  descriptive  comment  on  host) 

.tasklist: 

flag  (remainder  is  description  of  ’run’  task) 

limits: 

hostname  script  maximum-jobs-per-script 

.current: 

script  dataset  host  datadir  start  finish  status 

.waiting: 

script  dataset  host  datadir  queue-position 

.running: 

script  dataset  host  datadir  process-id 

.finished: 

script  dataset  host  datadir  finished-time 

.restart: 

script  dataset  host  datadir 

Table  1:  Control file  formats 


The  formats  of  the  various  control  files  are  shown  in  Table 
1.  The  other  control  files  (. run.ini and  .shepard.ini)  and  the 
application-specific  scripts  are  all  Bourne  shell  scripts,  and 
are  commented  with  respect  to  their  functions. 

Installation 

The  scripts  and  the  control  files  should  be  placed  on  all 
desired  machines.  Give  the  scripts  run,  shepard,  shepard_ 
queue,  shepard_exec,  and  run_update  (Listings  One  through 
Five,  pages  82-88)  execution  privilege,  and  place  them  in  a 
directory  accessible  through  the  path.  Place  the  control  files 
for  the  scripts  run  {.run.ini,  .current,  .hosts,  .tasklist,  and 
.runscripts,  Listings  Six  through  Nine,  page  90)  and  shepard 
{.limits  and  .shepard.ini,  Listings  Ten  and  Eleven,  page  90) 
in  the  user’s  login  directory.  Create  a  directory  for  the 
application-specific  scripts  (Listings  Twelve  through  Sixteen, 
page  90)  and  move  those  scripts  into  the  directory.  Finally, 
compile  lockon.c  (Listing  Seventeen,  page  90)  and  place  the 
executable  in  a  directory  accessible  through  the  path. 

Modify  the  control  files  according  to  your  needs  and  your 
network  setup.  Change  .hosts  to  reflect  the  accessible  ma¬ 
chines  on  your  network,  and  modify  .runscripts  so  that  it 
uses  both  the  accessible  machines  and  the  control  scripts 
for  your  applications.  Make  the  same  changes  to  .limits  that 
is  made  to  .runscripts,  and  add  the  numbers  that  correspond 
to  a  desired  mix  of  running  jobs  for  a  maximum  load 
situation. 

Create  the  application-specific  scripts  for  your  specific 
applications  and  needs.  Use  the  example  scripts  for  bmin31lv 
as  a  template.  If  your  applications  do  not  have  a  graceful 
terminate  or  probe  capability,  set  the  variable  assignments 
in  the  master  application  .script  file  equal  to  no  strings. 

Modify  the  control  file  .shepard.ini  to  reflect  your  appli¬ 
cations  present  on  all  available  platforms,  your  preferred 
mode  of  network  access,  and  the  directory  in  which  the 
application-specific  scripts  are  kept.  (The  application  names 
are  without  the  .script  extension.)  Make  sure  that  the  net¬ 
work  mode  is  the  same  in  the  .shepard.ini  files  for  pairs  of 
platforms.  Generally,  you  cannot  mix  network  modes  be¬ 
tween  specific  pairs  of  machines,  although  other  modes  can 
be  selected  for  other  pairs. 

Finally,  if  the  machines  on  your  network  are  not  commu¬ 
nicating  freely,  make  the  necessary  changes  to  the  system 
files  that  control  access.  You  should  have  accounts  on  all 
desired  machines.  The  /etc/hosts  and  /etc/hosts. equiv  on 
each  of  a  pair  of  desired  machines  must  be  set  so  that  the 
rsh  command  works  properly.  If  you  intend  to  use  nfs  to 
move  files  between  files,  make  sure  that  your  nfs  is  enabled 
and  that  the  necessary  directories  are  mounted  remotely. 

The  system  works  without  modifications  between  Silicon 
Graphics  Iris  platforms  that  use  Unix  System  V,  Version  3-2, 
and  a  Convex  C-220  that  uses  Berkeley  Unix  4.2,  when  all 
of  the  communications  requirements  are  met. 

Future  Enhancements 

The  shepard  system  is  functional,  but  not  complete.  A 
facility  to  check  for  crashed  jobs  and  then  clean  them  up  is 
under  development.  Also,  the  changes  necessary  in  order 
to  support  multiple  users  are  straightforward,  but  they  in¬ 
troduce  a  complication  with  respect  to  the  queuing  limits: 
The  mix  of  jobs  must  also  include  a  mix  of  users. 
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OSI  Test  Bed 


Synchronous  communications  device  drivers  are 
critical  to  success 


Kenneth  L.  Crocker  and  Michael  T.  Thompson 


As  of  August  1990,  new  govern¬ 
ment  procurements  must  com¬ 
ply  with  the  Government  Open 
Systems  Interconnection  Pro¬ 
file  (GOSIP,  see  Federal  Infor¬ 
mation  Processing  Standard  146).  One 
outgrowth  of  this  requirement  will  cer¬ 
tainly  be  accelerated  development  ef¬ 
forts  for  portable  OSI  applications,  like 
the  PC-based  OSI  protocol  test  bed  we 
describe  in  this  article. 

This  test  bed  utilizes  commercially 
available,  portable  source  code  to  pro¬ 
vide  a  Class  Four  Transport  over  X.25 
Wide  Area  Network  (WAN)  implemen¬ 
tation.  The  Class  Four  transport  service 
provides  connection-oriented,  end-to- 
end  service  regardless  of  the  underly¬ 
ing  network  services.  The  test  bed  soft¬ 
ware  consists  of  approximately  42,000 
lines  of  portable  C  source  code  pur¬ 
chased  from  Retix,  8000  lines  of  C  de¬ 
veloped  to  emulate  an  FAA  weather 
data  transfer  application,  and  200  lines 
of  C  to  interface  the  Intel  82530  com¬ 
munications  hardware  to  the  Retix  soft¬ 
ware.  In  particular,  we’ll  focus  on  de¬ 
veloping  the  synchronous  communica- 
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tions  device  drivers  that  enable  the  Re¬ 
tix  software  to  communicate  with  the 
82530  hardware. 

When  designing  the  hardware-level 
device  driver,  you  must  address:  1.  The 
amount  of  time  allocated  to  input/ 
output  (I/O)  routines  based  upon  the 
highest  expected  data  rate;  2.  Timing 
requirements  unique  to  the  communi¬ 
cations  hardware;  and  3.  The  interface 
to  the  portable  code.  The  information 
presented  in  this  article  can  be  used  as 
an  example  of  how  to  design  an  inter¬ 
face  to  the  Intel  82530  controller,  as 
well  as  an  example  of  overall  system 
design  when  using  portable  communi¬ 
cations  software. 


Software  and  Hardware  Platform 

The  test  bed  itself  is  a  DOS-based  sys¬ 
tem  using  Microsoft  C  5.1  and  Micro¬ 
soft  Assembler  (MASM)  5.0  as  the  de¬ 
velopment  environment.  A  non-Unix 
operating  system  was  chosen  to  better 
study  portability  issues.  Figure  1  shows 
the  communications  and  software  ar¬ 
chitecture  currently  implemented  on 
the  test  bed.  As  shown  in  the  figure, 
Class  Four  Transport,  X.25  packet  layer 
protocol  (PLP),  and  Link  Access  Proce¬ 
dure  Balanced  (LAPB)  were  purchased 
as  portable  source  code  from  Retix. 
Operating  as  a  transport  user,  emula¬ 
tions  of  the  FAA  Data  Link  Processor 
(DLP)  and  Weather  Message  Switching 
Center  Replacement  (WMSCR)  provide 
realistic  FAA  weather  data  to  demon¬ 
strate  the  OSI  protocols.  The  device 
driver  forms  the  interface  between  the 
Intel  82530  Serial  Communications  Con¬ 
troller  (SCC)  and  the  lower  interface 
of  the  Retix  LAPB  module.  The  SCC  is 
implemented  on  an  IBM  PC/XT-com- 
patible  communications  peripheral  pur¬ 
chased  from  Sealevel  Systems.  In  our 
implementation,  the  82530  provides  lim¬ 
ited  link-layer  functions  (for  example, 
framing  and  error  checking)  with  RS- 
232  drivers  provided  by  the  Sealevel 
Systems  physical  interface.  The  current 
end-state  hardware  platform  of  the  test 
bed  is  the  IBM  PC/XT  286.  The  XT  286 
operates  at  a  clock  speed  of  6  MHz 
with  zero  wait  states.  As  a  develop¬ 
ment  platform,  the  Compaq  386/33  is 
(continued  on  page  28) 
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(continued  from  page  24) 
used  in  conjunction  with  a  software 
in-circuit  emulation  package.  The  tim¬ 
ing  analysis  explained  in  this  article  is 
based  upon  the  XT  286  platform. 

Device  Driver  Timing  Requirements 

Unix,  a  multiuser,  multitasking  operat¬ 
ing  system  (OS),  was  the  OS  Retix  chose 
to  develop  its  portable  OSI  software 
products  in.  MS-DOS,  a  single-tasking 
OS,  allows  one  program  or  process  to 
run  at  any  given  time.  This  means  that 
the  device  driver  can  either  move  data 
via  software  polling  or  hardware  inter¬ 
rupts.  In  polling,  the  device  driver  rou¬ 
tines  are  placed  inside  what  is  essen¬ 
tially  an  infinite  loop.  The  polling  rou¬ 
tine  is  then  executed  during  each  pass 
through  the  loop;  however,  every  in¬ 
struction  that  is  added  to  the  polling 
code,  such  as  program  diagnostics,  in¬ 
creases  the  total  loop  execution  time, 
which  means  that  the  communications 
hardware  is  interrogated  less  often.  Con¬ 
versely,  interrupt-  or  event-driven  com¬ 
munications  alert  the  processor  when¬ 
ever  data  has  been  received  or  the  trans¬ 
mit  buffer  is  ready  to  accept  more  data. 
The  interrupt-driven  solution  gives  pro¬ 
gram  control  to  the  device  driver  when¬ 
ever  it  is  required,  unlike  the  polling 
method,  where  program  control  is 
gained  on  a  per-loop  basis.  The  system 
described  in  this  article  uses  a  combi¬ 
nation  of  polled  and  interrupt-driven 
I/O.  The  upper  layer  portable  code  is 
polled  to  check  a  series  of  event  queues, 
while  the  receive  and  transmit  data  are 


Figure  1:  Test  bed  architecture 


handled  via  interrupts.  The  design  of 
the  interrupt  handler  for  this  interface 
must  account  for  the  following  timing 
considerations:  1.  The  overall  time  to 
execute  the  interrupt  routine  must  al¬ 
low  for  non-interrupt  processing  to  oc¬ 
cur  during  data  transfer;  2.  The  cycle 
and  reset  recovery  times  of  the  SCC 
must  be  met;  and  3.  The  timing  win¬ 
dow  of  the  SCC  for  reading  and  writing 
data  must  also  be  met. 

Because  the  9600  bit-per-second 
(bps)  inbound  data  will  generate  a  re¬ 
ceive  interrupt  every  104  microseconds 
((is)  in  the  test  bed  environment,  the 
SCC  is  programmed,  as  will  be  described 
later,  to  generate  an  interrupt  for  every 
8  bits  of  received  data  and  whenever 
the  transmit  buffer  is  empty.  The  re¬ 
ceive  interrupt  period  is  derived  as: 

period  of  receive  interrupt  =  (no. 
bits  per  character  from  SCO  /  (trans¬ 
mission  rate  in  bps') 

The  104-|is  time  span  translates  into 
approximately  624  timing,  or  clock, 
states  for  the  6-MHz  XT  286.  The  80286 
can  process  approximately  100  assem¬ 
bler  instructions  in  that  time  frame,  as¬ 
suming  an  average  of  six  timing  states 
per  instruction  for  the  types  of  instruc¬ 
tions  used  in  the  device  driver  (for 
example,  push ,  pop,  mov,  test ,  in,  out) 
and  ignoring  other  pending  interrupts, 
system  calls,  and  so  on.  For  efficiency, 
the  interrupt  routine  that  loads  the  in¬ 
coming  data  into  the  communication 
stack  buffer  manager  should  not  oc¬ 


cupy  more  than  25  percent  of  the  total 
interrupt  period.  In  a  true  full-duplex 
environment,  one-half  of  the  total  pro¬ 
cessing  time  would  be  spent  handling 
I/O  while  the  other  half  would  be  used 
by  application  and  communications 
stack-processing  needs.  Development 
in  the  6-MHz  XT-286  environment  has 
shown  that  a  faster  processor  is  re¬ 
quired  for  this  type  of  interface.  At  6 
MHz,  our  interrupt  routines  can  take 
up  to  a  full  character  time  (or  104  (is) 
to  execute.  This  is  due  to  the  buffer 
management  requirements  imposed  by 
the  portable  software  design  and  the 
required  handshaking  with  the  com¬ 
munications  hardware.  In  our  proto¬ 
type  environment,  we  control  the  over¬ 
all  throughput  of  the  system  by  insert¬ 
ing  delay  to  limit  the  transmit  frame 
rate  at  the  transport  layer.  In  this  man¬ 
ner  we  are  able  to  adjust  the  transmit 
throughput  at  the  link  layer  to  accom¬ 
modate  our  specific  needs.  Because 
LAPB  is  a  windowing,  asynchronous, 
acknowledgment-based  protocol,  when 
system  A  is  transmitting  a  frame  to  sys¬ 
tem  B,  system  B  will  wait  until  a  set 
number  of  frames  have  been  correctly 
received  before  acknowledging  the  win¬ 
dow  to  system  A.  Once  a  link-layer 
connection  has  been  established,  nor¬ 
mal  communications  continue  in  this 
manner. 

Assuming  a  frame  size  of  512  bytes, 
this  will  yield  53  milliseconds  (ms)  of 
interrupt  processing  time  and  947  ms 
to  process  the  frame  at  the  upper  lay¬ 
ers.  For  proper  throughput  efficiency, 
either  a  faster  processor  or  a  more  stream¬ 
lined  interface  to  the  portable  code 
will  be  required;  however,  we  have 
been  able  to  successfully  interoperate 
with  hardware  and  software  manufac¬ 
tured  by  different  vendors  using  this 
processing  method. 

The  second  set  of  timing  considera¬ 
tions  of  the  device  driver  are  the  cycle 
and  reset  recovery  times  of  the  SCC. 
The  cycle  recovery  time  applies  to  the 
time  period  between  any  read  or  write 
cycles  to  the  SCC.  This  time  period  is 
defined  to  be  six  Processor  Clock 
(PCLK)  cycles.  The  reset  recovery  time 
applies  to  the  time  required  to  perform 
a  software  or  hardware  reset.  The  local 
PCLK  on  the  Sealevel  Systems  board 
operates  at  4.9152  MHz.  This  implies  a 
cycle  recovery  time  of  1.22  (is  and  a 
reset  recovery  time  of  2.24  (is.  To  en¬ 
sure  that  this  critical  timing  requirement 
is  met,  the  resulting  assembler  output 
from  the  C  compiler  must  be  analyzed. 
In  sections  where  the  cycle  and  reset 
recovery  times  are  not  met,  dummy 
code  (for  example,  nop,jmp$+2)  is  in¬ 
serted  to  achieve  the  proper  delay.  The 
modified  assembler  code  is  then  com- 
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(continued  from  page  28) 
piled  using  Microsoft  MASM  5.0. 

The  third  device  driver  timing  con¬ 
sideration  is  the  maximum  time  allowed 
to  transfer  data  to  and  from  the  chip. 
Synchronous  communication  transfers 
data  in  a  steady  stream.  Unlike  asyn¬ 
chronous  protocols,  which  use  start  and 
stop  bits  to  frame  each  character,  syn¬ 
chronous  data  is  transferred  in  streams 
of  128,  256,  and  greater  bytes  of  data. 
These  data  streams,  or  frames,  are  sepa¬ 
rated  by  flags.  Because  each  byte  of 
data  must  be  transmitted  in  succession 
with  the  previous  byte,  the  transmit 
routine  must  place  the  outbound  data 
into  the  SCC  before  the  previous  byte 
has  been  completely  transmitted.  This 
timing  requirement  is  imposed  by  the 
internal  architecture  of  the  82530.  The 
architecture  of  the  controller  and  the 
required  interface  software  are  discussed 
in  following  sections. 

Hardware  Architecture  and  Initialization 

The  SCC  has  two  independent  full- 
duplex  channels  with  14  write  registers 
and  7  read  registers  per  channel.  All 
modes  of  communications  are  estab¬ 
lished  by  the  bit  values  sent  to  the  write 
registers  when  the  system  is  initialized. 
As  data  is  received  or  transmitted,  the 
read  register  values  will  change  accord¬ 
ing  to  the  mode  programmed  in  the 
original  setup.  These  changes  to  the 
read  registers  can  cause  hardware  or 
software  actions  that  lead  to  changes 
to  other  registers  or  other  software  or 
hardware  reactions. 

The  SCC  also  utilizes  a  3-byte  first-in- 
first-out  (FIFO)  receive  queue  and  a 
20-bit  transmit  shift  register  which  is 
loaded  by  a  1-byte  transmit  data  buffer. 
The  user  of  the  SCC  communicates  with 
both  mechanisms  via  a  1-byte  I/O  buffer. 
For  synchronous  communications,  the 
transmit  shift  register  must  always  con¬ 
tain  data  during  a  frame  transmission. 
If  a  transmit  underrun  occurs,  the  SCC 
appends  the  2-byte  checksum  field  and 
flag  information  to  the  data  stream.  The 
receiving  side  of  this  data  transfer  will 
then  see  an  incomplete  link-layer  data 
frame,  resulting  in  a  link-layer  reject 
and  possibly  network-layer  error  re¬ 
covery.  If  the  3-byte  receive  queue  over¬ 
flows,  then  receive  data  is  lost,  again 
causing  link-layer  rejects  to  occur.  As 
stated  in  the  previous  section,  the  hard¬ 
ware  driver  must  assure  that  the  trans¬ 
mit  shift  register  always  contains  data 
when  sending  a  frame  and  that  the 
receive  queue  is  maintained  at  a  near- 
empty  level. 

The  initialization  of  the  SCC  for  in¬ 
terrupt-driven  synchronous  communi¬ 
cations  is  divided  into  three  parts.  Each 
part  is  unique  to  the  initialization  pro- 


Sl 


cess  and  must  follow  the  proper  in¬ 
itialization  sequence  for  correct  opera¬ 
tion  of  the  SCC.  The  proper  initializa¬ 
tion  sequence  is  the  most  critical  part 
of  the  initialization  process.  As  we 
learned,  the  SCC  can  appear  to  operate 
correctly,  but  not  be  capable  of  interoper¬ 
ating  with  other  communications  hard¬ 
ware.  In  our  case,  the  two  back-to- 
back  SCCs  on  our  test  bed  were  mov¬ 
ing  data  without  errors,  yet  when  we 
tried  to  communicate  across  a  packet 
switch,  every  frame  was  rejected  be¬ 
cause  of  a  bad  checksum.  The  trans¬ 
mitter  and  receiver  were  inverting  the 
checksum  due  to  an  out-of-sequence, 
but  otherwise  correct,  initialization  pro¬ 
cess. 

During  early  debugging  and  experi¬ 
mentation  with  the  device  driver,  we 
inserted  an  initialization  sequence  that 
corrected  our  current  problem  and 
caused  another  problem  that  did  not 
surface  until  we  introduced  a  different 
system,  such  as  the  packet  switch.  The 
initialization  of  the  SCC  must  strictly 
follow  the  sequence  explained  in  the 
technical  manual,  and  any  “debugging” 
changes  should  be  checked  against  this 
sequence  to  avoid  side  effects  similar 
to  what  we  encountered. 

The  first  part  of  the  initialization  se¬ 
quence  consists  of  programming  the 
operation  modes  of  the  SCC  such  as 
bits-per-character  and  time  constants. 
As  you  can  see  in  the  source  code 
listings,  we  begin  by  forcing  a  hard¬ 
ware  reset.  The  Synchronous  Data  Link 
Control  (SDLC)  mode  of  operation  is 
then  selected.  The  SCC  actually  imple¬ 
ments  a  small  subset  of  the  SDLC  pro¬ 
tocol.  This  subset,  in  conjunction  with 
the  LAPB  functions  provided  by  the 
Retix  link-layer  software,  meets  the  link- 
layer  requirements  of  the  test  bed.  The 
receive  and  transmit  character  lengths 
are  then  set  to  8  bits  each,  and  7Eh  is 
selected  as  the  flag  pattern  to  be  sent 
between  frames.  The  initial  checksum 
value  is  set  to  FFh  (required  for  proper 
SDLC  operation),  the  RTxC  pin  of  the 
82530  is  selected  as  the  source  for  DTE 
clocking,  and  the  baud-rate  time  con¬ 
stant  is  loaded  during  the  final  initiali¬ 
zation  steps  of  this  phase  of  SCC  in¬ 
itialization. 

The  second  phase  of  SCC  initializa¬ 
tion  consists  of  enabling  the  baud-rate 
generator  to  provide  transmit  clock  and 
enabling  the  transmitter  and  receiver. 
During  each  subsequent  phase  of  in¬ 
itialization,  the  previously  set  values 
(such  as  transmit  and  receive  character 
length)  must  again  be  set  during  each 
use  of  a  particular  write  register.  As  an 
example,  write  register  3  is  used  in  this 
section  to  enable  the  receiver,  yet  all 
previously  programmed  information  for 
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(continued  from  page  30) 
write  register  3  must  be  also  be  in¬ 
cluded.  This  phase  of  initialization  is 
completed  by  enabling  the  transmit 
checksum  generator,  transmit  interrupts, 
and  receive  interrupts. 

Part  three  consists  of  enabling  the 
different  interrupts  used  by  the  system. 
In  our  implementation,  the  transmit  un¬ 
derrun  interrupt  is  enabled  and  all  pre¬ 
viously  selected  interrupts  are  enabled. 
This  completes  the  initialization  of  the 
SCC.  For  further  initialization  informa¬ 
tion,  the  reader  should  consult  the  82530 
technical  reference  manual.  The  remain¬ 
der  of  this  article  describes  the  soft¬ 
ware  required  to  interface  the  Retix 
LAPB  portable  software  to  the  SCC,  as 
well  as  general  information  concerning 
the  implementation  of  portable  com¬ 
munications  software. 

Data  Buffers  Initialization 

At  the  start  of  the  initialization  process, 
a  large  block  of  memory  is  assigned  to 
the  system  buffer  pool  so  that  data 
buffers  can  be  allocated  for  both  the 
transmit  and  receive  routines.  Some  of 
those  buffers  are  preallocated  for  use 
by  the  receive  routine  only  and  pui 
into  the  Baddr  array  for  later  use  by  the 
receiver.  The  remaining  buffer  pool  can 
then  be  allocated  and  deallocated  to 
buffers  as  needed  by  the  transmit  rou¬ 
tine.  After  the  buffer  pool  is  created, 
the  init_rcvbuf( )  routine  in  x251t.c  (see 
Listing  One,  page  92)  is  used  to  fill  the 
receive  buffer  array  with  the  pointers 
to  the  allocated  buffers. 

Preallocation  of  the  receive  buffers 
is  necessary  in  the  synchronous,  inter¬ 
rupt-driven  environment.  Buffers  must 
be  allocated  when  the  interrupts  are 
enabled  so  that  if  no  buffer  is  currently 
available,  the  allocation  routine  can  loop 
until  one  becomes  available.  If  inter¬ 
rupts  were  disabled  during  this  period, 
no  buffers  would  ever  become  avail¬ 
able  —  none  could  ever  be  freed  with¬ 
out  the  transfer  of  data. 

Receiver 

After  the  system  has  preallocated  the 
first  buffer  in  the  Baddr  array,  the  first 
buffer  is  then  available  to  be  written 
to  by  the  interrupt  receiver  routine  as 
soon  as  the  interrupts  are  enabled.  As 
each  new  character  is  received,  the 
pointer  to  the  next  memory  location  is 
incremented  and  the  character  is  stored 
in  the  buffer.  When  the  last  character 
of  the  frame  is  received,  the  frame  is 
checked  for  a  valid  checksum.  If  the 
checksum  is  invalid,  the  software  per¬ 
forms  an  error  reset  and  discards  the 
bad  frame  by  resetting  the  character 
counter  to  zero.  If  the  frame  is  valid, 
the  MDATind  (listed  as  vpmidi  in  the 


code;  see  Listing  Two,  page  93)  routine 
is  called  and  the  new  buffer  pointer  is 
put  on  the  Retix  queue  for  further  pro¬ 
cessing  by  the  portable  software.  After 
the  buffer  pointer  is  added  to  the  in¬ 
coming  data  queue,  we  get  the  address 
of  the  next  available  buffer  from  the 
Baddr  array  and  set  the  proper  point¬ 
ers  so  that  it  is  now  available  for  new 
incoming  data.  The  data  receiver  rou¬ 
tine  has  a  higher  priority  than  the  trans¬ 
mitter  routine;  therefore,  at  the  end  of 
the  receiver  routine  we  check  to  see  if 
a  transmit  interrupt  is  pending.  If  so, 
that  character  is  processed  before  leav¬ 
ing  the  interrupt  routine. 

Transmitter 

On  the  transmit  side,  when  a  buffer  is 
first  sent  to  the  MDATreq  routine  (see 
Listing  Two),  we  check  to  see  if  an¬ 
other  frame  is  currently  being  transmit¬ 
ted.  If  one  is,  we  return  to  the  calling 
routine  and  try  again  later.  If  no  frame 
is  being  transmitted,  a  test  is  made  to 
see  if  the  SCC  transmit  buffer  is  empty. 
If  it  is,  the  pointers  and  counters  are 
set  and  the  first  character  is  sent.  At 
that  point,  we  confirm  the  buffer  and 
start  the  end  of  frame  processor.  The 
transmit  buffer  is  again  checked  to  see 
if  it  is  empty  and  when  it  is  we  send  the 
second  character.  The  interrupt  driver 
will  continue  to  send  the  remaining 
data  until  the  last  byte  of  the  frame  is 
delivered  along  with  the  frame’s  check¬ 
sum  data.  The  reason  two  characters 
are  sent  instead  of  one  is  because  the 
amount  of  processing  that  must  be  done 
after  the  first  character  is  sent  does  not 
allow  us  to  return  from  this  routine 
before  the  transmit  buffer  of  the  82530 
chip  empties.  The  transmit  underrun 
condition  will  result  in  a  false  end-of- 
frame  and  checksum  generation.  We 
essentially  “prime”  the  SCC  transmit 
shift  register  with  enough  data  to  allow 
the  driver  to  stay  ahead  of  the  SCC 
transmitter  during  the  first  few  bytes 
of  frame  transmission. 

System  Polling  Routine 

As  we  discussed  ear’ier,  the  system  em¬ 
ploys  a  combination  polled  and  inter¬ 
rupt-driven  environment.  The  portable 
software  is  executed  out  of  a  polling 
loop  and  is  driven  by  the  data  from  the 
SCC.  After  the  hardware  and  buffer  in¬ 
itialization  have  been  completed,  the 
polldatO  routine  (see  Listing  Three, 
page  92)  manages  the  preallocated,  re¬ 
ceiver  buffer  array.  As  a  buffer  is  used 
by  the  receiver  routine,  the  pointer  in 
the  array  is  set  to  NULL  and  the  buffer 
array  counter,  rbufent,  is  decremented 
by  one.  If  the  buffer  counter  ever  goes 
below  four,  then  the  test  in  poldat( ) 
will  be  true.  Each  NULL  pointer  in  the 
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(continued  from  page  32) 

Baddr  array  is  then  given  a  new  buffer 
address.  This  allows  the  receiver  rou¬ 
tine  to  always  have  a  fresh  supply  of 
buffer  pointers.  Buffer  management  is 
depicted  in  Figure  2. 


Interoperability  Results 

Our  test  bed  has  been  used  to  proto¬ 
type  several  query/response  applica¬ 
tions  that  run  over  the  transport  layer 
and,  in  another  environment,  the  net¬ 
work  layer.  The  applications  include 


weather  database  transfer  and  mainte¬ 
nance  messaging.  Furthermore,  we  have 
been  able  to  successfully  interoperate 
with  a  VAX  utilizing  DEC  OSI  software 
as  well  as  a  Tandem  computer  imple¬ 
menting  Tandem  X.25.  Successful  tests 


The  OSI  Reference  Model 


A  system  can  be  “closed,”  whereby 
components  are  not  interchangable 
with  another  supplier’s  equipment  (or 
alternate  technology)  without  affect¬ 
ing  other  parts  of  the  system;  or,  us¬ 
ing  well-defined,  publicly  available 
interface  standards  that  treat  compo¬ 
nents  as  black-boxes,  the  system  can 
be  “open.”  The  advantage  of  an  open 
system  is  its  access  to  multivendor 
systems  and  growth  without  requir¬ 
ing  totally  new  systems. 

The  International  Organization  for 
Standardization’s  (ISO)  Open  Systems 
Interconnection  (OSI)  Reference 
Model  is  an  open  system  approach 
for  communications  interfaces.  As  il¬ 
lustrated  in  Figure  3,  standardization 
reduces  the  number  of  unique  inter¬ 
faces  across  a  network.  In  the  exam¬ 


ple,  four  closed  systems  require  12 
unique  interfaces  to  communicate  with 
each  other.  With  a  standard  set  of 
rules  and  procedures,  like  OSI,  only 
four  unique  OSI-to-native  environment 
interfaces  are  required.  This  approach 
reduces  the  cost  of  system  develop¬ 
ment,  procurement,  support,  and  main¬ 
tenance  by  eliminating  the  need  to 
develop,  debug,  and  maintain  cus¬ 
tom  interfaces. 

The  OSI  reference  model  is  a  frame¬ 
work  divided  into  seven  data  com¬ 
munications  function  layers:  physi¬ 
cal,  data  link,  network,  transport,  ses¬ 
sion,  presentation,  and  application. 
The  OSI  architecture  presents  few  new 
ideas  to  data  communications:  It  is 
just  a  way  of  dividing  the  functions 
required  for  data  communications  into 


manageable  and  understandable  sub¬ 
sets.  Communications  systems  de¬ 
signed  without  using  the  OSI  Refer¬ 
ence  Model  contain  many  of  the  same 
functions  as  OSI-based  systems;  these 
functions,  however,  are  generally 
lumped  together  into  several  unde¬ 
fined  layers.  OSI  provides  primitives , 
a  minimum,  well-defined  flow  of  in¬ 
formation  between  the  layers.  The 
implementation  of  these  primitives  is 
unique  to  a  system,  but  the  informa¬ 
tion  passed  with  these  primitives  is 
standard  across  all  systems.  This  modu¬ 
lar  approach  to  communications  eases 
software  maintenance  since  it  lends 
itself  to  the  development  of  modular, 
maintainable  code. 

Within  each  function  layer,  several 
international  standard  protocols  exist 
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have  also  been  conducted  over  a  small 
packet  switch  with  two  PCs  function¬ 
ing  as  the  end-systems.  The  PC-based 
system  has  to  provide  the  flexibility  to 
interoperate  in  a  heterogeneous  hard¬ 
ware  and  software  environment. 


Time,  Skill,  and  Resource  Requirements 

Development  of  the  four-layer  system 
and  application,  including  learning 
curve,  required  approximately  15  staff 
months.  The  staff  working  on  a  project 
of  this  nature  should  possess  layered 


protocol,  real-time  software  develop¬ 
ment,  and  testing  knowledge.  This  type 
of  project  requires  the  same  hardware 
and  software  tools  as  any  real-time  pro¬ 
ject.  At  a  minimum,  a  logic  analyzer, 
oscilloscope,  in-circuit  emulator,  and 


for  implementation  within  the  realm 
of  the  OSI  Reference  Model.  GOSIP 
(the  U.S.  Government  OSI  Profile,  see 
Federal  Information  Processing  Stan¬ 
dard  146)  further  defines  the  refer¬ 
ence  model  into  sets  of  protocols  (or 
profiles)  that  will  be  used  for  govern¬ 
ment  data  communications  systems. 
The  OSI  suite  can  be  viewed  as  pro¬ 
viding  transport  and  application  ser¬ 
vices.  The  transport  services  (physi¬ 
cal,  data  link,  network,  transport)  pro¬ 
vide  communications-related  functions 
(such  as  network  routing  and  guar¬ 
anteed  delivery  of  data).  The  applica¬ 
tion  services  (session,  presentation, 
and  application)  provide  a  toolkit  of 
features  for  the  applications  program¬ 
mer,  so  you  do  not  need  to  know  the 
details  of  data  communications  to  write 
an  application. 

For  example,  if  you  need  to  write 
a  word  processor  that  includes  file 
transfer  capabilities,  you  would  de¬ 


sign  the  word  processor  to  use  the 
the  File,  Transfer,  Access,  and  Man¬ 
agement  application-layer  protocol 
(see  ISO  8571).  Using  the  standard 
application-layer  protocol,  the  basics 
of  file  transfer,  such  as  the  use  of 
synchronization  points  for  roll-back 
and  management  of  the  virtual 
filestore,  would  be  handled  in  the 
application-layer  protocol,  not  the 
word  processor.  This  layering  of  func¬ 
tions  is  the  basis  for  the  OSI  Refer¬ 
ence  Model.  If  you  need  to  design  a 
special  application  not  covered  by 
the  standard  application-layer  proto¬ 
cols,  you  could  use  the  other  applica¬ 
tion  services  features  (like  data  trans¬ 
lation  and  remote  operation  support) 
without  having  to  redevelop  these  func¬ 
tions. 

—  K.C..M.T. 


Dr.  Dobb’s Journal,  December  1990 

1106 


35 


Buffer  Pool 


Receiver  Array 


Buffer  Pool 
is  created  at 
initialization 


30 


Allocated 

to 

Receiver 

Array 


Used  by  the 
-  interrupt  driven 
receive  device 
driver 


Used  by  the 
interrupt  driven 
transmitter  device 
driver 


As  Buffers  are  used  by  the 
receiver  they  are  freed  to 
the  Buffer  Pool.  When  the 
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poldat  routine  replenishes 
the  Array  from  the 
Buffer  Pool. 
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Figure  2:  Buffer  management 


protocol  analyzer  with  simulation  ca¬ 
pability  should  be  available.  Code¬ 
level  debuggers  (such  as  Microsoft  Code¬ 
View)  are  useful  in  debugging  the  ap¬ 
plication  code;  however,  they  do  inter¬ 
fere  with  the  individual  protocol  timers 
of  each  layer  and  the  timing  require¬ 
ments  of  moving  data  up  and  down  the 
communications  stack.  Software  in- 
circuit  emulators  that  utilize  the  pro¬ 
tected  mode  of  the  80386  and  allow 
you  to  run  the  test  application  as  a 
virtual  machine  (for  example,  Nu-Mega 
Softlce)  are  very  useful.  If  an  80386- 
based  machine  is  available,  this  is  a 
cost-effective  substitute  for  a  hardware 
in-circuit  emulator. 

Recommended  Development  Process 

Development  of  the  test  bed  has  shown 
that  the  device  driver  is  the  most  criti¬ 
cal  part  of  the  system  design.  The  de¬ 
vice  driver  should  be  designed,  tested, 
and  tuned  before  the  upper  layers  are 
added.  Most  likely,  vendor-unique  man¬ 
agement  interfaces  will  need  to  be  im¬ 
plemented  with  the  device  driver.  The 
device  driver  can  be  written  in  the  na¬ 
tive  language  of  the  portable  code  to 
ease  the  interface  to  the  link  layer,  and 
the  assembler  output  of  your  compiler 
should  be  analyzed  to  determine  if  fur¬ 
ther  optimization  is  necessary.  In  our 
case,  Microsoft  C  5.1  (compiling  for 
execution  speed  optimization)  pro¬ 
duced  tight  assembler  code  that  re¬ 
quired  little  hand-tuning  outside  of  that 
necessary  to  meet  the  82530  cycle  and 
reset  times.  Once  the  device  driver  and 
management  routines  have  been  de¬ 
veloped,  work  can  then  progress  on 


porting  the  upper  layers.  Finally,  the 
application  can  be  written,  but  the  tim¬ 
ing,  polling,  and  interrupt  activity  must 
be  considered  at  every  phase  of  the 
system  debugging. 

Conclusions 

The  field  of  OSI  software  is  still  young, 
and  technical  risks  will  continue  to  de¬ 
crease  as  the  field  matures.  The  test 
bed  development  effort  has  shown  that 
at  least  the  lower  four  layers  can  be 
implemented  today  using  commercially 
available  portable  source  code.  Our 
work  has  confirmed  that  it  is  much 
easier  to  implement  portable  source 
code  than  to  redevelop  it  for  a  particu¬ 
lar  system.  However,  the  use  of  port¬ 
able  source  code  is  not  just  a  “compile- 
and-go”  situation,  since  it  is  essentially 
a  large  real-time  system  driven  by  the 
data  of  another  OSI  end-system  or  relay- 
system. 
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The  Macintosh 
Communications 
Toolbox 

Writing  comm  applications  that  are  terminal,  file  transfer, 
and  connection  independent 


Don  Gaspar 


Along  with  standardized  com¬ 
munications  functions,  Apple’s 
Macintosh  Communications 
Toolbox  provides  an  entire  spec¬ 
trum  of  dynamic  tools  to  aid 
you  in  constructing  dynamic  communi¬ 
cations  applications.  Programs  that 
make  use  of  the  Comm  Toolbox  be¬ 
come  completely  terminal,  file  transfer, 
and  connection  independent.  If  you 
have  to  add  any  new  functions  and  if 
your  program  is  written  properly ,  your 
communications  program  will  be  ex¬ 
tended  with  the  new  functionality.  The 
Comm  Toolbox  does  this  via  tools  kept 
in  the  System  Folder  that  offer  inde¬ 
pendence  for  the  communication  ap¬ 
plications. 

Before  putting  the  Comm  Toolbox 
to  work  for  you,  become  familiar  with 
the  Connection  Manager,  Terminal  Man¬ 
ager,  and  File  Transfer  Manager.  (A 
fourth  key  manager  —  the  Communica¬ 
tions  Resource  Manager  —  will  not  be 
discussed  in  the  context  of  this  article.) 
As  Figure  1  illustrates,  these  managers 
interact  with  specific  tools  that  work 
directly  with  the  ROM  OS.  The  three 
managers  expand  the  functionality  of 
the  Macintosh  Toolbox  by  offering  func¬ 
tions  for  any  type  of  application  that 
involves  communications.  The  manag- 


Don  is  a  software  engineer  at  Apple 
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working  for  Dialog  Information  Ser¬ 
vices  at  the  time  he  wrote  this  article. 


ers  are  simple  to  use,  and  their  func¬ 
tions  resemble  those  of  the  other  tool¬ 
box  managers  you’ve  already  been  us¬ 
ing  for  years.  If  you’ve  used  the  Mem¬ 
ory  Manager,  TextEdit,  QuickDraw,  the 
Window  Manager,  and  some  of  the 
others,  you’re  ready  to  go. 

The  Connection  Manager 

The  Connection  Manager  is  a  medium 
through  which  you  tell  the  Comm  Tool¬ 
box  what  type  of  physical  connection 
is  between  your  Mac  and  the  device  it’s 
talking  to.  This  “other"  device  might 
be  a  modem,  a  direct  serial  connection, 
ADSP,  perhaps  a  software  MNP  level  5 
or  X.25  tool,  or  maybe  something  that 


hasn’t  even  been  thought  of  yet.  No 
problem.  Just  write  your  own  connec¬ 
tion  tool  and  anyone  who  writes  a  pro¬ 
gram  using  the  Comm  Toolbox  will  be 
able  to  use  your  new  hardware  connec¬ 
tion  as  well. 

For' instance,  once  the  user  selects 
the  type  of  connection  being  used  (or 
sets  a  default),  special  preferences  can 
then  be  made  for  that  particular  con¬ 
nection.  If  using  a  modem  tool,  the 
user  should  be  able  to  tell  the  program 
what  type  of  modem  is  being  used,  the 
phone  number  to  dial,  baud  rate,  stop 
bits,  parity,  and  so  on. 

The  function  that  enables  this  pa¬ 
rameter  setting  is  CMChoose( ).  When 
called,  the  Comm  Toolbox  displays  a 
dialog  box  (see  Figure  2)  that  allows 
the  user  to  change  settings.  This  is  the 
standard  dialog  box  offered  through 
the  Comm  Toolbox;  you  don’t  have  to 
use  it  if  you  don’t  want  to.  You  can 
override  anything  you  don’t  like,  then 
design  and  use  your  own.  For  consis¬ 
tency  across  communications  programs, 
however,  it’s  recommended  you  stick 
with  the  standard  so  that  someone  un¬ 
familiar  with  your  program  will  under¬ 
stand  how  to  use  it. 

The  Terminal  Manager 

The  Terminal  Manager  tells  the  Comm 
Toolbox  what  type  of  emulation  is  tak¬ 
ing  place:  TTY,  VT-100,  VT-320,  or  even 
IBM  3278.  With  the  Comm  Toolbox, 
you  just  add  a  terminal  tool  with  the 
emulation  you  want  in  the  system  folder; 
your  program  then  becomes  terminal 
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(continued  from  page  38) 
independent.  Apple  has  implemented 
several  of  these  emulations,  including 
VT-320.  You  can  use  the  ones  that  al¬ 
ready  exist,  license  more  from  a  third 
party,  or  write  your  own. 

The  Terminal  Manager’s  counterpart 
to  the  Connection  Manager’s  CM- 
Choosei )  is  TMChooseC );  the  dialog 
changes  according  to  what  type  of  ter¬ 
minal  is  selected  and  allows  the  user 
to  change  their  preference  for  the  par¬ 
ticular  terminal  they  are  using  (the  tool 
controls  this). 

The  File  Transfer  Manager 

The  File  Transfer  Manager  allows  you 
to  implement  standard  file  transfer  (Ker- 
mit,  XModem,  ZModem,  text  transfer, 


and  so  on)  functions  with  minimal  ef¬ 
fort,  for  file  transfer  independence.  Sup¬ 
pose,  for  instance,  that  next  year  a  new 
file  transfer  scheme  is  implemented  on 
CompuServe.  What  would  happen  to 
your  program?  Would  you  have  to  send 
users  new  disks  with  the  new  file  trans¬ 
fer  added  to  it?  Not  at  all.  Users  simply 
add  the  new  file  transfer  tool  to  their 
System  Folder,  and  because  your  pro¬ 
gram  is  file  transfer  independent,  it  can 
automatically  use  the  new  tool  without 
any  modifications.  In  fact,  the  current 
file  transfer  tool  can  be  used  to  get  the 
new  one. 

A  Sample  Comm  Toolbox  Application 

In  this  section,  I’ll  briefly  describe  a 
communications  application  I  call 


Figure  1:  How  the  Communication  Managers  intereact 
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Figure  2:  The  Connections  Manager  dialog  box 


“CheapCom”  (see  Listing  One,  page 
94).  This  program,  written  using  MPW 
C  3-1,  illustrates  how  the  Comm  Tool¬ 
box  managers  and  other  functions  are 
implemented  to  easily  build  a  full- 
featured  communications  program  that 
supports  connection,  terminal  emula¬ 
tion,  and  file  transfer.  Because  of  space 
constraints,  I  haven’t  included  any  of 
the  standard  Macintosh  user  interface 
features  in  Listing  One;  the  code  pre¬ 
sented  is  the  communications  core.  How¬ 
ever,  the  complete  system  (including 
resource  files),  as  well  as  just  the  core 
code,  is  available  online  (see  Source 
Code  Availability,  page  3,  for  details). 
To  compile  and  use  the  program,  you'll 
need  the  Comm  Toolbox  installed  on 
your  Macintosh,  MPW  with  the  C  com¬ 
piler  Version  3-1  or  later,  and  the  Comm 
Toolbox  Interface.  (Contact  APDA,  Ap¬ 
ple  Computer  Inc.,  20525  Mariani  Ave., 
Cupertino,  CA  95014,  for  Comm  Tool¬ 
box  specifics.) 

To  start  off,  you  have  to  initialize  the 
communication  managers  just  as  you 
do  the  Window  Manager,  TextEdit, 
QuickDraw,  and  the  others.  A  typical 
initialization  function  might  resemble 
that  in  Figure  3-  For  compatibility  rea¬ 
sons,  always  initialize  the  Comm  Tool¬ 
box  in  the  order  shown  in  Figure  3. 
You  should  also  always  check  for  exis¬ 
tence  of  the  Comm  Toolbox  before 
initializing  it,  otherwise  the  error  codes 
returned  will  be  meaningless.  (If  the 
user  is  not  using  System  7.0,  then  the 
Comm  Toolbox  must  be  installed  via  a 
special  INIT,  available  from  APDA.)  If 
the  Comm  Toolbox  isn’t  there  when 
you  start  up,  your  program  will  either 
have  to  disable  its  communications  func¬ 
tionality  or  it  will  have  to  just  quit  (after 
notifying  the  user,  of  course). 

Next,  you  should  check  for  tools.  If 
no  tools  are  available,  the  value  “xxNo- 
Tools”  will  be  returned;  you  might  want 
to  quit  your  program  in  that  case.  For 
example,  if  no  connection  tools  were 
available,  it  would  be  physically  im¬ 
possible  to  establish  a  hardware  con¬ 
nection.  So  you  must  alert  the  user  and 
quit  the  application.  However,  if  no  file 
transfer  tools  were  available,  rather  than 
quit  the  program  you  might  simply  alert 
the  user  that  the  program  couldn’t  find 
any  and  disable  the  user’s  ability  to  se¬ 
lect  functions  that  deal  with  file  transfer. 

Then,  you  need  to  make  a  new  termi¬ 
nal  record,  connection  record,  and  file 
transfer  record.  Code  like  that  shown 
in  Figure  4  accomplishes  this.  The  calls 
TMNew( ),  CMNew( ),  and  FTNew(  )  set 
up  the  appropriate  records  for  your 
application  to  start  with  communica¬ 
tions;  these  calls  resemble  TENew( ) 
from  TextEdit,  and  will  be  familiar  to 
Mac  programmers.  You  also  have  to  set 
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InitGraf ( (Ptr)  &qd.thePort) ; 
InitFonts  ()  ; 

InitWindows () ; 

InitMenus  ()  ; 

TEInitO  ; 

InitDialogs (nil) ; 
InitCursorO  ; 


//  QuickDraw 
//  Font  Manager 

//  Window  Manager 
II  Menu  Manager 
//  Text  Edit 
//  Dialog  Manager 
//  starting  cursor 


//  Comm  Toolbox  Utilities 

II  Comm  Toolbox  Resource  Manager 
//  Terminal  Manager 


err  =  initCTBUtilities 0  ; 
err  =  InitCRMO; 
err  =  InitTMO; 
if  (err  ==  tmNoTools) 

AlertUser ("No  terminal  tools  found\0",  true); 
err  =  InitCMO;  //  Connection  Manager 

if (err  ==  cmNoTools) 

AlertUser ("No  connection  tools  found\0",  true); 
err  =  InitFTO;  //  File  Transfer  Manager 

if (err  »»  ftNoTools) 

AlertUser ("No  file  transfer  tools  foundXO", false); 


Figure  3:  Initializing  the  Comm  Toolbox 

up  a  buffer  at  this  point,  since  the  Comm 
Toolbox  must  have  access  to  it  here.  < 
Up  to  this  point,  all  we’re  doing  is 
setting  up  the  Comm  Toolbox  to  our  i 
specification.  However,  there’s  a  lot  : 
going  on  in  the  background.  For  exam¬ 
ple,  if  we  didn’t  want  the  Comm  Tool¬ 
box  to  automatically  handle  the  termi¬ 
nal  emulation  window  and  instead  ere-  , 
ate  some  iconic  wonderland  for  users  i 
when  we  call  TMNew  with  tmSaveBe-  i 
foreClear  +  tmAutoScroll,  we  could  add  < 
tmlnvisible  to  tell  the  Comm  Toolbox  i 
we’re  handling  our  own  emulation  ap-  : 


pearance.  Since  there’s  much  more  you 
can  do,  you  should  read  Inside  the 
Comm  unications  Toolbox  (the  manual 
that  accompanies  the  Comm  Toolbox) 
for  more  information. 

The  Idle  Function 

When  you  write  a  communications  pro¬ 
gram,  you  usually  set  up  some  type  of 
timer  to  read  from  the  serial  port  at  a 
timed  interval.  This  prevents  hardware 
overwrites  of  incoming  data.  Then  you 
display  the  data  in  a  window  on  your 
screen  by  reading  periodically,  possi¬ 


bly  every  nth  time  through  your  event 
loop.  In  order  to  handle  file  transfers, 
emulation,  and  data  arriving  via  your 
comm  buffer,  you  have  to  read  this 
data  and  figure  out  exactly  where  it 
goes;  the  Comm  Toolbox  aids  you  with 
the  functions  TMIdleO,  CMIdleO,  and 
FTIdleO  —  these  functions  assist  you 
in  delegating  the  data  to  the  appropri¬ 
ate  managers.  The  function  DoIdleC ) 
(see  Listing  One)  takes  care  of  this; 
please  take  a  look  at  it,  since  yours  will 
have  to  be  nearly  identical.  This  func¬ 
tion  updates  the  file  transfer  status;  the 
terminal  emulation  is  handled  by  the 
Comm  Toolbox. 

You  still  have  to  provide  your  own 
customization  and  buffer.  The  Comm 
Toolbox  only  buffers  the  terminal  emu¬ 
lation  window;  when  the  data  goes  off 
the  screen,  you’ll  have  to  save  it  to  your 
global  buffer.  (Refer  to  the  function 
cacheProc( )  in  the  source  code  for  an 
example.)  When  the  data  reaches  the 
region  that  is  outside  of  the  terminal 
emulation  region,  cacheProc( )  is  called; 
at  this  point,  you  would  have  to  either 
add  the  data  (one  line  at  a  time)  to 
TextEdit,  or  add  it  to  your  own  linked-list 
of  text  that  you  maintain  yourself.  Your 
own  linked-list  of  data  objects  is  prefer¬ 
able,  since  TextEdit  is  slow  and  limited. 

(continued  on  page  44) 
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gTerm  =  TMNew(stheRect,stheRect,  tmSaveBeforeClear  +  tmAutoScroll, 

procID,  window,  (ProoPtr)TermSendProc, (ProcPtr)cacheProc,nil, 
/* (ProcPtr) clikLoop*/nil,  (ProcPtr) ToolGetConnEnvirons, 0,0) ; 

if (gTerm  ==  nil) 

AlertUser ("Can't  create  a  terminal  tool\0",  true) ; 

HLock ( (Handle) gTerm) ; 

/*  connection  tool  */ 
procID  =  FindToolID (classCM) ; 

if (procID  ==  -1)  II  get  out  of  here  if  no  tools! 

AlertUser("No  connection  tools  found/0",  true); 

sizes [cmDataln]  =  kBufferSize;  //  just  data  channel;  large  incoming  buffer 

sizes [cmDataOut]  =  kBufferSize; 

sizes [cmCntlln]  =  0; 

sizes [cmCntlOut]  =  0; 

sizes [cmAttnlnJ  =  0; 

sizes [cmAttnOut]  =  0; 

gConn  *  CMNew(procID,  cmData,  sizes,  0,0); 
if(gConn  ==  nil) 

AlertUser ("Can't  create  a  connection  tool/0",  true); 

HLock ( (Handle) gConn) ; 

/*  allocate  space  for  reads/writes  using  number  returned  by  connection  tool  */ 
gBuffer  «  NewPtrClear (sizes (cmDataln] ) ; 
if (MemError ()  !=  noErr) 

AlertUser  ("Out  of  memoryNO",  true) ; 

/*  file  transfer  tool  */ 
procID  =  FindToolID (classFT) ; 
if (procID  =*  -1) 

AlertUser("No  file  transfer  tools  found\0",  false); 

/*  no  read/write  proc  —  tool  has  its  own  */ 

gFT  =  FTNew (procID,  0  , (ProcPtr) FTSendProc,  (ProcPtr) FTReceiveProc, 
nil,  nil,  (ProcPtr) ToolGetConnEnvirons,  window,  OL,0L); 

if (gFT  —  nil) 

AlertUser ("Can't  create  a  file  transfer  tool\0",  true); 


Figure  4:  Code  to  make  a  new  terminal,  connection,  and  file  transfer  record 


(continued  from  page  41) 

Other  Modifications 

There  are  a  lot  of  simple  things  com¬ 
mon  sense  will  tell  you  need  to  be 
added  to  your  program.  For  example, 
you  need  to  answer  questions  like 
“Where  does  the  Terminal  Manager  get 
updates  and  key  events?” 

Your  standard  update  loop  will  have 
to  be  able  to  notify  the  Terminal  Man¬ 
ager  that  it  needs  to  update  its  emula¬ 
tion  region  on  the  screen.  You  can  do 
this  by  verifying  the  terminal  record’s 
integrity  (not  NIL  and  not  odd)  and 
then  calling  TMUpdateC ).  This  is  pretty 
simple  and  allows  your  program  to  add 
communications  without  deviating  sig¬ 
nificantly  from  a  standard  Macintosh 
program. 

Suppose  the  user  is  typing  on  the 
keyboard.  That  action  (event)  will  have 
to  be  translated  if  terminal  emulation 
is  taking  place.  You’ll  have  to  add  a 
couple  of  lines  which  make  a  call  to 
TMKey( )  to  the  function  that  handles 
normal  key  events,  so  that  the  Termi¬ 
nal  Manager  will  be  able  to  handle 
such  events. 

There  are  several  other  similar  Ter¬ 
minal  Manager  functions  to  look  at; 
again,  refer  to  Inside  the  Communica¬ 


tions  Toolbox.  Functions  such  as  TMRe- 
size(  ),  TMClick( ),  and  TMScroll( )  will 
be  devoted  to  the  user  selecting  text 
(or  objects)  within  the  terminal  emula¬ 
tion  region  of  the  screen,  scrolling  (so 
that  data  is  not  lost),  resizing  the  win¬ 
dow  (so  the  emulation  region  is  af¬ 
fected),  and  so  on. 

If  your  communications  window  (per¬ 
haps  one  of  several  windows  your  pro¬ 
gram  is  using)  is  in  the  background 
and  is  then  activated  by  the  user  click¬ 
ing  on  it,  you  address  this  activate  event, 
bring  your  window  to  the  front,  and 
call  SetPortC )  so  that  the  Mac  will  know 
which  graflPort  to  draw  in.  Everything 
is  pretty  much  the  same  here,  except 
that  you  might  want  to  add  the  calls 
TMActivate( ),  CMActivate( ),  and  FTAc- 
tivate( )  so  that  the  three  managers  can 
activate  their  functions  appropriately. 

Cleaning  up  when  your  program  is 
complete  requires  that  you  cancel  the 
functions  of  the  three  managers  and 
dispose  of  your  buffer.  We  can  use  the 
Memory  Manager  function  DisposePtrJ ) 
to  get  rid  of  our  buffer,  but  what  about 
the  records  for  the  Connection  Man¬ 
ager,  Terminal  Manager,  and  the  File 
Transfer  Manager?  Just  use  the  routines 
the  Comm  Toolbox  provides:  CMDis- 


pose( ),  TMDispose( ),  and  FTDispose( ). 
Adding  these  calls  should  make  every¬ 
thing  look  like  a  regular  Mac  program . 

Installation 

If  you’re  still  working  with  System  6, 
you’ll  have  to  install  the  Comm  Tool¬ 
box  (it’s  not  built-in  to  6)  and  create  a 
new  folder  within  the  System  Folder 
called  “Communications”  to  put  all  of 
your  tools  in. 

If  you’re  distributing  an  application 
you  built  with  System  6,  you’ll  also 
need  to  offer  your  customers  an  instal¬ 
lation  disk.  You  can  get  this,  along 
with  several  connection,  terminal  emu¬ 
lation,  and  file  transfer  tools  from  De¬ 
veloper  Services  at  Apple. 
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Algebraic  Codes  for 

Error  Detection  and 
Correction 

Controlling  data  transmission  errors 


Hsi-Chiu  Liu 


code  word.  Because  there  are  2n  mes¬ 
sage  words,  a  maximum  of  2”  (n+r+1) 
code  words  will  be  involved  in  the 
transmission.  For  a  code  word  that  is 
composed  of  n+r  bits,  there  will  be  a 
total  of  2(n*r)  possible  code  words,  even 
though  it  is  not  possible  for  some  of 
them  to  be  present  in  the  transmission 
because  of  the  single-bit  error  trans¬ 
mission.  Based  on  this  reasoning,  we 
have  2"  (n+r+1)  <=  2(n+r).  This  inequal¬ 
ity  is  easily  reduced  to  n  +  r  +  1  <=  2r. 

Actually,  the  probability  of  a  multi¬ 
bit  transmission  error  is  much  lower 
than  a  single-bit  transmission  error.  For 
example,  if  the  bit  error  rate  is  10  '3, 
then  the  probability  of  a  double-bit  in 
error  will  be  10'6,  if  the  bit  error  is 
independent.  (That’s  why  I’m  only  con¬ 
sidering  single-bit  errors  in  this  article.) 
To  generalize  this  type  of  coding,  we 
suppose  that  the  message  words  con¬ 
sist  of  n  bits  each.  To  form  a  code 
word,  a  number  of  r  check  bits  will  be 
appended  to  the  message  word:  m, 
m,  m,  ...  rn  c,  c,  c,  ...  c.  Note  that 
there  are  only  2"  valid  code  words  out 
of  2n+r possible  ones. 


Electronic  data  transmission  er¬ 
rors  are  a  fact  of  life  and,  de¬ 
spite  rapid  advances  in  digital 
communication  and  computer 
networks,  transmission  error  con¬ 
trol  continues  to  be  a  major  software- 
and  hardware-engineering  task.  One 
of  the  most  efficient  methods  of  error 
detection  and  correction  is  algebraic 
coding ,  which  requires  only  a  minimal 
amount  of  bit  redundancy  in  forming 
code  words.  Using  algebraic  operations 
with  a  matrix  and  a  vector,  code  words 
can  be  easily  encoded  before  transmis¬ 
sion  and  decoded  at  the  receiving  end. 
When  compared  to  other  error  control 
schemes,  algebraic  coding  is  potentially 
capable  of  correcting  multi-bit  errors 
with  lower-bit  redundancy  overhead. 

Code  Word  Formation 

Algebraic  codes  are  a  series  of  code 
words,  each  of  which  is  formed  by 
attaching  a  number  of  check  bits  to  a 
message  word.  The  purpose  of  the  at¬ 
tached  check  bits  is  to  help  detect  and 
correct  transmission  errors.  To  correct 
multi-bit  errors,  more  check  bits  are 
needed.  For  an  algebraic  coding,  the 
inequality  n  +  r  +  1  <=  2r  is  used  to 
determine  the  minimum  number  of 
check  bits  needed  for  correcting  single¬ 
bit  errors  ( n  is  the  number  of  bits  of  a 
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message  word  and  r  the  number  of 
check  bits  needed).  For  example,  a 
4-bit  message  word  will  need  at  least 
three  check-bits  in  order  to  be  able  to 
correct  single-bit  errors. 

Suppose  that  a  message  word  is  n- 
bits  long  and  it  takes  r  check  bits  to 
form  a  code  word.  For  each  correctly 
formed  code  word,  there  may  be  (at 
most)  n+r  code  words,  each  of  which 
is  in  a  1-bit  error.  Each  of  these  errone¬ 
ous  code  words  is  formed  by  inverting 
any  one  of  the  n+r  bits  of  the  correctly 
formed  code  word.  For  a  transmission 
that  causes  only  single-bit  errors,  there 
will  be  n+r+1  possible  code  words  that 
may  be  received  in  transmitting  every 


CodeWord  Encoding 

To  generate  the  r  check  bits  algebrai¬ 
cally,  we  have  to  first  predefine  a  ma¬ 
trix  called  “H”  of  the  dimension  r  x 
(n+r).  Consider  each  code  word  to  be 
generated  as  a  vector  T  which  consists 
of  message  bits  followed  by  check  bits. 
If  even  parity  is  adopted  for  the  com¬ 
puting  system,  appropriate  values  can 
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(continued  from  page  46) 
be  assigned  to  each  of  the  check  bits 
from  the  matrix  equation  H  T  =  0.  See 
Example  1  for  definitions  of  H  and  T. 
Note  that  the  righthand  portion  of  H 


Example  1:  Definition  of  H  and  T 


is  an  identity  matrix.  The  entries  in  the 
lefthand  portion  of  H  must  be  either  0 
or  1 .  These  values  must  be  predefined 
under  the  following  two  conditions: 
No  column  consists  of  all  Os;  No  identi¬ 


cal  entries  are  assigned  to  any  two 
columns.  The  following  problem  illus¬ 
trates  how  to  assign  values  to  the  check 
bits. 

Problem :  Given  the  message  word 
1101  ( n  =  4),  then  the  number  of  check 
bits  is  set  to  3  (r  =  3).  If  the  predefined 
matrix  H  is  as  shown  in  Example  2(a), 
find  the  values  of  the  check  bits  for  the 
formation  of  a  code  word  with  the  given 
message  word. 

Solution :  First,  a  vector  for  the  mes¬ 
sage  word  1101  is  formed.  See  Exam¬ 
ple  2(b).  Secondly,  assume  that  even 
parity  is  adopted.  Then,  perform  the 
matrix  multiplication:  H  T=0.  Three  equa¬ 
tions  will  be  generated  from  this  matrix 
multiplication;  see  Example  2(c).  Us¬ 
ing  modulo-2  addition,  the  three  equa¬ 
tions  will  be  reduced  to  Example  2(d). 

Therefore,  the  valid  code  word  will 
be  1101100.  Following  this  procedure, 
all  of  the  valid  code  words  formed  with 
all  of  the  4-bit  message  words  can  be 
generated;  see  Example  3- 

Code  Word  Decoding 

Let’s  next  consider  how  to  detect  and 
correct  transmission  errors.  Assume  that 
the  received  code  word  is  a  vector  R. 
We  also  assume  that  an  error  vector  E 
is  of  the  same  dimension  as  that  of  the 
code  word  or  vector  R.  The  Is  in  E 
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(continued  from  page  48) 
represent  the  error  positions  in  the  code 
word.  We  then  have  R  =  T+E.  Now,  use 
the  following  to  perform  a  matrix  mul¬ 
tiplication:  H  R  =  HCT+E)  =  H  T  +  H  E 
=  0  +  HE  =  HE. 

Therefore,  if  this  multiplication  re¬ 
sults  in  product  zero  (i.e.,  H  E  =  0),  we 
then  conclude  that  E  consists  of  all  Os. 


Message  word 


Code  word 

0000000 

0001111 

0010011 

0011100 

0100101 

0101010 

0110110 

0111001 

1000110 

1001001 

1010101 

1011010 

1100011 

1101100 

1110000 

1111111 


Example  3:  Valid  code  words  formed 
from  4-bit  message  words 


This  means  that  there  is  no  transmis¬ 
sion  error  detected,  and  no  transmis¬ 
sion  error  has  occurred.  Otherwise,  at 
least  one  error  was  made  in  transmis¬ 
sion.  Of  course,  this  elaborate  system 
will  do  more  than  just  error  detection. 

The  value  of  the  algebraic  coding 
arises  in  multiple-error  detection  and 
correction.  The  product  HE  is  defined 
as  S,  the  syndrome.  The  dictionary  de¬ 
fines  syndrome  as  “a  number  of  symp¬ 
toms  occurring  together  and  character¬ 
izing  a  specific  disease  or  condition.” 
In  fact,  the  error  syndrome  character¬ 
izes  the  specific  bit  error. 

Let’s  first  assume  that  a  single-bit 
error  occurs.  E  would  then  be  a  vector 
composed  of  a  single  one,  and  the 
remaining  positions  would  be  zeros.  If 
we  take  the  product  of  this  with  H  to 
form  the  syndrome,  the  result  is  a  vec¬ 
tor  that  is  identical  to  one  column  of 
H,  that  column  being  the  one  corre¬ 
sponding  to  the  bit  position  in  error. 

To  illustrate  the  single-bit  error  cor¬ 
rection  mechanism,  consider  this  prob¬ 
lem: 

Problem  .  Given  the  code  word  T  = 
1101100  (before  transmission),  and  the 
received  code  word  R  =  1100100  (after 


transmission),  find  the  error  and  cor¬ 
rect  it. 

Solution  -.  First  form  the  product  HR; 
see  Example  4(a).  Note  that  the  result 
is  equal  to  the  fourth  column  of  H,  thus 
identifying  an  error  as  having  occurred 
in  the  fourth-bit  position.  This  error 
can  be  corrected  simply  by  inverting 
the  fourth  bit  of  the  received  code  word. 

If  an  error  of  more  than  1-bit  error 
occurs,  the  syndrome  will  be  equal  to 
the  sum  of  the  corresponding  columns 
of  H.  If,  for  example,  errors  occurred 
in  the  third  and  fourth  bits  of  the  exam¬ 
ple  above,  the  syndrome  would  be  as 
in  Example  4(b). 

This  would  be  incorrectly  interpreted 
as  a  single-bit  error  in  the  fifth  bit  posi¬ 
tion.  Even  though  in  this  article  we 
restrict  our  discussion  of  algebraic  de¬ 
coders  to  the  single-bit  error  correction 
case,  note  that  the  syndrome  can  cor¬ 
rect  two  errors,  provided  that  no  two 
columns  sum  to  either  zero  or  to  an¬ 
other  column  or  to  the  sum  of  two 
other  columns. 

Implementation 

Algebraic  codes  are  not  difficult  to  im¬ 
plement.  Calculation  of  the  various  vec- 


tor  products  is  equivalent  to  summing 
combinations  of  bit  positions.  This  is 
accomplished  by  entering  the  codes 
into  shift  registers,  tapping  off  at  the 
appropriate  positions,  and  feeding  these 
outputs  into  a  summation  device.  Modu¬ 
lo-2  addition  of  two  inputs  is  performed 
in  the  XOR  logic  block. 

One  simple  implementation  of  the 
algebraic  coding  and  decoding  system 
for  4-bit  message  words  is  shown  in 
Figures  1  and  2.  In  Figure  1,  the  4-bit 
message  word  to  be  transmitted  is  in¬ 
put  from  the  left.  The  correct  values  of 
the  check  bits  for  this  message  word 
are  output  from  the  right.  So,  a  code 
word  can  be  formed  with  the  message 
word  and  the  check  bits.  In  Figure  2, 
the  received  code  word  is  input  from 
the  left.  The  correct  message  word  is 
output  from  the  right.  Note  that  the 
implementation  setup  in  Figure  2  is 


capable  of  handling  both  detecting  and 
correcting  single-bit  errors.  Another  pos¬ 
sible  implementation  using  ROM  is 
shown  in  Figure  3.  Note  that  in  part 
(a),  each  message  word  to  be  transmit¬ 
ted  is  used  as  an  address  pointing  to 
the  ROM  location  where  the  needed 


Figure  3:  ROM  implementation:  (a) 
Check  bit  encoding;  (b)  Code  word  de¬ 
coding 


check  bits  are  stored.  Similarly,  in  part 
(b),  the  received  code  word  is  also 
used  as  address  pointing  to  (Jje  ROM 
location  where  the  correct  message 
word  is  stored. 
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Supercharging 

Sequential  Searches 

Speed  plus  compression  equals  faster  searches 


Walter  Williams 


We  all  know  a  sequential 
search  is  slow.  Search  time 
increases  linearly  with  the 
size  of  the  list;  and  as  a  list 
grows  beyond  a  few  items, 
the  search  time  quickly  becomes  unbear¬ 
able.  Nevertheless,  because  it  is  easy 
to  code,  works  on  just  about  any  list, 
and  provides  acceptable  speed  for  short 
lists,  the  sequential  search  remains  one 
of  the  most  commonly  used  search  algo¬ 
rithms. 

Consequently,  there  is  much  to  be 
gained  by  speeding  up  the  sequential 
search  algorithm,  while  maintaining  its 
inherent  generality  and  simplicity.  This 
article  describes  a  simple  algorithm  that 
can  often  speed  up  a  sequential  search 
by  a  factor  of  two  or  more.  And  there’s 
a  special  bonus  —  a  list  can  also  be 
compressed,  often  to  half  its  original 
size.  The  improvement  results  from  a 
better  method  of  comparing  each  key. 
The  number  of  key  comparisons  is  the 
same  as  with  any  sequential  search, 
but  the  time  spent  comparing  each  key 
is  dramatically  reduced. 

As  with  any  sorted  sequential  list, 
the  number  of  keys  compared  will  be, 
on  average,  half  the  number  of  keys  in 
the  list.  The  number  of  key  compari¬ 
sons,  however,  is  not  the  whole  stoiy. 
Each  key  comparison  is  itself  a  sequen¬ 
tial  search  (a  search  for  a  non-match¬ 
ing  character),  so  the  number  of  char- 
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acter  comparisons  (I’ll  assume  the  keys 
are  character  strings)  isN/2*K/2  (or 
NK  /  4)  where  N  is  the  number  of  items 
in  the  list  and  K  is  the  key  length. 

A  sorted  list,  however,  presents  us 
with  an  interesting  opportunity.  The 
opportunity  arises  from  the  fact  that 
the  sort  brings  similar  keys  together. 
Often,  the  first  few  characters  of  one 
key  duplicate  the  first  few  characters 
of  the  preceding  key.  As  a  consequence, 
a  typical  sequential  search  spends  much 
of  its  time  comparing  the  same  leading 
characters  over  and  over.  If  those  re¬ 
dundant  characters  are  skipped  the 
search  will  be  faster.  The  approach  de¬ 
scribed  here,  called  the  suffix  list,  speeds 
up  the  search  by  eliminating  those  need¬ 


less  comparisons.  Here’s  how  it  works. 

The  list  is  kept  in  ascending  order 
and  each  key  is  divided  into  two  parts, 
a  prefix  and  a  suffix.  The  prefix  is  the 
portion  of  the  key  which  matches  the 
previous  key.  The  suffix  is  the  remain¬ 
der  of  the  key,  beginning  with  the  first 
character  that  differs  from  the  previous 
key.  The  suffix  list  stores  an  integer 
that  represents  the  prefix  length  along 
with  each  key. 

Unlike  a  simple  list,  in  which  the 
complete  key  for  each  item  is  used 
during  the  search,  a  suffix  list  uses  only 
the  suffix  in  key  comparisons.  The  pre¬ 
fix  itself  is  ignored,  because  its  length  — 
the  number  of  characters  that  match 
the  previous  key  —  provides  all  the  in¬ 
formation  needed  for  the  search. 

The  data  can  be  stored  as  a  linked 
list,  as  an  array  of  fixed  length  items, 
or  as  a  series  of  variable  length  items 
concatenated  one  right  after  the  other 
in  contiguous  memory.  Listing  One, 
page  100,  shows  code  which  uses  a 
linked  list.  It  doesn’t  matter  which 
method  you  use;  the  basic  principles 
are  the  same,  although  the  methods  for 
traversing  the  list  differ. 

A  linked  list  has  the  advantage  of 
making  insertion  and  deletion  of  items 
easier,  but  storing  the  list  in  contiguous 
memory  uses  less  space. 

The  seq_cell_S  structure  in  Figure  1(a) 
illustrates  a  typical  structure  for  build¬ 
ing  a  linked  list.  The  sfx_cell_S  struc¬ 
ture  in  Figure  1(b),  on  the  other  hand, 
illustrates  a  structure  for  building  a  list 
to  be  used  with  a  suffix  search.  The 
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(continued  from  page  54) 
only  difference  is  the  addition  of  the 
element  cellpfxcnt ,  which  stores  the 
prefix  length. 

cell. key  is  the  first  byte  of  a  null  ter¬ 
minated  string  that  contains  the  key. 
Note  that  the  cell.key  is  not  a  pointer 
to  a  string,  but  is  the  actual  location  of 
the  beginning  of  the  string.  The  cellprev 
and  cell,  next  elements  are  pointers  to 
the  previous  and  following  cells  in  the 
list,  respectively. 

Figure  2  shows  a  list  of  city  names, 
the  prefix  counts,  and  prefix  and  suffix 
values.  In  seqjcell_S,  the  prefix  and 
suffix  are  not  stored  separately.  The 
full  key  is  stored  in  cell.key,  as  normal, 
but  is  now  supplemented  by  the  prefix 
length,  which  is  kept  in  cell.pfxlen. 

Searching 

Like  any  sequential  search,  a  pattern 
key  is  compared  to  each  successive 
key  in  the  list.  The  search  starts  at  the 
beginning  of  the  list  and  continues  un¬ 
til  a  matching  item  is  found  or  until  an 
item  greater  than  the  pattern  is  found. 
An  example  of  code  that  performs  this 
task  is  contained  in  the  Search( )  func¬ 
tion  in  Listing  One. 


Unlike  a  standard  sequential  search, 
a  suffix  list  search  does  not  examine 
the  actual  key  value  for  every  item  in 
the  list.  Instead,  the  prefix  length  for 
each  item  is  compared  to  a  running 
count  of  the  number  of  characters 
matched  so  far  in  the  pattern.  When 
the  search  begins,  the  match  count  is 
zero;  nothing  has  been  matched.  The 
search  progresses,  and  the  match  count 
increases  as  each  character  of  the  pat¬ 
tern  is  matched  until,  when  the  item  is 
found,  the  match  count  is  equal  to  the 
pattern  length. 

Only  when  the  match  count  is  equal 
to  the  item’s  prefix  count  does  the  ac¬ 
tual  key  value  come  into  play. 

If  the  prefix  length  is  greater  than  the 
number  of  characters  matched  in  the 
pattern,  the  search  skips  directly  to  the 
next  item  in  the  list.  Why?  Observe  that 
the  next  character  to  compare  is  part 
of  the  prefix  for  the  current  key;  it  is, 
by  definition,  the  same  as  the  character 
in  the  same  position  in  the  previous 
key.  It  is  also  the  first  character  in  the 
last  key  that  did  not  match  the  pattern. 
Obviously,  if  the  character  did  not  match 
in  the  last  key,  it  will  not  match  in  this 
one.  So  the  search  can  safely  jump  to 


(a) 

struct  seq_cell_S  { 

suuctseq  cell  S  *next; 

/*  Next  node  7 

struct  sea  cell  S  *arev; 

/*  Previous  node  7 

char  key[1  ]; 

/*  Key  value  7 

(b) 

struct  sfx_cell_S  { 

}  cell; 

struct  sea  cell  S  'next; 

/*  Next  node  7 

struct  sea  cell  S  *prev; 

/*  Previous  node  7 

unsigned  char  pfxcnt; 

/*  Prefix  Length  7 

char  key[1]; 

/*  Key  value  7 

}  cell; 

Figure  1:  The  seq_cell_S  structure  in  (a)  illustrates  a  typical  structure  for 
building  a  linked  list.  The  sfx_cell_S  structure  in  (b),  on  the  other  hand, 
illustrates  a  structure  for  building  a  list  to  be  used  with  a  suffix  search.  The 
only  difference  is  the  addition  of  the  element  cell.pfxcnt,  which  stores  the 
prefix  length  . 


Standard 

Pfxlen 

Prefix 

Suffix 

Acampo 

0 

Acampo 

Acton 

2 

Ac 

ampo 

Adelanto 

1 

A 

delanto 

Adin 

2 

Ad 

in 

Agoura  Hills 

1 

A 

goura  Hills 

Agoura  Hills 

12 

Agoura  Hills 

Aguanga 

2 

Ag 

uanga 

Ahwahnee 

1 

A 

hwahnee 

Alameda 

1 

A 

lameda 

Alamo 

4 

Alam 

0 

Figure  2:  A  list  of  city  names,  the  prefix  counts,  and  prefix  and  suffix  values 
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(continued  from  page  56) 
the  next  item  in  the  list. 

If  the  prefix  length  is  less  than  the 
match  count,  the  search  ends  in  failure  — 
the  pattern  is  not  in  the  list.  This  hap¬ 
pens  only  when  a  character  position 
that  has  already  been  successfully 
matched  contains  a  new  and  different 
character.  The  list  is  in  ascending  order, 

A  search  of  the  250  city 
names  was  about  twice 
as  fast  as  a  standard 
sequential  search 


so  that  new  character  would  have  to  be 
greater  than  the  one  already  matched 
in  that  position.  Therefore,  the  pattern 
key  would  have  to  have  come  before 
the  current  item  if  it  were  in  the  list. 

If  the  prefix  length  does,  in  fact,  equal 
the  match  count,  the  suffix  must  be 
compared  to  the  pattern.  The  compari¬ 
son  proceeds  character  by  character, 
beginning  with  the  first  character  of  the 
suffix  and  with  the  first  unmatched  char¬ 
acter  in  the  pattern.  The  match  count 
is  incremented  for  each  matching  char¬ 
acter.  If  it  turns  out  that  the  pattern 
matches  the  suffix  exactly,  the  item  has 
been  found,  and  the  search  is  over.  If 
the  pattern  is  greater  than  the  item,  the 
search  continues.  If  the  pattern  is  less 
than  the  item,  the  item  is  not  on  the  list, 
and  the  search  fails. 

Consider  the  following  example, 
which  searches  for  Adept  in  the  list  in 
Figure  2.  When  the  search  begins,  the 
match  count  is  zero.  The  prefix  count 
of  the  first  item  is,  of  course,  also  zero. 
So  Adept  is  compared  to  Acampo.  Only 
the  first  character  matches,  so  the  match 
count  becomes  1,  and  the  search  con¬ 
tinues.  The  prefix  count  for  the  next 
item  in  the  list,  Acton,  is  2,  which  is 
greater  than  the  match  count,  so  it  is 
skipped.  The  prefix  count  of  the  third 
item,  Adelanto,  is  the  same  as  the  match 
count,  so  the  pattern  and  suffix  are 
compared.  The  next  two  characters  of 
the  pattern,  de,  match  the  correspond¬ 
ing  characters  in  the  key,  so  the  match 
count  is  advanced  by  2,  to  become  3- 
The  next  character,  /,  is  less  than  p,  so 
the  search  continues.  The  fourth  item, 
Adin,  has  a  prefix  count  of  2,  which  is 
less  than  the  match  count.  The  search 
is  over  because  the  item  is  not  in  the 
list. 
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From  the  previous  example  it’s  clear 
that  this  algorithm  makes  relatively  few 
character  comparisons.  The  average  num¬ 
ber  of  comparisons  will  be  between 
N  /  2  +  K  and  N  +  K.  (Where  N  is  the 
number  of  records,  K  is  the  average 
key  length,  and  the  comparison  of  the 
prefix  count  to  the  match  count  is  a 
single  comparison.)  This  is  generally 
far  less  than  the  average  of  KN  /  4 
character  comparisons  which  a  stan¬ 
dard  search  would  make. 

Insertion 

Before  an  item  can  be  inserted  into  the 
list,  the  appropriate  location  for  the 
item  has  to  be  found.  After  all,  the  list 
has  to  remain  correctly  sorted  after  the 
new  item  is  added.  The  first  step  in 
adding  an  item,  therefore,  is  to  search 
for  the  item  by  using  the  algorithm 
described  above.  In  the  case  of  dupli¬ 
cate  items,  the  search  must  continue 
to  the  last  matching  item. 

After  the  position  for  the  new  item 
is  found,  the  key  has  to  be  separated 
into  prefix  and  suffix.  That’s  easy,  be¬ 
cause  the  prefix  was  already  identified 
during  the  search.  Search()  saves  the 
match  count  from  the  item  just  before 
the  position  at  which  the  new  key  is 
to  be  inserted.  That  match  count  is,  by 
definition,  the  prefix  count  for  the  new 
item.  We  just  allocated  enough  mem¬ 
ory  to  hold  the  cell  structure,  and  then 
insert  the  new  item,  including  the  pre¬ 
fix  length  and  key  value,  into  the  list. 
The  whole  process  is  not  much  differ¬ 
ent  from  that  of  any  other  linked  list 
insertion. 

But  there  is  a  wrinkle.  Remember 
that  each  item’s  prefix  length  depends 
on  the  previous  item.  It’s  possible  that 
after  insertion  there  will  be  greater  simi¬ 
larity  between  the  new  key  and  the 
next  one.  If  that’s  the  case,  the  prefix 
length  of  the  next  item  in  the  list  will 
change.  Because  the  list  is  sorted,  the 
prefix  length  will  increase  if  it  changes. 

The  prefix  lengths  tell  us  all  we  need 
to  know  to  adjust  the  next  item.  The 
prefix  length  of  the  new  item  will  never 
be  less  than  the  existing  prefix  length 
of  the  next  item  —  if  it  were,  the  list 
wouldn’t  be  properly  sorted.  If  the  pre¬ 
fix  length  of  the  new  item  is  greater 
than  that  of  the  next  item,  the  prefix 
length  of  the  next  item  will  not  change. 
Only  if  the  prefix  lengths  of  the  two 
items  are  the  same  will  the  prefix  length 
of  the  next  item  change.  In  that  case,  the 
two  suffixes  must  be  compared  and  the 
prefix  length  adjusted  accordingly. 

Let’s  insert  Adept  into  the  sample  list. 
The  first  step  is  to  search  the  list,  just 
as  we  did  before.  That  search  ended 
just  after  Adelanto  with  a  match  count 
of  3.  So  the  new  node  is  inserted  into 
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the  list  between  Adelanto  and  Adin 
with  a  prefix  length  of  3-  The  prefix 
length  for  Adin  is  not  the  same  as  the 
prefix  length  for  the  new  entry,  so  the 
prefix  length  for  Adin  does  not  change. 

It  was  somewhat 
surprising,  however,  to 
find  that  the 
compression  improves 
the  speed  of  the  search 


Deletion 

Deletion  of  an  item  from  the  list  is 
similar  to  insertion.  Again,  the  first  step 
is  to  search  through  the  list  until  the 
desired  item  is  found;  the  second  step 
is  to  remove  it. 

The  actual  removal  of  the  item  is  no 
different  than  removal  of  an  item  from 
any  other  list  —  memory  allocated  from 
the  heap  must  be  freed,  pointers  up¬ 
dated,  and  so  on.  But  just  as  with  inser¬ 
tion,  the  prefix  length  of  the  next  item 
following  the  deleted  item  may  change. 
This  time  it  will  get  smaller,  never  larger. 

The  adjustment  of  the  prefix  length 
depends,  not  surprisingly,  on  the  pre¬ 
fix  length  of  the  item  being  deleted  and 
the  prefix  length  of  the  item  following 
it.  The  new  prefix  length  for  the  next 
item  will  be  the  lesser  of  the  two. 

Let’s  delete  Adept.  The  search  pro¬ 
ceeds  as  before,  this  time  ending  suc¬ 
cessfully  with  Adept.  We  unlink  it  from 
the  list,  but  before  releasing  the  mem¬ 
ory  we  compare  the  prefix  length  of  the 
deleted  item  to  that  of  the  item  follow¬ 
ing  it.  The  new  prefix  length  of  Adin  is 
already  less  than  that  of  Adept ,  so  the 
prefix  length  for  Adin  does  not  change. 

Compression 

You  will  have  observed  that  the  prefix 
portion  of  the  key  is  never  used.  In 
fact,  as  far  as  the  search  is  concerned, 
it  can  be  eliminated  completely.  The 
prefix  will  never  have  to  be  reconsti¬ 
tuted  for  basic  list  operations.  Even 
when  part  of  the  suffix  must  be  rebuilt 


on  deletion,  all  of  the  information 
needed  is  contained  in  the  suffix  of  the 
key  being  deleted. 

By  eliminating  the  prefix,  the  list  can 
be  stored  more  compactly.  That’s  an 
obvious  advantage  if  the  list  is  kept 
entirely  in  memory.  But  it’s  also  an 
advantage  if  the  list  must  be  retrieved 
from  disk  frequently  —  the  more  com¬ 
pact  the  data,  the  greater  its  chance  of 
being  in  cache. 

How  much  space  does  it  save?  Tests 
run  on  a  list  of  250  city  names  and  zip 
codes  give  some  idea  of  the  improve¬ 
ment  possible.  The  original  list  used 
20  bytes  for  each  city  name.  The  aver¬ 
age  length  of  the  actual  names  was 
about  8.2  characters  and  the  average 
suffix  length  was  about  5.7  characters. 
The  suffix  structure  includes  a  single 
unsigned  charto  store  the  prefix  length, 
and  the  variable-length  keys  require  a 
null  terminator,  so  the  net  result  (in¬ 
cluding  4  bytes  for  links)  is  a  savings 
of  20  -  (5.7  +  6)  =  8.3  bytes  per  record. 
That’s  a  41  percent  savings  relative  to 
a  fixed  length  table.  (See  Table  1.) 

Of  course  the  amount  of  space  saved 
depends  upon  the  data.  The  greater 
the  similarity  between  keys,  the  greater 
the  savings.  Best  of  all,  when  duplicate 
keys  occur,  the  suffix  is  null  and  none 
of  the  key  is  stored. 

Performance 

A  search  of  the  250  city  names  was 
about  twice  as  fast  as  a  standard  sequen¬ 
tial  search.  The  improvement  agrees 
with  predictions  based  on  the  formulas 
for  character  comparisons  presented 
earlier. 

There  are  a  few  other  tricks  for  speed¬ 
ing  up  a  sequential  search.  These  in¬ 
clude  using  the  search  pattern  as  an 
end  marker,  unrolling  the  loop,  or  us¬ 
ing  a  self-organizing  list. 

The  self-organizing  list  is  generally 
the  most  effective  of  the  three.  When 
the  distribution  obeys  Zipf  s  law,  it  takes 
NK  /  log(2)N  character  comparisons. 
The  self-organizing  list  is  a  substantial 
improvement  over  a  standard  sequen¬ 
tial  search;  but  it  is  generally  not  quite  as 
fast  as  the  suffix  search.  The  trade-off 
between  a  self-oiganizing  list  and  a  suf¬ 
fix  list  will  not  favor  the  self-organizing 
list  unless  the  key  length  is  less  than  the 
log  (base  2)  of  the  number  of  records. 


Type  of  List 

List  Size 

Percent  Saved 

Fixed  length  records 

20.0  bytes 

0% 

Linked  list  (full  keys) 

13.2 

33% 

Linked  suffix  list 

11.7 

41% 

Contiguous  suffixes 

7.7 

61% 

Table  1:  Typical  savings  provided  by  compression  technique 
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Applications 

This  algorithm  was  originally  devised 
to  search  nodes  in  a  B-tree.  In  a  B-tree 
each  node  contains  keys  that  are  very 
similar  —  sometimes  all  of  the  keys  are 
identical  —  so  the  suffix  search  is  sub¬ 
stantially  faster  than  a  standard  sequen¬ 
tial  search.  But  the  real  payoff  is  that 
by  eliminating  the  prefix  many  more 
keys  fit  in  a  node  —  and  that  reduces 
the  number  of  disk  hits,  which  are  rela¬ 
tively  time-consuming.  A  binary  search, 
which  is  often  used  to  find  a  key  in  a 
B-tree  node,  is  still  faster  than  the  suffix 
search,  but  the  reduction  of  the  num¬ 
ber  of  disk  hits  more  than  makes  up  for 
the  slower  search.  (If  duplicate  keys 
are  permitted  in  the  B-tree,  the  binary 
search  must  be  followed  by  a  sequen¬ 
tial  search  anyway.) 

There  are,  of  course,  other  applica¬ 
tions  where  keys  with  similar  prefixes 
are  common:  directory  lists,  compiler 
symbol  tables,  and  so  forth.  Similar  im¬ 
provements  ought  to  be  possible  there, 
too.  It  makes  sense  to  compress  keys 
by  removing  the  redundant  prefix,  and 
that  was  the  original  objective  of  this 
method.  It  was  somewhat  surprising, 
however,  to  find  that  the  compression 
improves  the  speed  of  the  search.  One 
would  expect  the  elimination  of  the  pre¬ 
fix  portion  of  the  key  to  make  list  main¬ 
tenance  more  awkward.  Instead,  the 
prefix  count  turns  out  to  be  more  useful 
than  the  actual  characters  of  the  prefix. 

There  are  drawbacks  to  the  method. 
If  the  prefix  is  eliminated,  the  keys 
have  to  be  reconstructed  when  needed. 
The  programs  are  also  a  bit  more  com¬ 
plex  than  a  standard  sequential  search. 
But  for  many  applications,  the  advan¬ 
tages  far  outweigh  those  drawbacks. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  ZID/Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listing  begins  on  page  100.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  5. 
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Examining  the  Zinc 
Interface  Library 

High-powered  windowing  tools 
for  Turbo  C++ 


Gary  Entsminger 


Object-oriented  programming 
encourages  the  reuse  of  code, 
primarily  through  inheritance. 
A  programmer  can  create 
classes  of  objects  and  then 
derive  new  classes  from  them.  But  a 
crucial  and  (perhaps  surprisingly?)  sub¬ 
tle  aspect  of  inheritance  is  that  pro¬ 
grammers  can  derive  new  classes  from 
abstract  classes  they  didn’t  write.  If  these 
classes  are  general  enough  to  allow 
themselves  to  be  extended,  they  can 
be  distributed  in  the  form  of  extensible 
libraries,  without  including  source  code. 
Library  users  can  use  these  classes  with¬ 
out  necessarily  knowing  their  implemen¬ 
tation  details,  and  derive  new  classes 
from  them. 

A  great  idea,  I  believe,  but  one  still 
in  an  incipient  stage.  Hybrid  object- 
oriented  languages  such  as  C++  and 
Turbo  Pascal,  in  particular,  are  still  new 
enough  to  lack  a  good  assembly  of 
class  libraries.  Object-oriented  think¬ 
ing  is  substantially  different,  and  re¬ 
quires  fresh  perspectives.  Translating 
old  C  and  Pascal  code  just  won’t  do. 
So  it  isn’t  surprising  that  we’re  just  be¬ 
ginning  to  see  the  first  wave  of  com¬ 
mercial  libraries  that  are  truly  object- 
oriented,  and  not  just  rehashes  of  struc¬ 
tured  ideas.  In  this  article  I’ll  examine 
one  of  these,  an  impressive  interface 
library  from  Zinc  Software. 

The  Zinc  Interface  Library  (ZIL)  is  a 
C++  class  library  that  you  can  use  to 
construct  a  windowed  graphics  or  text 
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interface  for  your  applications.  The  in¬ 
terface  handles  all  input  (keyboard, 
mouse,  and  other  device  events),  cre¬ 
ates  and  manages  windows,  and  routes 
event  information  to  the  appropriate 
windows.  Your  applications  “run”  in 
these  windows. 

Browsing  the  Package 

ZIL  is  conceptually  smart  and,  when  in 
graphics  mode,  is  similar  in  appear¬ 
ance  to  Microsoft  Windows  or  possibly 
the  Next  machine.  While  the  people  at 
Zinc  have  plainly  stated  that  it  is  not  a 
Windows  look-alike,  ZIL  offers  a  pro¬ 
fessional-looking  user  interface  without 
the  overhead  of  a  complete  environment 
such  as  Windows.  In  text  mode,  ZIL 
mostly  follows  the  SAA/CUA  guidelines. 
ZIL  is  easy  to  use  (once  you  learn  to 
think  in  terms  of  events  and  messages), 
and  offers  an  excellent  alternative  for 
C++  developers  who  want  to  develop 
graphics  applications  outside  the  Win¬ 
dows  (and  other  GUI)  environments. 

The  Library  consists  of  seven  main 
sections.  The  first  section  involves  event 
mapping.  In  fact,  the  Zinc  Interface 
Library  design  is  an  excellent  example 
of  an  event-driven  architecture.  In  such 
an  architecture,  the  flow  of  a  program 
is  determined  by  an  event  —  a  force 
outside  the  current  process,  window, 
or  the  computer  itself. 

Events  are  essentially  anything  that 
happen  within  the  system:  keyboard, 
mouse,  and  other  device  input;  error 
messages;  messages  sent  to  and  from 
objects  and  devices,  and  so  on. 

Related  to  event  mapping  islhe  event 
manager,  which  consists  of  a  control 
unit  for  input  devices  and  a  storage 
unit  for  event  information.  The  other 


sections  of  ZIL  include  a  window  man¬ 
ager  (the  control  unit  for  any  windows 
added  to  the  screen  display),  a  screen 
display,  help  system,  error  system,  and 
palette  mapping  (for  customizing  dis¬ 
plays). 

Using  ZIL,  you  develop  applications 
that  respond  to  messages  triggered  by 
events.  You  set  the  interface  up  (eas¬ 
ily),  and  then  set  up  your  application 
to  run  in  a  ZIL  window  as  a  derived 
window  object.  Each  user-activated 
event  (keystroke,  mouse,  and  so  on) 
is  routed  to  the  appropriate  window, 
which  decides  how  it’s  supposed  to 
handle  the  event. 

Applications  “running”  under  ZIL 
share  a  similar,  general-purpose  inter¬ 
face.  You  can  use  the  interface  without 
having  to  rewrite  (or  even  know  about) 
the  implementation  details  of  the  inter¬ 
face.  You  can  add  windows,  window 
objects  (buttons,  icons,  and  so  on), 
and  pop-up  and  pull-down  menus,  leav¬ 
ing  the  management  of  these  objects 
to  the  event  and  window  managers. 

Each  application  that  uses  ZIL  works 
similarly.  An  event  manager  looks  for 
input  from  the  keyboard,  mouse,  and 
so  on,  and  routes  it  via  an  event  queue 
to  the  window  manager.  The  window 
manager  then  sends  a  message  to  the 
appropriate  window  (see  Figure  1). 

Because  the  event  manager  knows 
about  various  displays  (CGA,  VGA, 
EGA,  Here,  MDA,  43-line,  50-line,  and 
so  on)  it  can  determine  the  appropriate 
adaptor  and  display  automatically.  Thus, 
an  application  can  be  written  gener¬ 
ally,  without  concern  for  specific  hard¬ 
ware.  If  it  uses  multiple  display  classes, 
any  application  you  write  can  be  ab¬ 
stract  regarding  its  screen  display.  You 
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Device  Input— > 

Event  Manager  — >  Event  Queue  —  > 

Window  Manager — > 

Windowl 

(event  1 ) 

(event  2) 

(event...) 

— >  Window2 

— >  Window3 

— >  Window4 

Figure  1:  Design  ofZIL 


(continued  from  page  64) 
use  one  set  of  source  code  to  generate 
output  for  both  graphics-  and  text- 
based  environments. 

The  screen  display  controls  all  low- 
level  screen  ouput.  The  base  class  for 


the  screen  display  is  UI_DISPLAY.  It 
has  the  ZIL-defined  descendants: 
Ul_DOS_BGI_DlSPLAY  and  UI_DOS_ 
TEXT_  DISPLAY,  and  support  for  snow 
checking  on  CGA  monitors  and  IBM’s 
Topview  (which  supports  Microsoft  Win¬ 


dows  and  Quarterdeck’s  Desqview  en¬ 
vironments).  Additionally,  you  can  de¬ 
rive  new  DISPLAY  objects  and  incorpo¬ 
rate  them  in  an  application  as  easily  as 
you  would  ZIL-defined  objects. 

The  ZIL  Help  System  lets  you  pro¬ 
vide  context-sensitive  help  information 
for  end  users.  You  generate  a  help  file 
using  a  ZIL  utility  called  GENHELP, 
and  then  add  the  UI_HELP_SYSTEM 
class  and  its  descendants  to  your  appli¬ 
cation  (more  on  this  later). 

The  ZIL  Error  System  lets  you  dis¬ 
play  error  information  to  the  end  user 
in  a  similar  manner.  Simply  add  the 
UI_ERROR_SYSTEM  and  its  descendants 
to  your  application;  when  an  error  oc¬ 
curs,  information  you  specify  will  be 
presented  to  the  user  in  another  ZIL 
window. 

The  Palette  Mapping  class  allows  you 
to  define  color  combinations  for  win¬ 
dow  objects  with  either  global  color 
palette  mapping  or  individual  object 
color  palette  mapping.  Thus,  any  inter¬ 
face  you  develop  can  easily  be  custom¬ 
ized  by  you  or  an  end  user. 


Using  the  Library 

To  use  (and  extend)  the  library,  you 
should  create  an  instance  of  a  window, 
add  library-  or  user-defined  window 
objects,  and  add  the  window  to  the 
window  manager.  Window  objects  are 
anything  you  associate  with  a  window: 
Objects  that  compose  windows  (bor¬ 
ders,  titles,  and  scroll  bars,  for  exam¬ 
ple),  objects  that  specify  windows  (such 
as  menus  and  buttons),  and  objects 
that  are  inside  windows  (such  as  fields, 
numbers,  strings,  and  actions). 

Incorporating  the  library  into  an  ap¬ 
plication  means  you  must  construct  a 
screen  display  and  an  event  manager, 
add  any  input  devices  to  the  event 
manager,  construct  a  window  manager, 
and  add  any  windows  to  the  window 
manager. 

To  see  how  this  works  in  practice, 
the  code  shown  in  Example  1  (page 
70)  initializes  the  Zinc  Interface  Library 
and  adds  one  application  window  to 
the  window  manager.  Note  that  win¬ 
dow  objects  are  added  to  a  window 
dynamically  using  the  overloaded  + 
operator  and  new.  The  window,  in¬ 
cluding  any  window  object  added  to  it, 
is  similarly  added  to  the  window  man- 
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ager  with  *windowManager  +  window. 

Example  1,  by  the  way,  is  an  exam¬ 
ple  of  how  to  use  operator  overload¬ 
ing.  Any  class  derived  from  UIW_  WIN¬ 
DOW  inherits  the  +  operator  overload. 
So  window  objects  are  added  to  win¬ 
dows  and  windows  are  added  to  the 
window  manager  via  the  same  +  op¬ 
erator.  The  definition  is  shown  in  Ex¬ 
ample  2  (page  70). 

You  can  add  functionality  to  a  win¬ 
dow  by  constructing  a  new  window 
object  and  adding  it  to  the  window,  as 
shown  in  Example  3  (page  70).  Any 
window  derived  from  the  abstract 
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UI_  WlNDOW_OBJECT class  has  the  built- 
in  ability  to  move,  size,  minimize,  maxi¬ 
mize,  restore,  and  exit  itself.  So  any 
window,  regardless  of  its  specific  func¬ 
tionality,  generally  looks  and  behaves 
like  any  other. 

Under  the  Hood 

Once  we’ve  constructed  the  event  and 
window  managers  and  added  windows 
(containing  applications)  to  the  sys¬ 
tem,  we  sit  back  and  let  ZIL  do  the 
work,  essentially  through  an  event  loop. 
In  other  words,  the  ZIL  event  manager 
gets  an  event,  interprets  it  and  then 
sends  the  interpreted  information  via 


an  event  queue  to  the  window  man¬ 
ager.  The  window  manager  routes  the 
information  it  gets  from  the  queue  to 
the  appropriate  window,  which  acts 
accordingly.  The  event  manager  then 
loops  getting  the  next  keyboard,  mouse, 
or  other  device  event  until  the  window 

ZIL  offers  a 
professional-looking 
user  interface  without 
the  overhead  of  a 
complete  environment 
such  as  Windows 


gets  an  exit  request.  A  simple  event 
loop  is  shown  in  Example  4  (page  70). 

Besides  the  many  basic  window  ob¬ 
jects  that  describe  and  manipulate  a 
window,  ZIL  includes  many  complex 
window  objects  such  as  prompts,  pull¬ 
down  and  pop-up  menus,  icons,  strings, 
dates,  and  data  fields.  To  demonstrate 
window  object  usefulness,  the  code 
segment  in  Example  5  (page  71)  adds 
database-like  input  fields  to  a  window. 

ZIL’s  UIW_NUMBER  class  is  complete 
and  handles  the  char ,  unsigned  char, 
short,  unsigned  short,  int,  unsigned  int, 
long,  unsigned  long,  float,  and  double 
data  types.  UIW_NUMBER  also  permits 
various  formatting  including  decimal, 
scientific,  and  so  on. 

A  Smart  Line  Editor 

In  this  section,  I’ll  develop  a  smart  line 
editor  that  utilizes  many  of  ZIL’s  fea¬ 
tures.  The  example  demonstrates  how 
to  derive  a  new  class  of  objects  from 
existing  ZIL  classes,  construct  a  data 
field  and  add  it  to  the  line  editor,  con¬ 
struct  and  display  event  and  window 
managers,  add  a  new  instance  of  a 
derived  class  (the  line  editor)  to  the 
window  manager,  set  up  and  run  an 
event  loop,  and  destruct  everything  cre¬ 
ated. 

Listing  One  (page  101)  presents  the 
complete  source  (excluding  ZIL  header 
files)  for  the  line  editor.  The  new  class 
derived  from  ZIL  adds  file  I/O  capabil¬ 
ity  to  a  window.  It  consists  of  a  con¬ 
structor  that  opens  and  reads  a  file,  a 
destructor  which  writes  the  edited  text 
back  to  the  file,  and  a  buffer  for  hold¬ 
ing  characters.  Therefore,  all  the  ac¬ 
tion,  including  construction  of  event 
and  window  managers,  the  event  loop, 
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and  so  on,  occurs  during  construction 

and  destruction  phases. 

The  key  to  how  the  line  editor  works 
lies  in  the  built-in  capabilities  of 
UIW_STR1NG,  the  ZIL  string  class.  Note, 
for  instance,  the  *windowl->line_huffer 
reference  in  Listing  One.  The  line  buffer 
is  updated  each  time  the  line  displayed 


on  the  screen  is  revised.  When  we  con¬ 
struct  the  line  editor  in  window  1,  we 
pass  the  line  buffer  information  con¬ 
tained  in  a  file  (in  this  case,  MK.BAT). 
Then,  when  we  destruct  the  line  editor, 
the  contents  of  line_buffer  are  written 
back  out  to  MK.BAT. 

Any  class  derived  from  UIW_STR1NG 
and  connected  to  the  window  man¬ 


ager  can  automatically  detect  screen 
types  and  devices  (such  as  a  mouse), 
and  possesses  numerous  editing  abili¬ 
ties,  including  cursor  and  mouse  move¬ 
ment,  delete  word,  undo,  redo,  and  so 
on.  For  completion’s  sake,  Listing  Two 
(page  102)  shows  the  MAKE  file  (in¬ 
cluded  with  ZIL)  used  to  compile  with 
Turbo  C++. 


//  Construct  a  graphics  display  if  possible. 

UI_DISPLAY  *display  =  new  UI_DOS_BGI_DISPLAY; 
if  ( idisplay  -:>installed)  . 

//  if  this  system  can't  handle  graphics, 

//  delete  the  graphics 

UI  WINDOW  MANAGER  &operator+ (void  ‘object) 

{  Add( (UI_WINDOW_OBJECT  *) object);  return (*this) ;  ) 

Example  2:  Inheriting  an  overloaded  operator 

II  display  we  just  created  with  new. 

{ 

delete  display; 

//  then  create  a  text  display. 

+  new  MY_0BJECT 

display  =  new  UI_DOS_TEXT_DISPLAY; 

} 

//  Construct  an  event  manager. 

Example  3 :  Adding  functionality  to  a  window  using  the 

01  EVENT  MANAGER  *eventManager  = 

new  UI  EVENT  MANAGER(100,  display); 

+  operator 

‘eventManager  //  add  devices  by  constructing 

//  new  instances  of  device  class. 

int  ccode; 

+  new  UI  BIOS  KEYBOARD 

UI  EVENT  event;  //  an  event  is  an  instance  of  class  UI  EVENT 

+  new  UI  MS  MOUSE 

do  //  loop:  do-while  event  not  equal  to  ESCAPE 

+  new  UI  CURSOR; 

f 

//  Construct  a  window  manager. 

//  Get  input  from  a  user. 

UI  WINDOW  MANAGER  *windowManager  = 

eventManager .Get (event,  Q  NORMAL) ; 

new  UI_WINDOW_MANAGER (display,  eventManager) : 

//  Construct  and  add  a  window  to  the  window  manager. 

//  If  ESC  message,  exit. 

UIW  WINDOW  ‘windowl  =  new  UIW  WINDOW (1, 1, 50, 20, WOF  NO  FLAGS, 

If  (event. type  ==  E  KEY  &&  event . rawCode  ==  ESCAPE) 

WOAF  NO  FLAGS); 

event. type  =  L  EXIT; 

*windowl  //  add  window  objects  by  constructing  instances 

//  of  the  window  object  class. 

//  Send  event  information  to  the  window  manager 

+  new  UIW  BORDER 

ccode  =  windowManager .Event (event) ; 

+  new  UIW_TITLE ( "WIN1",  WOF_JUSTIFY_CENTER) ; 

}  while  (ccode  !=  L_EXIT) ; 

Example  1:  Initializing  the  Zinc  Interface  Library 

Example  4:  A  simple  event  loop 
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A  Database  System 
Automating  E-Mail 
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electronic  messages 
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The  proliferation  of  electronic  mail 
has  become  an  accepted  part 
of  today’s  workplace.  That’s  the 
good  news.  The  bad  news  is 
that  in  many  cases  the  sheer 
volume  of  electronic  messages  received 
demands  some  means  of  managing 
them.  This  article  presents  a  message 
storage  and  retrieval  system  just  for  this 
purpose.  For  the  sake  of  example,  the 
system  focuses  on  MCI  Mail,  a  widely 
used  electronic  mail  service,  and  is  built 
around  an  off-the-shelf  database  and 
engine,  Paradox  from  Borland. 

For  those  unfamiliar  with  MCI  Mail, 
it  is  an  electronic  mail  service  that  lets 
you  send  messages  to  individual  users 
(TO:)  as  well  as  to  a  long  list  of  users 
(CC:).  There  is  an  “inbox”  for  mes¬ 
sages  sent  to  you  and  an  “outbox”  to 
save  copies  of  messages  you  send.  MCI 
also  provides  a  number  of  advanced 
features,  including  those  which  let  you 
customize  your  electronic  “space”  and 
gain  access  to  other  services. 

For  its  part,  the  Paradox  Engine  is  a 
database  engine  with  a  library  of  70 
functions  callable  from  Turbo  C  or  Mi¬ 
crosoft  C.  Paradox  is  a  relational  data¬ 
base  that  includes  a  scripting  language 
called  “PAL”  (Paradox  Application  Lan- 
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guage)  that  lets  you  write  within  Para¬ 
dox  to  manipulate  the  environment  and 
perform  Queries  By  Example  (QBE), 
fast  I/O,  and  quick  prototypes.  The 
inherent  flexibility  of  Paradox  and  the 
Paradox  Engine  makes  them  ideal  for 
creating  an  electronic  mail  storage  and 
retrieval  database  system. 

Before  delving  too  deeply  into  the 
system  presented  here,  a  quick  over¬ 
view  might  be  useful.  As  illustrated  in 
Figure  1,  your  telecommunications  pro¬ 
gram  logs  on  to  MCI  and  prints  (and 
stores  on  disk)  all  messages  in  your 
MCI  “inbox.”  The  telecomm  program 


then  logs  off  MCI.  The  resulting  text  file 
is  then  parsed  by  the  database  applica¬ 
tion  into  several  Paradox  tables.  The 
PAL  script  presents  this  information  to 
you,  allowing  you  to  respond  to  a  mes¬ 
sage  or  create  a  new  one.  Next,  the 
database  application  parses  any  re¬ 
sponses  in  another  table  back  into  a 
text  file.  Finally,  the  telecomm  program 
uploads  the  responses  and  new  mes¬ 
sages  to  MCI. 

Table  Structures 

To  store  MCI  messages  in  a  Paradox 
database,  you  need  to  develop  a  data- 


Figure  1:  Flow  control  diagram  of  MCI  message  system 
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(continued from,  page  72) 
base  structure.  This  can  be  done  with 
four  tables:  the  Header,  Route,  Mes¬ 
sage,  and  Pending  tables. 

The  Header  table,  shown  in  Table 
1(a),  includes  subject,  date  received, 
and  name  of  sender  information.  With 
MCI,  there  are  two  ways  to  contact 
another  user.  You  can  use  their  “user 
name”  (for  example,  John  Smith  or 


Field  Name 

Field  Type 

(a)  DateReceived 

D* 

Message# 

N* 

Subject 

A40 

From  User 

A20 

From  ID 

A8 

(b)  Message# 

N* 

TOorCC 

A5* 

User  Name 

A20* 

User  ID 

A8 

(c)  Message# 

N* 

Line# 

N* 

Text 

A80 

(d)  Pending# 

N* 

Action 

A8* 

Text 

A40* 

Table  1:  Table  types:  (a)  defines  the 
Header  table,  (b)  Routing  table,  (c) 
Message  table,  and  (d)  Pending  table 


JSMITH)  or  their  “MCI  address”  (for 
example,  555-1234).  The  MCI  address 
is  always  unique  but  the  user  name 
may  not  be;  there  may  be  many  MCI 
users  named  John  Smith.  (Therefore, 
if  you  send  mail  to  a  user  name,  MCI 
prompts  you  with  a  list  of  all  users  who 
have  that  name  and  their  correspond¬ 
ing  unique  addresses;  you  then  select 
the  correct  John  Smith.)  However,  be¬ 
cause  the  goal  here  is  to  develop  an 
automatic  system,  you  should  use  the 
MCI  address. 

Next  is  the  Route  table,  shown  in 
Table  1(b),  which  contains  the  routing 
information  for  the  message,  with  a 
complete  list  of  all  the  TO:  and  CC: 
recipients.  The  program  needs  to  in¬ 
clude  all  the  names  if  you  respond  to 
the  message.  The  Route  table  lists 
whether  the  addressee  was  included 
as  a  TO:  or  CC:  and  includes  both  the 
user’s  name  and  ID. 

The  Message  table,  Table  1(c),  is  the 
message  itself  and  uses  a  separate  rec¬ 
ord  for  each  line  in  the  message.  The 
Message#  field  links  the  previous  two 
tables  with  this  table.  The  Line#  field 
allows  you  to  keep  the  fields  in  the 
order  that  messages  are  received.  The 
table  is  displayed  in  a  sorted  order 
based  on  the  Message#  field  and  the 
Line#  field. 


Finally,  the  Pending  table,  shown  in 
Table  1(d),  contains  responses  to  be 
processed  and  sent  to  MCI.  The  first 
field  is  the  Pending#  field,  which  links 
together  all  of  the  components  of  the 
response.  The  Action  field  contains  in¬ 
formation  such  as  TO:,  CC:,  Subject, 
and  Filename.  The  first  three  strings  are 
associated  with  the  routing  and  subject 
matter  of  the  message.  The  Filename 
string,  however,  needs  a  bit  more  dis¬ 
cussion.  Since  neither  PAL  nor  C  pro¬ 
vides  the  means  to  edit  a  message  eas¬ 
ily,  the  PAL  script  runs  an  external  edi¬ 
tor.  The  Filename  record  contains  the 
name  of  the  ASCII  file  to  be  transferred 
as  the  body  of  the  message. 

The  Paradox  Engine  Application 

The  storage/retrieval  application  pro¬ 
cesses  incoming  text  files  and  puts  the 
information  into  the  Paradox  tables  for 
later  use  by  the  PAL  script.  After  the 
PAL  script  has  ran,  this  application  takes 
the  pending  message  information  and 
translates  it  into  a  file  that  can  be 
uploaded  to  MCI.  However,  you  must 
first  initialize  the  database  engine,  open 
the  tables,  and  allocate  the  record  buff¬ 
ers.  Refer  to  the  C  program  in  Listing 
One,  page  104.  (Listing  Two,  page  104, 
is  the  accompanying  header  file.)  start- 
(continued  on  page  77) 
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(continued  from  page  74) 

Engine( )  performs  the  initialization.  A 
call  to  openTables( )  ensures  the  ex¬ 
istence  of  a  table  by  using  the  Engine 
function  PXTblExist( ).  If  such  a  table 
does  not  exist,  then  calls  to  PXTbl- 
Create( )  and  PXKeyAdd( )  create  the 

The  storage/retrieval 
application  processes 
incoming  text  files  and 
puts  the  information 
into  the  Paradox  tables 
for  later  use  by  the 
PAL  script 


Parsing  Incoming  Messages 

The  program  checks  the  command  line 
for  a  filename  to  determine  whether 
there  are  any  incoming  files.  If  there  is 
nothing  on  the  command  line,  it  does 
not  need  to  process  incoming  mes¬ 
sages.  The  program  will  process  an 
outgoing  message  only  if  the  Pending 
table  exists  on  the  disk.  The  PAL  script 
creates  this  table  and  places  all  of  the 
outgoing  message  information  in  it. 

To  understand  how  the  program 
parses  incoming  messages,  study  the 
layout  of  a  typical  MCI  message  in  Fig¬ 
ure  2  and  the  parser  listed  in  Listing 
Three,  page  104.  The  first  line  of  an 
MCI  message  contains  the  Date:  string. 


table  and  indexes.  Once  these  calls  are 
completed,  the  tables  are  opened  and 
record  buffers  allocated. 

At  this  point,  note  that  the  PXCheck( ) 
function  defined  in  this  module  takes 
two  parameters:  a  location  and  an  error 
code.  The  location  is  your  current  place 
in  the  program,  and  the  error  code  is 
the  return  value  from  the  function.  This 
method  is  a  quick  and  dirty  way  to  trap 
errors.  In  cases  where  an  engine  func¬ 
tion  returns  a  value  that  we  do  not 
want  to  stop  the  program  for,  add  the 
location  to  a  switch  statement  that  re¬ 
turns  to  the  caller.  The  calling  code  can 
then  check  PXLastErrJ )  to  determine 
if  there  was  an  unacceptable  error  in 
the  last  call.  An  example  of  wanting  to 
know  the  function’s  return  value  is 
PXSrchKey( ).  If  the  key  you  are  search¬ 
ing  for  does  not  exist,  you  do  not  want 
to  abort  the  program  but  continue.  The 
location  values  are  determined  as  fol¬ 
lows:  The  first  digit  is  the  module  con¬ 
taining  the  code;  the  second  is  the  func¬ 
tion  containing  the  code;  and  the  third 
is  the  specific  call  itself. 


Date :  Sun  Apr  22,  1990  12  :  52  pm  EST 
From:  Joe  Q.  Public  /  MCI  ID:  111-1111 

TO:  *  Chris  Ohlsen  /  MCI  ID:  222- 

2222 

TO:  John  Smith  /  MCI  ID:  333-3333 
TO:  Jane  Doe  /  MCI  ID:  444-4444 

CC:  Frank  Friend  /  MCI  ID  :  555-5555 
Subject:  Testing  MCI  program 
Hey  everybody !  This  is  just  a  sample 
message  to  see  what  the  layout  of 
an  MCI  message  looks  like . 

Joe 


Figure  2:  Layout  of  a  typical  MCI 
Message 
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You  can  ignore  anything  that  appears 
before  this  string  in  the  text  file.  The 
program  reads  the  Date:  string  and 
parses  it  using  strtokf )  to  remove  the 
components  of  the  date.  It  then  con¬ 
verts  these  components  into  data  the 
engine  can  use,  using  PXDateEncodeC  ), 
and  adds  it  to  the  record  for  the  Header 
table.  The  next  line  of  text  is  the  sender 
information.  The  program  parses  both 
the  user’s  name  and  MCI  ID  and  adds 
them  to  the  record. 

The  next  block  of  information  goes 
to  the  Routing  table.  The  program  uses 
getTo( )  and  getCC( )  to  add  the  TO: 
and  CC:  lines  to  the  Route  table.  Every 
TO:  and  CC:  line  is  read  and  parsed  to 
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remove  the  user’s  name  and  MCI  ID, 
and  the  information  is  appended  to  the 
end  of  the  Route  table.  Finally,  the 
program  reads  the  Subject  line,  parsing 
it  and  adding  it  to  the  record  in  the 
Header  table. 

The  script  files  are 
pseudo  scripts  that  you 
can  translate  into 
whatever 
communications 
package  you  are  using 


Once  you  have  all  the  information 
for  the  Header  and  Route  tables,  you 
need  to  work  with  the  message  itself. 
The  program  reads  the  message  one 
line  at  a  time  and  posts  it  to  the  Mes¬ 
sage  table  with  a  unique  line  number 
and  the  current  message  number.  If  the 
line  starts  with  a  Date:  string,  there  is 
another  message  to  process.  If  the  line 
starts  with  the  Command:  string,  there 
are  no  more  messages. 


Creating  Outgoing  Messages 

The  send( )  function  (see  Listing  Four, 
page  106)  checks  for  and  processes 
any  outgoing  messages.  The  existence 
of  the  Pending  table  determines  if  there 
are  any  messages  to  process.  The  PAL 
script  will  create  this  table  only  if  there 
is  a  reply  to  a  message  or  the  user 
composes  a  new  message.  If  there  are 
no  messages,  the  function  returns.  If 
there  is  a  message,  send( )  continues 
by  opening  the  table,  getting  the  han¬ 
dles  to  the  fields,  and  creating  an  index 
on  the  table. 

The  engine  application  now  enters 
the  main  loop  of  the  function,  which 
creates  the  message  script  for  the  com¬ 
munications  program.  The  first  line,  CR, 
creates  a  new  message.  Then  the  pro¬ 
gram  addresses  the  message  for  both 
the  TO:  and  CC:  fields.  Next  it  adds  the 
Subject:  line.  The  application  uses  pro- 
cessMany( )  for  each  of  these  fields.  It 
uses  a  string  and  the  current  pending 
message  number  as  parameters.  The 
program  adds  these  two  fields  to  a 
temporary  record  and  searches  for  them 
in  the  table.  If  it  finds  a  match,  it  reads 
the  record  into  the  Engine’s  internal 
buffers,  which  pull  out  the  desired  field 
and  append  it  to  the  text  file.  Then  it 
searches  for  another  match.  This  con¬ 
tinues  until  there  are  no  matches,  at 
which  point  the  function  returns. 


(a) 

Echo  Off 

comm  -sGETMCI . SCR 
mci  inbox.txt 
paradox3  mci 
mci 

comm  -sSENDMCI .SCR 
del  MCI-SEND.TXT 

(b) 

DIAL  #-###-###-#### 
WAIT  "user  name:" 

;  Dial  your  MCI  Mail  phone  number. 

SEND  "my  mci  name" 

WAIT  "Password:" 

;  Type  in  your  MCI  Account  name. 

SEND  "my  mci  password" 
WAIT  "Command:" 

;  Type  in  your  MCI  Password. 

CAPTURE  "inbox.txt" 

;  Start  capturing  everything  to  the  file 

INBOX . TXT . 

SEND  "pr  inbox" 

WAIT  "Command:" 

CAPTURE  OFF 

;  Tell  MCI  to  display  all  message  in  your 

Inbox. 

SEND  "exit" 

EXIT 

;  Log  off  of  MCI  Mail. 

(C) 

DIAL  #-###-###-#### 
WAIT  "user  name:" 

;  Dial  your  MCI  Mail  phone  number. 

SEND  "my  mci  name" 

WAIT  "Password:" 

;  Type  in  your  MCI  Account  name. 

SEND  "my  mci  password" 
WAIT  "Command:" 

;  Type  in  your  MCI  Password. 

ASCII  XFER  NOLF 

;  Turn  off  line  feeds  during  ASCII  upload. 

UPLOAD  ASCII  "mci-send 

txt"  ;  Upload  all  new  messages. 

Example  1:  Sample  scripts:  (a)  MCI. BAT,  (b)  GETMC1.SCR,  and  (c) 
SENDMCI.SCR 
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The  message  itself  is  stored  in  an 
external  file.  processFile( )  gets  the  name 
of  the  file  from  the  Pending  table,  opens 
the  file,  and  reads  it  line  by  line.  As  it 
reads  each  line  into  the  program,  pro- 
cessFile( )  writes  out  to  the  message 

The  Paradox  Engine  is 
a  database  engine  with 
a  library  of  70 functions 
callable  from  Turbo  or 
Microsoft  C 


recording  capability  allows  you  to  cre¬ 
ate  these  functions:  Just  lay  out  the 
fields  in  the  order  you  want  and  write 
down  the  layout.  Then,  select  Scripts/ 
Begin  Record  to  record  the  steps.) 

The  Message  table  has  MultiRecord 
views  so  you  can  display  and  scroll 
through  the  entire  message.  This  form 
is  linked  to  the  Header  form.  The  com¬ 
bined  information  comprises  the  view 
of  the  individual  fields.  Notice  that  the 
Line#  field  is  decreased  to  one  charac¬ 
ter  width  and  blocked  out  by  selecting 
a  color  because  the  field  is  necessary 
for  internal  use  only.  You  can  change 
the  color  selection  to  match  your  form 
display;  this  block  of  code  is  commented 


script  being  built.  When  the  end  of  the 
file  is  reached,  the  message  file  is  closed 
and  erased.  send( )  again  gains  control 
and  appends  a  “/”  to  the  end  of  the 
message,  which  tells  MCI  Mail  that  the 
text  of  the  message  is  ended.  send( ) 
then  adds  a  blank  line  to  skip  through 
MCI’s  Handling:  prompt,  and  the  “Yes” 
string  is  in  response  to  MCI’s  Send: 
prompt. 

Finally,  nextPendNum( /gets  the  num¬ 
ber  of  the  next  pending  function.  If 
there  are  no  more  messages  pending, 
it  sets  the  pendNum  variable  to  0.  When 
the  loop  sees  there  are  no  more  mes¬ 
sages  to  process,  it  adds  the  string  “exit\ 
n”  to  the  end  of  the  file,  which  logs  the 
script  off  of  MCI  Mail.  The  Pending 
table  (and  all  associated  files)  is  re¬ 
moved  from  the  disk. 

At  this  point,  main(  /takes  over  again 
and  closes  all  the  open  tables,  and  a 
call  to  PXExitC )  turns  the  engine  off. 

The  PAL  Script 

Because  PAL  cannot  compete  against 
your  favorite  word  processor,  the  MCI 
PAL  script  can  call  an  external  editor 
to  process  the  composed  messages.  The 
first  line  of  the  PAL  script  (see  Listing 
Five,  page  107)  defines  which  editor 
(ED)  is  called.  Make  sure  the  word 
processor  you  select  is  working  with 
an  ASCII  file  without  special  control 
characters. 

The  script  then  confirms  that  the  ta¬ 
bles  the  engine  application  has  created 
actually  exist.  If  one  of  the  tables  does 
not  exist,  the  script  displays  a  five- 
second  message  on  the  screen,  stating 
that  you  must  run  the  MCI. EXE  pro¬ 
gram  before  running  this  script. 

Next,  the  script  checks  the  forms  to 
display  the  Header  and  Message  table 
information.  If  the  forms  do  not  exist, 
it  will  build  them.  (The  Paradox  script 


in  BuildMsgForms( ).  The  third  field 
lets  you  view  the  headers  of  the  mes¬ 
sages  currently  stored  and  select  the 
messages  you  want  to  see  in  full. 

Next,  an  opening  screen  displays  the 
name  of  the  script  and  instructions  for 
working  with  the  menus,  and  the  main 
menu  is  displayed:  Inbox  lets  you  view 
a  message,  Compose  lets  you  create  a 
new  one,  and  Quit  exits  the  script.  You 
are  prompted  for  verification  if  you 
select  Quit. 

Viewing  the  Inbox  Messages 

The  Inbox( )  function  uses  the  form 
that  was  created  to  display  the  Header 
table  and  lets  you  choose  the  message 
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with  which  you  wish  to  work.  If  there 
are  no  messages  to  view,  “No  mes¬ 
sages  to  be  viewed”  is  displayed  on  the 
main  screen.  If  you  select  Escape,  you 
return  to  the  main  menu.  If  you  choose 
Enter,  ViewMessage( )  selects  the  mes¬ 
sage  the  cursor  is  currently  on. 

ViewMessage( )  also  uses  one  of  the 
forms  created  earlier  —  the  MultiTable 
form,  which  was  developed  with  both 
the  Header  and  Message  table.  The 
Message  table  form  has  a  MultiRecord 
region  that  displays  the  message  body. 
You  can  use  the  arrow  keys,  PgUp,  and 
PgDn  to  scan  through  the  message.  If 
you  want  to  view  the  previous  or  next 
message  in  the  Header  table,  press  F3 
or  F4,  respectively.  These  keys  corre¬ 
spond  with  the  Up  Image  and  Down 
Image  keys  in  Paradox.  You  can  also 
press  Escape  at  this  point  to  return  to 
the  main  menu. 

If  you  want  to  respond  to  the  mes¬ 
sage,  press  Insert  and  the  script  calls 
Respond( ),  which  grabs  the  current 
header  information  about  the  subject, 
message  number,  and  sender.  QBE  per¬ 
forms  a  query  on  the  Route  table  to  get 
all  those  who  received  the  message, 
so  they  can  be  included  in  the  reply. 

Several  other  fields  are  set  up  before 
pulling  the  information  returned  from 
the  query.  The  Subject  is  added  to  the 
table  with  the  RE:  string  appended  to 
it  to  denote  a  reply.  The  filename  added 
to  the  table  contains  the  body  of  the 
message.  The  filename  is  a  combina¬ 
tion  of  the  Pending  string  and  an  ex¬ 
tension  of  the  Pending  number  in  the 
table. 

When  these  fields  are  set  up,  the 
script  scans  the  answer  table  built  by 
the  previous  QBE.  It  adds  all  of  the 
fields  within  the  answer  table  to  the 
Pending  table  with  the  appropriate  ac¬ 
tion,  indicating  a  TO:  or  CC:.  DO_IT! 
saves  all  of  the  additions  to  the  Pend¬ 
ing  table.  Finally,  the  RUN  BIG  com¬ 
mand  calls  the  editor,  thus  providing 
the  maximum  amount  of  memory. 

Composing  a  New  Message 

Composing  a  new  message  is  similar 
to  responding  to  a  prior  message  ex¬ 
cept  that  the  information  pulled  from 
the  Header  and  Route  tables  is  pro¬ 
vided  by  the  user. 

At  least  one  TO:  field  is  required  to 
send  a  message.  Therefore,  the  script 
forces  you  to  input  at  least  one  field. 
After  receiving  the  TO:  fields,  it  prompts 
you  for  the  CC:  fields.  There  can  be  any 
number  of  CC:s  on  a  message.  Finally,  it 
prompts  you  for  the  Subject  field.  There 
can  be  only  one  of  these,  too.  When  all 
of  the  information  is  input,  the  modi¬ 
fied  table  is  saved,  and  the  editor  is 
called  with  the  RUN  BIG  command. 


Pseudo  Communication  Script 
and  Batch  File 

Now  that  you  have  the  major  players  in 
the  application,  the  PAL  script  and  the 
Paradox  Engine  application,  you  need 
something  to  tie  them  together.  You 
can  use  a  simple  batch  file  (see  Exam¬ 
ple  1)  to  call  everything,  including  the 
pseudo  telecommunications  package. 

The  batch  file  simply  needs  to  call 
the  communications  program  with  a 
script  that  will  grab  all  of  the  available 
messages  on  MCI  Mail.  After  it  does 
this,  it  calls  the  MCI. EXE  program  with 
the  name  of  the  capture  file  to  parse 
and  build  the  tables.  Next,  it  calls  Para¬ 
dox  to  execute  the  MCI  script.  It  calls 
the  MCI. EXE  application  again  to  parse 
any  responses  the  script  may  generate. 
Finally,  it  calls  the  communications  script 
again  to  upload  the  message  that  was 
created,  and  the  upload  file  is  deleted. 

The  script  files  are  pseudo  scripts 
that  you  can  translate  into  whatever 
communications  package  you  are  us¬ 
ing.  The  GETMCI.SCR  script  in  Exam¬ 
ple  1(b)  logs  on  to  MCI  Mail  and  down¬ 
loads  all  new  messages,  capturing  the 
entire  session  to  an  Inbox.Txt  file.  The 
SENDMCI.SCR  script,  in  Example  1(c) 
logs  on  to  the  service  and  performs  an 
ASCII  upload  of  the  file  generated  by 
the  MCI. EXE  program,  MCI-SEND.TXT. 
The  ASCII  file  creates  the  message, 
sends  it,  and  logs  off  the  service. 

Conclusions 

Many  enhancements  could  be  built  into 
the  basic  system  presented  here.  For 
one  thing,  the  PAL  script  could  be  en¬ 
hanced  to  support  an  address  book 
that  keeps  track  of  users’  MCI  addresses, 
and  the  PAL  script  could  add  the  Route 
table  information  to  the  Address  table. 

The  Paradox  Engine  application 
could  also  be  enhanced  to  do  commu¬ 
nications  internally.  It  could  dial  up 
MCI,  post  the  message,  and  receive 
new  mail.  The  program  could  be  set 
to  dial  MCI  early  in  the  morning  before 
work,  and  the  PAL  script  could  be  called 
so  your  messages  are  waiting  when 
you  get  there.  Another  possibility  is  a 
gateway  that  would  allow  many  peo¬ 
ple  to  use  a  single  MCI  Mail  account  via 
private  “mailboxes.”  To  send  a  mes¬ 
sage  to  one  of  these  people,  you  could 
place  additional  addressing  informa¬ 
tion  (such  as  MBXTO:  and  MBXCC:) 
in  the  body  of  the  message.  This  ex¬ 
tends  the  application  to  a  network. 

DDJ 

(Listings  begin  on  page  10  4.) 

Vote  for  your  favorite  feature/article. 
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Listing  One  ( Text  begins  on  page  16.) 

origin= 'hostname ' 

4  run  -  the  user  interface  component  of  the  shepard  system  —  B.  E.  Bauer  1990 
4  configuration  files  associated  with  run: 

#  .run. ini  defaults  for  script, dataset, host, datadir. 

#  .current  jobs  originating  from  workstation  environment 

#  .hosts  host  machines  able  to  run  shepard 

#  .tasklist  list  of  tasks.  Has  flags  for  shepard 

#  .runscripts  list  of  machines  and  possible  scripts 

#  these  files  must  be  located  in  the  login  directory 

#  flag  (and  task  definitions)  definitions,  Used  in  case  statement 

#  and  passed  as  actual  flag  arguments  to  shepard: 

#  x  executes  (submits)  a  job 

#  m  monitors  job 

#  p  probes  job 

4  s  status  of  running  jobs  on  all  platforms 

4  r  list  of  running  jobs 

#  k  kill  job  (with  extreme  prejudice) 

4  t  terminate  job  in  a  controlled  manner  (script  dependent) 

#  1  list  log  on  remote  machine 

#  b  bump  a  waiting  job  from  the  .waiting  list 

4  d  delete  a  waiting  job 

#  f  list  finished  jobs 

#  e  list  error  log 

#  c  change  host 

4  w  list  waiting  jobs 

4  a  list  restart  jobs 

#  g  restart  a  restartable  job 

Iplace  the  date/time  in  day-month-year@time  single  string  format 
set  -  'date' 

year=$6  month=$2  day*$3  tm-$4 
datetime*$day-$month-$year@$tm 

echo  'welcome  to  run  on  '$origin'  at  '$datetime 

.  $ HOME /.run. ini  *source  the  run-script  defaults 
.  $ HOME /.shepard. ini  #  has  network  definition 

#  check  for  finished  jobs,  update  list,  display  finished  list 

#  find  jobs  with  status  RUNNING,  check  host  for  status 

if  (test  -f  $ HOME /.cur rent)  then 

cnt= 'grep  -c  DONE  $HOME/ . current ' 
if  (test  "$cnt"  !*  "0"  )  then 
awk  'BEGIN  { 

printf  "\njobs  recently  finished\n" 

printf  "\n%-10s  %-10s  %-8s  %-21s  %-21s\n\n",\ 

"script", "dataset", "host", "start", "end" 

}  $7  —  "DONE"  { 

printf  "%-16s%-16s%-8s%-20s%-20s\n", $1, $2, $3, $5, $6 
}  '  $HOME/. current  >tmp 

echo  '  cat  tmp  #  display  list  of  completed  jobs 
e^ho  'press  any  key  to  continue  \c' ;  read  sel 
cat  tmp  »  $HOME/run.log  ♦  completed  job  data  to  runlog 
awk  '$7  !=  "DONE"  { 
print  $0 

}  '  $HOME/ .current  >tmp 
mv  tmp  $HOME/ . current 

else 

echo  "no  new  finished  jobs" 
fi 
fi 

#  set  default  host.  All  activities  focus  on  that  host  until  changed 
awk  'BEGIN  { 

n=l 

printf  "\n - current  hosts - \n\n" 

)  ( 

if  ("' $defhost' "  ==  $1) 

printf  "%-3s%-16s%s  %s  %s  (default) \n", n, $1, $2, $3, $4 
else  printf  "%-3s%-16s%s  %s  %s\n", n, $1, $2, $3, $4 
n++ 

) 

END  { 

printf  "\nselect  a  host  machine  by  number:  " 

}'  $HOME/. hosts 
read  sel 

if  (test  -z  "$sel")  then 
host=$defhost 

else 

sel='awk  'BEGIN  (n=l)(if  ("'$sel'"  ==  n)  print  $1;  n++)'  $HOME/. hosts ' 
host*$sel;  defhost=$sel 
fi 

loop=YES 

4  top  of  loop,  exit  with  <ret> 
while  (test  "$loop"  =  "YES") 
do 

4  display  menu  of  tasks 
echo  '  ';  echo  'current  host  is  '  $host 
echo  '  ' 
awk  '  BEGIN  ( 
n=l 

printf  "\t#  flag  task\n" 

printf  "\t - \n" 

H 

printf  "\t%-3s\t%s\n",n, $0 
n++ 

) 

END  ( 

printf  "\ntask  selection  number  [<ret>  to  exit] :  " 

)  '  $HOME/. tasklist 
read  sel 

#  look  up  value  for  shepard  flag  associated  with  task. 

#  Use  the  flag  in  the  case  statement 

task='awk  'BEGIN  (n=l)  (if("'$sel'"  ==  n)  print  $2;  n++}'  $HOME/ .tasklist ’ 
flag='awk  'BEGIN  (n=l)  (if("'$sel'"  ==  n)  print  $1;  n++}'  $HOME/ .tasklist ' 
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#  if  response  is  <ret>,  exit  while  loop 
if  (test  -z  "$sel")  then 
break 
fi 

case  $flag  in 

-x)  #  start  a  job.  Queries  for  script,  dataset,  datadir 

#  list  scripts  available  only  on  selected  host 
awk  '  BEGIN  { 

n-1 

def-0 

printf  "\n#  (host)  script" 

printf  "\n - \n" 

} 

"'$host'"  —  $1  ( 

if  ($2  —  "' $def script' ")  { 

printf  "%-2s  %s  (default) \n",n, $0 
def  *  n 

) 

else  printf  "%-2s  %s\n",n,$0 
n++ 

) 

END  ( 

printf  "\nselect  a  script  by  number  [%s] :  ",def 
)  '  $HOME/.runscripts 
read  tmp 

#  look  up  the  script  selected  by  number  (must  be  on  one  line) 
sel-'awk  'BEGIN (n-1)  "' $host' "-=$1  {if("'$tmp'B  —  n)  print  $2;  n++)  ' 

$HOME/ . runscripts ' 

if  (test  "$sel"  *  "")  then 
script-$def script 

else 

script-Ssel;  defscript-$sel 
fi 

echo  '  selected  script  is  '  $script 

#  get  the  dataset  name 

echo  '  echo  'enter  dataset  name  [' $defdata' ] :  \c' 
read  sel 

if  (test  "$sel"  -  "")  then  §  substitute  default  for  <ret> 
dataset-$defdat 

else 

dataset-$sel;  defdata-$sel 
fi 

echo  'selected  dataset  is  '$dataset 

#  get  the  directory  where  the  data  is  located 

#  if  $SHEPARD_NETWORK  is  set  to  "remote",  data  moves  between  machines 

#  using  nfs  otherwise,  data  is  retained  on  server 

#  home  directory  on  the  host  machine,  then  back  when  done 
echo  '  echo  'enter  directory  of  data  on  ' 

case  $SHEPARD_NETWORK  in 

remote)  echo  $iam' :  \c';; 

nfs)  echo  $iam'  using  nfs  mount  on  '$host':  \c';; 
server)  echo  $host' :  \c' ;  defdir-' $HOME' ; ; 

esac 
read  sel 

if  (test  "$sel"  =  "")  then  #  substitute  default  for  <ret> 
datadir-$defdir 

else 

datadir-$sel;  defdir*$sel 
fi 

echo  'selected  directory  is  '$datadir 

#  append  new  job  entry  to  $HOME/. cur rent 
Hist-' $script  Sdataset  $host  $datadir  $datetime' 
echo  $llist  'out'  'STARTED'  »$H0ME/ . current 

if  (test  "$origin"  -  "$host")  then 

shepard  $flag  $script  $dataset  $host  $datadir 

else 

rsh  $host  shepard  $flag  $script  $dataset  $origin  $datadir 

fi; ; 

-s)  #  listing  of  current  file,  shows  activity  on  other  platforms 
awk  '  BEGIN  ( 

fmt-"%-5s  %-16s  %-16s  %-21s  %-16s\n" 

dash5-" - " 

dashl6-" - " 

dash21-" - " 

n-1 

printf  "\n\ncurrent  job  status\n\n" 

printf  fmt, "script", "dataset", "submitted", "status" 
printf  fmt , dash5, dashl6, dashl6, dash21, dashl6 
printf  "\n" 

)  { 

printf  fmt, n, $1, $2, $5, $7 
n++ 

) 

END  ( 

printf  "\npress  any  key  to  continue  " 

)  '  $HOME/. current 
read  sel;; 

-  [ktpdbg] ) 

#  these  are  all  list  processing  commands  using  pick  an  item  menuing 

#  the  menu  is  generated  by  shepard  on  the  selected  host 

#  the  item  is  picked  in  run  and  the  selection  happens  in  shepard 
case  $flag  in 

-[ktp])  lflag-'-r';;  #  list  running  jobs 
-[dbj)  lflag-'-w';;  #  list  waiting  jobs 
-g)  lflag-'-a';;  #  list  restartable  jobs 

esac 

if  (test  "$origin"  -  "$host")  then 

shepard  $lflag  dummy2  dummy3  dummy4  dummy5 

else 

rsh  $host  shepard  $lflag  duramy2  dummy 3  dummy 4  dummy 5 
fi 

echo  '  ' ;  echo  ' select  number  of  job  to  \c' 
case  $flag  in 

-k)  echo  'kill  \c';; 

-t)  echo  'halt  gracefully  \c';; 

-g)  echo  'restart  \c';; 

-d)  echo  ' remove  from  waiting  queue  \c' ; ; 

-b)  echo  'bump  to  top  of  queue  \c';; 

-p)  echo  'probe  running  status  \c';; 

(continued  on  page  84) 
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Listing  One  ( Listing  continued,  text  begins  on  page  16.) 

esac 

read  sel  #  select  one  from  list 
arg5=$sel 

if  (test  "$origin"  -  "$host")  then 

shepard  $flag  dummy2  dummy3  dummy4  $arg5 

else 

rsh  $host  shepard  $flag  dummy2  dummy3  dummy4  $arg5 

fi; ; 

-c)  #  change  hosts 
awk  'BEGIN  { 
n-1 

printf  " - current  hosts - \n\n" 

}  ( 

if  ("' $defhost' "  --  $1)  { 

printf  "%-3s%-16s%s  %s  %s  (default) \n", n, $1, $2, $3, $4  } 
else  printf  "%-3s%-16s%s  %s  %s\n",n,$l,$2,$3,$4 
n++ 

} 

END  ( 

printf  "select  a  new  host  machine  by  number:  " 

}'  $HOME/. hosts 
read  sel 

if  (test  -z  "$sel")  then 
host-$defhost 

else 

sel-'awk  'BEGIN  (n-1) (if  ("'$sel'"« n)  print  $1;  n++}'  $HOME. hosts' 
host-$sel;  defhost-$sel 
fi; ; 

-[rewfalm])  #  process  listing  commands 
if  (test  "$origin"  *  "$host")  then 

shepard  $flag  dummy2  dummy3  dummy4  dummy5 

else 

rsh  $host  shepard  $flag  dummy2  dummy3  dummy4  dummy5 
fi 

read  sel;; 

*)  #  woops 

echo  $flag  'is  not  a  recognized  option,  try  again' 

esac 

done  #  bottom  of  while  loop 

#  write  current  values  to  run-script  default  file 

#  $HOME/.run.ini  is  sourced  on  invocation  in  effect  restoring  the 

#  last  values  used.  Handy  for  checking  on  a  previously 

#  started  job  -  values  properly  default  to  the  previous 
echo  ' def script-' $def script  >$HOME/.run.ini 

echo  ' defdata-' $defdata  »$HOME/.run.ini 
echo  'defhost-'$defhost  »$HOME/.run.ini 
echo  'defdir-' Sdefdir  »$HOME/.run.ini 

echo  'end  of  run' 


End  Listing  One 


Listing  Two 

trap  ' rm  -f  $HOME/.sheplock;  exit'  1  2  3  15 

#  shepard  -  task  management  component  od  shepard  system  —  B.  E.  Bauer  1990 

#  Shepard  is  the  action  component  of  the  system.  When  invoked,  it 

#  owns  all  the  associated  files  (see  top  of  shepard_queue  for  list) 

#  and  updates  the  current  file  on  the  originator,  log  and  err  files, 
t  Shepard  can  be  invoked  from  local  or  remote  machines;  it  senses 

#  local  or  remote  operation  and  behaves  accordingly. 

#  Shepard  handles  all  tasks  except  for  job  queueing  (shepard_queue)  and 

#  application-specific  job  probing  (defined  in  $probe_script  as  sourced 

#  in  ' script' .script) .  Shepard  is  called  by  terminating  jobs  for  cleanup. 

#  Shepard  can  be  present  in  several  executing  copies  called  by  run  (the 

#  user  interface)  and  by  completing  jobs  waiting  for  cleanup.  To  avoid 

#  collision  between  shepards,  absolute  ownership  of  all  associated  files 

#  is  essential,  and  is  accomplished  by  creating  a  lock  file.  All  other 

#  versions  of  shepard  have  to  wait  until  the  first  is  done. 

#  wait  until  lock  file  established  insures  complete  ownership 

#  of  all  files  by  only  one  version  of  shepard  at  a  time 
until  lockon  .sheplock 

do  sleep  5;  done 

iam= 'hostname' 

.  $HOME/. shepard. ini  ♦  source  the  initialization  file 
t  do  not  display  greeting  message  if  called  from  terminating  process 
if  (test  "$1"  !■  "-z")  then 

echo  'shepard  on  '$iam'  at  ''date' 
fi 

#  if  you  see  the  message,  you  made  it. 

#  Important  verification  that  remote  shell  command  is  functioning 

#  lookup  values  from  files  depending  on  mode 
pass-NO 

case  $1  in  *  select  the  file  name  associated  with  flag 
— [ktp] )  fname-$HOME/ . running;  pass-YES;; 

-[bdj)  fname-$HOME/. waiting;  pass-YES;; 

-g)  fname-$HOME/ .restart;  pass-YES;; 

esac 

if  (test  "$pass"  -  "YES")  then  #  do  the  lookup 

scr-'awk  'BEGIN  (n-1)  (if  ("'$5'"  —  n)  print  $1;  n++}'  $fname’ 

dset-'awk  'BEGIN  (n-1)  (if  ("'$5'"  --  n)  print  $2;  n++}'  $fname' 

host-'awk  'BEGIN  (n-1)  {if  ("'$5'"  --  n)  print  $3;  n++)'  $fname' 

ddir-'awk  'BEGIN  (n-1)  (if  ("'$5'"  --  n)  print  $4;  n++)'  $fname' 

sel- 'awk  'BEGIN  (n-1)  (if  ("'$5'"  —  n)  print  $5;  n++}'  $fname' 

tname-$host' : '$scr' (' $dset' ) '  #  compact  file  name 

fi 

#  no  loop  in  shepard.  Does  the  command  then  exits 
case  $1  in 

-x)  #  runs  job  through  queue  manager  which  handles  submission 
shepard_queue  $2  $3  $4  $5;; 

(continued  on  page  86) 
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Listing  Two  (Listing  continued,  text  begins  on  page  16.) 

-m)  #  system-dependent  code  here,  "big"  is  using  Berkeley  UNIX 

♦  while  all  others  use  SYSTEM  V.  Options  to  ps  are  different 
if  (test  "'hostname'"  =  "big")  then 

ps  -ax  !  grep  -n  shepard_exec  #  CONVEX  specific  (for  example) 

else 

ps  -ef  *  SGI  IRIS  specific  (for  example) 

fi;; 

-p)  #  probe  job  -  script-dependent 

♦  source  the  file  containing  application-specific  scripts 
.  $SHEPARD_DIR/ $2. script 

.  $probe_script; ;  ♦  defined  in  sourced  file  $script. script 

echo  'press  <ret>  to  continue  \c' 

-r)  #  list  running  jobs  on  host 

cnt-'wc  -1  $HOME/ . running  !  awk  '{print  $1)'' 
if  (test  "Sent"  =  "0")  then 

echo  '  ' ;  echo  ' no  jobs  running' ;  echo  '  ' 

else 

awk  '  BEGIN  { 

fmt="\n%-5s  %-16s  %-16s  %-8s\n" 


printf  "\n - running  jobs  on  %s - \n",  "' $host' " 

printf  fmt, "♦", "script", "dataset", "pid" 

printf  " - - - - \n" 


n-1 

)  ( 

printf  fmt,n, $1, $2, $5 
n++ 

} 

END  { 

printf  "\npress  any  key  to  continue  " 

)  '  SHOME/ . running 

fi;; 

-w)  #  list  waiting  jobs  on  host 

ent-'we  -1  $HOME/ .waiting  !  awk  '{print  $1)'’ 
if  (test  "Sent"  -  "0")  then 

echo  '  ';  echo  'no  jobs  waiting';  echo  '  ' 

else 

awk  '  BEGIN  { 

fmt="\n%-5s  %-16s  %-16s  %-8s\n" 

printf  "\n - waiting  jobs  on  %s - \n", "' Shost' " 

printf  fmt, "#", "script", "dataset", "position" 

printf  " - - \n" 

n=l 

)  { 

printf  fmt,n, $1, $2, $5 
n++ 

) 

END  { 

printf  "\npress  any  key  to  continue  " 

}  '  SHOME/. waiting 

fi; ; 

-a)  #  list  restartable  jobs  on  host 

cnt~'wc  -1  SHOME/. restart  I  awk  '{print  $1)'' 
if  (test  "Sent"  ■  "0")  then 

echo  '  ';  echo  'no  jobs  in  restart';  echo  '  ' 

else 

awk  '  BEGIN  { 

fmt="\n%-5s  %-16s  %-16s  %-8s\n" 

printf  "\n -  restartable  jobs  on  %s  - \n", "' Shost' " 

printf  fmt, "#", "script", "dataset",  "position" 

printf  " - - - \n" 

n*=l 

)  { 

printf  fmt,n,$l,$2,$5 
n++ 

}  '  SHOME/ . restart 
fi; ; 

-g)  #  restart  a  job  from  SHOME/ . restart  and  update 

#  file  to  select  passed  as  shell  argument  5 

#  copys  the  selected  entry  to  SHOME/ .waiting  with  priority=RESTART 
awk  '  BEGIN  { 

n=l 

•  )  { 

if  (n  ==  "'$5'")  printf  "%s  %s  %s  %s  RESTART\n", $1, $2, $3, $4 
n++ 

)  '  SHOME/. restart  »  SHOME/ .waiting 

awk  '  BEGIN  {  ♦  restarted  job  is  purged  from  SHOME/ . restart 

n=*l 

}  { 

if  (n  !-  "'$5'")  print  $0 
n++ 

)'  SHOME/ . restart  >  tmp 
mv  tmp  SHOME/. restart 

echo  'restarting  'Stname'  at  'Sdatetime  »shepard.log 
♦update  .current  on  origin  machine 
if  (test  "Shost"  =  "Siam")  then 
run_update  -g  Sscr  Sdset  $sel 

else 

rsh  Shost  run_update  -g  Sscr  Sdset  Ssel 
fi 

shepard_queue  -r;;  ♦  do  the  restart 

-k)  #  kill  job  with  extreme  prejudice 

#  pid  passed  as  shell  argument  5,  assigned  to  sel 

#  running  processes  have  2  entries  in  the  process  list 

#  first  *  shepard_exec  and  has  the  pid  stored  in  running 

#  second  =  the  executable  application 

#  searching  the  process  list  for  first  finds  second;  both 

#  must  be  killed  to  stop  the  application:  killing  shepard_exec 

#  alone  leaves  the  application  program  still  running 
if  (test  "Siam"  =  "big")  then 

cleanup='ps  -axl  !  awk  '  "'Ssel'"  ==  $4  {print  $3)'' 

else 

cleanup='ps  -ef  !  awk  '  "'Ssel'"  “  $4  {print  $3)'' 
fi 

kill  -9  Ssel 

kill  -9  Scleanup 

if  (test  "$?"  =  "0")  then 

echo  'killed  'Stname'  at  'Sdatetime  »$HOME/shepard.log 

else 

echo  'status  of  kill  command  nonzero  -  check  log  for  problems' 
fi 


Dr.  Dobb’s Journal,  December  1990 

1135 


awk  '  $5  !=  "'$sel'"  {  print  $0  }'  $HOME/ .running  >  $HOME/tmp 
mv  $HOME/tmp  $HOME/ . running 
♦update  .current  on  origin  machine 
if  (test  "$host"  -  "$iam")  then 
run_update  -k  $scr  $dset  $sel 

else 

rsh  $host  run  update  -k  $scr  $dset  $sel 
fi 

shepard_queue  -q; ;  ♦  check  for  waiting  jobs 
-t)  #  terminate  job  gracefully  pass  script  and  origin  variables 

♦  source  the  file  containing  application-specific  scripts 
.  $SHEPARD_DIR/$ 2. script 

.  $terminate_script  #  found  in  scriptname. script 
echo  'terminated  '$tname'  at  '$datetime  »  $HOME/shepard.log 
♦update  .current  on  origin  machine 
if  (test  "$host"  -  "$iam")  then 
run_update  -t  $scr  $dset  $sel 

else 

rsh  $host  run_update  -t  $scr  $dset  $sel 
fi;;  ♦  when  the  application  exits,  it  will  check  for  waiting  jobs 
-1)  ♦  list  the  job  log  on  host 

tail  -30  shepard.log;;  ♦  only  the  last  is  generally  interesting 
-b)  ♦  bump  priority  of  specific  job 

♦  $ HOME /.waiting  can  be  in  any  order,  use  2-pass  approach 

♦  pass  1;  set  desired  to  zero,  increment  all  others 

♦  pass  2:  change  0  to  1,  zero  now  being  easy  to  spot 
awk  '  ( 

if  ($1  ==  $scr' ")  ( 

if  ($5=="'$sel'")  $5-0 
if  ($5  <  "'$sel'")  $5  +=  1 

} 

printf  "%s  %s  %s  %s  %s\n", $1, $2, $3, $4, $5 
}  '  $HOME/ .waiting  !  awk  '  ( 
if  ($5  ==  0)  $5=1 

printf  "%s  %s  %s  %s  %s\n", $1, $2, $3, $4, $5 
}  '  >  $H0ME/tmp 
mv  $H0ME/tmp  $HOME/ .waiting 

echo  'bumped  '$tname'  at  '$datetime  »  $ HOME /shepard. log 
if  (test  "$host"  =  "$iam")  then 
run_update  -b  $scr  $dset  $sel 

else 

rsh  $host  run_update  -b  $scr  $dset  $sel 

fi;  ; 

-d)  ♦  delete  a  waiting  job  from  waiting,  selected  passed  as  shell  arg  5 

♦  same  script/higher  priority  have  their  priorities — 
awk  '  { 

if  ($1  ==  "'$scr'")  ( 

if  ($5=="' $sel' ")  next  ♦  excise  deleted  job 
if  ($5  >  "' $sel' ")  $5  =  $5  -  1 

} 

print  $0 

}  '  $H0ME/ .waiting  >  tmp 
mv  tmp  $HOME/. waiting 

echo  'deleted  '$tname'  at  '$datetime  »  $HOME/shepard.log 
♦update  .current  on  origin  machine 
if  (test  "$host"  =  "$iam")  then 
run_update  -d  $scr  $dset  $sel 

else 

rsh  $host  run_update  -d  $scr  $dset  $sel 

fi; ; 

-f)  ♦  list  finished  jobs 
awk  '  BEGIN  ( 

fmt="\n%-16s  %-16s  %-12s\n" 

printf  "\n - finished  jobs  on  %s - \n", "' $host' " 

printf  fmt, "script", "dataset", "origin" 

printf  " - - \n" 

}  ( 

printf  fmt, $1, $2, $3 

} 

END  ( 

printf  "\npress  any  key  to  continue  " 

}  '  $HOME/. finished; ; 

-e)  ♦  list  error  log 

tail  -30  $HOME/shepard.err; ; 

-z)  ♦  go  to  cleanup  routine,  $5  has  the  completed  jobs  pid  number 
echo  'finished  '  $4' : '  $2' (' $3' )  at  '’date'  »shepard.log 

♦  write  entry  to  .finished 

♦  run  on  origin  will  look  here  for  completed  jobs 
echo  $2  $3  $4  $5  'date'  »  $HOME/. finished 

♦  excise  finished  job  from  $HOME/ . running  list 
awk  '{ 

if  ("'$5'"  !=  $5)  print  $0 
}'  $H0ME/. running  >tmp 
mv  tmp  $HOME/ . running 
♦update  .current  on  origin  machine 
if  (test  "$4"  =  "$iam")  then 
run_update  -f  $2  $3  $5 

else 

rsh  $4  run_update  -f  $2  $3  $5 
fi 

♦check  queue  for  waiting  process 
shepard_queue  -q; ; 


rm  -f  $HOME/ . sheplock  ♦  remove  locking  file 

♦  normal  return  to  run  if  invoked  by  remote  shell,  otherwise  terminates 


Listing  Three 

trap  'rm  -f  $ HOME /tmp;  exit'  1  2  3  15 


End  Listing  Two 


♦  shepard_queue  -  queue  manager  for  shepard  system  —  B.  E.  Bauer  1990 

♦  shepard_queue  places  jobs  in  a  waiting  queue  and  allows  a  job 

♦  to  actually  start  if  the  count  of  similar  jobs  running  is 

♦  below  a  user  defined  threshold.  Its  like  a  FIFO  queue  with  a  twist. 

♦  This  is  intended  to  balance  throughput  vs  system  demands  on 

♦  multiprocessor  high  performance  computers.  Alter  for  your  environment 

(continued  on  page  88) 
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Listing  Three  (Listing  continued,  text  begins  on  page  16.) 

♦  jobs  in  $HOME/ .waiting  have  a  number  associated  with  their  place  in  the 


queue.  l=next  to  start  up  to  limit  defined  in  .limits 
passed  arguments: 

1 
2 
3 


normal  queue  submit: 


restart 
queue  check 


script  name 
dataset  name 

originating  machine  name 
dataset  directory 
-r  {no  other  values  passed) 
-q  (no  other  values  passed) 


* 

* 

* 

♦ 

♦ 

# 

♦ 

« 

♦ 

♦  for  restart,  $HOME/ .waiting  has  the  restart  job  preappended 
iam= 'hostname ' 

.  $HOME/. shepard. ini  #  source  the  initialization  file 
mode=NORMAL 

if  (test  "$1"  =  "-r")  then  ♦  restart  entry  submitted 

♦  get  the  script  which  has  the  RESTART  code  (normally  passed  as  $1) 
scr='awk  'BEGIN  (n=0)  $5=="RESTART"  (print  $1)'  $HOME/ .waiting ' 

♦  find  and  replace  RESTART  with  last  queue  slot  for  corresponding  script 
awk  '  BEGIN  { 

count  ■  1 

}  ( 

if  ("'$scr'"  !=  $1)  print  $0 
else  if  ($5  !=  "RESTART")  { 
count ++ 

printf  "%s  %s  %s  %s  %s\n", $1, $2, $3, $4, $5 

} 

else  printf  "%s  %s  %s  %s  %s\n",$l,$2,$3,$4,count 
}  '  $HOME/. waiting  >  $HOME/tmp 
mv  $HOME/tmp  $HOME/ .waiting 
elif  (test  "$1"  !«  "-q")  then  ♦  new  job  to  submit 

♦  append  new  job  entry  to  $HOME/ .waiting  list 
echo  $1  $2  $3  $4  'NEW'  »  $ HOME/ .waiting 

♦  change  NEW  label  to  count  of  jobs  having  that  script 

♦  newest  entry  has  the  highest  number/last  to  be  executed 
awk  '  BEGIN  { 

count  -  1 

}  i 

if  ("'$1'"  !=  $1)  print  $0 
else  if  ($5  !-  "NEW")  { 
count ++ 
print  $0 

) 

else  printf  "%s  %s  %s  %s  %s\n",$l,$2,$3,$4,count 
)  '  $HOME/. waiting  >  $HOME/tmp 
mv  $HOME/tmp  $H0ME/. waiting 

cnt-'awk  'BEGIN{n-0)"'$l'"  —  $1  (n++)  END  (print  n}'  $HOME/ .waiting' 
if  (test  "$3"  -  "$iam")  then 
run_update  -w  $1  $2  cnt 

else 

rsh  $3  run_update  -w  $1  $2  cnt 
fi 

else 

mode=QUEUE  ♦  flag  suppresses  terminal  response  when  in  -q  mode 
fi 

didit=NO  ♦  flag  reports  job  starting  status 

♦  loop  through  scripts  available  on  this  host 

♦  available  scripts  are  in  the  environment  variable  SHEPARD_SCRIPTS 

♦  The  FIFO  queue  has  a  twist:  differing  job  types  are  subqueued  with 

♦  limits  for  each  found  in  .limits  without  maintaining  separate  queue 

♦  structures.  This  method  is  easier  to  implement  and  permits  a  maximum 

♦  load  balance  consisting  of  a  mix  of  program  types,  tailored  to  ones 

♦  needs.  In  this  way,  a  number  of  program  type  'a'  exceeding  the  limit 

♦  only  runs  the  number  set  in  .limits,  while  the  others  queue  leaving 

♦  processor  time  for  program  types  'b'  and  'c'.  The  optimum  load  balance  is 
I  determined  by  the  system  resource  requirements  of  each  program  and 

♦  ones  needs  for  throughput;  adjusting  .limits  allows  changes  on  the  fly. 

for  i  in  $SHEPARD_SCRIPTS 
do 

♦  count  jobs  actually  running  for  each  script,  get  associated  job  limit 
if  (test  -f  "$HOME/ .running")  then 

rcnt= 'awk  ' BEGIN (n=0)  "'$i'"==$l  (n++)  END(print  n)'  $HOME/. running' 

else 

rcnt=0  ♦  set  rent  to  0  if  $HOME/. running  is  not  present 
fi 

rlim='awk  '"'$iam'"  ==  $1  &&  "'$i'"  ==  $2  (print  $3}'  $HOME/ . limits ' 
if  (test  -z  "$rlim")  then 

rlim=l  #  if  no  limit  in  $HOME/ .limits,  one  job  permitted 
fi 

♦  if  more  running  jobs  exceeds  the  limit,  continue  to  next  script 
if  (test  "$rcnt"  -ge  "$rlim")  then 

continue 

fi 

♦  loop  to  next  script  if  no  jobs  waiting  with  priority=l 
script='awk  '  "'$i'"  ==  $1  &&  $5  ==  "1"  (  print  $1)'  SHOME/ .waiting' 
if  (test  "$script"  !=  "$i")  then 

continue 

fi 

♦  found  one  for  current  script,  get  the  remaining  values 
dataset='awk  '  "'$i'"  ==  $1  &&  $5  ==  "1"  {  print  $2)'  $HOME/ .waiting' 
origin='awk  '  "'$i'"  ==  $1  &&  $5  ==  "1"  {  print  $3)'  $HOME/ .waiting ' 
datadir='awk  '  "'$i'"  ==  $1  &&  $5  ==  "1"  (  print  $4)'  $HOME/ .waiting' 

♦  put  date/time  in  a  single  string  format 
set  -  'date' 

day=$3  month=$2  year=$6  tm=$4 
datetime=$day-$month-$year@$tm 

♦  submit  shepard_exec  to  the  background,  get  its  pid 

wait  10  ♦  shepard_queue  does  not  wait  for  shepard_exec 

nohup  shepard_exec  $script  $dataset  $origin  $datadir  >shepard_ junk. log  & 

pid=$!  #  process  identification  number  -  unique  for  job 

errflag=$? 

♦  shepard_exec  did  not  initiate,  for  some  reason 

♦  append  the  shepard_junk.log  to  shepard. err,  alert  the  user 

♦  the  job  is  placed  in  .restart 
if  (test  "$errflag"  !=  "0")  then 

♦notify  the  user 


echo  Sscript' (' $dataset' )  did  not  start  at  '$datetime 
echo  '  return  code  ' $errf lag 

echo  ' -  process  error  logfile  contents  - ' 

cat  $HOME/shepard_ junk . log 

echo  ' - end  of  log  from  '  $script' {' $dataset' ) - ' 

echo  '  ';  echo  'check  the  contents  of  shepard. err  for  details' 

#  update  shepard. err 

echo  $script' {' $dataset' )  did  not  start  at  '$datetime  >tmp 

echo  ' -  process  error  logfile  contents  - '  »tmp 

cat  shepard_junk.log  »tmp 

echo  ' - end  of  log  from  '$script'  ('$dataset') - '  »tmp 

cat  tmp  »  $HOME/shepard.log;  rm  tmp 

♦  remove  from  $HOME/ .waiting,  place  in  .restart 

awk  '  $1  ==  "'$script'"  &&  $2  ==  "'$dataset'"  &&  $5  ==  1  ( 
print  $0 

)'  $HOME/ .waiting  »  $HOME/ .restart 
awk  '  { 

if  ($1  ==  "'$i'"  &&  $5  “  1)  continue 
if  ($1  ==  "'$i'")  ( 

$5  =  $5  -  1 

printf  ”%s  %s  %s  %s  %s\n”, $1, $2, $3, $4, $5 

) 

}'  $HOME/. waiting  >  $ HOME /tmp 
mv  $HOME/tmp  $HOME/ .waiting 
exit 


didit=YES 

#  append  job  specifics  to  SHOME/. running 

echo  $script  $dataset  Sorigin  $datadir  Spid  »$HOME/. running 

♦  append  job  info  to  shepard.log 

echo  $script' (' $dataset' )  started  'Sdatetime  »$HOME/ shepard. log 

#  remove  running  job  from  $HOME/. waiting,  update  priority 
awk  '  { 

if  ($1  ==  "'$i'H  &&  $5  *=  1)  next 
if  ($1  ==  "'Si'")  { 

$5  -  $5  -  1 

printf  "%s  %s  %s  %s  %s\n", $1, $2, $3, $4, $5 

} 

)'  $HOME/ .waiting  >  $HOME/tmp 
mv  $HOME/tmp  $HOME/ .waiting 
♦update  .current  on  origin  machine 
if  (test  "Siam"  =  "Sorigin")  then 

run_update  -r  Sscript  Sdataset  Spid 

else 

rsh  Sorigin  run_update  -r  Sscript  Sdataset  Spid 
fi 

♦  if  job  is  successfully  started,  notify  user 
if  (test  "Sdidit"  =  "YES")  then 

echo  '  ' 

echo  Sscript' ('Sdataset' )  started  on  'Siam'  at  'Sdatetime 
fi 

done 

if  (test  "Sdidit"  =  "NO")  then 

if  (test  "Smode"  !=  "QUEUE")  then 

echo  '  ';  echo  'no  jobs  were  submitted' 
fi 
fi 

trap  "  1  2  3  15 


Listing  Four 


End  Listing  Three 


trap  'shepard  -z  $1  $2  $3  $$'  1  2  3  15 

♦  shepard_exec  -  execution  potion  of  shepard  system  —  B.  E.  Bauer,  1990 

♦  passed  args:  1:  script,  2:  dataset,  3:  origin,  4:  datadir 

.  SHOME/. shepard. ini  ♦  source  initialization  file 

.  $SHEPARD_DIR/$1. script  ♦  source  application-specific  definitions 

♦  routine  to  move  the  required  files  into  the  execution  environment 

♦  sourcing  vs  separate  shell  obviates  need  to  pass  values 
.  $SHEPARD_DIR/$getdata_script 

♦  run  the  program.  Assumes  here  that  stdin,  stdout,  and  stderr  are 

♦  required  (generally  true  for  UNIX)  during  execution.  All  other  data 

♦  files  were  moved  into  the  execution  environment  by  $getdata_script 
$exe  <  $2$inp  1>  $2$log  2>  $2$err 

♦  source  the  script  to  return  data  back  in  its  proper  location 
.  $SHEPARD_DIR/$putdata_script 

♦  clean  up  and  update  status  files 

shepard  -z  $1  $2  $3  $$  ♦  pid  of  completing  process  returns  as  arg5 

trap  "  1  2  3  15 


Listing  Five 


End  Listing  Four 


trap  'rm  -f  $HOME/tmp;  exit'  1  2  3  15 

♦  run_update  -  update  component  of  shepard  system  —  B.E.  Bauer  1990 

♦  updates  the  .current  file  to  reflect  system  activities 

flag=$l  script=$2  dataset=$3  opt=$4 
set  -  'date' 

day=$3  month=$2  year=$6  tm=$4 
datetime=$day-$month-$year@$tm 

case  $flag  in 

-w)  stat=' WAITING' 

-r)  stat=' RUNNING' 

-g)  stat=' RESTART' 

-b)  stat=' BUMPED' ; 

-k)  stat=' KILLED' ; 

-f)  stat='D0NE' ; ; 


(continued  on  page  90) 
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Listing  Five  (Listing  continued,  text  begins  on  page  16.) 

-d)  stat-' DELETED';; 

-t)  stat-' TERMINATED' ; ; 


awk  '  { 

if  {"'$script'"  —  $1  &&  "'Sdataset'"  ==  $2)  { 

printf  ”  %s  %s  %s  %s  %s  %s  %s\n", $1, $2, $3, $4, $5, Sdatetime' ", $stat' " 

) 

else  print  $0 

}'  $HOME/. current  >$HOME/tmp 
mv  $HOME/tmp  $HOME/ . current 


trap  "  1  2  3  15 

Listing  Six 


End  Listing  Five 


big  bmin311v 
big  bmin31mv 
big  spartan 
big  amber 
big  smapps 
big  ampac 
big  dspace 
moe  bmin311s 
moe  bmin31ms 
moe  bmin31ss 
moe  amber 
moe  ampac 
moe  spartan 
moe  smapps 
larry  bmin31ss 
larry  ampac 


Batchmin  large  (<2000  atoms) 

Batchmin  medium  (<1000  atoms) 

ab  initio  electronic  structure  calculation 

biological  structure  simulation 

Monte  Carlo  peptide  simulation 

semi-empirical  electronic  structure  calculation 

NMR  distance  ->  structure 

Batchmin  large  (<2000  atoms)  use  with  caution! 
Batchmin  medium  (<1000  atoms)  default 
Batchmin  small  (<250  atoms) 
biological  structure  simulation 
semi-empirical  electronic  structure  calculation 
ab  initio  electronic  structure  calculation 
Monte  Carlo  peptide  simulation 
Batchmin  small  (<250  atoms) 
semi-empirical  electronic  structure  calculation 


Listing  Seven 


End  Listing  Six 


larry  SGI  IRIS  4D/25TG  (B-l-3-09) 
curly  SGI  IRIS  4D/120GTX  (B-8-3-22;  CADD  room) 
moe  SGI  IRIS  4D/240s  (B-8-3-22;  CADD  room) 
big  CONVEX  220  (B-20-B) 


Listing  Eight 


End  Listing  Seven 


-x  execute  (submit)  a  job 

-m  monitor  remote  host  process  status  (ps  command) 
-p  probe  running  job 

-s  status  of  running  jobs  on  all  platforms 

-r  running  job  list 

-k  kill  job  (with  extreme  prejudice) 

-t  terminate  job  gracefully 
-g  restart  job 

-1  log  file  on  remote  machine  (tail  -30) 

-b  bump  waiting  job  to  next 
-d  delete  a  waiting  job 
-f  finished  job  list  on  host  machine 
-e  error  log  on  host  machine  (tail  -30) 

-c  change  hosts 

-w  waiting  job  list  on  host  machine 
-a  restartable  job  list  on  host  machine 


Listing  Nine 


End  Listing  Eight 


#  Loads  values  for  script,  dataset,  host,  and  datadir  last  used  by  run. 

#  This  file  is  recreated  at  the  end  of  run. 


defscript-bmin311v 

defdata-bmintest3 

defhost-big 

defdir-pla2 


Listing  Ten 

big  bmin311v  3 
big  bmin31mv  1 
big  spartan  1 
big  amber  2 
big  smapps  1 
big  ampac  3 
moe  bmin31ms  2 
moe  bmin31ss  4 
moe  amber  2 
moe  smapps  1 
moe  ampac  4 
moe  spartan  1 
larry  bmin31ss  1 
larry  ampac  1 


Listing  Eleven 


End  Listing  Nine 


End  Listing  Ten 


#  Definitions  for  runnable  scripts,  dataset  network  movement  and  directory  for 

#  various  files.  The  runnable  scripts  must  be  in  agreement  with  contents  of 

#  .runscripts.  Behavior  of  network  for  the  originating  machine  is  set  here. 

#  options  for  SHEPARD_NETWORK :  server,  nfs,  remote 

#  SHEPARD_DIR  is  location  of  application-specific  shepard  scripts 

#  this  file  is  sourced  and  executes  directly  in  environment  of  script 
case  'hostname'  in 

larry! curly)  *  SGI  IRIS  workstation  definitions 
SHEPARD_SCRIPTS='bmin31ss  ampac' 

SHEPARD_NETWORK=server 
SHEPARD_DIR=$HOME/shepard_dir; ; 


moe)  *  SGI  IRIS-240  compute  server  definitions 

SHEPARD_SCRIPTS='bmin31ss  bmin31ms  amber  smapps  ampac  spartan' 
SHEPARD_NETWORK=server 
SHEPARD_DIR-$HOME/shepard_dir; ; 
big)  #  CONVEX  specific  definitions 

SHEPARD_SCRIPTS-'bmin311v  bmin31mv  amber  smapps  ampac  spartan  dspace' 

SHEPARD_NETWORK-server 

SHEPARD_DIR=$HOME/shepard_dir; ; 

esac 

End  Listing  Eleven 


Listing  Twelve 


#  bmin311v  script  for  large  vector  (CONVEX)  version  of  Batchmin  v  3.1 


exe-bmin311v 
inp-.com 
log- . log 
err-. err 

getdata_script-bmin311v . getdata 
putdata_script-bmin311v.putdata 
terminate_script-bmin311v. terminate 
probe_script=bmin311v . probe 


#  the  executable  (in  PATH) 

#  extension  for  standard  input 

#  extension  for  standard  output 

#  extension  for  error  output  (channel  2) 

#  get  the  input  datafiles 

#  put  the  output  back 

#  application-specific  shutdown 

#  conducts  an  application-specific  probe 


Listing  Thirteen 


End  Listing  Twelve 


#  bmin311v. getdata;  get  data  script.  Sourced  in  shepard_exec 

#  shell  args:  2:  dataset,  3: origin,  4:  datadir 

#  datadir  is  dependent  on  network  choice: 

#  server:  host-$HOME/datadir  (host-$HOME  is  prepended) 

#  nfs:  nfs  path  of  data  from  host  to  origin  machines 

#  remote:  origin-$HOME/datadir  (origin-$HOME  is  prepended) 


case  $SHEPARD_NETWORK  in 

server)  cd  $4;;  #  data  stays  put  on  host  machine 

remote)  rsh  $3  cat  $4/$2.dat  >$2.dat  #  move  data.  This  is  a  kluge 

rsh  $3  cat  $4/$2$inp  >$2$inp;;  #  remote  cat  puts  output  on  host 
nfs)  cp  $4/$2.dat  .  #  copy  via  remotely  mounted  nfs  dir 

cp  $4/$2$inp  .  ;; 

esac 


Listing  Fourteen 


End  Listing  Thirteen 


♦  bmin311v.putdata:  put  data  script.  Sourced  in  shepard_exec 

♦  shell  args:  2:  dataset,  3:origin,  4:  datadir 

♦  datadir  is  dependent  on  network  choice: 

#  server:  host-$HOJffi/datadir  (host-$HOME  is  prepended) 

#  nfs:  nfs  path  of  data  from  host  to  origin  machines 

#  remote:  origin- $HOME/datadir  (origin-$HOME  is  prepended) 


♦  all  application-specific  output  files  are  moved,  if  necessary 
case  $ SHEP ARD_NETWORK  in 

server)  cd  $HOME; ;  #  movement  of  files  is  not  necessary 


remote)  rsh  $3  cat  ">"$4/$2 .out  <$2.out 

rsh  $3  cat  ">"$4/$2$log  <$2$log 

rsh  $3  cat  ">"$4/$2$err  <$2$err;; 

nfs)  cp  $2. out  $4/$2.out 
cp  $2$log  $4/$2$log 
cp  $2$err  $4/$2$err;; 


#  another  network  kluge 

#  remote  cat  with  ">"  writes 

#  to  remote.  <  read  local. 


Listing  Fifteen 


End  Listing  Fourteen 


#  sourced  from  shepard 

f  batchmin  terminates  when  it  finds  dataset. stp  in  execution  dir 
case  $SHEPARD_NETWORK  in 

server)  echo  'help  me,  please  help  me'  >  $4/$2.stp;; 
remote  I nfs)  echo  'help  me,  please  help  me'  >  $2. stp;; 

esac 


Listing  Sixteen 


End  Listing  Fifteen 


#  Sourced  from  shepard.  $dset-jobname,  $ddir-directory,  $log-logfile  ext 

#  Script  prints  the  last  30  lines  of  the  log  file  from  the  selected  job 


case  $  SHEP ARD_NETWORK  in 

server)  tail  -30  $ddir/$dset$log; ; 
remote  Infs)  tail  -30  $dset$log;; 

esac 


Listing  Seventeen 


End  Listing  Sixteen 


/*  lockon.c  -  creates  lock  file  from  argv[l]  having  no  privelege 
B.  E.  Bauer,  1990 

*/ 

main  (argc,  argv) 
int  argc; 
char  *argv[]; 

{ 

int  fp,  locked; 


locked  =  0; 
if  (argc  !=  1)  ( 

printf  ("\nuseage:  lockon  lockfile\n") ; 
exit  (0); 

) 

if  ((fp  =  creat (argv[l] ,  0))  <  0)  ++locked; 
else  close (fp); 
return  (locked); 


End  Listings 
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Listing  One  (Text  begins  on  page  24.) 


/*♦♦♦♦♦♦♦♦♦♦  INITIALIZE  INTERRUPTS,  X.25  &  TRANSPORT  LAYER  DATA  ♦♦♦♦♦♦♦♦♦*/ 

/*  AUTHOR:  Michael  T.  Thompson,  Planning  Systems  Inc.  */ 

/*  2-16-89  for  Mitre  Corp.  (W85)  */ 

/*  initialize  interrupt  routines  */ 

♦include  <stdio.h>  /*  Microsoft  "C"  5.1  "  */ 

♦include  <dos.h>  /*  MS-DOS  3.30  */ 

♦include  <ctype.h> 

extern  interrupt  far  clock();  /*  Retix  clock  routine  */ 
extern  interrupt  far  rcvdata();  /*  Interrupt  interface  routine  */ 
extern  buf_type  bfh_head; 

extern  unsigned  char  ‘rcvdat;  /*  Common  Receiver  buffer  pointer  varible  */ 
extern  buf_type  rcvbuf;  /*  Receiver  User  Data  buffer  pointer  */ 

extern  int  icnt,  rbufcnt;  /*  Number  of  pointers  not  used  in  Baddr  Array  */ 

extern  buf_type  Baddr [];  /*  Array  of  buffer  pointers  */ 


int  xbufsiz3256;  /*  Standard  Buffer  size  */ 

int  number_of_buf fers»30;  /*  Total  number  of  transmit  and  receive  buffers  */ 


InitArray [28] 
InitArray [29] 
InitArray [30] 
InitArray [31] 
InitArray [32] 
InitArray [33] 

/* - 

InitArray [34] 
InitArray [35] 
InitArray [36] 
InitArray [37] 
InitArray [38] 
InitArray [39] 
InitArray [40] 
InitArray [41] 
InitArray [42] 
InitArray [43] 
InitArray [44] 
InitArray [45] 
InitArray [46] 
InitArray [47] 
InitArray [48] 
InitArray [49] 


5; 

0x69;  /*  tx  8  bits,  tx  enabled,  tx  CRC  */ 

0; 

0x80;  /*  tx  CRC  gen  */ 

1;  /*  int  on  all  rx  chars  or  special  cond.  */ 

0x12;  /*  enable  tx  interrupts  */ 

- Section  ♦  3 - */ 

15; 

0x41;  /*  tx  underrun  int  enabled  */ 

0; 

0x30;  /*  error  reset  */ 

0; 

0x90;  /*  tx  CRC  gen,  reset  ext/status  int  */ 

0; 

0x90;  /*  twice  */ 

1;  /*  int  on  all  rx  chars  or  special  cond.  */ 

0x12;  /*  enable  tx  interrupts  */ 

9; 

8;  /*  Master  int  enable  */ 

0; 

OxFO;  /*  reset  tx  underrun,  error  reset  */ 

0; 

0x28;  /*  reset  tx  int  pending  */ 


/*  -  Primary  system  Initialization  routine  -  */ 

x25_init () 


for  (iCount  *  0;  iCount  <  50;  iCount++) 

outp(0x239, InitArray [iCount] ) ;  /*  Output  Data  to  SDLC  Chip  */ 


int  i,  tbufsiz,  result; 
tbufsiz  -  xbufsiz  +  30; 


Local  varibles  */ 

Buffer  size  plus  header  data  */ 


_disable{);  /*  disable  interrupts  while  initializing  */ 

init_memory () ;  /*  get  available  memory  from  DOS  */ 

init_bufpool (ibpool, tbufsiz, number_of_buf fers) ;  /*  setup  buffer  pool 

init_timers () ;  /*  initialize  system  timers  */ 

init_rcvbuf () ;  /*  initialize  receive  buffers  */ 

cominzO;  /*  initialize  clock  and  I/O  Interrupt  routines  */ 

_enable();  /*  start  interrupts  backup  */ 


Listing  Two 


End  Listing  One 


/* -  Initialize  Receive  Buffer  Array  - */ 

init_rcvbuf () 

I 

int  i; 

for (i— 0; i<10;i++)  /*  store  pointers  in  buffer  array  */ 

Baddr [i]  *  getbuf (Sbpool, xbufsiz+30) ;  /*  +30  for  X.25  header  info 
rbufcnt  *  9;  /*  0  to  9  -  10  buffers  */ 

rcvbuf  *  Baddr [rbufcnt] ;  /*  preallocate  first  buffer  pointer  * 

Baddr [rbufcnt]  -  (buf_type)  NULL;  /*  clear  the  array  pointer  */ 
rcvdat  *  (char  *) (BuffData (rcvbuf )) ;  /*  point  to  the  user  space  */ 
icnt  *  0;  /*  zero  frame  character  count  * 

} 


*  RCV2.C  —  Interrupt  Handler  routine  for  use  with  the  Sealevel  * 

*  Systems  synchronous  communications  board  that  uses  preallocated  * 

*  buffers  to  Transmitt  and  Receive  X.25  data  frames.  * 

********************************************************************/ 

'  /*  AUTHORS  -  Michael  T.  Thompson,  Planning  Systems  Inc.  and 

*  Ken  Crocker,  The  MITRE  Corporation  5/23/89 
*/ 

♦include  <stdio.h>  /*  Microsoft  "C"  5.1  "  */ 

♦include  <dos.h>  /*  MS-DOS  3.30  */ 

♦include  <ctype.h> 


/*  ♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦  COMINZ.C  ♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦  */ 

/*  Initialize  the  Clock  and  Synchronous  Interrupt  routines  */ 
cominz () 

{ 

unsigned  intnum; 

unsigned  int  val;  /*  local  varibles  */ 


/*  install  MAC  I/O  driver  */ 
intnum  *  Oxlc; 

_dos_setvect (intnum, clock) ; 
Istart  ()  ; 
intnum  *  0x0c; 

_dos_setvect (intnum, rcvdata) ; 

val  *  inp(0x21); 

outp (0x21, (val  &  0xc7)); 


/*  Clock  interrupt  vector  */ 

/*  setup  new  clock  interrupt  routine  */ 
/*  enable  I/O  interrupt  processing  */ 

/*  I/O  interrupt  vector  */ 

/*  setup  tx  &  rx  interrupt  routine  */ 

t*  start  irq  3,  4,  4  5  */ 


/*  ++++++++++++++++  INITIALIZE  SEALEVEL  BOARD  +++++++++++++++++  */ 
istart  () 


unsigned  char  InitArray [50] ; 
int  iCount; 

/* - - - 


InitArray [0] 

-  9; 

InitArray [1] 

3  OxCO; 

InitArray [2] 

3  0; 

InitArray [3] 

3  0x00; 

InitArray [4] 

=  4; 

InitArray [5] 

3  0x20; 

InitArray [6] 

-  3; 

InitArray [7] 

=  OxCO; 

InitArray [8] 

3  5; 

InitArray [9] 

3  0x61; 

InitArray [10] 

3  6; 

InitArray [11] 

3  0; 

InitArray [12] 

3  7; 

InitArray [13] 

3  0x7E; 

InitArray [14] 

=  10; 

InitArray [15] 

=  0x80; 

InitArray [16] 

3  11; 

InitArray [17] 

=  0; 

InitArray [18] 

3  12; 

InitArray [19] 

3  OxFE; 

InitArray [20] 

3  13; 

InitArray [21] 

3  00; 

InitArray [22] 

3  14 

InitArray [23] 
/* - 

=  2; 

InitArray [24]  3  14; 
InitArray [25]  =  3; 
InitArray [26]  =  3; 
InitArray [27]  *  0xD9; 


/*  Allocate  the  size  of  the  Init  Array  */ 

Section  ♦  1 - */ 

/*  force  hardware  reset  */ 

/*  (SDLC)  mode  selected  */ 

/*  rx  8  bits,  sync  char  inhabit  *1 
/*  tx  8  bits  */ 

/*  For  Mono-sync  */ 

/*  sdlc  sync  character  */ 

/*  CRC  set  to  inverted  bit  pattern  */ 

/*  for  dte  clock  from  RTxC  pin  */ 

/*  Low  order  baud  rate  value  */ 

/*  High  order  baud  rate  value  */ 

/*  H  L  */ 

/*  38400  =  00  3E  */ 

/*  19200  -  00  7E  */ 

/*  time  constant:  9600  *  00  FE  */ 

/*  4800  *  01  FE  */ 

/*  gen  enabled,  gen  source  */ 

Section  ♦  2 - */ 

/*  gen  enabled,  gen  source  */ 

/*  rx  8  bits,  hunt  mode,  rx  CRC,  rx  enabled  */ 


/*  RETIX  OSI  SOFTWARE  COMMON  HEADER  FILES  */ 
♦include  "c:\retix\include\bufflib.h" 
♦include  "c : \retix\include\common . h" 

♦include  "c:\retix\include\system.h" 

♦include  "c: \retix\include\lapb.h" 

♦include  "c:\retix\include\address . h" 
♦include  "c:\retix\include\network.h" 
♦include  "c:\retix\include\x25.h" 


extern  buf_type  MDATconO;  /* 
extern  struct  sp_ent  *mac;  /* 
extern  xbufsiz;  /* 
extern  vpmidiO;  /* 


Data  Confirm  routine  */ 

Service  provider  table  */ 

Current  TPDU  buffer  size  */ 
MDATind  Data  Indiction  routine  */ 


unsigned  char  * rcvdat; 
buf_type  rcvbuf; 
buf_type  Baddr [10] ; 
int  icnt,  rbufcnt,  fcnt; 
int  fsize; 
char  * frame; 


/*  Pointer  to  received  user  data  input  buffer  V 
/*  Pointer  to  received  buffer  header  */ 

/*  Array  of  allocated  receive  buffer  pointers  */ 
/*  Receiver  and  Transmitter  counters  */ 

/*  Size  of  Transmit  Frame  */ 

/*  Temporary  pointer  to  Transmit  frame  */ 


************************  RCVDATA. C  *************************** 
Interrupt  Driven  Receiver  and  Transmitter 
RECEIVER:  On  the  receive  side  an  array  of  buffer  pointers  is 
allocated  in  the  x251t.c  initialization  Routine.  The  first 
buffer  is  preassigned  to  the  receive  routine  and  then  that 
buffer  can  be  written  to  by  the  interrupt  routine.  When  the 
last  character  of  the  frame  is  received  the  MDATind  (vpmidi) 
routine  is  called  and  the  new  buffer  is  put  on  the  queue  for 
processing  later.  After  that  we  get  the  address  of  another 
preallocated  buffer  from  the  array  and  setup  the  proper 
pointers . 


void  interrupt  cdecl  rcvdata () 

{ 

unsigned  int  c,  cl,  delay;  /*  local  varibles  */ 

_enable();  /*  enable  interrupts  */ 

/*  check  if  this  is  an  error,  a  receive  or  a  transmitt  interrupt  */ 
outp (0x239, 3) ; 

delay  =  0;  /*  allow  time  for  the  register  to  setup  */ 

if ( ( (c  =  inp(0x239))  S  0x30)  !-  0)  /*  if  not  an  error  continue  */ 

( 

if((c  &  0x20)  !=  0)  /*  if  not  receive  interrupt  continue  */ 

{ 

/********  RECEIVE  DRIVER  *********/ 

/*  we  must  have  receive  data  */ 

rcvdat [icnt++]  =  inp (0x238);  /*  get  character  and  store  it  */ 

outp (0x239, 1) ; 
delay  =  0; 

if  (((cl  »  inp  (0x239))  &  0x80)  !==  0)  /*  check  for  end  of  frame  */ 

( 

if ((cl  &  0x70)  0)  /*  check  for  a  valid  CRC  */ 

(  /*  must  be  OK  */ 
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rcvdat [icnt-2]  *  0; 

Buf fAdjust (rcvbuf , ( (xbufsiz+30) - (icnt-2) ) ) ; 

/*  reajust  buffer  size  for  lapb  */ 
vpmidi (rcvbuf,  mac) ; 

/*  send  MDATind  to  service  user  */ 
icnt  =  0; 

while  (Baddr[ — rbufcnt]  —  (buf_type)  NULL) ; 

/*  Find  an  unused  buffer  pointer  */ 
rcvbuf  =  Baddr [rbufcnt] ; 

/*  got  a  new  receive  buffer  pointer  */ 

Baddr [rbufcnt]  ■  (buf_type)  NULL; 

/*  clear  buffer  pointer  from  array  */ 
rcvdat  =  (char  *) (BuffData (rcvbuf )) ; 

/*  setup  receive  data  pointer  */ 

/*  check  for  a  transmit  interrupt  pending  */ 
if ( (c  &  0x10)  —  0) 

goto  ENDINT;  /*  no  interrupt  so  end  */ 

/*  found  transmit  interrupt  pending  so  send  it  */ 
goto  TXINT; 

} 

/*  frame  is  to  short  so  go  to  error  reset  */ 
goto  ERRRES; 

) 

/*  We  got  a  BAD  CRC  */ 

goto  ERRRES;  /*  goto  error  reset  */ 

) 

/*  not  end  of  frame  so  check  for  a  transmit  interrupt  pending  */ 
if  ( (c  &  0x10)  --  0) 

/*  no  transmit  interrupt  so  end  interrupt  routine  */ 
goto  ENDINT; 


*  Poll  timer  queue  for  any  expired  timers.  Next  check  to  see  if  there  is 

*  any  X.25  traffic  to  be  moved  on  Inbound  or  Outbound  packet  queue.  The 

*  last  process  we  check  is  if  Baddr  Array  is  low  on  preallocated  receive 

*  buffers  that  are  used  by  RCV2.C  Interrupt  Handler. 

/*  AUTHOR  -  Michael  T.  Thompson,  Planning  Systems  Inc.  5/23/89  */ 


int  i;  /*  index  varible  */ 

do_timer_queue () ;  /*  Test  for  expaired  timers  */ 

do_lapb_queue () ;  /*  Check  for  X.25  Traffic  */ 

if (rbufcnt  <  4)  /*  replenish  array  if  less  than  four  pointers  */ 

( 

for (i=0; i<9; i++)  /*  check  all  receive  buffers  */ 

( 

if (Baddr [i]  -■  NULL)  /*  If  Null,  pointer  has  been  used  */ 

(  /*  Get  new  buffer  pointer  &  assign  it  to  the  array  */ 

Baddr [i]  *  getbuf (sbpool, xbufsiz+30) ; 
rbufcnt++;  /*  Increment  buffer  count  */ 


END  OF  P OLD AT  */ 


End  Listings 


TXINT: /************************  TRANSMIT  DRIVER  *****************************/ 
/*  After  we  have  determined  that  we  have  received  a  transmit  interrupt*/ 
/*  we  check  to  see  if  we  are  at  end  of  frame  by  checking  its  size.  If  */ 
/*  not,  then  we  send  out  character  pointed  at  by  frame  pointer  and  */ 

/*  then  end  the  interrupt.  If  we  are  at  end  of  frame,  we  clear  frame  */ 
/*  counter  and  reset  the  transmit  interrupt  flag.  */ 

/**********************************************************************/ 


if(fsize  >  0)  /*  are  at  the  end  of  the  frame  ?  */ 


fsize — ; 

outp(0x238, frame[fcnt++] ) ; 
goto  ENDINT; 


/*  decrement  frame  size  */ 

/*  NO  -  send  character  */ 

/*  end  the  interrupt  routine  */ 


outp(0x239,0) ;  /*  must  be  at  the  end  of  the  frame  */ 

fcnt  *  0;  /*  clear  the  frame  count  */ 

outp (0x239, 0x28) ;  /*  reset  transmit  interrupts  */ 
goto  ENDINT;  /*  end  the  interrupt  routine  */ 


ERRRES: 

outp (0x239,0); 
icnt  -  0; 
outp (0x239, 0x30) ; 

ENDINT: 

outp (0x20, 0x20) ; 
return; 


/*  error  reset  */ 

/*  reuse  the  same  buffer  */ 


/*  End  of  interrupt  report  */ 


/********************************  MDATreqO  ********************************* 

*  MDATreq:  Transmit  LAPB  output  requests.  When  a  buffer  is  ready  to  be 

*  transmitted,  that  buffer  is  sent  to  MDATreq  routine  where  we  check  to  see 

*  if  data  is  currently  being  transmitted.  If  it  is,  we  return  to  calling 

*  routine  and  try  again  later.  If  no  data  is  being  transmitted,  we  check 

*  transmit  buffer  register  of  synchronous  controller  chip  to  see  if  it  is 

*  empty  so  that  when  it  is,  we  can  send  out  first  character  of  frame.  When 

*  we  can  send  out  a  character  the  pointers  and  counters  are  setup  and 

*  first  character  is  sent.  After  first  character  is  sent,  buffer  is  removed- 

*  from  outbound  queue  and  a  second  character  is  sent  to  help  with  system 

*  timing.  At  this  point,  interrupt  driver  will  take  over  and  continue  to 

*  send  remaining  data  until  last  byte  of  frame  is  delivered  along  with 

*  frames  CRC. 


void  MDATreq  (msdu) 
buf_type  msdu; 


/*  Transmitt  buffer  pointer  */ 


int  rval,  delay;  /*  local  varibles  */ 

if (fsize  !=  0)  /*  if  we  are  still  transmitting  a  frame  return  */ 

return; 

outp (0x239,0) ; 
fcnt=0; 

while  (((rval  =  inp (0x239))  &  4)  ==  0);  /*  test  for  buffer  empty  */ 

frame  =  (char  *) (BuffData (msdu) ) ;  /*  get  pointer  to  user  buffer  */ 

fsize  *  (Buf fSize (msdu) -1) ;  /*  get  size  minus  first  char  */ 

QRemove (msdu) ;  /*  remove  buffer  from  queue  */ 

delay-0; 

outp(0x238,frame[fcnt++]);  /*  send  first  byte  of  frame  */ 

msdu- (buf_type)MDATcon (msdu, mac) ;  /*  and  confirm  the  buffer  */ 

while  (((rval  =  inp(0x239))  S  4)  -=  0);  /*  test  for  buffer  empty  */ 


fsize — ; 

outp(0x238, frame [fcnt++] ) ; 

outp (0x239,  0)  ; 
delay  -  0; 
outp (0x239, OxCO) ; 


/*  decrement  frame  size  */ 

/*  send  second  byte  of  frame  */ 


/*  process  end  of  frame  CRC  */ 


End  Listing  Two 
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Listing  One  (Text  begins  on  page  38.) 

/*  Cheap  Com  by  Don  Gaspar  */ 

/*  Requires  MPW  C  and  the  Comm  Toolbox.  The  complete  program,  including  */ 

/*  the  resource  file,  header  file,  and  make,  are  available  electronically.  */ 
/*  These  are  the  standard  Mac  includes  for  all  managers  */ 


♦include  <values.h> 
♦include  <types.h> 
♦include  <Resources.h> 
♦include  <QuickDraw.h> 
♦include  <fonts.h> 
♦include  <events.h> 
♦include  <windows.h> 
♦include  <menus.h> 
♦include  <textedit.h> 
♦include  <dialogs.h> 
♦include  <Controls.h> 
♦include  <desk.h> 
♦include  <toolutils.h> 
♦include  <memory.h> 
♦include  <Lists.h> 
♦include  <SegLoad.h> 
♦include  <Files.h> 
♦include  <Packages.h> 
♦include  <OSEvents.h> 
♦include  <OSUtils.h> 
♦include  <DiskInit.h> 
♦include  <Traps.h> 
♦include  <String.h> 
♦include  <Strings.h> 


♦include  <CRMIntf.h> 
♦include  <CMIntf.h> 
♦include  <FTIntf.h> 
♦include  <TMIntf.h> 
♦include  <CTBUtils.h> 


//  Communications  Resource  Manager  stuff 
//  Connection  Manager  stuff 
//  File  Transfer  Manager  stuff 
//  Terminal  Manager  stuff 
//  Communications  Toolbox  Utility  stuff 


♦include  "CommTypes.h"  //  communications  types,  etc. 

♦include  "CheapComm.h"  //  constants,  forward  declarations,  etc. 


/*  global  variables  */ 

Boolean  gHasWaitNextEvent; 

Boolean  glnBackground; 

Boolean  gStopped; 


//  does  user's  machine  have  WaitNextEvent? 
//  are  we  in  the  background? 

//  are  we  stopped? 


TermHandle  gTerm; 
ConnHandle  gConn; 
FTHandle  gFT; 


//  handle  to  terminal  record 
//  handle  to  connection  record 
//  handle  to  file  transfer  record 


Ptr 

long 

Boolean 

Boolean 


gBuffer; 

gFTSearchRefNum; 

gStartFT; 

gWasFT; 


//  global  connection  buffer 

//  are  we  doing  a  file  transfer? 

//  was  a  file  transfer  in  progress? 


short  gDummy; 

Handle  gCache;  //  buffer  for  last  terminal  line  received/sent 

TEHandle  gTE;  //  buffer  for  terminal  emulator 

ControlHandle  gScrollHHandle,  gScrollVHandle; 


♦pragma  segment  Main 

/*  Sends  data  out  via  choosen  connection  */ 

pascal  long  TermSendProc (thePtr,  theSize,  refCon, 

Ptr  thePtr; 

long  theSize; 

long  refCon; 

short  flags; 

{ 


flags) 


CMErr  theErr; 

long  termSendProc  =  OL; 

if  (gConn  !~  nil)  { 

theErr  =  CMWrite (gConn, thePtr, StheSize, cmData, false, nil, 0, flags) ; 
if  (theErr  ==  noErr) 

termSendProc  =  theSize; 


I 

return (termSendProc) ; 


) 

♦pragma  segment  Main 

/*  Gets  the  data  from  the  connection  tool  and  sends  it  to  the  terminal  tool  */ 
pascal  void  TermRecvProc () 

{ 

CMErr  theErr; 

CMStatFlags  status; 

CMBufferSizes  sizes; 

short  flags; 

if  (gConn  !=  nil  &&  gTerm  !=  nil)  ( 

theErr  =  CMStatus (gConn,  sizes,  &status) ; 
if  (theErr  ==  noErr)  { 

if  ((status  &  (cmStatusOpen+cmStatusDataAvail) )  !=  0  &&  sizes [cmDataln]  !=  0)  { 
if  (sizes [cmDataln]  >  kBufferSize) 

sizes [cmDataln]  =kBufferSize; 

theErr=CMRe ad (gConn,  gBuffer,  &sizes [cmDataln] ,  cmData,  false,  nil,  0,  sflags); 
if  (theErr  ==  noErr)  //  give  it  to  terminal  emulation  buffer 

sizes [cmDataln]  =  TMStream (gTerm,  gBuffer,  sizes [cmDataln] ,  flags); 

} 

} 

else 

;  //  Connection  Manager  will  handle  this 

) 


) 


♦pragma  segment  Main 

/*  Gets  the  connection  environments  for  FT  or  Term  tool  */ 
pascal  OSErr  ToolGetConnEnvirons (refCon,  theEnvirons) 

long  refCon; 

ConnEnvironRec  *theEnvirons; 

{ 

OSErr  toolGetConnEnvirons  =  envNotPresent; 
if (gConn  ! =  nil) 

toolGetConnEnvirons  =  CMGetConnEnvirons (gConn,  theEnvirons) ; 
return (toolGetConnEnvirons) ; 

} 
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♦pragma  segment  Main 

/*  Sends  data  during  a  file  transfer  */ 

pascal  long  FTSendProc {thePtr,  theSize,  refCon,  channel,  flags) 


Ptr 
long 
long 

CMChannel 

short 


thePtr; 

theSize; 

refCon; 

channel; 

flags; 


OL; 


CMErr  theErr; 
long  ftSendProc  ; 

if  (gConn  !■  nil)  { 

theErr  *  CMWrite (gConn,  thePtr, &  theSize,  channel,  false,  nil,  0,  flags); 
if (theErr  "  noErr) 

ftSendProc  *  theSize; 

} 

return ( ftSendProc) ; 

} 

♦pragma  segment  Main 

/*  Gets  the  data  during  a  data  transfer  */ 

pascal  long  FTReceiveProc (thePtr,  theSize,  refCon,  channel,  flags) 


Ptr 
long 
long 

CMChannel 

short 


thePtr; 

theSize; 

refCon; 

channel; 

‘flags; 


-  OL; 


CMErr  theErr; 

long  ftReceiveProc  ! 

if  (gConn  !-  nil)  { 

theErr  -  CMRead(gConn,  thePtr,  stheSize,  channel,  false,  nil,  0,  flags); 
if  (theErr  ■«  noErr) 

ftReceiveProc  ■  theSize; 

) 

return (ftReceiveProc) ; 

) 

♦pragma  segment  Main 

/*  Sets  file  transfer  flag  if  an  autoreceive  string  was  found  */ 
pascal  void  AutoRecCallBack (theConn,  data,  refNum) 

ConnHandle  theConn; 

Ptr  data; 

long  refNum; 


{ 


if  (gFTSearchRefNum  «  refNum) 
gStartFT  -  true; 


♦pragma  segment  Main 

/*  Checks  if  file  transfer  has  autoreceive  string;  adds  a  search  to  find  it  */ 
void  AddFTSearch() 

{ 

Str255  tempStr; 

if  (gFT  !-  nil  &&  gConn  !-  nil)  { 

//tempStr  -  (*gFT) ->autoRec; 
if  ( (*gFT)->autoRec[0)  !«  0)  ( 

gFTSearchRefNum  -  CMAddSearch (gConn, (*gFT) ->autoRec,  cmSearchSevenBit, 
(ProcPtr) AutoRecCallBack) ; 
if  (gFTSearchRefNum  -*=  -1)  { 

AlertUser( "Couldn't  add  stream  search\0",  false); 
gFTSearchRefNum  =  0; 


) 


) 


♦pragma  segment  Main 

/*  Initiates  a  file  transfer  send  from  menu  command  */ 
void  DoSendO 


SFReply 
Point 
short 

SFTypeList 
FTErr 
if (gFT  ! ■  nil) 


theReply; 

where; 

numTypes; 

typeList; 

anyErr; 

{ 


SetPt (&where, 100, 100) ; 


if  (( (“gFT)  .attributes  &  ftTextOnly)  !=  0)  { 
typeList [0]  =  'TEXT'; 
numTypes  =  1; 

) 

else 


numTypes  *  -1; 

sfgetfile (4where,  "File  to  send",  nil,  numTypes,  typeList,  nil,  &theReply) ; 
if (theReply. good)  ( 

anyErr  =  FTStart (gFT,  ftTransmitting,  StheReply) ; 
if (anyErr  !=  noErr) 

;  //  file  transfer  tool  will  alert  user 


} 

) 

) 

♦pragma  segment  Main 

/*  Initiates  a  file  transfer  receive  from  menu  */ 


void  DoReceiveO 

{ 

SFReply  theReply; 
OSErr  anyErr; 


if  (gFT  !=  nil)  { 

theReply. vRefNum  =  0; 

//theReply .  fName  =  "; 
gStartFT  *=  false; 
if  (gConn  !=  nil  )  { 

if  ( (**gFT) .autoRec  !-  "\0n  &&  gFTSearchRefNum  !-  0)  { 
CMRemove Search (gConn,  gFTSearchRefNum) ; 
gFTSearchRefNum  =  0; 

} 


anyErr  =»  FTStart  (gFT,  ftReceiving,  StheReply)  ; 
if (anyErr  !=  noErr) 

;  //  file  transfer  tool  will  alert  user 

(continued  on  page  96) 
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Listing  One  (Listing  continued,  text  begins  on  page  38.) 


♦pragma  segment  Main 
/*  Initiates  a  connection  */ 
void  OpenConnectionO 
{ 


CMErr  theErr; 

CMBufferSizes  sizes; 

CMStatFlags  status; 

if(gConn  !=  nil)  { 

theErr  =  CMStatus (gConn,  sizes,  fistatus); 
if (theErr  ==  noErr) 

if ((status  &  (cmStatusOpen  +  cmStatusOpening) )  ■■  0) 
theErr  =CMOpen (gConn,  false,  nil,  -1); 
if  (theErr  !-  noErr) 

;  //  connection  tool  will  tell  user  if  there's  an  errror 

} 

} 

♦pragma  segment  Main 
/*  Cancels  connection  */ 
void  CloseConnection () 

{ 


CMErr  theErr; 

CMBufferSizes  sizes; 

CMStatFlags  status; 

if  (gConn  !=  nil)  ( 

theErr  =  CMStatus (gConn,  sizes,  fistatus); 
if  (theErr  =*=  noErr) 

if  ((status  &  (cmStatusOpen+cmStatusOpening) )  !-  0) 

theErr  =  CMClose (gConn,  false,  nil  ,0,  true); 
if  (theErr  !=  noErr) 

;  //  connection  tool  will  handle  error 


) 

♦pragma  segment  Main 

/*  tries  to  get  default  tool  proc  ID,  otherwise  gets  first  one  it  can  find  */ 
short  FindToolID (toolClass) 

OSType  toolClass; 

I 


Str255  toolName; 

OSErr  anyErr; 

short  procID  -  -1; 

if  (toolClass  —  classTM)  ( 

StuffHex  (fitoolName,  JcDefaultTermTool)  ; 
procID  -  TMGetProcID (toolName) ; 
if (procID  *=  -1)  { 

anyErr  =  CRMGetlndToolName (toolClass, 1,  toolName); 
if  (anyErr  ==  noErr) 

procID  =  TMGetProcID (toolName) ; 

1 

} 

else  if  (toolClass  —  classCM)  ( 

StuffHex (fitoolName, kDefaultConnTool) ; 
procID  =  CMGetProcID (toolName) ; 
if (procID  —  -1)  { 

anyErr  *  CRMGetlndToolName (toolClass, 1,  toolName); 
if  (anyErr  ==  noErr) 

procID  *  CMGetProcID (toolName) ; 

} 


} 

else  if  (toolClass  —  classFT)  ( 

StuffHex (fitoolName, kDefaultFTTool) ; 
procID  *  FTGetProcID (toolName) ; 
if (procID  ==  -1)  { 

anyErr  *  CRMGetlndToolName (toolClass, 1,  toolName); 
if  (anyErr  ==*  noErr) 

procID  ■  FTGetProcID (toolName) ; 

) 


} 

return (procID) ; 

} 

♦pragma  segment  Main 

/*  this  is  click  loop  for  terminal  emulation  to  track  */ 
pascal  Boolean  clikLoop (ref con) 
long  ref con; 

{ 

return (true) ; 

} 

♦pragma  segment  Initialize 

/*  this  function  sets  up  CommToolbox  for  what  we  need; 

it  should  resemble  most  other  Macinotosh  toolbox  calls  */ 
void  InitCommTBO 
{ 

(void) InitCTBUtilitiesO ;  //  Comm  Toolbox  Utilities 

(void)  InitCRMO ;  //  Communications  Resource  Manager 

//  initialize  the  Terminal  Manager 

if  (InitTMO  ==  tmNoTools)  //  Did  we  fail? 

AlertUser ("No  terminal  tools  found\0",  true); 

//  Initialize  the  Connection  Manager 

if  (InitCMO  ==  cmNoTools)  //  failure? 

AlertUser ("No  connection  tools  found\0",  true); 

//  Initialize  the  File  Transfer  Manager 

if(InitFT()  ==  ftNoTools)  //  failure? 

AlertUser ("No  file  transfer  tools  found\0", false) ; 
gTerm  =  nil;  //  initialize  our  globals 

gConn  =  nil; 
gFT  *  nil; 
gCache  *  nil; 
gFTSearchRefNum  =  0; 

♦pragma  segment  Main 

/*  this  will  cache  all  data  coming  in  through  serial  port  */ 
pascal  long  cacheProc (refCon,  theTermData) 
long  refCon; 

TermDataBlock  ‘theTermData; 

{ 

long  sizeCached; 

TermEnvironRec  theEnvirons; 
theEnvirons. version  =  curTermEnvRecVers; 
theEnvirons. termType  =  tmText Terminal; 


(continued  on  page  98) 
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Listing  One  (Listing  continued,  text  begins  on  page  38.) 

(void) TMGetTermEnvirons (gTerm,  stheEnvirons) ; 
if  (theTermData->theData  ==  nil) 
return (-1) ; 

if(gCache  !*=  nil)  //  is  it  valid? 

DisposHandle (gCache) ; 

HLock ( (Handle) theTermData->theData) ; 
gCache  =  theTermData->theData; 
i f ( HandToHand ( &  gCache ) )  ( 

DisposHandle (gCache) ; 
sizeCached  -  -1; 

) 

else  { 

sizeCached  *  GetHandleSize (gCache) ; 

) 

HUnlock ( (Handle) theTermData->theData) ; 

if (theTermData->flags  ■■  tmTextTerminal  &&  sizeCached  >0L)  ( 
/♦HandAndHand (gCache,  (**gTE) .hText); 

(**gTE) .teLength  +=  80; 

(**gTE) .nLines  +■  1;*/ 

( (Ptr) * gCache, 80L, gTE) ; 

// (**gTE) .viewRect. top  —  (**gTE) . lineHeight; 

//(**gTE) .destRect .top  —  (**gTE) .lineHeight; 

/ /TECalText (gTE) ; 

//TEScroll (0, - (**gTE) . lineHeight, gTE) ; 

) 

return (tmNoErr) ; 

) 

♦pragma  segment  Main 

/*  gets  window  and  create  session  */ 

Boolean  DoNewWindow ( ) 

{ 

WindowPtr  window; 

Rect  theRect; 

short  procID; 

CMBufferSizes  sizes; 

Rect  tempRect; 

short  index; 

Rect  r; 

window  =  GetNewWindow(rWindow,  nil,  (WindowPtr) -1) ; 

SetPort (window) ; 

/*  no  cache,  breakproc,  or  clikloop  */ 

gTerm  =  TMNew (&theRect, itheRect,  tmSaveBeforeClear  +  tmAutoScroll, 

procID,  window,  (ProcPtr) TermSendProc, (ProcPtr)cacheProc,nil, 
/* (ProcPtr) clikLoop*/nil,  (ProcPtr) ToolGetConnEnvirons, 0, 0) ; 
SetRect ( &  r , theRect . lef t , -theRect . bottom, theRect . right , theRect . top) ; 
gTE  *  TENew (&r, Sr) ; 

(**gTE) .txSize  =  9; 

(**gTE) .txFont  =  monaco; 

(**gTE) .viewRect. bottom  *  (( (**gTE) .viewRect .bottom  -  (**gTE) .viewRect .top) / 
(**gTE) .lineHeight) * (**gTE) .lineHeight  +  (**gTE).viewRect.top; 

TEAutoView (true, gTE) ; 

/*  custom  configure  with  personal  settings  —  store  as  a  file  later  */ 

(void) TMSetConfig (gTerm,  "Scroll  Smooth\0") ; 


if  (gTerm  =*=  nil) 

AlertUser ("Can' t  create  a  terminal  tool\0",  true); 

HLock ( (Handle) gTerm) ; 

/*  connection  tool  */ 
procID  =  FindToolID (classCM) ; 
if (procID  ==  -1) 

AlertUser ("No  connection  tools  found/0",  true); 
sizes [cmDataln]  =  kBufferSize*10;  //  data  channel;  large  incoming  buffer 
sizes [cmDataOut]  =  kBufferSize; 
sizes [cmCntl In]  =  0; 
sizes [cmCntlOut]  =  0; 
sizes [cmAttnln]  =  0; 
sizes [cmAttnOut]  =  0; 

gConn  *  CMNew (procID,  cmData,  sizes,  0,0); 

(void) CMSetConfig(gConn, "Baud  9600,  Bits  7,  StopBits  1,  Parity  Even, 

ModemType  Other,  PhoneNumber  \0429, 1800-346-0145\042\0") ; 
if (gConn  ==  nil) 

AlertUser ("Can' t  create  a  connection  tool/0",  true); 

HLock ( (Handle) gConn) ; 

/*  allocate  space  for  reads/writes  using  number  returned  by  connection  tool  */ 
gBuffer  =  NewPtrClear (sizes [cmDataln] ) ; 
if (MemError ()  !=  noErr) 

AlertUser ("Out  of  memory\0",  true); 

/*  file  transfer  tool  */ 
procID  =  FindToolID (classFT) ; 
if (procID  «  -1) 

AlertUser ("No  file  transfer  tools  found\0",  false); 

/*  no  read/write  proc  —  tool  has  its  own  */ 

gFT  =  FTNew (procID,  0  , (ProcPtr) FTSendProc,  (ProcPtr) FTReceiveProc, 
nil,  nil,  (ProcPtr) ToolGetConnEnvirons,  window,  0L,0L); 
if (gFT  ~=  nil) 

AlertUser ("Can' t  create  a  file  transfer  tool\0",  true); 

HLock ( (Handle) gFT) ; 
gWasFT  *=  false; 
gStartFT  =  false; 
gFTSearchRefNum  =  0; 

AddFTSearchO ; 
return (true) ; 

I 

♦pragma  segment  Main 
/*  Updates  the  window  */ 
void  DoUpdate (window) 

WindowPtr  window; 

l 

RgnHandle  savedClip; 

Graf Ptr  savedPort; 


if  ( IsAppWindow (window) )  { 

GetPort (SsavedPort) ; 

SetPort (window) ; 

/*  clip  to  the  window  content  */ 
savedClip  *  NewRgnO; 

GetClip (savedClip) ; 

ClipRect (&window->portRect) ; 
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DrawControls (window) ; 

DrawGrowIcon (window) ; 

BeginUpdate (window) ; 

if (gTerm  !-  nil  ) 

TMUpdate (gTerm,  window->visRgn) ; 
if (gTE  !*  nil) 

TEUpdate (4window->portRect,gTE) ; 

EndUpdate (window) ; 

SetClip (savedClip) ; 

DisposeRgn (savedClip) ; 

SetPort (savedPort) ; 

) 

} 

♦pragma  segment  Main 
/*  suspends/resumes  terminal  window  */ 
void  DoResume (becomingActive) 

Boolean  becomingActive; 

{ 

WindowPtr  theWindow; 

GrafPtr  savedPort; 

GetPort (fcsavedPort)  ; 
theWindow  -  FrontWindow {) ; 
while  (theWindow!-  nil)  { 

if  (IsAppWindow (theWindow) )  { 

SetPort (theWindow) ; 
if (gTerm  !-  nil) 

TMResume (gTerm,  becomingActive); 
if(gConn  !-  nil) 

CMResume (gConn,  becomingActive) ; 
if (gFT  !-  nil) 

FTResume (gFT,  becomingActive); 

theWindow-  (WindowPtr) (( (WindowPeek)  theWindow) ->nextWindow) ; 

) 

SetPort (savedPort) ; 

) 

♦pragma  segment  Main 

/*  (de) activates  window  */ 

void  DoActivate (window,  becomingActive) 

WindowPtr  window; 

Boolean  becomingActive; 

if  (IsAppWindow (window) )  {  //  does  window  belong  to  us? 

SetPort (window) ;  //  set  current  port 

if (gConn  !-  nil)  //  do  we  have  a  valid  connection? 

CMActivate (gConn,  becomingActive);//  activate  it 
if (gTerm  !-  nil)  //  do  we  have  a  terminal? 

TMActivate (gTerm,  becomingActive);  //  activate  it 
if (gFT  !-  nil)  //  do  we  have  a  valid  file  transfer? 

FTActivate (gFT,  becomingActive);//  activate  it 


} 

♦pragma  segment  Main 

/*  tries  to  pass  event  to  a  tool  if  window  is  a  tool  window; 

handles  event  if  appropriate  */ 

Boolean  DoToolEvent (event,  window) 

EventRecord  *event; 

WindowPtr  window; 


{ 

Boolean  doToolEvent; 

if  (window  !-  nil  &&  ! IsAppWindow (window) )  {  //  is  window  valid? 
doToolEvent  -  true; 

/*  copies  of  commtb  record  must  be  in  refCon  field  of 
window  for  changing  the  settings  */ 

if (gFT  !-  nil  &&  gFT  --  (FTHandle) GetWRefCon (window) ) 

FTEvent (gFT, event ) ;  //  handle  file  transfer  manager  event 
else  if (gConn  !-  nil  &&  gConn  —  (ConnHandle) GetWRefCon (window) ) 
CMEvent (gConn, event) ;  //  handle  connection  manager  event 
else  if (gTerm  !-  nil  &&  gTerm  --  (TermHandle) GetWRefCon (window) ) 
TMEvent (gTerm, event);  //  handle  terminal  manager  event 

else 

doToolEvent  -  false; 


} 

else 

doToolEvent  -  false; 
return (doToolEvent) ; 

) 

♦pragma  segment  Main 

/*  idles  all  communications  tools;  this  was  taken  from  the  Surfer  pascal 
example  provided  from  Apple  —  you  can  get  it  from  APDA.*/ 
void  DoIdleO 
{ 

WindowPtr  theWindow; 

Boolean  doFT,  doTM; 

GrafPtr  savedPort; 

GetPort (4 savedPort) ; 
theWindow  =  FrontWindow () ; 
while  (theWindow  !-  nil)  { 

if  (IsAppWindow (theWindow) )  { 

SetPort (theWindow) ; 

//TEIdle(gTE) ; 
if (gConn  !-  nil) 

CMIdle (gConn) ; 
doFT  -  false; 
doTM  =  true; 
if  (gFT  !-  nil  )  ( 

if  (( (**gFT) .flags  &  ftlsFTMode)  !=  0)  { 
doFT  -  true; 
gWasFT  -  true; 

if (( (**gFT) .attributes  &  ftSameCircuit) 
doTM  -  false; 


} 

else  { 

if  (gWasFT)  { 

gWasFT  -  false; 
if (( (**gFT) .flags  &  ftSucc) 


!=  0) 


-=  0) 


AddFTSearch ( ) ; 

) 

if (gStartFT) 

DoReceive () ; 


} 

if  (doFT) 

FTExec (gFT) ; 

)  /*  if  gFT  ! -  nil  */ 
if (gTerm  !-  nil)  { 
if  (doTM)  ( 

TMIdle (gTerm) ; 

TermRecvProc () ; 

) 

}/*  gTerm  !-  nil  */ 

} 

theWindow  =  (WindowPtr) ( ( (WindowPeek) theWindow) ->nextWindow) ; 

} 

SetPort (savedPort) ; 


End  Listing 
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Listing  One  (Text  begins  on  page  54.) 


*  SS.C  —  Sample  Sorted  Sequential  Suffix  Search  (c)  1989  Walter  Williams 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  <malloc.h> 

♦ifndef  TRUE 
♦define  TRUE  1 

♦define  FALSE  0 

♦endif 


typedef  struct  snode_S 

( 

struct  snode_S  *prev; 
struct  snode_S  *next; 
unsigned  int  pfxlen; 
char  key [11; 

}  snode  T,  *snode  TP; 


/*  Address  of  previous  node  in  list 
/*  Address  of  next  node  in  list 
/*  Number  of  characters  in  prefix 
/*  First  character  of  key 


/************************  Function  Prototypes  ************ 
snode_TP  Search (char  *,  snode_TP,  int  *,  unsigned  int  *); 
snode_TP  Insert (char  *,  snode_TP) ; 
snode_TP  Delete (char  *,  snode_TP) ; 


/*  SEARCH ()  —  Search  the  list  for  a  pattern  key.  */ 

/*  'pattern'  is  a  null  terminated  string  containing  the  key  which  is  */ 

/*  the  object  of  the  search.  */ 

/*  'list'  is  the  address  of  a  dummy  node  which  contains  head  and  tail  */ 

/*  pointers  for  a  linked  list.  */ 

/*  'exact'  is  the  address  of  a  flag  which  is  TRUE  for  an  exact  match  */ 

/*  and  FALSE  if  the  pattern  is  not  found.  */ 

/*  'match'  is  the  address  of  an  unsigned  int  to  use  as  a  match  counter  */ 

/*  The  return  value  is  a  pointer  to  the  structure  containing  the  */ 

/*  matching  key,  or  the  next  largest  node  if  the  pattern  was  not  found.  */ 

/* - - - */ 

snode_TP  Search (char  ‘pattern,  snode_TP  list,  int  ‘exact,  unsigned  int  ‘match) 


snode_TP  cnode;  /*  Pointer  to  current  node  * 

char  7sp;  /*  Suffix  pointer  * 

int  tm-  0;  /*  Temp  storage  for  match  count  * 

/*“/ 

‘exact-  FALSE;  /*  Assume  unsuccessful  se 

‘match-  tm; 

for  (cnode-  list->next;  cnode  !-  list;  cnode-  cnode->next) 


/*  Assume  unsuccessful  search 


/*  Compare  match  count  to  prefix  count  */ 

if  (tm  <  cnode->pfxlen) 
continue; 

else  if  (tm  >  cnode->pfxlen) 


break; 

else  /*  (tm  ==  cnode->pfxcnt)  */ 

< 

/*  Compare  the  actual  key  suffix,  maintain  match  count  */ 
sp=  cnode->key  +  cnode->pfxlen; 
while  (‘pattern  —  *sp  &&  *sp  &&  ‘pattern) 

{ 

++sp; 

++pattern; 

++tm; 

) 

/*  Done  if  suffix  greater  than  or  equal  to  pattern  */ 
if  (‘pattern  <  *sp  ) 

{ 

break; 

) 

else  if  (‘pattern  ==  '\0'  &&  *sp  —  '\0') 

( 

‘match-  tm; 

‘exact-  TRUE; 
break; 


‘match-  tm; 
} 

return  (cnode) ; 


/*—  INSERT ()  Adds  an  item  to  the  list.  — */ 
snode_TP  Insert (char  ‘pattern,  snode_TP  list) 


snode_TP  cnode;  /*  Node  we  are  inserting 

snode_TP  nnode;  /*  Next  node  after  cnode 

char  *sp;  /*  Pointer  to  suffix 

unsigned  int  match; 
int  exact; 

/***/ 

/*  Find  spot  where  we  insert  the  node 
nnode  -  Search (pattern,  list,  fiexact,  imatch) ; 
if  (exact  —  TRUE)  /*  Skip  to  first  non-matching  key 

{ 

nnode  =  nnode->next; 

while  (nnode  !-  list  &&  nnode->key [nnode->pfxlen]  —  '\0') 
nnode  =  nnode->next; 

) 

/*  Allocate  space  for  the  new  node 
cnode  =  (snode_TP)  malloc (sizeof (snode_T)  +  strlen (pattern) ) ; 
cnode->pfxlen  =  match; 
strcpy (cnode->key,  pattern); 

/*  Link  it  into  the  list  ahead  of  nnode 

cnode->next  -  nnode; 
cnode->prev  =  nnode->prev; 
nnode->prev->next  =  cnode; 
nnode->prev  =  cnode; 

/*  Update  pfxlen  in  following  node 
sp  =  nnode->key  +  nnode->pfxlen; 
if  (cnode->pfxlen  —  nnode->pfxlen) 

{  /*  Compare  the  two  suffixes 

nnode->pfxlen-  0; 

while  ( ‘sp  --  ‘pattern  &&  ‘pattern  &&  *sp) 

++sp; 

++pattern; 

++nnode->pfxlen; 


return  (cnode) ; 

I 

/* —  DELETE ()  Deletes  an  item  from  the  list 
snode_TP  Delete (char  ‘pattern,  snode  TP  list) 
{ 

snode_TP  cnode;  /*  Node  we  are  de 

snode_TP  nnode;  /*  Next  node  afte 

int  exact;  /*  Flag  set  if  ex 

unsigned  int  match;  /*  No.  of  charact 

/***/ 


/*  Node  we  are  deleting 

/*  Next  node  after  cnode 

/*  Flag  set  if  exact  match 

/*  No.  of  characters  matched  in  pattern 


/*  Find  the  node  we  want  to  delete 
cnode  =  Search (pattern,  list,  &exact,  Smatch) ; 
if  (exact  —  FALSE)  /*  Abort  if  not  an  exact  match 


printf("%s  not  found\n" 
nnode-  NULL; 

) 


(  /*  Remove  it  from  the  list 

cnode->next->prev  -  cnode->prev; 
cnode->prev->next  -  cnode->next; 
nnode  =  cnode->next;/‘  Save  for  return  value 

/‘  Update  suffix  in  following  node 
if  (cnode->pfxlen  <  cnode->next->pfxlen) 
cnode->next->pfxlen  -  cnode->pfxlen; 

/*  Release  deleted  node 
free ((char  *)  cnode); 
printf("%s  deleted\n",  pattern); 

) 

return  (nnode) ; 

) 


End  Listing 
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Listing  One  (Text  begins  on  page  64.) 

//  Write  edited  text  to  the  file 

strcpy (In, ‘line  buffer); 

//  Line  Editor  example  using  Zinc  Interface  Library  —  (c)  Gary  Entsminger 

fwrite (In, 64, 1, textfile) ; 

♦include  <ui  win.hpp> 

//  Close  file 

♦include  <stdio.h> 

fclose (textfile) ; 

♦include  <string.h> 

♦include  <stdlib.h> 

)  //  end  destructor. 

//  Derive  a  new  class  which  adds  File  I/O  to  a  window. 

main  () 

class  Line  editor:  public  UIW  WINDOW 

{ 

{ 

//  Construct  the  display,  trying  for  graphics  first. 

public  : 

UI  DISPLAY  ‘display  =  new  UI  DOS  BGI  DISPLAY; 

Line  editor ();  //  Constructor 

if  ( !display->installed) 

"Line  editor  0;  //  Destructor 

( 

char  *  line  buffer [64]; 

delete  display; 

};  //  end  class  Line_editor  declaration 

display  =  new  UI  DOS  TEXT  DISPLAY; 

) 

//  Define  Line  editor's  constructor 

Line  editor  ::  Line  editor ()  :  UIW  WINDOW (2, 2, 70, 5, 

//  Construct  the  event  manager  and  add  three  devices  to  it. 

WOF  NO  FLAGS,  WOAF  NO  FLAGS) 

UI  EVENT  MANAGER  ‘eventManager  = 

{ 

new  UI  EVENT  MANAGER (100,  display); 

FILE  ‘textfile;  //  pointer  to  file 

char  In [64];  //  local  char  array  to  hold  lines  read  from  file 

‘eventManager 

+  new  UI  BIOS  KEYBOARD 

//  Open  file 

+  new  UI  MS  MOUSE 

if  ((textfile  =  f open ("mk. bat",  "r"))  ==  NULL) 

+  new  UI_CURSOR; 

printf ("Error  opening  text  file\n  Aborting."); 

//  Construct  the  window  manager. 

exit (0) ; 

UI  WINDOW  MANAGER  ‘windowManager  = 

) 

new  UI  WINDOW  MANAGER (display,  eventManager); 

//  Read  first  64  characters  of  file 

//  Construct  a  new  Line  editor  in  window  1. 

fseek (textfile, SEEK  SET,0); 

Line  editor  ‘windowl  =  new  Line  editor (); 

fread(ln, 64, 1, textfile) ; 

//  Construct  a  new  string  field  for  the  Line  editor  in  windowl. 

//  Close  file 

UIW  STRING  ‘stringfield  =  new  UIW  STRING (1, 1, 64, 

fclose (textfile) ; 

*windowl->line  buffer,  64, 

STF  NO  FLAGS,  WOF  NO  ALLOCATE  DATA) ; 

strcpy(*line  buffer, In); 

)  //  end  Line  editor  constructor 

//  Add  the  window  objects  to  the  line  editor  in  window  1. 

‘windowl 

//  Define  Line  editor's  destructor. 

+  new  UIW  BORDER 

Line  editor::  "Line  editor () 

+  new  UIW  MAXIMIZE  BUTTON 

{ 

+  new  UIW  MINIMIZE  BUTTON 

FILE  ‘textfile;  //  pointer  to  file 

+  new  UIW  SYSTEM  BUTTON 

char  In [64];  //  char  array  to  hold  a  line  read  from  file 

+  new  UIW  TITLE ("MAKE  .BAT  editor",  WOF  JUSTIFY  CENTER) 

+  stringfield;  //  Add  the  string  field  we  constructed  to  windowl 

//  Open  Make  file  (MK.BAT) 

if  ((textfile  -  f open ( "mk . bat " ,  "w"))  ==  NULL) 

//  Add  windowl  to  the  window  manager. 

I 

‘windowManager  +  windowl; 

printf ("Error  opening  text  file.  Aborting.  \n"); 

exit (0) ; 

) 

(continued  on  page  102) 
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Listing  One  (Listing  continued,  text  begins  on  page  64.) 

II  Loop  for  user  response, 
int  ccode; 

UI_EVENT  event; 

do 

{ 

//  Get  input  from  the  user. 
eventManager->Get (event,  Q_NORMAL) ; 

//  Send  event  information  to  the  window  manager, 
ccode  -  windowManager->Event (event) ; 

} 

while  (ccode  !-  L_EXIT  &&  ccode  !-  S_NO_OBJECT) ; 

//  Manually  decouple  stringfield  from  windowl.  Destruct  all  the  objects  we 
//  constructed  in  the  opposite  order  in  which  we  created  them. 

♦windowl  -  stringfield; 
delete  stringfield; 
delete  windowl; 
delete  windowManager; 
delete  eventManager; 
delete  display; 

}  //  end  main. 

End  Listing  One 


Listing  Two 

♦  ♦♦  Production 
OPTIONS— 0  -w  -P 

♦♦♦  Debugging 
♦OPTIONS— v  -w  -P 

♦  ♦♦  Zinc  information 
INCLUDE-. .\include 
LIB-.  Alib 

! if  !$d (MODEL) 

MODEL-1 

lendif 

.SWAP 

. PATH. obj-$ (MODEL) 

. PATH. lib-$ (LIB) 

.cpp.exe  : 

tcc  $ (OPTIONS)  -m$ (MODEL)  -1$ (INCLUDE)  -L$(LIB) 

{$<  zil$ (MODEL) .lib  graphics. lib 

End  Listing  Two 


Listing  Three 

♦include  <ui  win.hpp> 

♦include  "editor. hlh" 

main  () 

{ 

//  Initialize  the  display,  try  for  graphics  first. 

UI_DISPLAY  * display  -  new  UI_DOS_BGI_DISPLAY; 
if  ( !display->installed) 

{ 

delete  display; 

display  -  new  UI_DOS_TEXT_DISPLAY; 

} 

//  Initialize  the  event  manager. 

UI_EVENT_MANAGER  ‘eventManager  =  new  UI_EVENT_MANAGER (100,  display); 
♦eventManager  +  new  UI_BIOS_KEYBOARD  +  new  UI_MS_MOUSE  +  new 
UI_CURSOR; 

//  Initialize  the  window  manager. 

UI_WINDOW_MANAGER  ‘windowManager  - 

new  UI_WINDOW_MANAGER (display,  eventManager); 

//  Initialize  the  help  window  system. 

_helpSystem  -  new  UI_HELP_WINDOW_SYSTEM( "notepad. hip", 
windowManager,  HELP_GENERAL) ; 

//  Initialize  the  error  window  system. 

_errorSystem  =  new  UI_ERROR_WINDOW_SYSTEM; 

//  Create  a  field  editor  window. 

UIW_WINDOW  ‘editor  =  new  UIW_WINDOW (4,  5,  66,  12, 

WOF_NO_FLAGS ,  WOAF_NO_FLAGS ) ; 

//  Add  window  objects  to  editor. 

‘editor 

+  new  UIW_BORDER 
+  new  U I W_MAX IM I Z E_BUTTON 
+  new  UIW_MINIMIZE_BUTTON 
+  new  UIW_SYSTEM_BUTTON 

+  new  UIW_TITLE ( "FieldEditor" ,  WOF_JUSTIFY_CENTER) 

+  new  UIW_PROMPT (2,  1,  "To:",  WOF_NO_FLAGS) 

+  new  UIW_STRING (6,  1,  15,  "Dr.  Dobbs  folk",  40,  STF_NO_FLAGS , 

WOF_BORDER) 

+  new  UIW_PROMPT (28,  1,  "Date:",  WOF_NO_FLAGS) 

+  new  UIW_DATE (35,  1,  20,  &UI_DATE(),  "", 

DTF_SYSTEM  !  DTF_ALPHA_MONTH,  WOF_BORDER, 

NO_HELP_CONTEXT ) 

+  new  UIW_PROMPT (2,  2,  "Message:",  WOF_NO_FLAGS ) 

+  new  UIW_TEXT (2,  3,  60,  4,  "",  1028,  TXF_NO_FLAGS,  WOF_BORDER) ; 

//  Add  field  editor  to  the  window  manager. 

‘windowManager  +  editor; 

//  Wait  for  user  response, 
int  ccode; 

UI_EVENT  event; 
do 

I 

eventManager->Get (event,  Q_NORMAL) ; 
ccode  -  windowManager->Event (event) ; 

)  while  (ccode  !=  L_EXIT  &&  ccode  !-  S_NO_OBJECT) ; 

//  Clean  up. 
delete  _helpSystem; 
delete  _errorSystem; 
delete  windowManager; 
delete  eventManager; 
delete  display; 


//  Contents  of  editor. hlh . 

//  This  file  was  created  by  the  GENHELP  utility. 

const  int  HELP_GENERAL  =1;  //  General  Help 
const  int  HELP_EDITOR  =2;  //  Editor  Help 


End  Listings 
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Listing  One  (Text  begins  on  page  72.) 

PXCheck (0x143, PXFldHandle (headerTbl, "From  User" , &hdrUserFld) ) ; 

PXCheck (0x144, PXFldHandle (headerTbl, "From  ID", ihdrIDFId) ) ; 

/*  You  will  need  the  Paradox  Engine  to  compile  this  program.  If  you  have  */ 

/*  placed  directory  for  Engine  in  your  INCLUDE  path  and  LIBRARY  path,  the  */ 

/*  modules  should  compile  fine  with:  tcc  -ml  mci  parse  send  pxengtcl.lib  */ 

/*  Otherwise,  specify  where  Engine  header  file  and  library  files  are  */ 

/*  using  the  -I  and  -L  compiler  switches.  */ 

PXCheck (0x145, PXFldHandle (msgTbl, "Messaged", &msgMsgNumFld) ) ; 

PXCheck (0x146, PXFldHandle (msgTbl, "Line^" , &msgLineFld) ) ; 

PXCheck (0x147, PXFldHandle (msgTbl, "Text", SmsgTextFld) ) ; 

PXCheck (0x148, PXFldHandle (routeTbl, "Messaged", SrouteMsgFld) ) ; 

PXCheck (0x149, PXFldHandle (routeTbl, "ToOrCC", SrouteToFld) ) ; 

PXCheck (0xl4A, PXFldHandle (routeTbl, "User  Name", SrouteUserFld) ) ; 

♦define  MCIMAIN 

PXCheck (0x1 4B, PXFldHandle (routeTbl, "User  ID" , &routeIDFld) ) ; 

return; 

♦include  <stdio.h> 

} 

♦include  <pxengine.h> 

♦include  "mci.h" 

void  makeTblExist (char  *tblName,int  nFlds,char  **fld,char  **types, 

int  keyFields) 

void  closeTables (void) ; 
void  getFldNames (void) ; 

int  exist; 

PXCheck (0x150, PXTblExist (tblName, &exist) ) ; 
if  (lexist) 

void  makeTblExist (char  ‘tblName, int  nFlds,char  **fld,char  **types, 

int 

keyFields) ; 

void  openTables (void) ; 
void  shutdownEngine (void) ; 

PXCheck (0x151, PXTblCreate (tblName, nFlds, fid, types) ) ; 
if  (keyFields) 

PXCheck (0x152, PXKeyAdd (tblName, keyFields, fh, PRIMARY) ) ; 

void  startEngine (void) ; 

return; 

/****  DEFINE  HEADER  TABLE  INFORMATION  ****/ 

} 

char  *headerFields [ ]  = 

{ 

void  PXCheck (int  loc,int  errCode) 

"Date  Received", "Messaged", "Subject", "From  User", "From  ID" 

{ 

lastPXErr=errCode; 

char  *headerTypes [ ]  ■ 

if  (errCode=PXSUCCESS) 
return; 

"D", "N", "A40", "A20", "A8" 

switch  (loc) 

}  > 

int  headerKeyFields  *  2; 

case  0x234: 

♦define  headerNFields  sizeof (headerTypes) /sizeof (char*) 

case  0x247: 

/****  define  MESSAGE  TABLE  INFORMATION  ****/ 
char  *msgFields [ ]  « 

case  0x253: 

case  0x254 :  return; 

default:  printf ("Error  '%s'  at  %04x\n", PXErrMsg (errCode) , loc) ; 

"Messaged", "Line^", "Text" 

}; 

char  *msgTypes [ ]  * 

exit  (1); 

} 

) 

{ 

"N", "N", "A80" 

int  PXLastErr (void) 

}; 

return  lastPXErr; 

int  msgKeyFields  -  2; 

♦define  msgNFields  sizeof (msgTypes) /sizeof (char*) 

End  Listing  One 

/****  DEFINE  ROUTE  TABLE  INFORMATION  ****/ 

char  *routeFields []  - 

{ 

"Messaged", "TOorCC", "User  Name", "User  ID" 

}; 

char  *routeTypes ( ]  * 

( 

Listing  Two 

♦ifdef  MCIMAIN 

♦define  extern 

"N","A5", "A20", "A8" 

♦endif 

int  routeKeyFields  *  3; 

♦define  MESSAGELENGTH  90 

♦define  routeNFields  sizeof (routeTypes) /sizeof (char*) 

♦define  STARTOFNEWMESSAGE  "Date:" 

♦define  ENDOFSCRIPT  "Command:" 

int  lastPXErr; 

FI ELD HANDLE  fh ( ]  -  (1); 

int  PXLastErr (void) ; 

TABLEHANDLE  headerTbl, msgTbl, routeTbl; 

void  PXCheck (int  loc, int  errCode); 

void  send (void) ; 

int  main (int  argc,char  *argv[]) 

void  parse (char  ‘filename); 

startEngine () ; 

extern  short  MessagelD; 

openTables () ; 

extern  TABLEHANDLE  headerTbl, msgTbl, routeTbl; 

getFldNames () ; 

extern  RECORDHANDLE  headerRec,msgRec, routeRec; 

if  (argc  >  1) 

parse (argv[l] ) ;  /*  only  add  to  tables  if  filename  passed  in  */ 

extern  FIELDHANDLE  hdrDateFld; 

send() ; 

extern  FIELDHANDLE  hdrMsgFld; 

closeTables () ; 

extern  FIELDHANDLE  hdrSub jectFld; 

shutdownEngine () ; 

extern  FIELDHANDLE  hdrUserFld; 

return  0; 

extern  FIELDHANDLE  hdrIDFId; 

extern  FIELDHANDLE  msgMsgNumFld; 

void  startEngine (void) 

extern  FIELDHANDLE  msgLineFld; 

{ 

extern  FIELDHANDLE  msgTextFld; 

PXCheck (0x101, PXInit {) ) ; 

} 

extern  FIELDHANDLE  routeMsgFld; 

extern  FIELDHANDLE  routeToFld; 

void  shutdownEngine (void) 

extern  FIELDHANDLE  routeUserFld; 

{ 

extern  FIELDHANDLE  routelDFld; 

PXCheck (0x110, PXExit () ) ; 

} 

End  Listing  Two 

void  openTables (void) 

{ 

Listing  Three 

makeTblExist ("Header" , headerNFields, headerFields, headerTypes,  headerKeyFields) ; 

makeTblExist ( "Message " , msgNFields , msgFields , msgTypes , msgKeyFields ) ; 

♦include  <stdio.h> 

makeTblExist ("Route", routeNFields, routeFields, routeTypes, routeKeyFields) ; 

♦include  <stdlib.h> 

PXCheck (0x120, PXTblOpen ( "Header", iheaderTbl, 0, 0) ) ; 

♦include  <string.h> 

PXCheck (0x121, PXTblOpen ("Message", fimsgTbl, 0,0)); 

PXCheck (0x122, PXTblOpen ("Route", irouteTbl, 0, 0) ) ; 

♦include  "mci.h" 

PXCheck (0x123, PXRecBufOpen (headerTbl, fiheaderRec) ) ; 

PXCheck (0x125, PXRecBufOpen (msgTbl, imsgRec) ) ; 

void  getCC(FILE  *inMsgFp, char  inBuf fer [ ] , int  msgID) ; 

j  PXCheck (0x126, PXRecBufOpen (routeTbl, SrouteRec) ) ; 

void  getHeaderInfo(FILE  *inMsgFp, char  inBuf fer t] , int  msgID); 

void  closeTables (void) 

short  getNextMsgID (short  *MessageID) ; 

void  getTo(FILE  *inMsgFp, char  inBuf fer [], int  msgID); 

PXCheck (0x130, PXTblClose (headerTbl) ) ; 

PXCheck (0x131, PXTblClose (msgTbl) ) ; 

PXCheck (0x132, PXTblClose (routeTbl) ) ; 

} 

void  parseAddr (char  inBuf fer [], char  Person [] ,char  ID [ ] ) ; 
void  parseDate (char  *dateStr) ; 

void  whoFrom(FILE  *inMsgFp, char  inBuf fer [], int  msgID); 
int  convertMonth(char  *str); 

void  getFldNames (void) 

void  parse (char  ‘filename) 

{ 

{ 

PXCheck (0x140, PXFldHandle (headerTbl, "Date  Received", ShdrDateFld) ) ; 

FILE  ‘inMsgFp; 

PXCheck (0x141, PXFldHandle (headerTbl, "Messaged", ShdrMsgFld) ) ; 

PXCheck (0x142, PXFldHandle (headerTbl, "Subject", ShdrSubjectFld) ) ; 

(continued  on  page  106) 

104 

Dr.  Dobb’s  Journal,  December  1990 

1149 

PROGRAMMER'S  WORKBENCH 


Listing  Three  (Listing  continued,  text  begins  on  page  72.) 

char  inBuf fer [MESSAGELENGTH+1] ; 
short  LineNumber; 

if  ((inMsgFp  =  fopen (filename, "r") )  =-  NULL) 

{ 

perror (filename) ; 

PXExitO; 

return; 

} 

/*  Parse  through  text  file  searching  for  first  MCI  message.  */ 
while  (fgets (inBuf fer, MESSAGELENGTH, inMsgFp) ) 

if (strstr (inBuffer, STARTOFNEWMESSAGE)  *=  inBuffer) 
break; 
do 
{ 

/*  If  STARTOFNEWMESSAGE  is  at  beginning  of  current  line,  save  last  */ 
/*  message  and  get  remainder  of  header  information  for  the  message.  */ 
/*  Otherwise,  keep  getting  text.  */ 

if  (strstr (inBuffer, ENDOFSCRIPT)  —  inBuffer) 

break;  /*  Reached  end  of  messages  */ 

if  (strstr (inBuffer, STARTOFNEWMESSAGE)  ««  inBuffer) 

{ 

LineNumber  -  1; 

getNextMsgID (&MessageID) ; 

getHeaderlnfo (inMsgFp, inBuffer, MessagelD) ; 

) 

if  (strlen (inBuffer)  >  0  &&  inBuffer [strlen (inBuffer) -1]  -=  '\n') 
inBuffer [strlen (inBuffer) -1]  *  '\0'; 

PXCheck (0x300, PXPutAlpha (msgRec,msgTextFld, inBuffer) ) ; 

PXCheck (0x301, PXPutShort (msgRec,msgLineFld,  LineNumber++) ) ; 

PXCheck (0x302, PXPutShort (msgRec, msgMsgNumFld, MessagelD) ) ; 

PXCheck (0x303, PXRecAppend (msgTbl, msgRec) ) ; 

Jwhile  (fgets (inBuffer, MESSAGELENGTH, inMsgFp) ) ; 

f close ( inMsgFp) ; 

return; 


void  getHeaderlnfo (FILE  ‘inMsgFp, char  inBuffer [], int  msgID) 

{ 

char  subject [41] , dummy [1] ; 

parseDate (inBuffer) ; 

whoFrom (inMsgFp, inBuffer, msgID) ; 

/‘Skip  the  Blank  Line*/ 

fgets (inBuffer, MESSAGELENGTH, inMsgFp) ; 

/‘Skip  the  First  TO:  line  (ignore  address  to  self)  */ 
fgets (inBuffer, MESSAGELENGTH, inMsgFp) ; 

getTo (inMsgFp, inBuffer, msgID) ; 
getCC (inMsgFp, inBuffer, msgID) ; 

parseAddr (inBuffer, subject, dummy) ; 

PXCheck (0x330, PXPutAlpha (headerRec, hdrSub jectFld, subject) ) ; 
PXCheck (0x3 3 !,PXRecAppend(headerTbl,headerRec) ) ; 


{ 

char  *p; 

char  *s  «  person; 

if  ( (p  *  strchr (inBuffer, ':')) l-NULL) 

{ 

while  (*(++p)  “  '  '  :  I  *p  mm  •*•  ) 

while  (  (*s++  -  *p++)  !-  '/'  &&  *p) 

* ( — s)  =''\0'; 

} 

s  *  id; 

if  ( (p  *  strchr(p, ':'))•' -NULL) 

{ 

while  (  *(++p)  rnm  ' 

while  (  (*s++  *  *p++)  !-  '\n') 

*(— s)  •  '  \0' ; 

} 

) 

short  getNextMsgID (short  ‘msgID) 

{ 

RECORDNUMBER  nRecs; 

PXCheck  (0x360,  PXTblNRecs  (msgTbl,  JinRecs) ) ; 
if  (nRecs  «*  0) 

‘msgID  -  1; 

else 

{ 

PXCheck (0x370, PXRecLast (msgTbl) ) ; 

PXCheck (0x371, PXRecGet (msgTbl, msgRec) ) ; 

PXCheck (0x372, PXGetShort (msgRec, msgMsgNumFld, msgID) ) ; 
++ (‘msgID ) ; 

) 

return (‘msgID ) ; 

} 

void  parseDate (char  ‘dateStr) 

{ 

char  *mon, ‘day, ‘year; 
int  iMon, iDay, iYear; 
long  engDate; 

strtok (dateStr, "  "); 

strtok (NULL, "  "); 

mon-strtok (NULL, "  " ) ; 

day-strtok (NULL, "  "); 

year-strtok (NULL, "  ") ; 

if  ( (iMon-convertMonth  (mon) )  “0) 

PXCheck (0x380, PXERR_INVDATE) ; 
iDay-atoi (day) ; 
iYear«atoi (year) ; 

PXCheck(381,PXRecBufEmpty(headerRec) ) ; 

PXCheck (382, PXDateEncode (iMon, iDay, iYear, SengDate) ) ; 

PXCheck (383, PXPutDate (headerRec, hdrDateFld, engDate) ) ; 


/*  Skip  blank  lines  */ 

fgets (inBuffer, MESSAGELENGTH, inMsgFp) ; 

fgets (inBuffer, MESSAGELENGTH, inMsgFp) ; 

} 

void  getTo (FILE  ‘inMsgFp, char  inBuffer [], int  msgID) 

{ 

char  person [MESSAGELENGTH+1] ; 
char  id [MESSAGELENGTH+1]; 

while  (fgets (inBuffer, MESSAGELENGTH, inMsgFp)  && 

strstr (inBuffer, "TO")  !!  strstr (inBuffer, "EMS") ) 

{ 

parseAddr (inBuffer, person, id) ; 

PXCheck (0x310, PXPutAlpha (routeRec, routeUserFld, person) ) ; 
PXCheck (0x311, PXPutAlpha (routeRec, routelDFld, id) ) ; 
PXCheck (0x312, PXPutShort (routeRec, msgMsgNumFld, msgID) ) ; 
PXCheck (0x313, PXPutAlpha (routeRec, routeToFld, "TO") ) ; 
PXCheck (0x314, PXRecAppend(routeTbl, routeRec) ) ; 

} 

} 

void  getCC (FILE  ‘inMsgFp, char  inBuffer [], int  msgID) 

( 

char  person [MESSAGELENGTH+1 ] ; 
char  id [MESSAGELENGTH+1 ] ; 
while  (strstr (inBuffer, "CC") ) 

{ 

parseAddr (inBuffer, person, id) ; 

PXCheck (0x320, PXPutAlpha (routeRec, routeUserFld, person) ) ; 
PXCheck (0x321, PXPutAlpha (routeRec, routelDFld, id) ) : 
PXCheck (0x322, PXPutShort (routeRec, msgMsgNumFld, msgID) ) ; 
PXCheck (0x323, PXPutAlpha (routeRec, routeToFld, "CC") ) ; 
PXCheck (0x324, PXRecAppend(routeTbl, routeRec) ) ; 
fgets (inBuffer, MESSAGELENGTH, inMsgFp) ; 

) 

) 

void  whoFrom (FILE  ‘inMsgFp, char  inBuffer [], int  msgID) 


int  convertMonth(char  *str) 

{ 

switch  (str[0]) 

{ 

case  'A':  switch  ( str [ 1 ] ) 

{ 


case 

case 

} 

case  'D':  return  12; 
case  'F':  return  2; 
case  'J':  switch  (str[l]) 

{ 


case 

case 


'p': 
'u' : 


'a' : 
'u' : 


case  ' 1' : 
case  'n' : 


} 

case  'M' :  switch  (str[2]) 

{ 

case  ' r' : 
case  'y' : 

) 

case  'N' :  return  11; 
case  'S':  return  9; 
case  'O':  return  10; 

} 

return  0; 

) 


return  4;  /*  April  */ 

return  8;  /*  August  */ 

/*  December  */ 
/*  February  */ 


return  1;  /*  January  */ 
switch  (str [2]) 

{ 

return  7;  /*  July  */ 
return  6;  /*  June  */ 

} 


return  3;  /*  March  */ 
return  5;  /*  May  */ 

/*  November  */ 
/*  September  */ 
/*  October  */ 


End  Listing  Three 


Listing  Four 


char  person [MESSAGELENGTH+1] ; 
char  id [MESSAGELENGTH+1 ] ; 

fgets (inBuf fer, MESSAGELENGTH, inMsgFp) ; 
parseAddr (inBuffer, person, id) ; 
printf ("From:  %s\n", person) ; 
printf ("MCI  ID:  %s\n",id); 

PXCheck (0x350, PXPutAlpha (headerRec, hdrIDFId, id) ) ; 
PXCheck (0x351, PXPutAlpha (headerRec, hdrUserFld, person) ) ; 
PXCheck (0x352,  PXPutShort (headerRec, hdrMsgFld, msgID) ) ; 


void  parseAddr (char  ‘inBuffer, char  ‘person, char  *id) 


♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <pxengine.h> 

♦include  "mci.h" 

void  createlndex (TABLEHANDLE  *tbl, FIELDHANDLE  f ld[3] ) ; 

void  processMany (FILE  *fp, FIELDHANDLE  f [3] , TABLEHANDLE  t,int  pn,char  ‘st) 
void  processFile (FILE  *fp, FIELDHANDLE  f [3] , TABLEHANDLE  t,int  pn) ; 
void  nextPendNum (TABLEHANDLE  t, FIELDHANDLE  f, short  *pn) ; 

♦define  PENDFIELD  0 
♦define  ACTFIELD  1 
♦define  TEXTFIELD  2 
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void  send (void) 

{ 

TABLEHANDLE  tbl; 

FIELDHANDLE  fids [3]; 

FILE  * output; 
int  exists; 
short  pendNum; 

PXCheck (0x200, PXTblExist ("Pending",  Sexists) ) ; 
if ( (exists) 

return; 

createlndex (Stbl, fids) ; 

PXCheck (0x201, PXTblOpen ("Pending" , Stbl,  0,0) ) ; 
pendNum- 1; 

output-fopen("mci-send.txt",  "wt") ; 
if  (output —NULL) 

{ 

perror  ( "mci.-send .  txt " ) ; 
exit (1) ; 

) 

do 

{ 

fprintf (output, "\ncr\n") ; 

processMany (output, fids, tbl, pendNum, "TO") ; 

fputs ("\n", output) ; 

processMany (output, fids, tbl,  pendNum, "CC") ; 
fputs ("\n", output) ; 

processMany (output, fids, tbl, pendNum, "Subject") ; 
processFile (output, fids, tbl, pendNum) ; 
fputs ("\n/\n\nYes\n", output) ; 
nextPendNum(tbl, fids [PENDFIELD] , & pendNum) ; 

) while (pendNum>0) ; 

fputs ("exit\n", output) ; 
f close (output) ; 

PXCheck (0x202, PXTblClose (tbl) ) ; 

PXCheck (0x203, PXTblDelete ("Pending") ) ; 
return; 

} 

void  createlndex (TABLEHANDLE  *tbl, FIELDHANDLE  fid [3]) 

{ 

PXCheck (0x210, PXTblOpen ( " Pending" , tbl , 0 , 0 ) ) ; 

PXCheck (0x211, PXFldHandle (*tbl, "Pending#", &f Id [PENDFIELD] ) ) ; 
PXCheck (0x212, PXFldHandle (*tbl, "Action", s fid [ACTFIELD] ) ) ; 

PXCheck (0x213, PXFldHandle ( * tbl , "Text ",  &  fid [ TEXTFIELD ])); 

PXCheck (0x214, PXTblClose  <*tbl) ) ; 

PXCheck (0x215, PXKeyAdd( "Pending", 1, & fid [ACTFIELD] , SECONDARY) ) ; 

) 

void  processMany (FILE  *fp, FIELDHANDLE  f [3] , TABLEHANDLE  t,int  pn,char  *st) 

{ 

char  txtSt[81]; 

RECORDHANDLE  srchRec, rec; 

PXCheck (0x230, PXRecBufOpen (t, &rec) ) ; 

PXCheck (0x231, PXRecBufOpen (t, SsrchRec) ) ; 

PXCheck (0x232, PXPutShort (srchRec, f [PENDFIELD] ,pn) ) ; 

PXCheck (0x233, PXPutAlpha (srchRec, f [ACTFIELD] , st) ) ; 
PXCheck(0x234,PXSrchKey(t, srchRec, 2, SEARCHFIRST) ) ; 

while (PXLastErr ( ) — PXSUCCESS) 

{ 

PXCheck (0x235, PXRecGet (t, rec) ) ; 

PXCheck (0x236, PXGetAlpha (rec, f [TEXTFIELD] , sizeof (txtSt) , txtSt) ) ; 
fprintf (fp, "%s\n", txtSt) ; 

PXCheck (0x237, PXSrchKey (t, srchRec, 2, SEARCHNEXT) ) ; 

] 

PXCheck (0x238, PXRecBufClose (rec) ) ; 

PXCheck (0x239, PXRecBufClose (srchRec) ) ; 

} 

void  processFile (FILE  *fp, FIELDHANDLE  f [3] , TABLEHANDLE  t,int  pn) 

{ 

char  txtSt [81] , fname [21] ; 

FILE  *inFp; 

RECORDHANDLE  srchRec, rec; 

PXCheck (0x240, PXRecBufOpen (t,&rec) ) ; 

PXCheck (0x241, PXRecBufOpen (t, SsrchRec) ) ; 

PXCheck (0x242, PXPutShort (srchRec, f [PENDFIELD] , pn) ) ; 

PXCheck (0x243, PXPutAlpha (srchRec, f [ACTFIELD] , "Filename") ) ; 

PXCheck (0x244, PXSrchKey (t, srchRec, 2,  SEARCHFIRST) ) ; 

while  (PXLastErr  ( )  —PXSUCCESS) 

{ 

PXCheck (0x245, PXRecGet (t, rec) ) ; 

PXCheck (0x246, PXGetAlpha (rec, f [TEXTFIELD] , sizeof (fname) , fname) ) ; 
if  ( (inFp=f open (fname,  "rt") )  —NULL) 

{ 

perror (fname) ; 

exit (1) ; 

) 

while (fgets (txtSt, 80, inFp) !=NULL) 
fputs (txtSt, fp) ; 
f close (inFp) ; 
unlink (fname) ; 

PXCheck (0x247, PXSrchKey (t, srchRec, 2, SEARCHNEXT) ) ; 

) 

PXCheck (0x248, PXRecBufClose (rec) ) ; 

PXCheck (0x24 9, PXRecBufClose (srchRec) ) ; 

} 

void  nextPendNum (TABLEHANDLE  t, FIELDHANDLE  f, short  *pn) 

{ 

RECORDHANDLE  r; 

PXCheck (0x250, PXRecBufOpen (t, Sr) ) ; 

PXCheck (0x251, PXPutShort (r, f , *pn) ) ; 

PXCheck (0x252, PXSrchKey (t, r, 1, SEARCHFIRST) ) ; 
while  (PXLastErr  ()  —PXSUCCESS) 

PXCheck (0x253, PXSrchKey (t, r, 1, SEARCHNEXT) ) ; 

PXCheck (0x254, PXRecNext (t) ) ; 
if  (PXLastErr  ( )  —PXSUCCESS) 


{ 

PXCheck (0x255, PXRecGet (t, r) ) ; 
PXCheck (0x256, PXGetShort (r, f ,pn) ) ; 
PXCheck (0x257, PXRecBufClose (r) ) ; 

1 

else 

*pn=0; 


End  Listing  Four 

Listing  Five 

editor  =  "ED"  ;  Change  this  to  your  word  processor 
PROC  BuildHdrForm() 

(Forms)  (Design)  (Header)  (2)  (Brief  Header)  ;  Design  form  for  HEADER 
"  Date  Recvd  From  Subject"  ;  Place  text... 

Enter 


Enter 

Menu  (Field)  (Place)  [Regular)  [Date  Received)  ;  Place  DATE  field 
Enter  Enter  Right 

Menu  (Field)  (Place)  (Regular)  (From  User)  ;  Place  FROM  USER  field 

Enter  Enter  Right 

Menu  (Field)  (Place)  (Regular)  (Subject)  ;  Place  SUBJECT  field 

Enter  Enter  CtrlHome 

Menu  (Multi)  (Records)  (Define)  ;  Define  as  MultiRecord 

Enter  Left  Enter  Down  Down  Down  Down  Down  Down  Down  Enter 
Do_It !  ;  Save  this  form 

ENDPROC  ;  BuildHdrForm 

PROC  BuildMsgForms () 

(Forms)  (Design)  (Message)  (1)  (Message  Body)  ;  Design  form  for  MESSAGE 
MENU  (Field)  (Place)  (Regular)  {Line#}  ;  Place  LINE#  field 

ENTER  LEFT  LEFT  LEFT  LEFT  LEFT  LEFT  LEFT  LEFT  LEFT  LEFT;  Truncate  field  size 
LEFT  LEFT  LEFT  LEFT  LEFT  LEFT  LEFT  LEFT  LEFT  LEFT  LEFT  LEFT  LEFT  ENTER 

MENU  (Field)  (Place)  (Regular)  (Text)  ;  Place  TEXT  field 

RIGHT  ENTER  ENTER 

MENU  (Multi)  (Records)  (Define)  ;  Define  as  MultiRecord  fields 

ENTER  LEFT  ENTER  DOWN  DOWN  DOWN  DOWN  DOWN  DOWN  DOWN  DOWN  ENTER 

;  The  next  four  lines  set  up  the  position  and  color  for  hiding  the  line# 

;  field.  It  currently  sets  the  color  to  a  light  grey  on  light  grey. 

HOME  CTRLHOME 

MENU  (Style)  (Color)  (Area) 

ENTER  DOWN  DOWN  DOWN  DOWN  DOWN  DOWN  DOWN  DOWN  ENTER 
RIGHT  RIGHT  RIGHT  RIGHT  RIGHT  RIGHT  RIGHT  ENTER 

(continued  on  page  108) 
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Listing  Five  (Listing  continued,  text  begins  on  page  72.) 

DO  IT1  '  Save  this  form 

{Forms}  {Design}  {Header}  {1}  {Message}  ;  Design  for  for  HEADER  table 

ENTER  "  Date  Received  "  :  Set  UP  position  and. text 

MENU  {Field}  {Place}  {Regular}  {Date  Received}  ;  Place  DATE  RECEIVED  field 


ENTER  ENTER  ENTER  "  Subject  .  " 

MENU  {Field}  {Place}  {Regular}  {Subject} 

ENTER  ENTER  ENTER  "  From  .  " 

MENU  {Field}  {Place}  {Regular}  {From  User} 
ENTER  ENTER 


;  Set  up  position  and  text 
;  Place  SUBJECT  field 

;  Set  up  position  and  text 
;  Place  FROM  USER  field 


;  Place  MultiTable  Linked  Form  from 
;  MESSAGE  table.  ' 

;  Position  the  field 

;  Save  this  form 


MENU  {Multi}  {Tables}  {Place} 

{Linked}  {Message}  {1}  (Message#} 

UP  UP  UP  UP  UP  UP  UP  UP  UP  ENTER 

DO_IT! 

ENDPROC  ;  BuildMsgForms 

PROC  MenuScrnO 
CANVAS  OFF 
04,0 

SETMARGIN  25 

PAINTCANVAS  ATTRIBUTE  31  2,0,24,79  ;  Fill  Background  w/White  on  Blue 
PAINTCANVAS  ATTRIBUTE  0  5,27,8,54  ;  Shadow  Box  in  Black 

STYLE  ATTRIBUTE  7 
TEXT 


MCI  Message  System 


SETMARGIN  0 
622,0 


Use  Cursor  Keys  < - >  To  Move  Between  Menu  Choices,  or  1st  Character 

ENDTEXT 

PAINTCANVAS  ATTRIBUTE  31  22,0,24,79 
CANVAS  ON 
ENDPROC  ;  MenuScrn 

PROC  Inbox () 

IF  (  ISEMPTY( "Header")  )  THEN 
0  20,27 

??  "No  messages  to  be  viewed" 

RETURN 

ENDIF 

VIEW  "Header" 

PICKFORM  2 
WAIT  TABLE 

PROMPT  "Arrow  to  message,  press  RETURN  to  view.", 

"ESC  aborts  to  main  menu." 

UNTIL  "Enter",  "Esc" 

SWITCH 

CASE  retval  *  "Enter"  : 

ViewMessage () 

CASE  retval  *  "Esc"  : 

CLEAR 
CLEARALL 
RETURN 
ENDSWITCH 
ENDPROC  ;  Inbox 

PROC  ViewMessage () 

PICKFORM  1 
DOWNIMAGE 
WHILE  (TRUE) 

WAIT  TABLE 

PROMPT  "F3/F4  move  to  Previous/Next  message.  INS  responds  to  message.", 
"Arrow  keys  scroll  the  current  message.  ESC  aborts  to  main  menu. 
UNTIL  "Esc",  "F3",  "F4",  "Ins" 

SWITCH 

CASE  retval  =  "Ins": 

Respond () ; 

PICKFORM  1 
DOWNIMAGE 

CASE  retval  =  "F3": 

UP IMAGE 
PGUP 

DOWNIMAGE 

CASE  retval  =  "F4": 

UP IMAGE 
PGDN 

DOWNIMAGE 

CASE  retval  =  "Esc": 

QUITLOOP 

ENDSWITCH 

ENDWHILE 

CLEAR 

CLEARALL 

ENDPROC  ;  ViewMessage 

PROC  CheckPendingO 

IF  (  NOT  I STABLE ("Pending")  )  THEN 
CREATE  "Pending" 

"Pending#" 


"Action" 
"Text" 
RETURN  1 
ELSE 


"A8*" 

"A40* 


(continued  on  page  110) 
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Listing  Five  (Listing  continued,  text  begins  on  page  72.) 


IF  (  ISEMPTY( "Pending")  )  THEN 
RETURN  1 
ELSE 

RETURN  CMAX( "Pending",  "Pending#")  +  1 
ENDIF 
END  IF 

ENDPROC  ;  CheckPending 
PROC  Respond () 

UP IMAGE 

mnum  *  [Message#] 

subject  =  [Subject] 

from  =  [From  ID] 

pnum  *  CheckPending () 


QUERY 

Route 


Message#  I  TOorCC 
“mnum  !  Check 


User  Name 


User  ID 
Check 


ENDQUERY 
DO  IT! 


VIEW  "Answer" 

IF  (  ISEMPTY( "Answer")  )  THEN 
an  s we  rTable=TRUE 
ELSE 

answerTable=FALSE 

ENDIF 

VIEW  "Pending" 

EDIT  "Pending" 

END 

DOWN 

[Pending#]  =  pnum 
[Action]  =  "Filename" 

[Text]  *  "Pending."  +  STRVAL(pnum) 
DOWN 


[Pending#]  -  pnum 
[Action]  =  "Subject" 

[Text]  =  "RE:"  +  subject 
DOWN 


[Pending#]  -  pnum 
[Action]  ■  "TO" 
[Text]  =  from 
DOWN 
UP IMAGE 


IF  (  NOT  answerTable  )  THEN 
WHILE  (  TRUE  ) 
to_cc  *  [TOorCC] 
uid  *  [User  ID] 

DOWN IMAGE 
[Pending#]  =  pnum 
[Action]  -  to_cc 
[Text]  -  uid 
DOWN 


UP IMAGE 

IF  (  ATLASTO  )  THEN 
QUITLOOP 
ENDIF 
DOWN 
END WHILE 
ENDIF 


DO_IT ! 

RUN  BIG  editor  +  "  Pending."  +  STRVAL (pnum) 
CLEAR 

CLEARIMAGE  ;  Close  the  Pending  Table 

CLEARIMAGE  ;  Close  the  Answer  Table 

UP IMAGE 

CLEARIMAGE  ;  Close  Route  Query  Table 

ENDPROC  ;  Respond!) 

PROC  Compose () 

pnum  ■  CheckPending!) 

VIEW  "Pending" 

EDIT  "Pending" 

END 

DOWN 

[Pending#]  =  pnum 
[Action]  =  "Filename" 

[Text]  =  "Pending."  +  STRVAL (pnum) 

DOWN 

CLEAR 

0  0,0 

GetMultiple ( "TO" ,  TRUE)  ; 

IF  (  NOT  retval  )  THEN 
CANCELED IT 
CLEAR 
CLEARALL 
RETURN 
ENDIF 

GetMultiple ( "CC" ,  FALSE)  ; 

IF  (  NOT  retval  )  THEN 
CANCELED IT 
CLEAR 
CLEARALL 
RETURN 
ENDIF 


?  "Subject:  " 

ACCEPT  "A40"  to  sub 
IF  (  NOT  retval  )  THEN 
CANCELEDIT 
CLEAR 
CLEARALL 
RETURN 
ENDIF 
ENDWHILE 

[Pending#]  =  pnum 
[Action]  *  "Subject" 

[Text]  *  sub 

DO_IT ! 

RUN  BIG  editor  +  "  Pending."  +  STRVAL (pnum) 

CLEAR 

CLEARALL 

ENDPROC  ;  Compose 


PROC  GetMultiple (where, one) 

IF  (one)  THEN 
name  =  " " 

WHILE  (  LEN (name)  =  0  ) 

?  where  +  " :  " 

ACCEPT  "A20"  TO  name 
IF  (  NOT  retval  )  THEN 
RETURN  FALSE 
ENDIF 
ENDWHILE 

[Pending#]  =  pnum 
[Action]  =  where 
[Text]  =  name 
DOWN 
ENDIF 

WHILE  (TRUE) 

?  where  +  ":  " 

ACCEPT  "A20"  TO  name 
IF  (  NOT  retval  )  THEN  ;  Esc  was  pressed 

RETURN  FALSE 
ENDIF 

IF  (  LEN (name)  =  0  )  THEN 
QUITLOOP 
ENDIF 

[Pending#]  =  pnum 
[Action]  -  where 
[Text]  *  name 
DOWN 
ENDWHILE 
RETURN  TRUE 
ENDPROC  ;  GetMultiple 

PROC  Main() 

WHILE  (TRUE) 

Menuscrn () 

SHOWMENU 

"Inbox"  :  "View  Current  Messages", 

"Compose":  "Compose  a  new  Message", 

"Quit"  :  "Quit  the  MCI  Message  System" 

TO  choice 

SWITCH 

CASE  choice  -  "Inbox"  : 

Inbox () 

CASE  choice  =  "Compose"  : 

Compose ( ) 

CASE  choice  =  "Quit"  : 

SHOWMENU 

"No"  :  "Do  NOT  Quit  The  Application.", 

"Yes"  :  "Quit  The  Application." 

TO  theexit 

IF  (  theexit  -  "Yes"  )  THEN 
MENU  (Exit)  (Yes) 

ENDIF 
ENDSWITCH 
ENDWHILE 
ENDPROC  ;  Main 

;****  Mainline  **** 

RESET 

CLEAR 

CLEARALL 

IF  (  NOT  ISTABLE ("Message")  )  OR  (  NOT  ISTABLE ("Header")  )  0 
(  NOT  ISTABLE ("Route")  )  THEN 
0  12,17 

??  "You  must  run  MCI.EXE  before  running  this  script" 

SLEEP  5000 
RETURN 
ENDIF 

IF  (  NOT  ISFILE ("Header. FI")  )  OR  (  NOT  ISFILE("Message.Fl") 
BuildMsgForms () ; 

ENDIF 

IF  (  NOT  ISFILE ( "Header. F2")  )  THEN 
BuildHdrFormO ; 

ENDIF 

Main ( ) 


;  Loop  until  at  least 
;  has  been  input. 

;  Esc  was  pressed 


sub  -  "" 

WHILE (  LEN (sub)  =  0  ) 


[where]  field 


)  THEN 


End  Listings 
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Wrapping  Up 
Loose  Ends 


The  occasion  of  the  last  “Para¬ 
digms”  column  of  this  year  is  to 
tie  up  some  long-dangling  loose 
ends  and  float  some  semi-de- 
tatched  observations  on  parallel  pro¬ 
cessing,  transputers,  fractal  graphics, 
multiparadigm  programming,  and  hy¬ 
pertext,  and  other  hyperstuff.  And  to 
mention  a  few  books  that  are  unlikely 
to  show  up  in  “Programmer’s  Book¬ 
shelf,”  but  that  still  may  be  worth  a 
look,  for  reasons  to  be  explained  herein. 

MINOS  Addition 

Last  November,  I  wrote  about  the  MI¬ 
NOS  system,  perhaps  the  earliest  prac¬ 
tical  implementation  of  neural  net  tech¬ 
nology.  I  also  described  an  even  earlier 
neural  net  system  in  something  I  re¬ 
ferred  to  as  the  ADAM  system.  One 
reader  wrote  to  ask  for  sources  on  the 
ADAM  computer.  The  body  of  litera¬ 
ture  on  this  device  is  enormous,  but  a 
primary  source  is  Genesis,  which,  while 
of  disputable  reliability  and  often  weak 
on  technical  detail,  is  at  least  widely 
available. 

Transputer  Refuter 

Quite  some  time  ago  I  allowed  a  prob¬ 
ably  overly  harsh  assessment  of  the 
transputer  architecture  to  appear  in  this 
column.  One  reader,  a  former  Inmos 
employee,  wrote  to  take  me  to  task  for 
this,  but  time  and  space  didn’t  allow 


Michael  Swaine 


printing  his  comments  then.  Belatedly, 
here  is  a  brief  defense  of  the  Inmos 
transputer: 

The  lack  of  a  register  add  is  offset 
by  the  RISC-like  nature  of  the  stack 
workspace  access  being  as  quick  as 
an  R-to-R  add  in  33nS  on-chip  memory 
(the  4  Kbytes  are  like  1000  word-length 
registers).  The  30MHz  T800  processor 
puts  the  fastest  68030/68882  pair  to 


shame  speedwise,  in  most  applica¬ 
tions.  ...  I  understand  that  there  are 
plenty  of  things  to  be  critical  of  in  the 
transputer,  but  the  structure  isn’t  one 
of  them!  I  still  support  the  transputer 
and  can  honestly  say  after  seeing  many 
benchmarks  and  comparisons  that  the 
transputer  definitely  keeps  up  with  the 
other  processors  and  still  provides  a 
direct  method  of  parallelization  that  no 
other  processor  can  approach. 

The  latest  transputer-based  applica¬ 
tion  whose  notice  crossed  my  desk  is 
Equator,  a  3-D  spreadsheet  for  the  Mac 
II  with  a  transputer  board,  from  Tri- 
Millennium  Corp.  (40  Horace  Street, 
Needham,  MA  02194).  It  looks  interest¬ 
ing  because:  Speed  and  memory  size 
are  scalable  with  additional  processors; 
the  spreadsheet  will  read  and  save  in 
standard  spreadsheet  formats;  Equator 
is  priced  competitively  with  other  spread¬ 
sheet  software;  and  it  looks  like  one 
of  the  few  commercial  applications  avail¬ 
able  that  could  provide  some  useful 
real-world  benchmarking  for  parallel 
processing. 

Multiparadigmatic  Programming 

I  have  recently  had  a  chance  to  play 
around  with  release  2.0  Prograph  from 
TGSSystem  (Halifax,  Nova  Scotia). 
Prograph  is  a  Macintosh-based  develop¬ 
ment  system  that  purports  to  be  a 
multiparadigmatic  system,  supporting 
object-oriented  programming,  dataflow 
programming,  and  visual  programming 
paradigms.  Well  purports  may  be  un¬ 
fair;  the  product  is  just  described  as  an 
object-oriented  visual programming  lan¬ 
guage  and  software  development  envi¬ 
ronment.  Besides,  while  it  does  sup¬ 
port  dataflow  specification  of  program 
execution,  maybe  being  multiparadig¬ 
matic  isn’t  much  of  a  distinction  these 
days.  Prograph  is  interesting,  though, 
from  a  couple  of  perspectives. 

First,  though,  the  component  list  and 
system  requirements.  Prograph  consists 


of  an  editor/interpreter  for  its  visual 
programming  language,  a  compiler,  an 
application  builder,  and  a  number  of 
examples  and  online  tutorial  aids.  It 
runs  on  a  Mac  Plus  or  above  with  2- 
Mbyte  RAM,  a  hard  disk,  and  System 
software  Version  6  or  above. 

As  soon  as  you  invoke  the  editor, 
you’re  up  against  the  visual  program¬ 
ming  language,  and  using  it  is  certainly 
a  different  experience  from  conven¬ 
tional  programming.  Prograph  is  not 
the  only  visual  programming  language 
around,  even  for  the  Mac:  Prototyper 
and  VIP  are  competitors.  Its  approach 
to  visual  programming,  though,  is  its 
own,  and  my  first  reaction  is  positive. 

Lots  of  products  and  approaches  have 
been  labeled  as  visual  programming 
systems.  There  are  diagrammatic  sys¬ 
tems  that  communicate  aspects  of  the 
structure  of  the  program,  or  that  permit 
manipulation  of  that  structure,  using 
flowcharts  or  dataflow  diagrams  or  state 
transition  diagrams;  there  are  table- 
based  and  form-based  programming 
systems  for  producing  databases;  and 
there  are  iconic  languages  in  which 
icons  take  the  place  of  linguistic  com¬ 
ponents  in  conventional  languages.  Pro¬ 
graph  is  in  the  iconic  camp,  but  has 
characteristics  of  other  approaches. 
Icons  are  strung  together  via  dataflow 
links,  for  example. 

The  visual  approach  in  Prograph  is 
not  cosmetic:  The  whole  system  is  fun¬ 
damentally  visual,  with  multiple  win¬ 
dows  for  editing  and  executing  pro¬ 
grams  and  for  specifying  classes  and 
methods.  Even  the  debugging  environ¬ 
ment  is  visual.  The  icons  and  dataflow 
diagrams  constructed  from  them  are 
not  pictures  representing  blocks  of  code, 
but  executable  items.  Click  on  them 
and  they  do  their  thing.  The  visual  ele¬ 
ments  really  are  the  program. 

So  what  is  it  like  to  program  with 
icons  and  diagrams?  It  comes  down  to 
a  lot  of  picking  items  from  lists  and 
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pasting  them  where  you  want  them,  at 
the  most  mundane  level.  And  typing 
names  into  newly  created  objects.  Most 
of  the  icons  are  really  just  variously 
shaped  text  boxes,  which  is  to  be  ex¬ 
pected.  They  are  icons,  not  Chinese 
ideographs,  and  the  only  way  the  set 
of  icons  can  be  extensible  is  through 
the  use  of  existing  linguistic  devices, 
meaning  names  spelled  out  with  let¬ 
ters.  Most  of  the  Mac  Toolbox  calls  are 
represented  iconically  and  accessed  as 
Mac  Methods.  Their  names  are  not 

Hypertext  is  creeping 
into  everything  I  read. 

There  is  definitely 
something  there,  but  the 
hype  can  be  off-putting 


editable,  but  are  fixed  to  be  the  names 
given  for  Pascal  functions  and  proce¬ 
dures  in  Inside  Macintosh. 

With  Prograph  I  get  more  of  a  sense 
that  it  works  than  with  other  visual 
programming  systems  I’ve  looked  at. 
The  icons  and  the  dataflow  links  that 
tie  them  together  do  make  a  lot  of 
sense.  Working  with  the  system  actu¬ 
ally  makes  programming  feel  more  like 
building  a  structure  from  components, 
and,  at  least  in  the  simple  examples 
I’ve  played  with,  gives  me  a  clearer 
sense  of  the  structure  of  the  program 
than  I  get  from  programming  in  a  con¬ 
ventional  language.  A  moderately  com¬ 
plex  application  might  be  another  mat¬ 
ter  entirely. 

I  also  like  the  commenting  style  built 
into  the  system.  Since  the  program  it¬ 
self  consists  of  graphical  elements  — 
structures  of  boxes  —  the  snatches  of 
text  pasted  next  to  the  boxes  or  in  the 
margins  stand  out  much  more  than  I’ve 
seen  comments  stand  out  in  any  con¬ 
ventional  code.  They  are  clearly  in  a 
different  language.  The  message  that 
comes  through  is:  If  it’s  a  block  of  text, 
it’s  a  comment. 

The  dataflow  model  is  inherently  con¬ 
current,  and  it’s  a  fine-grained  concur¬ 
rency  based  on  data  availability.  That's 
true  of  any  dataflow  system,  and  it  is 
completely  academic  on  a  single  pro¬ 
cessor  machine  like  the  Mac,  but  TGSSys- 
tems  hints  at  the  likelihood  of  making 
use  of  the  concurrency  in  some  future 
release  that  would  support  a  parallel 
processing  architecture,  though  not  nec¬ 
essarily  in  an  Apple  box.  I  had  won¬ 


dered  how  dataflow  specification 
matches  with  object-oriented  program¬ 
ming,  and  got  at  least  a  partial  answer 
in  the  fact  that  Prograph  allows  the 
data  that  flows  along  the  links  to  be 
instances  of  object-oriented  classes,  as 
well  as  elementary  data  types.  More 
than  one  data  item  can  be  passed  along 
a  link,  with  the  node  receiving  this 
pool  of  data  recognizing  the  value  it 
needs  and  selecting  it:  This  is  dynamic 
dataflow. 

There’s  an  interesting  point  about 
Prograph’s  positioning.  The  marketing 
copy  on  the  box  explicitly  refers  to 
HyperCard.  This  is  curious,  because 
Prograph  is  clearly  more  powerful  and 
more  complex  than  HyperCard  and 
other  products  of  that  hyperilk.  The 
point  seems  to  be  to  project  it  as  falling 
midway  between  HyperCard  and  Pas¬ 
cal  or  C  on  some  spectrum.  TGSSys- 
tems  calls  Prograph  a  very  high-level 
language  and  a  fifth-generation  tool. 

Perhaps  what  they  have  in  mind  in 
invoking  HyperCard  is  the  Application 
Builder.  This  is  a  toolkit  of  editors  and 
OOP  classes  for  building  Mac  applica¬ 
tions.  It’s  purely  an  alternative  for  be¬ 
ginners  or  for  those  occasions  when 
building  from  the  ground  up  is  not 
necessary,  but  it  does  give  Prograph 
the  aspect  of  an  application  generator. 
This  should  aid  the  new  Mac  devel¬ 
oper,  for  whom  the  advice  has  always 
been:  First,  read  Inside  Macintosh  Vol¬ 
umes  1-5  (and  counting).  With  Pro¬ 
graph’s  approach,  a  developer  ought 
to  be  able  to  start  programming  and 
refer  to  IM  as  needed.  And  it  may  ex¬ 
plain  the  reference  to  HyperCard. 

Hypertext  and  Hyperstuff 

One  thing  that  Prograph  doesn’t  claim 
to  be  is  hypertext.  I  don’t  know  why 
not;  everybody  in  the  world  seems  to 
be  jumping  on  that  bandwagon.  Hy¬ 
pertext  is  creeping  into  everything  I 
read.  There  is  definitely  something  there, 
but  the  hype  can  be  off-putting.  The 
best  source  I  know  of  on  the  subject, 
touching  on  its  roots  and  underlying 
philosophy  and  current  implementa¬ 
tions,  is  Macintosh  Hypermedia  by  Mi¬ 
chael  Fraase  (Scott,  Foresman,  1990). 
Too  bad  it’s  Mac-specific. 

I  don’t  recommend  the  book  The 
Society  of  Text  (Edward  Barrett,  ed., 
MIT  Press,  1989)  unless  you’re  really 
into  hypertext.  It  seems  to  be  oriented 
toward  academics  first  and  people  who 
work  with  text  second;  not  toward  soft¬ 
ware  authors  at  all.  I  do  recommend 
one  particular  article  in  the  book, 
though,  to  any  readers  who  suspect 
that  they  might  find  themselves  pressed 
against  their  will  to  incorporate  a  hy¬ 
pertext  approach  into  some  software 
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(continued  from  page  114) 
project.  It’s  “The  Missing  Link:  Why 
We’re  All  Doing  Hypertext  Wrong”  by 
Norman  Meyerowitz,  and  it  could  help 
to  argue  your  way  out  of  something 
you  don’t  want  to  do. 

Meyerowitz’s  view  is  that  hypertext 
has  to  be  integrated  into  the  operating 
system  before  it  really  makes  sense. 
What  we  have  now,  he  says,  are  insular 
tools  that  may  solve  some  specific  prob¬ 
lem  but  that  aren’t  what  he  has  in  mind 
when  he  thinks  of  hypertext.  Hyper¬ 
Card  may  not  be  the  best  example  of 
the  hypertext  state  of  the  art,  but  it 
amply  demonstrates  Meyerowitz’s  con¬ 
cerns.  You  can  do  hypertextish  things 
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in  HyperCard,  but  the  problem  is  that 
you  have  to  be  in  HyperCard  to  do 
them.  And  what  you  probably  want, 
or  would  want  if  you  really  knew  why 
you  should  want  to  do  hypertextish 
things,  is  to  do  them  where  you  are 
with  what  you’ve  got. 

Meyerowitz,  who  heads  Brown  Uni¬ 
versity’s  Intermedia  project  in  hypertext 
or  hypermedia,  has  the  credentials  to 
make  his  view  of  what  hypertext  is 
supposed  to  be  worth  noting.  What 
he  thinks  is  required  is  to  tie  the  hy- 
pertexting  into  the  operating  system, 
and  the  way  to  do  that  is  to  add  the 
element  of  a  navigational  link  at  the 
appropriate  operating  system  level.  Mey¬ 


erowitz  takes  this  to  be  the  level  of 
desktop  tools  in  Windows  or  the  Mac 
or  similar  GUI  systems.  Meyerowitz  and 
his  colleagues  have  actually  imple¬ 
mented  such  links  in  their  Intermedia 
system,  but  this  is  a  case  of  prototyping 
the  future,  to  use  his  words.  The  fact 
is,  existing  operating  systems  don’t  have 
such  navigational  links,  therefore  they 
can’t  support  true  hypertext,  and  any¬ 
thing  short  of  true  hypertext  is  just  pseu¬ 
dohypertext,  or  in  other  words,  just  the 


When  the  grumbling 
stops  and  everything 
settles  down,  we’ll 
have  a  better  idea 
what  HyperCard’s 
future  will  be 


current  fad.  That,  anyway,  is  an  argu¬ 
ment  that  you  can  use. 

Since  I  have  previously  in  this  col¬ 
umn  mentioned  ToolBook,  Asymetrix’s 
HyperCard-like  product  for  Windows 
3.0,  I’ll  pass  on  the  news  that  Asymetrix 
is  shipping  its  ToolBook  Author’s  Re¬ 
source  Kit  (ARK)  for  $450.  The  ARK 
includes  a  master  copy  of  the  runtime 
version  of  ToolBook  and  a  license  to 
distribute  royalty-free  copies  of  the  run¬ 
time  version  and  the  DLLs  included 
with  the  full  version  of  ToolBook.  It 
also  includes  tech  support,  a  utility  pro¬ 
gram  for  examining  and  changing  prop¬ 
erties  of  books  you  create  with  Tool¬ 
Book,  online  books  of  ideas  on  design, 
and  Script  Remover,  an  application  that 
lets  you  remove  the  readable  source 
from  your  ToolBook  application,  be¬ 
fore  distributing  them.  The  telepl  ine 
number,  if  you  want  to  order  the  ARK 
or  to  find  out  about  the  developer  pro¬ 
gram,  is  206-637-1500. 

And  while  we’re  on  the  subject,  Hy¬ 
perCard  itself  will,  I  suspect,  begin  to 
evolve  into  clearly  distinguished  user 
and  developer  versions,  now  that  it  is 
a  Claris  product. 

A  poorly  written  press  release  re¬ 
sulted  in  a  MacWeek  story  to  the  effect 
that  Apple  would  be  selling  a  crippled 
version  with  new  systems,  basically  a 
runtime  HyperCard,  with  the  developer 
version  available  at  a  competitive  price. 
Since  anything  that  could  be  consid¬ 
ered  competitive  with  HyperCard  costs 
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(continued  from  page  116) 
an  order  of  magnitude  more  than  Hy¬ 
perCard,  and  since  the  HyperCard  user 
community  felt  that  it  had  a  moral  com¬ 
mitment  from  Apple  that  HyperCard 
would  continue  to  be  distributed  like 
system  software,  this  did  not  go  over 
well.  I  read  the  press  release,  and  the 
confusion  was  all  Apple’s  fault. 

The  true  story  is  —  but  come  to  think 
of  it,  I  only  know  what  the  true  story 
is  this  week.  Apple’s  reingestion  of  Claris 
seems  not  to  be  proceeding  altogether 
smoothly,  and  there  may  be  further 
burps.  When  the  grumbling  stops  and 
everything  settles  down,  we’ll  have  a 
better  idea  what  HyperCard’s  future  will 
be.  It  appears,  though,  that  Claris  knows 
that  if  it  is  going  to  create  two  versions 
of  HyperCard,  it  should  do  so  by  add¬ 
ing  functionality  to  the  developer  ver¬ 
sion,  not  by  removing  it  from  the  user 
version. 

Holiday  Reading 

1  have  discussed  fractal  flora  here  in 
past  columns.  Anyone  interested  in  pur¬ 
suing  the  topic  of  how  fractal  graphics 
can  be  applied  to  the  study  and  simula¬ 
tion  of  plant  structure  and  growth 
should  get  hold  of  The  Algorithmic 
Beauty  of  Plants ,  by  Przemyslaw 
Prusinkiewicz  and  Aristid  Lindenmayer 
(Springer- Verlag,  1990).  It’s  a  beautiful 
book,  as  well  as  a  good  presentation 
of  the  major  algorithms  in  this  field.  It 
is  based  on  Aristid  Lindenmayer’s  L- 
systems  approach,  which  I  was  sur¬ 
prised  to  learn  dates  back  to  1968.  The 
book  deals  with  modeling  plant  devel¬ 
opment,  particular  plant  organs  and 
cellular  structures,  as  well  as  produc¬ 
ing  animated  displays  of  plants  grow¬ 
ing.  The  dust  jacket  describes  the  sub¬ 
ject  matter  as  an  attempt  to  re-create 
the  structures  of  life ,  and  that  seems 
pretty  accurate  to  me. 

The  authors  supply  enough  theory 
and  pseudocode  to  make  their  points 
clear,  but  there  are  no  type-and-run 
examples.  In  fact,  the  system  that  the 
authors  used  to  produce  the  beautiful 
plant  forms  reproduced  in  the  book  is 
not  something  they’d  be  likely  —  or 
able  —  to  reproduce  in  the  book.  It 
sounds  interesting  enough  to  justify  a 
book  on  its  own.  The  authors  refer  to 
the  system  as  a  virtual  laboratory,  a 
microworld  which  can  be  explored  un¬ 
der  the  guidance  of  a  hypertext  system. 
Yeah,  hypertext  again.  By  microworld, 
they  mean  an  interactive  environment 
for  creating  and  coytducting  simulated 
experiments. 

They  got  the  basic  ideas  for  their 
virtual  laboratory  from  Ted  Nelson’s 
Computer  Lib/Dream  Machines  (their 
reference:  Ted  Nelson,  1974;  latest  edi¬ 
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tion,  Tempus  Books,  Microsoft  Press, 
1987).  Ted  Nelson,  as  the  whole  world 
knows,  coined  the  term  hypertext  and 
has  devoted  more  energy  to  its  achieve¬ 
ment  than  anyone  else  in  the  world. 
And,  just  to  make  sure  I  get  all  the  links 
linked,  I  should  mention  that  Norman 
Meyerowitz  took  over  Brown  Univer¬ 
sity’s  hypertext  research  from  Andries 
van  Dam,  who  codesigned  the  world’s 
first  hypertext  editing  system  in  1967 
with  Ted  Nelson  and  a  group  of  Brown 
undergraduates. 

Wherever  they  got  the  idea,  the  vir¬ 
tual  laboratory  sounds  nifty.  I  wish  some¬ 
one  would  buy  me  one  for  Christmas. 
The  book  is  pretty  enough  to  be  a  gift, 
though.  See  if  you  can  get  someone  to 
buy  it  for  you. 

Shared  Minds  by  Michael  Shrage  (Ran¬ 
dom  House,  1990)  is  a  book  worth 
taking  a  look  at  for  what  it  has  to  say 
about  the  future  direction  of  software 
development.  It’s  a  nontechnical  treat¬ 
ment  of  the  phenomenon  of  collabora¬ 
tive  computing:  groupware  and  such¬ 
like  stuff.  What  Shrage  has  to  say  about 
collaborative  efforts,  particularly  in  sci¬ 
ence,  runs  counter  to  a  widespread 
spirit  of  do-it-yourself-ism  in  the  per¬ 
sonal  computer  field.  As  someone  who 
has  been  in  deep  retreat  from  collabo¬ 
rative  efforts  for  the  past  three  years,  I 
found  that  it  made  me  think  a  little 
more  deeply  about  individual  vs.  group 
efforts.  It  may  make  you  question  some 
of  your  deeply  held  rugged  individual¬ 
ism,  or  it  may  make  you  mad,  or  it  may 
make  a  lot  of  sense.  In  any  case,  it 
makes  good  leisure-time  reading.  The 
Mac  Is  Not  a  Typewriter  by  Robin  Wil¬ 
liams  (a  different  Robin  Williams)  (Peach¬ 
pit  Press,  1990)  is  not  a  book  that  DDJ 
readers  need  to  read,  but  it  is  an  excel¬ 
lent  gift  book  for  anyone  you  know 
who  is  nontechnical  and  is  getting  to 
know  the  Macintosh.  It’s  filled  with 
simple  but  useful  advice  on  producing 
printed  output  from  the  Mac  that  even 
professionals  may  not  handle  well. 
Things  like  not  double-spacing  after 
periods,  using  real  quotes  and  apostro¬ 
phes,  handling  punctuation  and  paren¬ 
theses,  advice  on  typefaces:  It’s  not  a 
complete  treatise  on  grammar  or  type 
handling,  but  a  wise  selection  of  the 
most  helpful  tips  for  the  broadest  pos¬ 
sible  audience.  It’s  a  quick  read,  and 
only  costs  $9  95.  Give  it  to  someone 
you  like  about  that  much. 

See  you  next  year! 

DDJ 
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The  B-tree 
Again 


In  the  June  1990  issue  on  hypertext, 
I  published  a  program  that  used  a 
subset  of  the  B-tree  algorithm  to 
build  a  HyperTree  index  into  a  text 
file.  That  algorithm  lacked  many  of  the 
features  of  a  complete  B-tree,  because 
it  was  dedicated  to  a  single  purpose, 
the  construction  and  search  of  a  static 
index  into  text.  The  B-tree  code  I  used 
was  an  adaptation  of  some  B-tree  algo¬ 
rithms  from  a  book  I  wrote  about  using 
the  C  language  to  describe,  build,  and 
maintain  databases.  I  am  writing  a  sec¬ 
ond  edition  of  the  book  now  to  up¬ 
grade  the  code  and  techniques  to  the 
facilities  of  ANSI  C,  and  this  column  is 
a  preview  of  the  B-tree  code  as  it  will 
appear  in  the  new  work. 

You  don’t  need  all  the  code  in  the 
book  to  use  these  algorithms.  As  with 
most  of  the  code  I  develop  and  pub¬ 
lish,  the  B-tree  functions  are  stand¬ 
alone  C  tools  for  you  to  use  anywhere 
you  need  a  B-tree  solution. 

What  is  a  B-tree? 

The  B-tree  algorithm  was  developed 
in  1970  by  R.  Beyer  and  E.  McCreight. 
It  is  a  tree-structured  index  mechanism 
that  is  balanced  and  that  is  self-tend¬ 
ing.  First  some  definitions.  (My  pal, 
Tommy  Saunders,  the  great  Dixieland 
cornet  player,  tells  a  story  about  bee 


Al  Stevens 


trees.  These  B-trees  are  different, 
Tommy.) 

A  “tree”  is  a  multilayered  hierarchy 
of  “nodes.”  There  is  one  “root”  node 
at  the  top.  The  root  is  the  “parent” 
node  to  the  “child”  nodes  at  the  next 
level  down.  Nodes  contain  key  values 
which  deliver  corresponding  data  val¬ 
ues.  Each  parent  node  can  have  multi¬ 
ple  child  nodes,  and  any  child  node 


can  have  no  more  than  one  parent.  The 
nodes  at  the  bottom  of  the  hierarchy 
contain  all  the  data  values  for  the  keys, 
even  if  the  key  values  are  in  nodes  at 
higher  levels.  Therefore,  the  data  val¬ 
ues  themselves  are  the  “leaves.”  Usu¬ 
ally  the  leaves  are  vectors  to  records 
in  a  file  where  the  data  elements  asso¬ 
ciated  with  the  key  values  exist. 

A  balanced  tree  is  one  where  all  the 
paths  from  the  root  to  the  leaves  de¬ 
scend  the  same  number  of  levels.  A 
self-tending  tree  is  one  where  the  tree 
balance  is  maintained  by  the  addition 
and  deletion  algorithms;  the  tree  needs 
no  extra  tree-balancing  procedures. 

A  B-tree  node  contains  a  fixed  maxi¬ 
mum  number  of  keys  referred  to  as  m. 
The  algorithm  assures  that  each  node, 
except  the  root,  will  have  at  least  m/2 
keys.  The  root  can  have  from  one  to 
m  keys.  When  the  root  is  empty,  the 
tree  is  empty.  When  the  root  is  the  only 
level  of  the  tree,  the  root  itself  contains 
the  leaves. 

The  B-tree  has  another  interesting 
property.  You  can  search  the  tree  for 
an  arbitrarily  chosen  key  value.  This 
search  is  random  retrieval.  You  can 
navigate  the  same  tree  in  the  sequence 
of  the  keys  in  either  direction  starting 
from  any  given  key.  This  search  is  se¬ 
quential  retrieval.  You  can,  therefore, 
locate  a  chosen  key  value  and  proceed 
from  there  through  the  keys  in  ascend¬ 
ing  or  descending  sequence.  This  mix 
is  often  called  Indexed  Sequential  Ac¬ 
cess  Method  (ISAM),  a  phrase  I  first 
heard  in  the  1960s  used  for  mainframe 
Cobol  files.  The  B-tree  algorithms  post¬ 
date  ISAM,  but  many  ISAM  implemen¬ 
tations  use  B-trees.  Figure  1  illustrates 
a  simple  B-tree.  It  uses  letters  of  the 
alphabet  as  keys  and  the  words  of  the 
phonetic  alphabet  as  data  values.  In 
this  example,  m  is  2,  but  most  B-trees 
will  have  a  much  higher  m  value. 


A  node  contains  key  values  and  vec¬ 
tors.  The  vectors  in  the  root  and  subor¬ 
dinate  nodes  are  pointers  to  nodes  in 
the  next  lower  level  in  the  tree.  The 
vectors  in  the  lowest  level  are  the  leaves, 
and  these  usually  point  to  the  data 
records.  The  keys  in  each  node  are  in 
ascending  collating  sequence  so  that  a 
search  can  proceed  from  left  to  right. 
Some  B-tree  implementations  have  large 
m  values  and  use  a  binary  search  to 
search  each  node. 

A  node  has  one  more  vector  than  it 
has  key  values.  Each  key  value  has  a 
vector  that  points  to  the  nodes  with 
key  values  less  than  this  one  and  an¬ 
other  vector  that  points  to  the  key  value 
greater  than  this  one.  Look  at  Figure  1. 
The  root  node  has  the  key  value  “I” 
and  two  vectors.  The  first  vector  points 
to  the  node  with  keys  “C”  and  “F” 
while  the  second  vector  points  to  the 
node  with  “L”  and  “O.” 

The  tree  in  Figure  1  has  three  levels. 
The  vectors  from  the  third  level  are 
leaves  that  point  to  the  data  records 
that  contain  the  data  values  (phonetic 
alphabet  words)  associated  with  the 
keys  (letters  of  the  alphabet). 

There  is  room  for  confusion  here. 
Earlier  I  said  that  the  leaves  were  the 
data  values.  Now  I  am  saying  that  they 
are  pointers  to  the  data  values.  The 
B-tree  delivers  its  answer  in  the  form 
of  the  leaf  associated  with  the  key  value. 
The  leaf  can  be  whatever  you  want  it 
to  be.  But  to  simplify  the  architecture 
of  the  B-tree,  a  leaf  should  resemble  a 
vector  so  that  the  format  of  the  nodes 
at  the  lowest  level  is  the  same  as  the 
format  of  nodes  at  higher  levels.  Usu¬ 
ally  the  leaf  points  to  a  record  in  an¬ 
other  file,  and  the  file  can  be  in  random 
order.  Access  to  the  file  is  a  function 
of  retrievals  from  the  index. 

The  structure  we  are  discussing  looks 
like  an  inverted  tree.  The  root  is  at  the 
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top,  and  the  leaves  are  at  the  bottom,  fore  point  to  more  than  one  file  record,  department.  In  that  case,  the  Depart- 
Because  of  this  metaphor,  such  indexes  A  database  record  usually  has  a  “pri-  ment  Number  index  into  the  Employee 
are  called  “inverted”  indexes.  As  you  mary  key”  value  that  uniquely  identi-  File  must  support  duplicate  values  be- 
might  expect,  you  can  have  more  than  fies  the  record.  The  Employee  File  has  cause  many  employees  can  work  in 

one  inverted  index  into  a  data  file.  Any  one  record  per  Employee  Number.  The  the  same  department.  A  data  element 

data  element  or  combination  of  data  index  for  the  primary  key  must  not  with  an  index  that  supports  multiple 
elements  in  a  file  can  become  the  keys  allow  duplicate  key  values  because  only  key  values  is  a  “secondary  key.” 
to  an  index.  The  leaf  vector  would  point  one  employee  can  have  a  given  Em- 
to  the  file  record  that  matches  the  key.  ployee  Number.  But  an  employee  rec-  Searching  a  B-tree 

A  B-tree  can  support  duplicate  key  ord  might  also  have  the  Department  A  B-tree  search  starts  with  a  key  argu- 
values.  This  feature  allows  one  key  Number,  and  you  might  want  to  re-  ment  and  delivers  either  the  leaf  or  the 

value  to  have  several  leaves  and  there-  trieve  all  the  employees  for  a  given  fact  that  the  argument  does  not  exist 
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( continued  from  page  122) 
in  the  B-tree.  Look  at  Figure  1  again. 
Every  search  begins  at  the  root  node 
because  the  algorithms  can  always  find 
it.  To  search  for  the  value  K  you  read 
the  root  node  and  search  it.  If  you  find 
the  value,  you  are  almost  done.  If  not, 
you  must  proceed  to  the  next  level. 
To  proceed  down,  you  use  the  vector 
that  sits  after  the  next  lower  key  and 
before  the  next  higher  key  in  the  cur¬ 
rent  node.  In  this  case,  the  root  has  only 
the  value  /,  so,  by  using  the  vector  just 
past  it,  you  retrieve  the  LO  node  in  it 
and  begin  the  search  again.  This  search 
continues  until  you  either  find  the  value 
or  are  at  the  lowest  level.  You  would 
find  /at  the  bottom  level,  so  the  vector 
just  to  the  right  of/  is  its  associated  leaf 
and  does,  in  fact,  point  to  the  data 
record  that  contains  the  value  JULIET. 

The  search  is  slightly  more  complex 
when  the  argument  matches  a  key  in  a 
higher  level.  If  you  were  searching  for 
C the  search  would  stop  at  the  CY-'node 
on  the  second  level.  The  vector  just 
past  C  is  not  a  leaf.  It  points  to  a  lower 
node.  When  this  happens,  you  use  the 
vector  to  read  the  lower  node.  The 
leftmost  vector  in  that  node  is  the  one 
you  want.  You  keep  reading  nodes  by 
using  the  leftmost  vector  until  you  get 
to  the  lowest  level.  The  leftmost  vector 


in  the  lowest  level  is  the  leaf  for  the 
argument.  Observe  that  to  find  /  you 
read  the  LO  node,  use  its  leftmost  vec¬ 
tor  to  read  the  JK  node,  then  use  its 
leftmost  vector  as  the  leaf  that  points 
to  INDIA. 

A  balanced  tree  is  one 
where  all  the  paths  from 
the  root  to  the  leaves 
descend  the  same 
number  of  levels 


Adding  a  Key  to  the  B-tree 

When  you  want  to  add  a  key  to  a  B-tree 
you  must  provide  the  key  value  and 
the  leaf  value  to  the  insertion  algo¬ 
rithm.  For  a  database  application,  you 
might  be  adding  a  record,  so  the  leaf 
might  be  the  number  of  the  database 
record. 

To  add  a  key  you  must  search  for  it 
first.  If  it  exists,  you  must  see  if  the 
B-tree  supports  multiple  key  values. 
Some  will  not,  particularly  those  desig¬ 


nated  for  the  primary  key  of  a  database 
file.  If  the  value  exists  and  the  index  is 
for  unique  values,  the  key  addition  pro¬ 
cedure  must  return  an  error  indication. 
If  the  value  does  not  exist  or  the  tree 
allows  duplicates,  you  will  insert  the 
key  in  the  tree. 

Key  insertion  always  begins  at  the 
lowest  node  level.  If  you  found  the  key 
in  a  higher  level,  you  must  navigate  to 
the  lowest  level  where  the  matching 
key’s  leaf  is  kept.  If  you  did  not  find  the 
key,  the  search  ended  in  the  lowest 
level  at  the  place  where  the  key  goes 
and  that  is  where  you  insert  the  key. 

You  insert  the  key  and  leaf  in  the 
node  in  its  collating  sequence.  If,  after 
the  insertion,  the  node  still  has  m  or 
fewer  keys,  the  insertion  is  done.  If, 
however,  the  node  now  has  m+1  keys, 
the  node  must  split. 

Splitting  the  node  involves  building 
a  new  node  and  copying  the  second 
half  of  the  keys  into  it,  leaving  the  first 
half  in  the  original  node.  The  key  at  the 
center  of  the  split  must  be  inserted  into 
the  parent  of  the  original  node  with  a 
vector  to  the  new  node.  That  insertion 
uses  the  same  code  as  the  first  one,  so 
the  splitting  and  growth  of  the  B-tree 
proceeds  upwards  to  the  root.  When 
the  root  fills  and  splits,  the  algorithm 
builds  a  new  root  with  only  one  key. 

Deleting  a  Key  from  the  B-tree 

Key  deletion  always  occurs  at  the  low¬ 
est  level.  If  the  key  to  be  deleted  is  in 
a  higher  node,  you  navigate  down  to 
the  lowest  node,  move  its  leftmost  key 
value  over  the  top  of  the  key  value  to 
be  deleted,  and  then  proceed  to  delete 
the  leftmost  key  from  the  lowest-level 
node. 

To  maintain  tree  balance,  the  delete 
algorithm  looks  at  the  two  nodes  on 
either  side  of  the  current  one  at  the 
same  level.  These  nodes  are  siblings 
to  the  current  ones.  If  possible,  the 
algorithm  redistributes  the  keys  between 
the  current  node  and  one  of  its  sib¬ 
lings.  Further,  if  the  keys  of  the  two 
nodes  would,  as  a  result  of  the  dele¬ 
tion,  fit  into  one  node  with  room  for 
one  more,  the  algorithm  combines  the 
keys  from  both  nodes  with  the  key 
from  their  mutual  parent,  and  deletes 
one  of  the  nodes.  The  key  must  be 
deleted  from  the  parent,  a  procedure 
that  repeats  the  delete  algorithm,  al¬ 
lowing  the  tree  to  shrink  in  height  as 
keys  depart. 

The  B-tree  Code 

There  are  three  source  files  for  the  B- 
tree  functions.  Listing  One,  page  142, 
is  database. h,  a  file  that  includes  those 
elements  from  the  larger  database  sys¬ 
tem  that  the  B-tree  functions  use.  If 
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Function  Description 


void  build_b(char  ‘name,  int  len) 

This  function  builds  a  B-tree  file  with  a  file  name  specified  in  the  name 
parameter.  The  len  parameter  specifies  the  length  of  a  key.  The  function 
creates  the  file,  computes  and  writes  all  the  initial  values  for  the  header 
record,  and  closes  the  file. 

int  btree_init(char  ‘ndx_name) 

After  you  have  created  a  B-tree  with  build  b,  you  can  use  it  in  other 
programs  by  calling  btreejnit.  The  name  parameter  matches  the  name 
you  created  the  B-tree  with.  The  function  returns  -1  if  the  B-tree  does 
not  exist,  if  it  is  locked,  or  if  you  have  the  maximum  number  of  B-trees 
already  open  as  defined  in  btree.h  by  the  global  MXTREES  variable. 
Otherwise,  the  function  opens  the  file,  locks  it,  and  returns  an  integer 
tree  number  that  you  will  use  in  all  subsequent  function  calls  related  to 
this  B-tree. 


int  btree_close(int  tree) 

This  function  closes  and  unlocks  the  B-tree. 


RPTR  locate(int  tree,  char  *k) 

This  is  the  key  search  function.  You  provide  a  pointer  to  a  key  value,  and 
the  function  returns  the  leaf  vector  if  a  match  exists  and  a  zero  vector  if 
it  does  not.  The  database. h  file  defines  the  RPTR  variable  type.  It  is  an 
integral  type,  and  its  width  defines  the  range  of  leaf  values. 

int  deletekey(int  tree,  char  *x,  RPTR  ad) 

This  is  the  function  to  delete  a  key  from  the  B-tree.  You  pass  a  character 
pointer  for  the  key  and  the  RPTR  vector  that  matches  the  one  you  want 
to  delete.  This  parameter  allows  the  function  to  differentiate  between 
multiple  keys. 

int  insertkeyfint  tree,  char  *x,  RPTR  ad,  int  unique) 

This  function  adds  the  specified  key  value  and  its  RPTR  leaf  value  to  the 
tree.  The  unique  parameter  is  TRUE  if  the  key  value  must  be  unique, 
and  FALSE  otherwise.  If  you  attempt  to  add  a  key  that  exists  when  the 
unique  indicator  is  TRUE,  the  function  returns  -1 . 

RPTR  firstkey(int  tree) 

RPTR  lastkey(int  tree) 

RPTR  nextkey(int  tree) 

RPTR  prevkey(int  tree) 

These  four  functions  navigate  the  B-tree.  The  first  two  functions  position  the 
navigation  at  the  beginning  or  end  of  the  tree  in  its  collating  sequence  and  return 
the  RPTR  vectors  that  match  those  positions.  If  the  B-tree  is  empty,  these  functions 
return  a  zero  RPTR.  The  other  two  functions  move  either  forward  or  backward  to 
the  next  sequential  key  value  returning  the  associated  RPTR.  You  can  use  these 
functions  following  locate,  firstkey,  lastkey,  or  each  other.  They  return  the  RPTRs 
associated  with  the  new  positions.  If  you  call  nextkey  when  you  are  already 
positioned  at  the  last  key  or  prevkey  when  you  are  already  positioned  at  the  first 
key,  the  functions  will  return  a  zero  RPTR. 

RPTR  currkey(int  tree) 

This  function  returns  the  RPTR  for  the  current  key  position, 
void  keyvalfint  tree,  char  *ky) 

This  function  copies  the  key  value  of  the  current  key  position  into  the 
string  pointed  to  by  the  ky  parameter. 


Table  1:  B-tree  functions 


(continued  from  page  124) 
we  go  further  into  this  technology  in 
future  columns,  we  will  need  to  re¬ 
place  this  file.  Listing  Two,  page  142, 
is  btree.h,  the  header  file  that  describes 
the  format  of  the  B-tree  records  as  well 
as  the  prototypes  for  the  functions  that 
external  programs  would  call.  Listing 

The  delete  algorithm 
looks  at  the  two  nodes 
on  either  side  of  the 
current  node  at  the 
same  level,  and 
redistributes  the  keys 
between  the  current 
node  and  one  of 
its  siblings 


Three,  page  142,  is  btree.c,  the  code 
that  implements  B-trees. 

The  treehdr  structure  in  btree.h  de¬ 
scribes  the  header  record  at  the  front 
of  every  B-tree.  The  rootnode  item  is  a 
vector  to  the  root  node.  The  keylength 
item  is  the  length  of  each  key.  Keys  in 
this  B-tree  implementation  are  a  fixed 
length.  The  m  variable  is  the  m  value 
of  the  B-tree. 

The  next  two  elements,  rlsed_node 
and  endnode ,  support  the  file  mainte¬ 
nance  of  the  B-tree.  Nodes  come  and 
go  as  you  insert  and  delete  keys.  The 
rlsedjnode  variable  is  a  vector  to  the 
first  in  a  linked  list  of  deleted  nodes. 
When  the  addition  algorithm  adds  a 
new  node,  it  takes  an  entry  from  this 
list  if  one  exists.  If  not,  it  appends  the 
new  node  onto  the  B-tree  file  and  in¬ 
crements  the  endnode  variable.  This 
technique  reuses  deleted  nodes  to  elimi¬ 
nate  unnecessary  tree  growth. 

The  locked  variable  indicates  that  the 
B-tree  is  in  use.  The  function  that  initi¬ 
ates  B-tree  processing  sets  this  flag  and 
writes  the  header  record  back  to  the 
file.  The  function  that  terminates  pro¬ 
cessing  clears  the  flag.  Because  B-tree 
integrity  is  a  multirecord  matter  and 
because  nodes  and  the  header  hang 
around  in  memory  until  they  need  to 
be  written,  a  system  failure  could  com¬ 
promise  the  integrity  of  the  index.  The 
program  will  not  allow  you  to  use  a 
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B-tree  that  is  locked. 

The  leftmost  and  rightmost  vectors 
point  to  the  leftmost  and  rightmost  nodes 
in  the  B-tree  as  viewed  in  its  collating 
sequence.  These  vectors  allow  immedi¬ 
ate  access  to  either  end  of  the  tree. 

The  treenode  structure  describes  the 
format  of  a  node  record.  Each  node  has 
some  header  information  of  its  own 
followed  by  the  list  of  keys  and  vec¬ 
tors.  The  nonleaf  v ariable  is  zero  if  the 
node  is  at  the  lowest  level  of  the  tree, 
non-zero  otherwise.  The prntnode vec¬ 
tor  points  to  the  parent  node  for  this 
node.  If  this  vector  is  zero,  the  node  is 
the  root  node,  the  only  one  without  a 
parent.  The  Ifsib  and  rtsib  vectors  point 
to  the  left  and  right  sibling  nodes  for 
the  current  node.  The  keyct  variable  is 
the  number  of  keys  currently  recorded 
in  the  node.  The  keyO  vector  is  the 
vector  that  will  be  to  the  left  of  the 
leftmost  key  in  the  node  and  that  points 
to  the  node  containing  keys  less  than 
all  keys  in  this  node.  The  keyspace 
array  is  the  space  for  the  keys  and 
vectors.  This  space  is  dynamically  dis¬ 
tributed  according  to  the  key  length 
with  room  for  m  keys  and  m  vectors. 
The  spil  space  is  in  the  structure  to 
allow  key  insertion  to  go  to  m+1  keys 
prior  to  a  split  but  is  not  a  part  of  the 
node  in  the  B-tree  file. 

The  functions  in  btree.c  implement 
the  B-tree  algorithms  in  a  way  that  al¬ 
lows  you  to  have  more  than  one  B-tree 
running  at  a  time.  If  you  use  an  operat¬ 
ing  system  such  as  MS-DOS  that  limits 
the  number  of  open  files  for  a  running 
program,  you  might  want  to  modify 
the  code  to  close  and  reopen  the  B-tree 
files  at  strategic  points. 

Table  1  lists  the  functions  that  you 
call  from  your  applications  program  to 
use  the  B-trees.  To  use  the  B-tree  func¬ 
tions,  you  must  write  a  program  that 
links  with  and  calls  these  functions. 
You  must  also  provide  a  simple  error¬ 
processing  function  named  dberrorthat 
does  not  return  to  the  caller.  There  are 
two  error  conditions  that  will  invoke 
dberror.  One  is  when  the  program  can¬ 
not  allocate  enough  heap.  The  other  is 
any  file  error  reading  or  writing  the 
B-tree  file.  These  error  conditions  place 
D_OM  and  D_IOERR,  which  are  de¬ 
fined  in  database.h,  into  the  global  ermo 
variable. 

There  are  many  other  functions  in 
btree.c,  ones  that  your  program  does 
not  call  but  which  are  used  internally 
by  the  algorithms.  The  btreescan  func¬ 
tion  scans  the  tree  for  a  match  on  the 
specified  key.  It  modifies  pointers  in 
the  calling  function  to  indicate  where 
the  scan  stops  and  returns  TRUE  or 
FALSE  depending  on  whether  it  found 
a  match  or  not.  It  calls  the  nodescan 
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function,  which  searches  individual 
nodes.  That  function  calls  compare_keys 
to  test  a  key  in  a  node  for  a  match  to 
an  argument  key.  The  fileaddr  func¬ 
tion  returns  the  leaf  value  for  the  cur¬ 
rent  key  position.  It  calls  the  leaflevel 
function  to  navigate  down  to  the  low¬ 
est  level  in  the  B-tree.  The  implode 
function  combines  the  keys  of  two  sib¬ 
ling  nodes,  and  the  redist  function  re¬ 
distributes  the  keys  of  two  sibling  nodes 
so  that  the  keys  are  evenly  distributed 
between  the  two.  The  adopt  function 
is  used  by  implode ,  redist ,  and  insert_key 
to  assign  a  new  parent  to  a  child  node. 
The  nextnode  function  gets  a  new  node 
vector  from  either  the  released  node 
linked  list  or  from  the  end  of  the  file 
to  be  assigned  to  a  new  node.  The 
scannext  and  scanprev  functions  do 
the  tree  navigation  for  nextkey  and 
prevkey.  The  childptr  function  reads 
the  parent  node  of  the  current  one  and 
positions  a  pointer  to  the  key  in  the 
parent  node  that  points  to  this  child. 
The  read_node  and  ivrite_node  func¬ 
tions  do  all  the  node  input/output  for 
the  functions.  They  both  use  the  bseek 
function  to  seek  to  the  node  position. 

Dear  Customer  #  00183882 

I  got  my  second  personal  letter  from 
Philippe  Kahn  today.  I  could  tell  it  was 
personal  because  it  was  signed  in  blue 
ink  in  Philippe’s  unmistakable  scrawl. 
The  only  other  celebrity  who  ever  sent 
me  such  a  personal  letter  was  Jerry 
Falwell.  He  wanted  money  too.  I  know 
Philippe's  letter  was  the  second  one 
he  sent  because  the  manilla  window 
envelope  has  a  big  red  SECOND  NO¬ 
TICE  stamp  on  it.  Philippe  thinks  that 
if  he  makes  my  neighbors,  the  mail¬ 
man,  and  my  bride  think  I’m  a  dead¬ 
beat  who  doesn’t  pay  his  bills,  I’ll  do 
whatever  he  asks  to  prevent  him  from 
sending  more  letters. 

Philippe  invited  me  as  a  registered 
user  of  Turbo  C  2.0  to  upgrade  to  Turbo 
C++  for  the  pittance  of  $79.95,  a  price 
reduction  from  his  earlier  personal  let¬ 
ter.  He  says  the  price  reduction  is  the 
result  of  the  overwhelming  response 
from  programmers  to  the  first  offering. 
The  law  of  supply  and  demand  has 
been  overturned,  I  guess.  Probably  an¬ 
other  innovative  rendering  of  the  Su¬ 
preme  Court. 

I  think  I’ll  wait  for  the  THIRD  AND 
FINAL  NOTICE  so  I  can  get  the  Ginsu 
knives. 

DDJ 

(Listings  begin  on  page  142.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  11. 
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The  Cuba 
Lake  Effect 


It  was  a  wonderful  trade:  Nancy  Kress 
taught  me  how  to  write  fiction,  and 
I  taught  her  how  to  use  computers. 
She  has  gone  on  to  win  the  coveted 
Nebula  Award  for  science  fiction,  and 
I,  well,  I’ve  gone  on  using  computers. 
But  now  I  can  write  a  character  that 
isn’t  part  of  the  ASCII  table.  A  good 
deal  all  the  way  around. 

Nan  published  a  story  some  years 
back  that  still  haunts  me.  In  “Down 
Behind  Cuba  Lake,”  the  protagonist  is 
travelling  through  rural  New  York  State 
to  make  amends  with  an  old  lover  with 
whom  she  has  had  —  and  broken  off  — 
a  disastrous  affair.  As  night  falls  she  is 
forced  off  the  main  highway  by  road 
construction  and  decides  to  cut  through 
the  back  roads  near  a  small  lake. 

The  first  back  road  she  takes  dead¬ 
ends  on  the  shore  of  the  lake.  No 
problem  —  back  roads  can  be  that  way. 
So  she  backtracks  and  tries  another 
dark,  twisting  road  —  and  again,  winds 
up  headlights  to  the  water.  Again,  she 
backtracks  —  and  again,  she  winds  up 
somewhere  down  behind  Cuba  Lake, 
on  a  dead-end  dirt  road  that  vanishes 
into  the  black  water.  No  matter  where 
she  goes,  or  how  far  she  follows  the 
increasingly  narrow  and  rough  dirt 
roads,  she  can’t  get  around  Cuba  Lake. 
Worse,  she  can’t  go  back. 


Jeff  Duntemann,  KI6RA/7 


It’s  an  exquisite  piece  of  low-key  psy¬ 
chological  horror.  What  it  means,  of 
course,  is  that  there  are  some  decisions 
you  simply  can’t  rescind,  and  the  more 
you  try,  the  deeper  in  trouble  you  get. 

You  Can't  Get  Out 

Nan  would  protest  that  she  doesn’t 
know  anything  about  programming,  but 
anybody  who’s  ever  gotten  lost  some¬ 


where  seven  levels  down  in  the  menu 
tree  of  an  elaborate  transaction-pro¬ 
cessing  application  would  swear  she’s 
been  there  too. 

What  I  call  the  “Cuba  Lake  Effect”  is 
something  that  almost  invariably  hap¬ 
pens  in  traditional  menu-tree  applica¬ 
tions  that  mix  modes  and  menus  with 
data  dependencies.  You  know,  things 
such  as  this:  You’re  editing  a  record, 
and  you  try  to  enter  a  Canadian  cus¬ 
tomer  from  the  Yukon  Territory,  prov¬ 
ince  code  “YT.”  Whoops,  undefined 
code  error  —  you  forgot  to  add  “YT” 
to  the  table  when  you  set  it  up.  (No¬ 
body  really  lives  up  there,  do  they? 
Yup,  they  do  .  .  .  .) 

The  table  maintenance  screen  is  up 
three  levels,  across,  and  down  two. 
You  hammer  the  ESC  key,  scoot  up 
three  screens,  and  back  down  into  ta¬ 
ble  maintenance  .  .  .  but  you  get  stopped 
cold:  You  can’t  edit  tables  while  you’re 
editing  records.  So  back  you  go,  up  a 
screen,  across,  and  down  three.  Then 
your  blood  runs  cold  as  you  remem¬ 
ber:  You  can’t  get  out  of  record  edit 
mode  without  closing  the  customer  file. 
You  can’t  close  the  customer  file  while 
the  current  record  edit  screen  is  in  an 
error  mode,  and  you  can’t  close  the 
record  edit  screen  without  deleting  the 
current  record,  and  you  can’t  delete  the 
current  record  without  going  through 
the  state/province  code  key  file  to  bring 
it  up  on  the  screen  again,  and  the  key 
for  the  current  record  is  in  an  error 
state  with  an  undefined  value  .... 

Get  me  out  of  here! 

Who  Chooses  the  Path? 

This  sort  of  nightmare  is  one  major 
reason  that  office  staffers  traditionally 
hate  computers.  What  I’ve  described 
is  a  common  situation  on  traditional 
mainframe  and  minicomputer  applica¬ 
tions.  Such  applications  begin  with  a 


top-level  menu  screen.  The  user  picks 
a  number,  and  goes  “down”  into  the 
next  level,  typically  another  menu,  and 
continues  until  some  sort  of  data  entry 
screen  or  report  definition  screen  is 
found.  There  are  a  number  of  paths 
from  the  top  level  down  to  the  leaves 
of  the  menu  tree,  but  every  path  is 
defined  by  the  structure  of  the  menus, 
and  may  be  constrained  by  modes  and 
data  dependencies.  If  you  change  some¬ 
thing  the  return  path  may  change.  It 
may  even  be  blocked. 

The  essence  of  a  system  such  as  this 
(which  is  about  as  hideous  a  way  of 
programming  as  I’ve  ever  seen)  is  that 
every  path  is  dictated  to  the  user.  Navi¬ 
gating  through  the  program  is  done 
strictly  on  the  program’s  terms.  In  a 
badly-designed  program  (which  in¬ 
cludes  most  minicomputer  and  nearly 
all  mainframe  software  I’ve  experienced) 
the  program’s  terms  don’t  necessarily 
include  the  imperative  that  the  user  be 
able  to  back  gracefully  out  of  any  op¬ 
eration  without  having  to  yell  for  help 
or  abort  the  whole  session. 

The  essence  of  writing  ergonomic 
software  is  giving  the  user  more  con¬ 
trol  of  what’s  going  on.  This  begins 
with  providing  the  user  near-absolute 
control  over  how  to  navigate  the  sys¬ 
tem.  Ideally,  this  should  be  the  differ¬ 
ence  between  having  to  follow  the  roads 
on  a  map  to  get  from  point  A  to  point 
B,  or  simply  having  to  put  your  finger 
over  point  B  on  the  map  and  saying,  “I 
want  to  be  here.”  It  is  the  difference 
between  the  view  from  the  inside  and 
the  view  from  a  height;  in  the  country 
of  the  flat,  the  3-D  view  is  king. 

Event-Driven  Architectures 

If  you’ve  lived  your  programming  life 
creating  endless  full-screen  menu  trees, 
your  first  impression  might  be  that  this 
is  impossible.  It’s  not  impossible  at  all, 
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but  like  object-oriented  programming, 
such  an  ideal  requires  a  whole  differ¬ 
ent  way  of  thinking  about  the  architec¬ 
ture  of  an  application.  This  new  archi¬ 
tecture  was  invented  by  Xerox,  bor¬ 
rowed  and  popularized  by  the  Macin¬ 
tosh  (to  the  extent  that  Apple  has  now 
convinced  itself  that  Apple  did  the  in¬ 
venting)  and  is  now  (with  Microsoft 
Windows  at  the  vanguard)  percolating 
through  most  commercial  applications 
for  DOS.  It’s  called  an  event-driven  ar¬ 
chitecture ,  and  if  you’re  not  using  it  yet 
you’re  already  way  behind  the  times. 

Rather  than  being  a  maze  of  full¬ 
screen  menus,  an  event-driven  applica¬ 
tion  is  typically  a  single  screen  with 
two  major  parts.  At  the  center  of  the 
application  (and  usually  at  the  center 
of  the  screen)  is  the  workspace.  This 


contains  some  representation  of  the 
work  that  is  being  done.  It  might  be  a 
technical  drawing,  a  spreadsheet,  a  docu¬ 
ment,  or  a  database  arranged  as  rows 
and  columns  of  records  and  fields.  All 
around  the  workspace  are  tools  that 
may  be  selected  to  manipulate  the  work¬ 
space  and  the  information  within  it. 

It  always  pays  to  have 
a  handle  on  what’s 
going  on  beneath  the 
surface 


The  user  selects  tools  either  from  the 
keyboard,  with  some  combination  of 
control  keys,  or  (much  more  appropri¬ 
ately)  with  a  mouse  cursor  that  zips 
around  the  screen  and  allows  the  user 
to  “click  on”  a  tool  when  the  mouse 
cursor  is  over  that  tool’s  representation 
on  the  screen.  This  representation  might 
in  fact  be  a  graphics  icon,  but  remem¬ 
ber  that  nothing  in  an  event-driven  ar¬ 
chitecture  limits  us  to  a  graphics  envi¬ 
ronment.  The  new  Turbo  C++  and 
Turbo  Pascal  6.0  environments  are 
mouse-based  and  truly  event-driven, 
yet  both  run  strictly  in  text  mode. 

A  Natural  for  Windows 

Nor  is  there  anything  in  an  event-driven 
architecture  that  requires  the  use  of 
windows,  but  windows  are  a  natural 
way  to  return  a  measure  of  control  to 
the  user  in  an  event-driven  system. 
Think  back  to  the  transaction  process¬ 
ing  nightmare  I  described  a  little  ear¬ 
lier.  In  an  event-driven  system,  the  user 
would  be  editing  records  in  the  central 
workspace  of  the  application.  (Editing 
records  is,  at  the  heart  of  it,  what  such 
transaction  processing  applications  are 
about.)  If  an  invalid  state  code  turned 
up,  the  user  would  simply  reach  out 
with  the  mouse  to  a  tools  icon  or  menu 
of  some  sort,  “grab”  the  codes’  editor, 
and  open  it  as  a  window,  either  beside 
or  even  on  top  of  the  record  being 
edited  in  the  central  workspace. 

You  need  to  think  of  the  user’s  ac¬ 
tion  as  the  equivalent  of  a  subroutine 
call  in  the  work  flow.  While  editing  a 
record,  programmers  find  the  need  to 
do  some  code  table  editing.  Rather  than 
close  the  edit  screen  and  backtrack 
through  the  menu  tree  to  open  another 
screen  devoted  to  code  table  editing, 
the  user  simply  “ducks  out”  from  rec¬ 
ord  editing  for  a  while  and  opens  a 
window  into  the  code  tables.  Once 


done  with  the  code  tables,  you  close 
the  code  table  tool  window  and  you 
are  instantly  back  where  you  were  in 
the  central  workspace  when  you  dis¬ 
covered  the  undefined  state  code.  No 
backing  up,  no  opportunity  to  get  lost 
behind  Cuba  Lake.  When  you  find  a 
need  for  a  tool,  you  reach  out  and  grab 
it.  While  you’re  using  the  tool,  your 
previous  work  remains,  perhaps  dor¬ 
mant,  in  the  central  workspace.  That’s 
the  metaphor  of  an  event-driven  archi¬ 
tecture. 

Beneath  the  Surface 

I’m  not  going  to  tell  you  how  to  code 
up  an  event-driven  application  frame¬ 
work  here.  It’s  probably  too  big  a  pro¬ 
ject  for  a  magazine  article,  and  to  be 
honest,  99.999  percent  of  you  would 
be  wasting  your  time  trying  to  roll  your 
own,  because  there  are  far,  far  better 
ones  on  the  open  market  right  now 
than  you  could  ever  hope  to  create 
yourselves.  They’re  inexpensive,  too  — 
in  fact,  one  of  the  very  best  now  comes 
bundled  free  with  every  copy  of  Turbo 
Pascal  6.0. 

Still,  it  always  pays  to  have  a  handle 
on  what’s  going  on  beneath  the  sur¬ 
face.  So  I’ll  speak  in  broad  terms  of 
how  event  managers  work. 

First,  to  define  this  thing  called  an 
“event:”  An  event  is  an  occurrence  that 
effects  your  program  but  which  is  not 
dictated  by  the  flow  of  control  in  the 
program.  In  other  words,  an  event  is 
not  something  triggered  by  an  IF  state¬ 
ment.  It  is  triggered,  instead,  by  forces 
outside  of  the  current  program,  and 
even  outside  of  the  machine  itself. 

The  best  example  of  an  event  is  some¬ 
thing  that  the  user  does.  A  keystroke 
is  perhaps  the  crispest  example  of  an 
event.  The  program  has  no  idea  what 
the  user  will  type,  or  when.  Similarly, 
the  user’s  moving  a  mouse  cursor  over 
a  predefined  “hot  area”  (such  as  a  menu 
bar)  is  something  done  when  the  user 
chooses  to  do  it.  A  mouse  button  click, 
like  a  keystroke,  is  another  excellent 
example  of  an  event. 

Events  can  also  come  from  within 
the  machine.  A  character  from  a  serial 
port  can  be  an  event,  as  one  can  ap¬ 
pear  at  any  time  once  the  port  is  en¬ 
abled.  The  system  software  (DOS,  BIOS) 
can  also  create  events.  The  best  known 
of  these  is  the  “timer  tick”  that  happens 
18  times  every  second.  Timer  ticks  are 
not  beholden  to  the  currently-running 
program.  They  march  inexorably  in  step 
with  the  hardware  timer  regardless  of 
what  the  current  program  does  (un¬ 
less,  of  course,  the  current  program 
inhibits  interrupts).  Usually,  timer  tick 
events  don’t  happen  every  tick,  but 
every  Micks,  providing  a  programmable- 


132 


Dr.  Dobb’s Journal,  December  1990 

1165 


STRUCTURED  PROGRAMMING 


(continued  from  page  132) 
time  delay  between  events. 

Similarly,  timer  ticks  can  be  used  to 
create  “now  is  the  time”  events;  you 
set  a  specific  date  and  time  when  some¬ 
thing  must  happen,  and  at  each  timer 
tick,  a  simple  comparison  determines 
whether  it’s  zero  hour  or  not.  If  the 
time  is  now,  the  event  is  generated. 

Event  Managers 

Beneath  the  surface  of  an  event-driven 
application  must  be  some  sort  of  event 
manager.  The  event  manager  is  a  mecha¬ 
nism  that  watches  for  events,  (typically 
by  “capturing”  an  interrupt  vector  sig¬ 
nalling  an  event’s  occurrence)  places 
them  in  an  application-friendly  “wrap¬ 
per”  of  some  sort,  and  then  queues  the 
wrapped  events  up  for  processing  in 
some  sort  of  FIFO  (First  In,  First  Out) 
data  structure.  The  event  manager  then 
processes  the  queued  events  in  order. 

Nearly  all  event-driven  systems  have 
this  much  in  common.  How  the  queued- 
up  events  are  processed  is  up  to  the 
cleverness  of  the  system  architect,  and 
varies  with  the  event-driven  system  or 
toolkit  under  discussion.  Typically,  the 
programmer  associates  an  event  with 
a  procedure,  function,  or  object  method 
that  is  called  when  the  event  occurs. 
Turbo  Pascal  4.x  and  later,  for  exam¬ 
ple,  considers  function  key  F10  an  event. 
When  the  F10  event  is  detected,  Turbo 
Pascal  calls  its  menuing  system  and 
moves  the  cursor  to  the  menu  bar  at 
the  top  of  the  screen. 

Events  can  be  prioritized,  meaning 
that  some  events  are  handled  immedi¬ 
ately  even  if  others  are  waiting  in  the 
queue.  The  word  “queue”  suggest  a 
whole  conga-line  of  events  in  a  row 
struggling  toward  their  ultimate  fate, 
but  that’s  misleading.  In  nearly  all  cases, 
the  event  queue  is  empty  or  contains 
one  or  (on  the  outside)  two  events.  A 
good  system  should  not  allow  events 
to  pile  up;  there’s  nothing  like  watch¬ 
ing  a  system  try  to  execute  a  queue  of 
a  dozen  accumulated  mouse  clicks  to 
drive  a  user  to  distraction.  If  something 
is  begun  that  absolutely  cannot  be  in¬ 
terrupted,  (like  saving  the  work  file  to 
disk)  event  sensing  should  be  sus¬ 
pended  until  —  but  only  until  —  the 
critical  task  is  finished. 

More  typically,  an  event  “freezes” 
the  current  task  and  opens  something 
new  in  a  process  akin  to  (as  just  men¬ 
tioned)  a  subroutine  call.  You  can  duck 
out  of  editing  the  work  file  in  Turbo 
Pascal  by  pressing  any  of  numerous 
hot  keys  such  as  F10,  Alt-F,  Alt-C,  and 
so  on,  each  of  which  generates  an  event. 
The  edit  screen  waits  patiently  while 
you  fool  around  in  the  menus;  when 
the  menu  work  is  done,  the  focus  re¬ 
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turns  to  the  edit  file  exactly  where  you 
left  off  when  you  triggered  one  of  the 
keyboard  events. 

Event-driven  architectures  facilitate 
a  level  of  concurrency  impossible  in 
menu-tree  systems.  Even  if  the  under¬ 
lying  platform  isn’t  multitasking  in  na- 

We’re  coming  to  the 
close  of  another  era 
in  structured 
programming:  The  era 
of  doing  it  all  yourself 


ture,  having  three  windows  open  on 
the  screen  with  an  edit  file  in  each  is 
nearly  as  useful,  especially  if  you  can 
zip  from  one  to  another  with  a  single 
click  of  the  mouse  on  the  selected  win¬ 
dow. 

Getting  Involved 

People  who  have  been  using  event- 
driven  systems  for  years  will  find  all 
this  stultifyingly  obvious,  but  a  great 
many  people  (particularly  programming 
newcomers)  haven’t  caught  on.  I  think 
a  good  many  of  those  holding  back 
assume  you  have  to  come  up  with  the 
event  management  and  menuing  code 
yourself,  which  simply  isn’t  true.  There 
are  a  dozen  or  more  solid  event-driven 
application  framework  products  out 
there,  with  more  appearing  all  the  time. 

Most  of  them,  as  you  might  imagine, 
are  limited  to  C,  and  many  operate 
only  in  graphics  mode.  Still,  some  of 
the  best  support  text  mode  and  are  in 
fact  available  for  Pascal.  (The  best  one 
I’ve  seen  for  any  language,  The  Zinc 
Interface  Library,  is  an  SAA-compliant 
C++  product  that  operates  interchange¬ 
ably  in  either  graphics  or  text  mode;  if 
you’re  working  in  C++,  I  powerfully 
suggest  that  you  look  into  it.)  Tur- 
boPower  Software’s  Object  Professional 
is  one  that  I’ve  mentioned  in  the  past, 
and  will  mention  again. 

Turbo  Vision 

But  the  one  that  most  people  will  be 
talking  about  for  a  while  is  the  event- 
driven  application  framework  provided 
as  part  of  the  recently  released  Turbo 
Pascal  6.0.  Borland’s  Turbo  Vision  is 
an  “empty  application”  in  object  form 
that  you  inherit  and  extend  using  object- 
oriented  techniques. 

Turbo  Vision  provides  a  classic, 
mouse-based  windowing  user  interface 
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in  text  mode.  In  fact,  the  Turbo  Pascal 
6.0  integrated  development  environ¬ 
ment  (IDE)  itself  was  written  using 
Turbo  Vision,  so  if  you  want  to  see 
what  a  Turbo  Vision  application  looks 
like,  just  look  at  Turbo  Pascal. 

Turbo  Vision’s  TApplication  object 
type  and  the  object  types  it  includes 
already  contain  thousands  of  lines  of 
code  implementing  event  management, 
menuing,  and  windowing,  as  well  as 
dialog  boxes,  buttons,  pick  lists,  and 
other  controls.  Your  part  in  the  pro¬ 
gramming  process  is  to  define  a  child 
class  of  TApplication  and  add  the  code 
specific  to  your  own  application. 

If  your  application  is  fairly  simple, 
you  don’t  even  have  to  write  the  main 
program.  These  three  method  calls  com¬ 
prise  the  main  program  of  most  Turbo 
Vision  applications,  and  all  three  are 
inherited  whole  from  TApplication-. 

BEGIN 

MyApp.Init; 

MyApp.Run; 

MyApp.Done 

END. 

Init  is  the  application’s  constructor,  and 
Done  is  its  destructor.  You  set  the  ap¬ 
plication  up,  you  run  it,  and  you  shut 
it  down.  This  is  structured  program¬ 
ming  with  a  vengeance. 

Like  its  elder  cousin  Object  Profes¬ 
sional,  Turbo  Vision  defies  easy  de¬ 
scription  in  a  3500-word  magazine  col¬ 
umn.  The  best  I  can  do  this  time  is  give 
you  a  flavor  for  how  it  works,  and 
show  you  a  simple  program  that  uses 
it.  In  future  columns  I’ll  be  speaking 
of  Turbo  Vision  regularly,  now  that  it’s 
an  intrinsic  part  of  Turbo  Pascal. 

An  Experimental  Desktop  Manager 

In  only  an  hour  or  two,  I  was  able  to 
come  up  with  the  prototype  of  a  desk¬ 
top  manager  in  Turbo  Vision,  and  I’ve 
presented  it  in  Listing  One  (page  151). 
It’s  a  prototype  because  what’s  there 
is  a  menu  structure  and  a  couple  of 
dialog  boxes;  there’s  no  real  “guts”  to 
the  program.  That’s  by  design,  because 
Turbo  Vision  is  a  user  interface  tool, 
and  I  wanted  to  show  how  it  helps  you 
put  together  an  event-driven  user  inter¬ 
face.  The  guts  are  a  separate  issue. 

Working  with  Turbo  Vision  begins 
with  the  definition  of  your  application 
object,  which  is  always  a  child  class  of 
the  abstract  class  TApplication.  I  called 
mine  TDesk  (the  “T”  prefix  means 
“type,”  and  is  an  Object  Pascal  conven¬ 
tion  going  back  to  Apple’s  Lisa  days). 
You  must  override  three  TApplication 
methods:  InitMenuBar,  which  sets  up 
menus  in  the  menu  bar  at  the  top  of  the 
screen;  InitStatusLine,  which  sets  up 
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any  prompts  in  the  status  line  at  the 
bottom  of  the  screen;  and  HandleEvent , 
which  is  your  application’s  event  han¬ 
dler,  and  in  many  ways  the  key  to  the 
whole  process. 

Your  own  code  never  actually  calls 
any  of  these  three  methods.  The  appli¬ 
cation  constructor  Init  calls  InitStatus¬ 
Line  and  InitMenuBartbem  while  it’s 
setting  up  the  program.  HandleEvent 
is  called  from  within  TApplication ’s  Run 
method,  which  is  inherited  unchanged 
by  your  own  specific  application  class. 

This  struck  me  very  oddly  at  first, 
but  like  OOP  in  general,  it  gets  more 
natural  the  more  you  work  with  it.  Work¬ 
ing  with  Turbo  Vision  might  be  consid¬ 


ered  a  process  of  setting  up  a  series  of 
effects,  and  allowing  Turbo  Vision’s 
internals  to  provide  the  causes. 

When  you  call  the  Run  method,  what 
happens  is  that  execution  vanishes  into 
Turbo  Vision  (for  which  source  code 
is  not  available,  sadly)  and  waits  for 
events  to  happen.  When  an  event  hap¬ 
pens,  Turbo  Vision  gets  first  crack  at 
handling  the  event.  (Some  events,  like 
the  Alt-X  hotkey  for  exiting  an  applica¬ 
tion,  are  pre-coded  into  Turbo  Vision 
and  inherited  by  your  own  application 
class.)  If  the  event  is  not  something 
Turbo  Vision  handles,  it  passes  the  event 
on  to  your  application  by  calling  your 
application’s  HandleEvent  method.  In- 
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side  your  HandleEvent  method,  you 
parse  the  event  passed  along  by  Turbo 
Vision,  typically  through  a  CASE  state¬ 
ment.  If  the  event  provided  by  Turbo 
Vision  is  something  your  application 
knows  how  to  handle,  the  CASE  state¬ 
ment  calls  an  appropriate  method  or 
other  routine  to  service  the  event.  If  the 
event  is  undefined,  you  have  the  op¬ 
tion  of  safely  ignoring  it.  See  Figure  1. 

This,  at  the  highest  level,  is  how  the 
flow  of  control  goes  in  a  Turbo  Vision 
application:  Events  happen.  Turbo  Vi¬ 


Figure  1:  Turbo  Vision  event  processing 


sion  queues  them  up,  and  gets  first 
shot  at  processing  them.  If  it  cannot 
process  an  event,  Turbo  Vision  passes 
the  event  along  to  your  application. 
Once  your  application  processes  the 
event,  control  eventually  falls  back  into 
Turbo  Vision  to  wait  for  the  next  event. 

For  simplicity’s  sake  I  have  created 
only  one  method  that  handles  an  event 
in  JXDESK:  SystemStatistics,  which  is 
called  in  response  to  the  Statistics  op¬ 
tion  in  the  System  menu.  The  call  is 
made  from  the  HandleEvent  method. 


Note  that  the  event  is  passed  out  from 
within  Turbo  Vision  as  a  named  con¬ 
stant,  SysStatCmd,  which  is  simply  a 
name  given  to  the  value  102.  Such  a 
constant  is  called  a  “command”  in  Turbo 
Vision.  You  define  commands  and  as¬ 
sociate  them  with  events  by  passing  a 
command  to  Turbo  Vision  along  with 
a  menu  option  definition,  when  Init- 
MenuBar  is  called.  Note  that  all  the 
Newltem  calls  made  from  within  Init- 
MenuBar  associate  their  menu  items 
with  the  null  command  except  for  one: 


Products  Mentioned 

Turbo  Pascal  6.0 
Borland  International 
1800  Green  Hills  Road 
Scotts  Valley,  CA  95066 
408-438-8400 
$149.95 

Turbo  Professional  $299.95 

The  Zinc  Interface  Library 
Zinc  Software  Incorporated 
405  South  100  East 
Pleasant  Grove,  UT  84062 
801-785-8900 
$199.95 
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The  one  that  sets  up  the  Statistics  menu 
item  on  the  System  menu. 

Read  the  code  for  JXDESK  a  few 
times,  and  it  should  start  making  sense. 
Better  still,  download  the  .EXE  file  that 
I  have  provided  along  with  the  source 
to  JXDESK  and  play  around  with  it  for 
a  while.  Like  many  other  things  in  our 
complicated  world,  Turbo  Vision  shows 
better  than  it  tells. 

The  End  of  an  Era 

I’ll  have  more  to  say  about  JXDESK  in 
my  next  column,  and  more  about  Turbo 
Vision  as  well.  And  I’ll  wrap  this  month 
up  by  positing  that  we’re  coming  to  the 
close  of  another  era  in  structured  pro¬ 
gramming:  The  era  of  Doing  It  All  Your¬ 
self.  Everywhere  I  look,  Pascal  and 
Modula-2  programmers  are  using  screen 
generators,  procedure  and  object  librar¬ 
ies,  menu  generators,  and  all  other  man¬ 
ner  of  productivity  enhancers  and 
canned  code.  Nobody  but  the  rankest 
beginners  or  the  hardest-headed  com¬ 
pulsives  sit  down  with  the  naked  com¬ 
piler  and  roll  it  all  from  scratch. 

This  makes  the  apps  happen  a  lot 
faster,  but  there’s  a  whole  crop  of  new 
dangers  heaving  over  the  horizon,  stem¬ 
ming  from  not  really  knowing  how  your 
“own”  code  works.  Turbo  Vision  is  a 
case  in  point;  from  now  on,  as  much 
as  half  of  your  application  will  prob¬ 
ably  remain  a  total  mystery  from  a  source 
code  standpoint,  rather  than  just  some 
canned  procs  here  or  there.  You  can 
even  get  away  without  learning  in  de¬ 
tail  what  Turbo  Vision  does,  as  long 
as  you  can  set  up  menus  and  an  event 
handler. 

Is  this  good?  I  don’t  know  yet.  I 
haven’t  the  vaguest  idea  how  DOS 
works,  and  don’t  care  much,  because 
it  hasn’t  hurt  me.  This  wasn’t  always 
the  case;  back  in  the  CP/M  era  we  had 
to  understand  what  the  OS  did,  be¬ 
cause  we  had  to  modify  and  extend  it 
to  mate  with  our  oddball  hardware. 
And  before  CP/M,  it  was  every  hacker 
for  himself.  I  even  wrote  my  own  oper¬ 
ating  system  once,  lordy. 

Now,  more  and  more  of  the  code  we 
use  in  creating  our  applications  comes 
standard  in  a  can  from  somebody  else 
and  can  be  taken  for  granted  once  we 
learn  how  to  use  it.  Obviously,  we’re 
heading  somewhere.  When  I  figure  out 
where,  I’ll  be  sure  to  let  you  know. 

DDJ 

(Listing  begins  on  page  151.) 
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Taking  Care  of 
Business 


Have  you  ever  noticed  how,  on 
certain  workdays,  the  wheels 
of  progress  seem  to  turn  back¬ 
wards?  Well,  I’ve  had  entire 
months  like  that.  If  Peopleware ,  by  Tom 
DeMarco  and  Timothy  Lister,  had  been 
published  about  ten  years  earlier,  I  might 
have  been  saved  from  a  lot  of  aggrava¬ 
tion.  (Assuming,  of  course,  that  I  had 
the  good  fortune  to  stumble  across  the 
book,  and  then  had  the  good  sense  to 
take  it  to  heart.) 

During  my  first  few  years  as  a  full¬ 
time  software  developer  and  vendor,  1 
made  a  concerted  effort  to  be  instantly 
available  to  my  customers  by  phone.  I 
tried  to  keep  tabs  on  every  facet  of  my 
company’s  operation,  from  managing 
inventory,  to  ad  design  and  placement, 
to  paying  the  bills.  1  selected  an  office 
suite  with  a  few  large  rooms  rather 
than  many  small  rooms,  free  passage 
between  the  rooms,  and  little  in  the 
way  of  outside  views,  under  the  as¬ 
sumption  that  this  would  improve  com¬ 
munication  and  minimize  distractions. 
Ah,  the  follies  of  youth! 


Ray  Duncan 


As  the  years  went  by,  working  con¬ 
ditions  at  my  little  company  evolved.  I 
moved  the  firm  to  another  building, 
where  each  employee  could  have  a 
sunny,  private,  and  above  all,  quiet 
office.  I  arranged  to  screen  out  nearly 
all  incoming  phone  calls,  diverting  tech¬ 
nical  support  questions  to  electronic 
mail,  a  24-hour  electronic  bulletin  board, 
or  a  FAX  machine.  And  1  learned  to 
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delegate  routine  decisions  about  prod¬ 
uct  promotion,  purchasing  supplies,  and 
triaging  of  invoices  to  a  trustworthy 
office  manager. 

What  happened?  Over  a  long  period 
of  time,  I  independently  derived  one 
of  PeoplewarP s  many  axioms:  “There 
are  a  million  ways  to  lose  a  work  day, 
but  not  even  a  single  way  to  get  one 
back.”  I  also  became  alerted  to  the 
destructive  influence  of  ambient  noise 
and  particularly  of  that  demonic  inven¬ 
tion,  the  telephone.  When  I  began  to 
keep  a  call  log,  I  realized  how  a  rela¬ 
tively  few  telephone  conversations,  scat¬ 
tered  through  the  course  of  a  normal 
business  day,  could  reduce  the  num¬ 
ber  of  lines  of  new  code  generated  that 
day  nearly  to  zero.  Peopleware  describes 
and  explains  this  phenomenon  all  too 
clearly: 

Duringsingle-mindedwork-time,  peo¬ 
ple  are  ideally  in  a  state  that  psycholo¬ 
gists  call  “flow.”  Flow  is  a  condition 
of  deep,  nearly  meditative  involvement. 
In  this  state,  there  is  a  gentle  sense  of 
euphoria,  and  one  is  largely  unaware 
of  the  passage  of  time:  “I  began  to 
work.  I  looked  up,  and  three  hours 


had  passed.”  There  is  no  conscious¬ 
ness  of  effort;  the  work  just  seems  to, 
well,  flow.  You’ve  been  in  this  state 
often,  so  we  don’t  have  to  describe  it 
to  you. 

Not  all  work  roles  require  that  you 
attain  a  state  of  flow  in  order  to  be 
productive,  but  for  anyone  involved 
in  engineering,  design,  development, 
writing,  or  like  tasks,  flow  is  a  must. 
These  are  high-momentum  tasks. 

It’s  only  when  you’re  in  flow  that  the 
work  goes  well.  Unfortunately,  you 
can’t  turn  on  flow  like  a  switch.  It 
takes  a  slow  descent  into  the  subject, 
requiring  fifteen  minutes  or  more  of 
concentration  before  the  state  is  locked 
in.  During  this  immersion  period,  you 
are  particularly  susceptible  to  noise 
and  interruption.  A  disruptive  envi¬ 
ronment  can  make  it  difficult  or  im¬ 
possible  to  attain  flow. 

Once  locked  in,  the  state  can  be 
broken  by  an  interruption  that  is  fo¬ 
cused  on  you  (your  phone,  for  in¬ 
stance)  or  by  insistent  noise  (“Atten¬ 
tion!  Paging  Paul  Portulaca.  Will  Paul 
Portulaca  please  call  extension  .  .  .  ”). 
Each  time  you’re  interrupted,  you  re¬ 
quire  an  additional  immersion  period 
to  get  back  into  flow.  During  this  im¬ 
mersion  period,  you're  not  really  do¬ 
ing  work. 

If  the  average  incoming  phone  call 
takes  five  minutes  and  your  reimmer¬ 
sion  period  is  fifteen  minutes,  the  total 
cost  of  that  call  in  flow  time  (work 
time)  lost  is  twenty  minutes.  A  dozen 
phone  calls  use  up  half  a  day.  A  dozen 
other  interruptions  and  the  rest  of  the 
work  day  is  gone.  This  is  what  guaran¬ 
tees,  “You  never  get  anything  done 
around  here  between  9  and  5.” 
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( continued  from  page  139) 

DeMarco  and  Lister  are  justly  famous 
for  their  texts  and  seminars  on  project 
management,  structured  programming, 
and  software  metrics.  But  in  this  slen¬ 
der,  witty,  and  engaging  book,  they 
have  put  aside  cold  statistics  and  data¬ 
flow  diagrams  to  concentrate  on  the 
human  aspects  of  software  develop¬ 
ment:  Why  some  people  are  produc¬ 
tive  and  others  aren’t;  why  some  teams 
jell  and  others  don’t;  why  some  strate¬ 
gies  to  increase  quality  and  beat  dead¬ 
lines  have  the  opposite  effect;  and  why 
some  working  environments  are  con¬ 
ducive  to  timely,  error-free  program¬ 
ming  and  others  hinder  it.  In  many 
ways,  Peopleware  is  a  New  Age  coun¬ 
terpart  of  Frederick  Brooks’  legendary 
book,  The  Mythical  Man-Month. 

Most  of  the  guidelines  in  Peopleware 
arise  from  the  authors’  personal  experi¬ 
ence,  managing  projects  or  consulting 
on  project  management  for  America’s 
largest  corporations.  Other  recommen¬ 
dations  are  derived  from  analysis  of  the 
“Coding  War  Games,”  an  annual  pub¬ 
lic  competition  which  pits  teams  of  im¬ 
plementors  from  different  organizations 
against  each  other  in  the  design,  cod¬ 
ing,  and  testing  of  a  medium-sized  pro¬ 
gram  to  a  fixed  specification.  Overall, 
the  book  is  written  from  an  administra¬ 
tor’s  viewpoint,  and  directed  at  an  ad¬ 
ministrator’s  concern.  But  there’s  hardly 
a  page  that  wouldn’t  interest  the  indi¬ 
vidual  programmer  and  consultant  just 
as  well.  The  book  won’t  change  your 
life,  but  it  may  improve  it. 


If  I  have  a  single  gripe  with  People- 
ware,  it’s  that  the  book  seems  to  be 
designed  for  the  MTV  generation.  It’s 
elaborately  ornamented  with  amusing 
anecdotes,  cute  subtitles,  aphorisms, 
and  quotations,  and  it  takes  pains  never 
to  exceed  what  it  assumes  to  be  its 
reader’s  limited  attention  span.  In  truth, 
Peopleware  often  seems  less  like  a  book 
than  a  collection  of  25  essays-as-sound- 
bites,  each  treating  a  discrete  topic  (“The 
Hornblower  Factor,”  “Open  Kimono,” 
“Brain  Time  versus  Body  Time,”  “The 
Telephone,”  and  so  on)  in  five  or  six 


pages.  I  repeatedly  found  myself  wish¬ 
ing  that  the  authors  would  flesh  out  a 
particular  concept  or  case  study  in,  say, 
an  additional  10,000  or  20,000  well- 
chosen  words!  Of  course,  this  is  less 
an  indictment  of  Peopleware  than  a  sad 
commentary  on  the  book’s  intended 
audience. 
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C  PROGRAMMES 


Listing  One  (Text  begins  on  page  121.) 


/* - database,  h - */ 

♦define  MXKEYLEN  80  /*  maximum  key  length  for  indexes  */ 

♦define  ERROR  -1 
♦define  OK  0 

♦ifndef  TRUE 
♦define  TRUE  1 
♦define  FALSE  0 
♦endif 

typedef  long  RPTR;  /*  B-tree  node  and  file  address  */ 
void  dberror (void) ; 

/* - dbms  error  codes  for  errno  return - */ 

enum  dberrors  { 

D_OM,  /*  out  of  memory  */ 

D  IOERR  /*  i/o  error  */ 

); 


End  Listing  One 


Listing  Two 

/* - btree.h - */ 

♦define  MXTREES  20 

♦define  NODE  512  /*  length  of  a  B-tree  node  */ 

♦define  ADR  sizeof (RPTR) 


/* - btree  prototypes - */ 

int  btree_init (char  *ndx_name) ; 

int  btree_close (int  treeT; 

void  build_b(char  *name,  int  len); 

RPTR  locate (int  tree,  char  *k) ; 

int  deletekey (int  tree,  char  *x,  RPTR  ad); 

int  insertkey (int  tree,  char  *x,  RPTR  ad,  int  unique); 

RPTR  nextkey(int  tree); 

RPTR  prevkey(int  tree); 

RPTR  firstkey (int  tree); 

RPTR  lastkey (int  tree); 

void  keyval(int  tree,  char  *ky) ; 

RPTR  currkey(int  tree); 


/* - the  btree  node  structure - */ 

typedef  struct  treenode  { 

int  nonleaf;  /*  0  if  leaf,  1  if  non-leaf 

RPTR  prntnode;  /*  parent  node 

RPTR  lfsib;  /*  left  sibling  node 

RPTR  rtsib;  /*  right  sibling  node 

int  keyct;  /*  number  of  keys 

RPTR  keyO;  /*  node  ♦  of  keys  <  1st  key  this  node 

char  keyspace  (NODE  -  ( (sizeof (int)  *  2)  +  (ADR  *  4))]; 
char  spil  [MXKEYLEN] ;  /*  for  insertion  excess  */ 

}  BTREE; 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


/* - the  structure  of  the  btree  header  node - */ 

typedef  struct  treehdr  { 

RPTR  rootnode;  /*  root  node  number  */ 

int  keylength;  /*  length  of  a  key  */ 

int  m;  /*  max  keys /node  */ 

RPTR  rlsed_node;  /*  next  released  node  */ 

RPTR  endnode;  /*  next  unassigned  node  */ 

int  locked;  /*  if  btree  is  locked  */ 

RPTR  leftmost;  /*  left-most  node  */ 

RPTR  rightmost;  /*  right -most  node  */ 

)  HEADER; 


End  Listing  Two 


Listing  Three 

/* - btree. c - */ 

♦include  <stdio.h> 

♦include  <errno.h> 

♦include  <string.h> 

♦include  <stdlib.h> 

♦include  "database. h" 

♦include  "btree.h" 


static  void  implode (BTREE  ‘left,  BTREE  ‘right); 

static  void  redist(BTREE  ‘left,  BTREE  ‘right); 

static  void  adopt (void  *ad,  int  kct,  RPTR  newp) ; 

static  RPTR  nextnode(void) ; 

static  RPTR  scannext  (RPTR  *p,  char  “a); 

static  RPTR  scanprev (RPTR  *p,  char  “a); 

static  char  ‘childptr (RPTR  left,  RPTR  parent,  BTREE  *btp) ; 

static  void  read_node (RPTR  nd,  void  *bf); 

static  void  write_node (RPTR  nd,  void  *bf); 

static  void  bseek(RPTR  nd) ; 

static  void  memerr (void) ; 

/*  -  initiate  b-tree  processing  -  */ 

int  btree_init (char  *ndx_name) 

{ 

for  (trx  -  0;  trx  <  MXTREES;  trx++) 
if  (fp[trx]  ==  NULL) 
break; 

if  (trx  ==  MXTREES) 
return  ERROR; 

if  ((fp(trx)  *  fopen (ndx_name,  "rb+"))  ■-  NULL) 
return  ERROR; 

fread(Sbheader [trx] ,  sizeof (HEADER) ,  1,  fpftrx]); 

/*  —  if  this  btree  is  locked,  something  is  amiss  -  */ 

if  (bheader [trx] . locked)  ( 
fclose (fp[trx] ) ; 
fp[trx]  -  NULL; 
return  ERROR; 

) 

/* - lock  the  btree - */ 

bheader [trx] .locked  =  TRUE; 
fseek (fp[trx] ,  OL,  SEEK_SET) ; 

fwrite(Sbheader[trx] ,  sizeof (HEADER) ,  1,  fp[trx]); 
currnode[trx]  *  0; 
currkno[trx]  -  0; 
return  trx; 


/* - terminate  b  tree  processing - */ 

int  btree_close (int  tree) 

{ 

if  (tree  >=  MXTREES  !1  fp[tree]  ==  0) 
return  ERROR; 

bheader [tree] .locked  »  FALSE; 
fseek (fp [tree] ,  0L,  SEEK_SET) ; 

fwrite (ibheader[tree] ,  sizeof (HEADER) ,  1,  fp[tree]); 
fclose (fp[tree] ) ; 
fp[tree]  -  NULL; 
return  OK; 

} 

/* - Build  a  new  b-tree -  */ 

void  build_b(char  ‘name,  int  len) 

I 

HEADER  *bhdp; 

FILE  *fp; 

if  ( (bhdp  -  malloc (NODE) )  ««  NULL) 
memerr () ; 

memset(bhdp,  '\0',  NODE); 
bhdp->keylength  =  len; 

bhdp->m  -  ((NODE- ((sizeof (int) *2) + (ADR*4) ) ) / (len+ADR) ) ; 

bhdp->endnode  -  1; 

remove (name) ; 

fp  -  fopen (name,  "wb"); 

fwrite(bhdp,  NODE,  1,  fp) ; 

fclose (fp) ; 

free (bhdp) ; 


/* - Locate  key  in  the  b-tree - */ 

RPTR  locate (int  tree,  char  *k) 

{ 

int  i,  fnd  =  FALSE; 

RPTR  t,  ad; 
char  *a; 

trx  *  tree; 

t  =  bheader [trx] .rootnode; 
if  (t)  { 

read_node(t,  Strnode); 
fnd  =  btreescan (&t,  k,  &a); 
ad  =  leaflevel (&t,  &a,  Si); 
if  (i  ==  trnode. keyct  +  1)  { 

i  =  0; 

t  =  trnode. rtsib; 

1 

currnode [trx]  =  t; 
currkno[trx]  *  i; 

) 

return  fnd  ?  ad  :  0; 


♦define  KLEN  bheader [trx] .keylength 
♦define  ENTLN  (KLEN+ADR) 

HEADER  bheader [MXTREES] ; 

BTREE  trnode; 

static  FILE  *fp[MXTREES] ;  /*  file  pointers  to  indexes  */ 

static  RPTR  currnode [MXTREES] ;  /*  node  number  of  current  key  */ 

static  int  currkno [MXTREES] ;  /*  key  number  of  current  key  */ 

static  int  trx;  /*  current  tree  */ 

/* - local  prototypes - */ 

static  int  btreescan (RPTR  *t,  char  *k,  char  “a); 
static  int  nodescan (char  ‘keyvalue,  char  “nodeadr) ; 
static  int  compare_keys (char  *a,  char  *b) ; 
static  RPTR  fileaddr (RPTR  t,  char  *a); 
static  RPTR  leaflevel  (RPTR  *t,  char  “a,  int  *p) ; 


/* - Search  tree - */ 

static  int  btreescan  (RPTR  *t,  char  *k,  char  “a) 
{ 

int  nl; 
do  { 

if  (nodescan (k,  a))  ( 

while  (compare_keys (*a,  k)  ==  FALSE) 
if  (scanprev (t,  a)  ==  0) 
break; 

if  (compare_keys (*a,  k) ) 
scannext (t,  a); 
return  TRUE; 

) 

nl  =  trnode. nonleaf ; 
if  (nl)  { 


( continued  on  page  144) 
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Listing  Three  (Listing  continued,  text  begins  on  page  121.) 

*t  =  * ( (RPTR  *)  (*a  -  ADR)); 
read_node (*t,  fitrnode) ; 

} 

}  while  (nl) ; 
return  FALSE; 


/* - Search  node - */ 

static  int  nodescan (char  *keyvalue,  char  **nodeadr) 

{ 

int  i; 
int  result; 

*nodeadr  -  trnode.keyspace; 

for  (i  =  0;  i  <  trnode. keyct;  i++)  { 

result  *  compare_keys (keyvalue,  *nodeadr) ; 
if  (result  “  FALSE) 
return  TRUE; 
if  (result  <  0) 
return  FALSE; 

*nodeadr  +=  ENTLN; 

) 

return  FALSE; 


/* - Compare  keys - */ 

static  int  compare_keys (char  *a,  char  *b) 

{ 

int  len  *  KLEN,  cm; 
while  (len — ) 

if  ((cm  =  (int)  *a++  -  (int)  *b++)  !-  0) 
break; 
return  cm; 


/* - Compute  current  file  address  - */ 

static  RPTR  fileaddr (RPTR  t,  char  *a) 

{ 

RPTR  cn,  ti; 
int  i; 

ti  “  t; 

cn  =*  leaflevel (4ti,  &a,  &i) ; 
read_node(t,  itrnode) ; 
return  cn; 


/* - Navigate  down  to  leaf  level - */ 

static  RPTR  leaf level (RPTR  *t,  char  **a,  int  *p) 

{ 

if  (trnode. nonleaf  «==  FALSE)  {  /*  already  at  a  leaf?  */ 
*p  =  (*a  -  trnode.keyspace)  /  ENTLN  +  1; 
return  *((RPTR  *)  (*a  +  KLEN)); 

} 

*p  =  0; 

*t  -  * ( (RPTR  *)  (*a  +  KLEN)); 

read_node (*t,  itrnode) ; 

*a  =  trnode.keyspace; 

while  (trnode. nonleaf)  { 

*t  -  t mode. key 0; 
read  node(*t,  Strnod#)  ; 

} 

return  trnode. keyO; 


/* - Delete  a  key  - */ 

int  deletekey (int  tree,  char  *x,  RPTR  ad) 

{ 

BTREE  *qp,  *yp; 
int  rt_len,  comb; 

RPTR  p,  adr,  q,  *b,  y,  z; 
char  *a; 

trx  =  tree; 

if  (trx  >=  MXTREES  \  fp[trx]  ==  0) 
return  ERROR; 

p  =  bheader [trx] .rootnode; 
if  (p  ==  0) 
return  OK; 

read_node (p,  &trnode) ; 
if  (btreescan (&p,  x,  &a)  ==  FALSE) 
return  OK; 

adr  =  fileaddr (p,  a); 
while  (adr  !=  ad)  { 

adr  =  scannext(&p,  &a); 
if  (compare_keys (a,  x) ) 
return  OK; 

} 

if  (trnode. nonleaf)  { 

b  =  (RPTR  *)  (a  +  KLEN); 

q  =  *b; 

if  ( (qp  =  malloc (NODE) )  ==  NULL) 
memerr  () ; 
read_node  (q,  qp) ; 
while  (qp->nonleaf )  { 

q  =  qp->key0; 
read_node (q,  qp) ; 

} 

/*  Move  the  left-most  key  from  the  leaf 

to  where  the  deleted  key  is  */ 
memmove(a,  qp->keyspace,  KLEN) ; 
write_node (p,  fitrnode)  ; 

p  =  q; 

trnode  =  *qp; 
a  =  trnode.keyspace; 
b  =  (RPTR  *)  (a  +  KLEN); 

(continued  on  page  146) 
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Listing  Three  (Listing  continued,  text  begins  on  page  121.) 

t mode. key 0  «  *b; 
free (qp) ; 

} 

cur  mode  [trx]  =  p; 

currkno[trx]  =  (a  -  trnode.keyspace)  /  ENTLN; 

rt_len  =  (trnode.keyspace  +  (bheader [trx] .m  *  ENTLN))  -  a; 

memmove(a,  a+ENTLN,  rt_len) ; 

memset (a+rt_len,  '\0',  ENTLN); 

trnode.keyct — ; 

if  (currkno[trx]  >  trnode.keyct)  { 
if  (trnode.rtsib)  { 

currnode[trx]  =  trnode.rtsib; 
currkno[trx]  =  0; 

} 

else 

currkno[trx] — ; 

) 

while  (trnode.keyct  <=  bheader [trx] .m  /  2  ss 

p  !=  bheader [trx] .rootnode)  { 

comb  =  FALSE; 
z  =  trnode.prntnode; 
if  ((yp  =  malloc (NODE) )  —  NULL) 
memerr () ; 

if  (trnode.rtsib)  { 
y  ■  trnode.rtsib; 
read_node(y,  yp) ; 
if  (yp->keyct  +  trnode.keyct  < 

bheader [trx] .m  SS  yp->prntnode  ==  z)  ( 
comb  *  TRUE; 
implode (Strnode,  yp) ; 

» 

} 

if  (comb  ==  FALSE  ss  trnode.lfsib)  ( 
y  =  trnode.lfsib; 
read_node(y,  yp) ; 
if  (yp->prntnode  ==  z)  ( 

if  (yp->keyct  +  trnode.keyct  < 

bheader [trx] .m)  { 

comb  =  TRUE; 
implode (yp,  Strnode) ; 

} 

else  { 

redist (yp,  Strnode) ; 
write_node (p,  itrnode) ; 
write~node (y,  yp) ; 
free (yp) ; 
return  OK; 

) 

) 

} 

if  (comb  ==  FALSE)  ( 
y  =  trnode.rtsib; 
read_node(y,  yp); 
redist  (st mode,  yp)  ; 
write_node (y,  yp) ; 
write_node(p,  strnode) ; 
free (yp) ; 
return  OK; 

} 

free (yp) ; 
p  =  z; 

read_node(p,  Strnode); 

I 

if  (trnode.keyct  ==  0)  ( 

bheader [trx] . rootnode  =  trnode.keyO; 
t  mode,  nonleaf  =  FALSE; 
trnode.keyO  =0; 

trnode.prntnode  =  bheader [trx] .rlsed_node; 
bheader [trx] .rlsed_node  =  p; 

} 

if  (bheader [trx] .rootnode  ==  0) 

bheader [trxj .rightmost  =  bheader [trx] .leftmost  =  0; 
write_node (p,  Strnode); 
return  OK; 


/* - Combine  two  sibling  nodes.  - */ 

static  void  implode (BTREE  ‘left,  BTREE  ‘right) 

{ 

RPTR  If,  rt,  p; 
int  rt_len,  lf_len; 
char  *a; 

RPTR  *b; 

BTREE  ‘par; 

RPTR  c; 
char  *j; 

If  =  right->lfsib; 
rt  *  left->rtsib; 
p  =  left->prntnode; 
if  ((par  =  malloc (NODE) )  ==  NULL) 
memerr () ; 

j  *  childptr(lf,  p,  par); 

/*  —  move  key  from  parent  to  end  of  left  sibling  -  */ 

lf_len  =  left->keyct  *  ENTLN; 
a  =  left ->key space  +  lf_len; 
memmove(a,  j,  KLEN) ; 
memset (j,  '\0',  ENTLN); 

/*  —  move  keys  from  right  sibling  to  left  —  */ 
b  =  (RPTR  *)  (a  +  KLEN); 

*b  =  right->key0; 

rt_len  =  right->keyct  *  ENTLN; 

a  *  (char  *)  (b  +  1); 

memmove(a,  right->keyspace,  rt_len) ; 

/*  —  point  lower  nodes  to  their  new  parent  —  */ 
if  (left->nonleaf ) 

adopt (b,  right->keyct  +  1,  If); 
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/*  —  if  global  key  pointers  ->  to  the  right  sibling, 

change  to  ->  left  —  */ 
if  (currnode[trx]  --  left->rtsib)  ( 
currnode [trx]  =  right->lfsib; 
currkno[trx]  +=  left->keyct  +  1; 

} 

/*  -  update  control  values  in  left  sibling  node  —  */ 

left->keyct  +»  right->keyct  +  1; 
c  «  bheader [trx] .rlsed_node; 
bheader [trx] .rlsed_node  =  left->rtsib; 
if  (bheader [trx] .rightmost  ==  left->rtsib) 
bheader [trx] .rightmost  =  right->lfsib; 
left->rtsib  =  right->rtsib; 

/*  —  point  the  deleted  node's  right  brother 

to  this  left  brother  -  */ 

if  (left->rtsib)  { 

read_node (left->rtsib,  right) ; 
right->lfsib  ■  If; 
write_node (left->rtsib,  right); 

} 

memset (right,  ' \0' ,  NODE) ; 
right->prntnode  =  c; 

/*  —  remove  key  from  parent  node  -  */ 

par->keyct — ; 
if  (par->keyct  —  0) 
left->prntnode  ■  0; 
else  { 

rt_len  =  par->keyspace  +  (par->keyct  *  ENTLN)  -  j; 
memmove(j,  j+ENTLN,  rt_len) ; 

) 

write_node (If ,  left); 
wr ite_node ( rt ,  right ) ; 
write_node (p,  par); 
free (par) ; 


/* - Insert  key  - */ 

int  insertkey(int  tree,  char  *x,  RPTR  ad,  int  unique) 

{ 

char  k [MXKEYLEN  +  1],  *a; 

BTREE  *yp; 

BTREE  *bp; 

int  nl_flag,  rt_len,  j; 

RPTR  t,  p,  sv; 

RPTR  *b; 

int  lshft,  rshft; 
trx  ■  tree; 

if  (trx  >=  MXTREES  I!  fp[trx]  ==  0) 
return  ERROR; 
p  *  0; 
sv  *  0; 
nl_flag  =  0; 
memmove(k,  x,  KLEN) ; 
t  =  bheader [trx] .rootnode; 

/* - Find  insertion  point - */ 

if  (t)  { 

read_node  ( t ,  S t mode ) ; 
if  (btreescan (st,  k,  Sa) )  { 

if  (unique) 

return  ERROR; 
else  { 

leaflevel (St,  Sa,  Sj); 
currkno[trx]  -  j; 

) 

} 

else 

currkno[trx]  =  ( (a  -  trnode.keyspace)  /  ENTLN) +1; 
cur  mode  [trx]  =  t; 

1 

/* - Insert  key  into  leaf  node - */ 

while  (t)  { 

nl_flag  =1; 

rt_len  =  (trnode . keyspace+ (bheader [trx] .m*ENTLN) ) -a; 
memmove (a+ENTLN,  a,  rt_len) ; 
memmove(a,  k,  KLEN); 
b  =■  (RPTR  *)  (a  +  KLEN); 

*b  *  ad; 

if  (trnode. non leaf  ==  FALSE)  { 
currnode [trx]  =  t; 

currkno[trx]  =  ( (a  -  trnode.keyspace)  /  ENTLN) +1; 

) 

trnode.keyct++; 

if  (trnode. keyct  <=  bheader [trx] .m)  { 

write_node  (t,  St  mode ) ; 
return  OK; 

) 

/*  -  Redistribute  keys  between  sibling  nodes  - */ 

lshft  =  FALSE; 
rshft  =  FALSE; 

if  ( (yp  =  malloc (NODE) )  ==  NULL) 
memerr  () ; 

if  (trnode. lfsib)  { 

read_node (trnode .lfsib,  yp) ; 
if  (yp->keyct  <  bheader [trx] .m  SS 

yp->prntnode  ==  trnode.prntnode)  { 

lshft  -  TRUE; 
redist (yp,  s trnode) ; 
write_node (trnode. lfsib,  yp) ; 

) 

} 

if  (lshft  ==  FALSE  SS  trnode. rtsib)  { 
read_node  ( t  mode  .rtsib,  yp ) ; 
if  (yp->keyct  <  bheader [trx] .m  SS 

yp->prntnode  ==  trnode.prntnode)  { 

rshft  =*  TRUE; 
redist (Strnode,  yp) ; 
write_node (trnode . rtsib,  yp) ; 

} 

) 


free(yp) ; 

if  (lshft  ! I  rshft)  [ 
write_node (t,  strnode); 
return  OK; 

} 

p  =  nextnode ( ) ; 

/* - Split  node - */ 

if  ((bp  =  malloc (NODE) )  —  NULL) 
memerr () ; 

memset (bp,  ' \0' ,  NODE) ; 

trnode. keyct  =  (bheader [trx] .m  +  1)  /  2; 

b  =  (RPTR  *) 

(trnode. keyspace+ ( (trnode. keyct+1) *ENTLN)-ADR) ; 
bp->key0  *  *b; 

bp->keyct  =  bheader [trx] .m  -  trnode. keyct; 

rt_len  =  bp->keyct  *  ENTLN; 

a  *  (char  *)  (b  +  1); 

memmove (bp->keyspace,  a,  rt_len); 

bp->rtsib  =  trnode. rtsib; 

trnode. rtsib  =  p; 

bp->lfsib  *  t; 

bp->nonleaf  =  trnode. nonleaf; 
a  -=  ENTLN; 
memmove (k,  a,  KLEN) ; 
memset (a,  '\0',  rt_len+ENTLN) ; 
if  (bheader [trx] .rightmost  ==  t) 
bheader [trx] .rightmost  =  p; 
if  (t  ==  currnode [trx]  SS 

currkno [trx] >trnode. keyct)  { 
currnode [trx]  =  p; 
currkno [trx]  -=  trnode. keyct  +  1; 

) 

ad  =  p; 
sv  =  t; 

t  =  trnode.prntnode; 
if  (t) 

bp->prntnode  *  t; 
else  { 

p  =  nextnode (); 
trnode.prntnode  =  p; 
bp->prntnode  =  p; 

} 

write_node (ad,  bp) ; 
if  (bp->rtsib)  { 

if  ( (yp  =  malloc (NODE) )  ==  NULL) 
memerr  () ; 

read_node (bp->rtsib,  yp) ; 
yp->lfsib  ■  ad; 
write_node(bp->rtsib,  yp) ; 
free (yp) ; 

) 

if  (bp->nonleaf) 

adopt (Sbp->key0,  bp->keyct  +  1,  ad); 
write_node (sv,  strnode) ; 
if  (t)  { 

read_node(t,  Strnode); 
a  «  trnode.keyspace; 
b  *  Strnode. key 0; 
while  (*b  !=  bp->lfsib)  { 
a  +=  ENTLN; 

b  =  (RPTR  *)  (a  -  ADR); 

I 

) 

free (bp) ; 

I 

/* - new  root - */ 

if  (p  ==  0) 

p  -  nextnode (); 

if  ((bp  =  malloc (NODE) )  —  NULL) 
memerr () ; 

memset (bp,  '\0',  NODE); 
bp->nonleaf  =  nl_flag; 
bp->prntnode  =  0; 
bp->rtsib  =  0; 
bp->lfsib  =  0; 
bp->keyct  =  1; 
bp->key0  -  sv; 

* ( (RPTR  *)  (bp->keyspace  +  KLEN))  =  ad; 
memmove (bp->keyspace,  k,  KLEN); 
write_node(p,  bp); 
free (bp) ; 

bheader [trx] .rootnode  -  p; 
if  (nl_flag  —  FALSE)  ( 

bheader [trx] .rightmost  *  p; 
bheader [trxj .leftmost  -  p; 
currnode [trx]  *  p; 
currkno [trx]  ■  1; 

) 

return  OK; 


/* - redistribute  keys  in  sibling  nodes - */ 

static  void  redist (BTREE  *left,  BTREE  *right) 

( 

int  nl,  n2,  len; 

RPTR  z; 

char  *c,  *d,  *e; 

BTREE  *zp; 

nl  *  (left->keyct  +  right->keyct)  /  2; 
if  (nl  --  left->keyct) 
return; 

n2  =  (left->keyct  +  right->keyct)  -  nl; 
z  =  left->prntnode; 
if  ( (zp  -  malloc (NODE) )  ==  NULL) 
memerr () ; 

c  *  childptr (right->lfsib,  z,  zp) ; 


(continued  on  page  148) 
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Listing  Three  (Listing  continued ,  text  begins  on  page  121.) 

if  (left->keyct  <  right ->keyct)  { 

d  *  left->keyspace  +  (left->keyct  *  ENTLN) ; 
memmove(d,  c,  KLEN) ; 
d  +=  KLEN; 

e  =  right ->keyspace  -  ADR; 

len  =  ( (right->keyct  -  n2  -  1)  *  ENTLN)  +  ADR; 
memmove(d,  e,  len); 
if  (left->nonleaf) 

adopt (d,  right->keyct  -  n2,  right->lfsib) ; 
e  +=  len; 

memmove(c,  e,  KLEN); 
e  +=  KLEN; 

d  =  right->keyspace  -  ADR; 
len  =  (n2  *  ENTLN)  +  ADR; 
memmove(d,  e,  len); 
memset (d+len,  '\0',  e-d) ; 
if  (right->nonleaf  ==  0  && 

left->rtsib  ==  currnode[trx] ) 
if  (currkno [trx]  <  right->keyct  -  n2)  { 

currnode[trx]  -  right->lfsib; 
currkno [trx]  +=  nl  +  1; 

} 

else 

currkno[trx]  -=  right->keyct  -  n2; 

} 

else  { 

e  =  right->keyspace+ ( (n2-right->keyct) * ENTLN) -ADR; 
memmove(e,  right ->keyspace-ADR, 

(right->keyct  *  ENTLN)  +  ADR) ; 
e  —  KLEN; 

memmove(e,  c,  KLEN); 
d  ■  left->keyspace  +  (nl  *  ENTLN) ; 
meiranove(c,  d,  KLEN)  ; 
memset (d,  '\0\  KLEN); 
d  +-  KLEN; 

len  -  ( (left->keyct  -  nl  -  1)  *  ENTLN)  +  ADR; 
memmove(right->keyspace-ADR,  d,  len); 
memset (d,  '\0',  len); 
if  (right->nonleaf) 

adopt (right->keyspace  -  ADR, 

left->keyct  -  nl,  left->rtsib) ; 
if  (left->nonleaf  ==  FALSE) 

if  (right->lfsib  —  currnode(trx]  && 

currkno [trx]  >  nl)  { 
currnode[trx]  =  left->rtsfb; 
currkno(trx]  —  nl  +  1; 

) 

else  if  (left->rtsib  ==  currnode [trx] ) 
currkno[trx]  +=  left->keyct  -  nl; 

} 

right ->keyct  -  n2; 
left  ->keyct  =  nl; 
write_node (z,  zp) ; 
free(zp) ; 


/* - assign  new  parents  to  child  nodes - */ 

static  void  adopt (void  *ad,  int  kct,  RPTR  newp) 

( 

char  *cp; 

BTREE  *tmp; 

if  ((tmp  =  malloc (NODE) )  ==  NULL) 
memerr  () ; 

while  (kct — )  { 

read_node ( * (RPTR  *) ad,  tmp) ; 
tmp->prntnode  =  newp; 
write_node(* (RPTR  *)ad,  tmp); 
cp  =  ad; 
cp  +-  ENTLN; 
ad  =  cp; 

} 

free (tmp) ; 


/* - compute  node  address  for  a  new  node - */ 

static  RPTR  nextnode (void) 

( 

RPTR  p; 

BTREE  *nb; 

if  (bheader [trx] .rlsed_node)  { 
if  ((nb  =  malloc (NODE) )  ==  NULL) 
memerr () ; 

p  =  bheader [trx] .rlsed_node; 
read_node(p,  nb) ;  . 

bheader [trx] .rlsed_node  =  nb->prntnode; 
free (nb) ; 

) 

else 

p  =  bheader [trx] .endnode++; 
return  p; 


/* - next  sequential  key - */ 

RPTR  nextkey(int  tree) 

< 

trx  =  tree; 

if  (currnode [trx]  ==  0) 
return  firstkey (trx) ; 
read_node (currnode [trx] ,  Strnode) ; 
if  (currkno[trx]  ==  trnode.keyct)  ( 
if  (trnode.rtsib  ==  0)  { 

return  0; 

) 

currnode [trx]  =  trnode.rtsib; 

currkno[trx]  =  0; 

read_node (trnode . rtsib,  strnode) ; 


} 

else 

currkno[trx]++; 
return  *((RPTR  *) 

(trnode. keyspace+ (currkno [trx] *ENTLN) -ADR) ) ; 

} 

/* - previous  sequential  key - */ 

RPTR  prevkey(int  tree) 

{ 

trx  =  tree; 

if  (currnode [trx]  ==  0) 
return  lastkey (trx) ; 
read_node (currnode [trx] ,  Strnode) ; 
if  (currkno [trx]  ==  0)  [ 

if  (trnode. If sib  ==  0) 
return  0; 

currnode [trx]  =  trnode. If sib; 
read_node (trnode. If sib,  Strnode) ; 
currkno [trx]  =  trnode.keyct; 

} 

else 

currkno [trx] — ; 
return  * ( (RPTR  *) 

(trnode. keyspace  +  (currkno[trx]  *  ENTLN)  -  ADR) ) ; 


/* - first  key - */ 

RPTR  firstkey (int  tree) 

{ 

trx  =  tree; 

if  (bheader [trx] . leftmost  ==  0) 
return  0; 

read_node (bheader [trx] . leftmost,  Strnode) ; 
currnode[trx]  =  bheader  [trx]  .leftmost- 
cur  rkno[  trx]  =  1; 

return  *((RPTR  *)  (trnode. keyspace  +  KLEN) ) ; 


/* - last  key - */ 

RPTR  lastkey (int  tree) 

{ 

trx  -  tree; 

if  (bheader [trx] .rightmost  ■■  0) 
return  0; 

readjnode (bheader [trx] .rightmost,  Strnode) ; 
currnode[trx]  =  bheader [trx] .rightmost- 
cur  rkno[  trx]  -  trnode.keyct; 
return  *((RPTR  *) 

(trnode. keyspace  +  (trnode.keyct  *  ENTLN)  -  ADR) ) ; 


/* - scan  to  the  next  sequential  key - */ 

static  RPTR  scannext (RPTR  *p,  char  **a) 

{ 

RPTR  cn; 

if  (trnode. nonleaf)  { 

*p  =  *  ( (RPTR  *)  (*a  +  KLEN)); 
read_node (*p,  Strnode); 
while  (trnode. nonleaf)  { 

*p  =  trnode.keyO; 
read_node (*p,  Strnode) ; 

} 

*a  =  trnode. keyspace; 

return  * ( (RPTR  *)  (*a  +  KLEN) ) ; 

} 

*a  +=  ENTLN; 
while  (-1)  ( 

if  ( (trnode. keyspace  +  (trnode.keyct) 

*  ENTLN)  !=  *a) 
return  fileaddr(*p,  *a) ; 
if  (trnode. prntnode  ==01!  trnode.rtsib  ==  0) 
break; 
cn  =  *p; 

*p  =  trnode. prntnode; 
read_node (*p,  Strnode); 

*a  =  t  mode,  keyspace  ; 

while  (* ( (RPTR  *)  (*a  -  ADR))  !=  cn) 

*a  +=  ENTLN; 

) 

return  0; 


/*  -  scan  to  the  previous  sequential  key  -  */ 

static  RPTR  scanprev (RPTR  *p,  char  **a) 

{ 

RPTR  cn; 

if  (trnode. nonleaf)  ( 

*p  =  * ( (RPTR  *)  (*a  -  ADR)); 
read_node (*p,  Strnode); 
while  (trnode. nonleaf )  ( 

*p  =  *( (RPTR  *) 

(trnode. keyspace+ (trnode.keyct) *ENTLN-ADR) ) ; 
read_node ( *p ,  Strnode); 

) 

*a  =  trnode. keyspace  +  (trnode.keyct  -  1)  *  ENTLN; 
return  * ( (RPTR  *)  (*a  +  KLEN) ) ; 

) 

while  (-1)  1 

if  (trnode. key space  !=  *a)  { 

*a  -=  ENTLN; 

return  fileaddr(*p,  *a) ; 

} 

if  (trnode. prntnode  ==  0  ! !  trnode. lfsib  ==  0) 
break; 
cn  =  *p; 

*p  =  trnode. prntnode; 

( continued  on  page  1 50) 
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Listing  Three  (Listing  continued ,  text  begins  on  page  121.) 

read_node ( *p,  Strnode) ; 

*a  *  t  mode,  key  space; 

while  (* ( (RPTR  *)  (*a  -  ADR))  !»  cn) 

*a  +=  ENTLN; 

} 

return  0; 


/* - locate  pointer  to  child - */ 

static  char  * chi idptr (RPTR  left,  RPTR  parent,  BTREE  *btp) 

{ 

char  *c; 

read_node (parent ,  btp) ; 
c  =  btp->key space; 

while  (* ( (RPTR  *)  (c  -  ADR))  !=  left) 
c  +=  ENTLN; 
return  c; 

} 

/* - current  key  value - */ 

void  keyval(int  tree,  char  *ky) 

( 

RPTR  b,  p; 
char  *k; 
int  i; 

trx  =  tree; 
b  =  cur  mode  [trx]  ; 

if  (b)  { 

read_node (b,  itrnode) ; 
i  *  currkno[trx] ; 

k  -  t  mode,  key  space  +  ( (i  —  1)  *  ENTLN); 
while  (i  “  0)  { 

p  =  b; 

b  =  trnode.prntnode; 

read_node (b,  Strnode) ; 

for  (;  i  <■  trnode.keyct;  i++)  { 

k  =  trnode.keyspace  +  ( ( i  -  1)  *  ENTLN); 
if  (* ( (RPTR  *)  (k  +  KLEN))  —  p) 
break; 

) 

} 

memmove(ky,  k,  KLEN); 

I 

) 

/* - current  key - */ 

RPTR  currkey(int  tree) 

[ 

RPTR  f  -  0; 
trx  ■  tree; 

if  (cur mode  [trx] )  [ 

read  node (currnode [trx] ,  itrnode) ; 
f  =  *(  (RPTR  *) 

(trnode . keyspace+ (currkno [trx] * ENTLN) -ADR) ) ; 

) 

return  f; 


/* - read  a  btree  node - */ 

static  void  read_node (RPTR  nd,  void  *bf) 

[ 

bseek(nd) ; 

fread(bf ,  NODE,  1,  fp[trx]); 
if  (ferror(fp[trx] ) )  ( 

errno  *  D_IOERR; 
dberror () ; 

1 

) 

/* - write  a  btree  node - */ 

static  void  write_node (RPTR  nd,  void  *bf) 

{ 

bseek (nd) ; 

fwrite(bf ,  NODE,  1,  fp[trx]); 
if  (terror (fp [trx] ) )  { 

errno  *  D_IOERR; 
dberror () ; 

} 

I 

/* - seek  to  the  b-tree  node - *  I 

static  void  bseek (RPTR  nd) 

{ 

if  (fseek (fp[trx] , 

(long)  (NODE+( (nd-1) *NODE) ) ,  SEEK_SET)  “ERROR)  { 
errno  =  D_IOERR; 
dberror () ; 

) 

1 

/* - out  of  memory  error - */ 

static  void  memerr(void) 

( 

errno  =  D_OM; 
dberror ( ) ; 

) 


End  Listings 
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Listing  One  (Text  begins  on  page  131 ■) 

{ - 

{ 

{  JXDESK 

{ 

{  Jeff's  Experimental  Desktop  Manager  for  Turbo  Vision 

{ 

{  by  Jeff  Duntemann 

{  For  Turbo  Pascal  V6.0 

{ 

{ - 


PROGRAM  JDesk; 

{  These  are  all  Turbo  Vision  units:  } 

USES  Objects,  Drivers,  Views,  Menus,  Dialogs,  App; 


CONST 

SysStatCmd  -  102; 
NullCmd  -  101; 


TYPE 

PDesk  -  ATDesk; 

TDesk  -  OBJECT (TApplication) 

PROCEDURE  HandleEvent (VAR  Event:  TEvent);  VIRTUAL; 
PROCEDURE  InitMenuBar;  VIRTUAL; 

PROCEDURE  InitStatusLine;  VIRTUAL; 

PROCEDURE  SystemStatistics; 

END; 


NewSubMenu ( ' ~T~ erm' ,  hcNoContext , NewMenu ( 

NewItem('Link  to  “M“CI',  "  ,0, NullCmd, hcNoContext, 

NewItem('Link  to  “CompuServe' ,",  0, NullCmd,  hcNoContext, 
NewItem('Link  to  “B“ix' ,  ",  0,  NullCmd,  hcNoContext, 

Newltem  ('Terminal  window',  ", 0, NullCmd, hcNoContext, 
nil))))), 
nil) ))))))  ; 

END; 


PROCEDURE  TDesk. InitStatusLine; 
VAR 

R:  TRect; 


BEGIN 

GetExtent (R) ; 

R.A.Y  R.B.Y-1; 

StatusLine  :•  New (PStatusLine,  Init(R, 

NewStatusDef (0,  $FFFF, 

NewStatusKey('“Alt-X“  Exit' ,kbAltX, cmQuit,nil) ,nil) ) ) ; 

END; 


BEGIN 

Desk.Init; 
Desk. Run; 
Desk. Done; 
END. 


VAR 

Desk:  TDesk;  {  Allocate  an  instantiation  of  TDesk  } 
(  TDesk  method  definitions:  ) 

PROCEDURE  TDesk. HandleEvent (VAR  Event:  TEvent); 


End  Listing 


BEGIN 

TApplication. HandleEvent (Event) ; 

IF  Event. What  -  evCommand  THEN  {  If  the  event  was  a  command  } 
BEGIN 

CASE  Event . Command  of 

{  The  system  invokes  a  method  in  response  to  a  command:  ) 
SysStatCmd  :  SystemStatistics; 

ELSE 

Exit;  {  Exit  the  event  handler;  i.e.,  do  nothing  ) 

END; 

ClearEvent (Event) ; 

END; 

END; 


PROCEDURE  TDesk. SystemStatistics; 


VAR 

R:  TRect; 

D:  PDialog; 
C:  Word; 


BEGIN 

(  Create  a  new  dialog:  ) 

R.Assign(25,  5,  55,  14); 

D  New (PDialog,  Init (R, ' System  Stats')); 

(  Create  and  insert  controls  into  the  dialog:  ) 
R.Assign(9,  6,  21,  8); 

DA . Insert (New (PButton, Init (R, ' OK' , cmCancel, bfNormal) ) ) ; 

(  Execute  the  modal  dialog:  ) 

C  :-  DeskTopA.ExecView(D) ; 

END; 


PROCEDURE  TDesk. InitMenuBar; 


VAR 

R:  TRect; 


BEGIN 

GetExtent (R) ; 

R.B.Y  :«  R.A.Y+1; 

MenuBar  : -  New (PMenuBar, Init (R, NewMenu ( 

NewSubMenu ( ' ~p~' ,  hcNoContext , NewMenu ( 

Newltem ( ' ~A~bout ' ,  "  , 0 , NullCmd, hcNoContext , 

NewItem('How  to  ~R~egister' ,",  0, NullCmd, hcNoContext, 
nil))), 

NewSubMenu ( ' ~S~ystem' ,  hcNoContext ,  NewMenu ( 

Newltem  (' “Statistics' ,  ",  0,  SysStatCmd,  hcNoContext, 

Newltem  ('Set  ~T“ime',  ",0,  NullCmd,  hcNoContext, 

Newltem ('Set  ~D“ate',  "  ,0, NullCmd, hcNoContext, 
Newltem ('“R“un  DOS  app. 0, NullCmd, hcNoContext, 
NewLine ( 

Newltem {' E“x“it' , ' Alt-X' ,kbAltX, cmQuit, hcNoContext, 
nil))))))), 

NewSubMenu ( ' Address  “B~ook' , hcNoContext, NewMenu ( 

Newltem ('“0“pen  book',  " ,0, NullCmd, hcNoContext, 
Newltem ('“C“reate  book' ,  "  , 0, NullCmd, hcNoContext, 
Newltem ('“P“rint  book',  ", 0, NullCmd, hcNoContext, 
nil)))), 
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OF  1  N  T  E  R  E  S  T 


Third-party  CAD/CAM  developers  may 
be  interested  in  the  CAD/CAM  Devel¬ 
oper’s  Kit  (CCDK)  from  Building  Block 
Software.  CCDK  is  a  toolbox  of  C  func¬ 
tions  that  provides  full  3-D  DXF,  2-D 
and  3-D  display  and  geometry  opera¬ 
tions,  and  list-management  capabilities. 

DD/spoke  with  Kevin  Green  of  Karta 
Technology,  who  said  that  “We  needed 
to  create  a  drawing  with  AutoCAD  and 
bring  the  drawing  into  our  program, 
which  links  to  databases  or  a  variety 
of  other  things.  The  big  advantage  [of 
CCDK]  was  the  DXF  support.  It  would 
have  taken  us  a  lot  of  time  to  develop 
this  on  our  own.”  Kevin  also  men¬ 
tioned  that  the  documentation  and  tech 
support  are  exceptional. 

CCDK  can  be  used  for  developing 
DXF  file  viewer  add-ons  to  database 
programs,  numerical  code  generators, 
finite  element  mesh  generators,  3-D  pip¬ 
ing  layout  tools,  and  printed  circuit 
board  layout  checking  programs.  CCDK 
augments  Autodesk’s  C-binding  envi¬ 
ronment  with  a  full  set  of  functions  for 
CAD/CAM  operations,  saving  develop¬ 
ers  the  task  of  writing  all  the  computa¬ 
tional  functions  themselves.  Object  hi¬ 
erarchies  and  data  encapsulation  make 
programming  faster  and  minimize  the 
number  of  public  routines  required  to 
support  all  of  CCDK’s  operations.  Full 
DXF  Release  10  functionality  is  sup¬ 
ported,  so  programs  can  read  and  write 
both  ASCII  and  binary  DXF  formats. 
Block  inserts  can  be  exploded  into  ge¬ 
ometry  and  solid  models  can  be  gener¬ 
ated  for  shading  with  AutoSolid.  The 
routines  are  adaptable  to  popular  graph¬ 
ics  libraries.  CCDK  is  compatible  with 
Microsoft  C  5.1  and  6.0  and  Borland 
Turbo  C  2.0,  and  supports  Metaware 
and  Watcom  compilers  as  well.  Single 
programmer  licenses  start  at  $1,295. 
Reader  service  no.  20. 

Building  Block  Software  Inc. 

P.O.  Box  1373 
Somerville,  MA  02144 
617-628-5217 


The  Am29050  Floating  Point  Processor 
is  a  general-purpose,  32-bit  microproc¬ 
essor  from  Advanced  Micro  Devices. 
Featuring  a  RISC  architecture,  the 
Am29050  has  a  pipelined,  on-chip  float¬ 
ing  point  unit  that  performs  IEEE-com¬ 
patible,  single-  and  double-precision 
arithmetic  at  a  rate  of  80  MFLOPS  at  40 
MHz.  Other  features  improve  the  per¬ 
formance  of  loads  and  branches,  al¬ 
lowing  sustained  integer  performance 
of  32  MIPS  at  40  MHz. 

The  Am  29050  microprocessor  is  pin 
and  code-compatible  with  the  Am  29000 
microprocessor,  so  existing  Am29000 
microprocessor  applications  can  use  the 
Am29050  processor  without  modifica¬ 
tion  and  can  achieve  a  factor-of-four 
increase  in  performance  for  such  float¬ 
ing-point-intensive  applications  as  graph¬ 
ics  (faster  3-D  performance)  and  laser 
printers  (highest  page  description  lan¬ 
guage  performance).  Reader  service  no. 
21. 

Advanced  Micro  Devices 
901  Thompson  Pi. 

Sunnyvale,  CA  94088 
408-732-2400 

The  ToolBook  Author’s  Resource  Kit 
(ARK)  is  now  available  from  Asymet¬ 
rix.  The  ARK  includes  a  license  to  dis¬ 
tribute  a  royalty-free  runtime  version 
of  ToolBook  and  three  DLLs,  as  well 
as  development  tools.  ToolBook  1 .0  is 
a  software  construction  set  for  building 
graphical  applications  without  using  tra¬ 
ditional  programming  languages.  You 
can  use  ToolBook  to  build  Windows 
3.0  applications. 

ARK  includes  two  development  utili¬ 
ties,  and  two  online  applications  offer 
ideas  on  user  interface  design  for  Tool¬ 
Book  applications.  The  Windows  DLLs 
include  a  DLL  that  provides  access  to 
and  file  manipulation  of  dBase  III  data 
files;  another  for  determining  the  charac¬ 
teristics  of  a  display  device,  for  deter¬ 
mining  which  fonts  are  available  for 
display  and  printing,  and  for  setting 
and  retrieving  values  in  a  Windows 
initialization  file  directly  from  a  Tool¬ 
Book  script;  and  one  for  copying  and 
deleting  DOS  files  and  for  performing 
other  DOS  functions  within  a  Tool¬ 
Book  script. 

Merillin  Paris,  head  engineer  on  the 
project,  told  DDJxhaX.  “a  misconception 
some  people  have  is  that  ToolBook  is 
interpreted.  It  is  not  interpreted,  it  is 
p-code.  You  can  strip  the  code  down 
to  binary  and  remove  the  script  to  pro¬ 
tect  your  source  code.”  The  utility  in¬ 
cluded  for  that  is  Script  Remover.  An¬ 
other  utility  included  is  BookLook,  for 
examining  and  changing  an  object’s 
properties.  The  ARK  is  priced  at  $450, 
and  for  another  $495  you  can  subscribe 


to  the  Asymetrix  Developer  Support  Part¬ 
nership  program  and  be  assigned  to  a 
support  engineer  for  one  year  of  tech¬ 
nical  support.  Reader  service  no.  22. 
Asymetrix  Corp. 

110  110th  Ave.  NE,  Ste.  717 
Bellevue,  WA  98004 
206-637-1500 

If  you  need  high-performance,  interrupt- 
driven  control  of  asynchronous  com¬ 
munications  in  your  C  programs,  you 
might  want  to  check  out  the  new  Sil- 
verComm  C  Async  Library  from  Silver- 
Ware.  The  library  is  customizable,  as 
full  source  code  is  included. 

A  device  event  monitor  capability 
permits  execution  of  your  C  functions 
at  interrupt  time.  These  functions  can 
set  flags  that  signal  an  event  in  your 
application.  And  you  can  create  func¬ 
tions  that  process  the  interrupt. 

Jim  McCusker  of  Electronics  Unlim¬ 
ited  has  been  a  beta  tester  for  all  evolu¬ 
tions  of  the  Async  package.  He  told 
DDJ,  “We  have  used  the  library  on 
various  projects  here.  We  do  a  lot  of 
custom  software  and  hardware  for  the 
process-control  industry.  This  package 
takes  the  burden  off  the  user  —  you 
don’t  need  to  know  about  serial  ports 
on  a  PC.  You  can  write  a  comm  pro¬ 
gram  in  about  10  minutes  for  a  dumb 
terminal.  You  can  grow  with  this 
package  —  it  has  extra  functions,  such 
as  timers  for  setting  a  delay  and  basic 
video  I/O.  And  it  supports  multiple 
communication  ports  simultaneously, 
asynchronously.  One  of  the  best  things 
is  the  manual;  each  function  is  described 
in  detail  and  has  an  example  of  its  use.” 

The  SilverComm  C  Async  Library  fea¬ 
tures  huge  model  queues;  terminal  emu¬ 
lation;  XModem,  YModem,  YModem 
batch,  and  ASCII;  background  timers; 
enhanced  compatibility;  flow  control; 
smart  modem  support;  high-level  re¬ 
mote  input;  character  filtering;  and  sup¬ 
ports  up  to  115Kbaud.  The  library  sells 
for  $259.  Reader  service  no.  25. 
Silverware  Inc. 

3010  LBJ  Freeway,  Ste.  740 
Dallas,  TX  75234 
214-247-0131 

UniFLEX.wks,  from  UniFLEX  Comput¬ 
ing,  is  a  real-time  cross-development 
package  for  VME  designers.  Previously 
only  available  as  a  self-hosted  develop¬ 
ment  system,  UniFLEX  is  now  fully  in¬ 
tegrated  with  Sun  Microsystems  SPARC 
and  68000  workstations.  UniFLEX  is 
Unix-compatible,  multitasking,  and 
multiprocessing.  You  can  use  Sun’s  Unix 
development  tools  to  edit,  track,  and 
manage  system  software,  and  then  use 
UniFLEX.wks  to  compile,  link,  and  down- 
(continued  on  page  157) 
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(continued  from  page  153) 
load  object  modules  over  the  Ethernet 
to  the  target  VME  system,  and  then 
debug  with  UniFLEX  tools  such  as  the 
GBD  symbolic  debugger. 

UniFLEX.wks  produces  a  pseudo¬ 
disk  that  contains  the  UniFLEX  kernel 
and  application  programs  and  which 
can  be  placed  in  .  ROM  for  embedded 
system  applications.  Real-time  features 
include  programmer-declared  real-time 
priorities,  task  synchronization,  contigu¬ 
ous  file  system,  and  intertask  commu¬ 
nication  using  binary  semaphores  or 
named  message  exchanges.  Tightly  cou¬ 
pled  multiprocessing  allows  multiple 
CPUs  on  a  single  backplane  executing 
in  concert  with  dynamic  load  balanc¬ 
ing.  UniFLEX.wks  allows  for  the  devel¬ 
opment  of  X  Window  (with  Motif)  ap¬ 
plications  on  target  systems  using  Sun 
Workstations.  Reader  service  no.  23. 
UniFLEX  Computing  Ltd. 

Ill  Providence  Rd. 

Chapel  Hill,  NC  27514 
919-493-1451;  800-486-1000 

The  C++  Rider  package  for  source  code 
analysis  and  online  help  for  C  and  C++ 
is  now  available  from  Western  Wares. 
Based  on  the  CC-Rider  tool  for  C,  C++ 
Rider  consists  of  a  pop-up  source¬ 
browsing  utility  (CCRIDER)  and  a  source 
code  analyzer  (CCSYM).  CCRIDER  can 
be  used  with  any  text-mode  editor,  in¬ 
tegrated  environment,  or  debugger  to 
provide  hypertext  symbol  referencing 
as  you  program.  You  can  display,  view 
source,  edit,  or  paste  any  symbol  defi¬ 
nition  using  a  hotkey,  and  you  can 
recall  all  classes,  structures,  unions, 
enums,  enum  values,  typedefs,  mac¬ 
ros,  functions,  and  data  symbols. 

CCSYM  performs  analysis  and  sym¬ 
bol  database  management  for  C  and 
C++  programs,  and  can  generate  func¬ 
tion  prototype  header  files  as  required 
by  the  C++  language.  The  package  sup¬ 
ports  Microsoft  C  6.0,  Zortech  C++  2.1, 
and  Borland’s  Turbo  C++.  It  is  avail¬ 
able  in  both  a  standard  edition  and  a 
professional  edition.  Contact  the  com¬ 
pany  for  pricing.  Reader  service  no.  26. 
Western  Wares 
Box  C 

Norwood,  CO  81423 
303-327-4898 

Macintosh  programmers  now  have  an 
alternative  to  TextEdit  with  the  release 
of  DataPak  Software’s  Word  Solution 
Engine,  a  new  module  for  basic  text 
editing  with  multiple  font  and  style  sup¬ 
port.  The  company  claims  that  Word 
Solution  Engine  has  superior  buffering 
capabilities  (16  Mbytes)  to  TextEdit 
(which  has  a  32K  limit),  is  faster,  and 
formats  better. 
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Ben  Cahan  of  MacToolkit  concurs. 
He  told  DDJ that  Word  Solution  Engine 
“is  very  complete  and  works  flawlessly. 
I’m  working  in  an  application  that  is 
text-editing  intensive,  and  this  product 
handles  pretty  much  everything.  It  could 
save  one  or  two  years  of  work  writing 
your  own  text  editor.  This  is  the  only 
solution  I’ve  seen  so  far  for  quality  text 
editing.” 

Word  Solution  Engine  features  fast 
editing  and  display  of  large  text  files, 
Script  Manager  support,  Quickdraw 
color  support,  and  “User  Styles.”  Also 
multiple  stylations,  tab  handling,  I/O 
and  printing  support,  “scrap”  support, 
and  full-justification.  The  package  in¬ 
cludes  a  programmer’s  guide,  sample 
source  code  that  demonstrates  each 
function,  interface  files  for  MPW  Pascal 
and  Think  C,  and  linkable  object  files 
for  both.  Object  code  is  being  offered 
at  an  introductory,  one-time  royalty- 
free  rate  of  $300.  Reader  service  no.  24. 
DataPak  Software  Inc. 

9317  NE  Highway  99,  Ste.  G 
Vancouver,  WA  98665-8900 
206-573-9155 
800-327-6703 

The  Solid  Link  Library  from  Solid  Soft¬ 
ware  is  a  telecommunications  package 
for  C,  C++,  and  Modula-2  program¬ 
mers.  It  includes  the  difficult-to-imple- 
ment  ZModem  protocol,  as  well  as 
XModem,  XModem-lK,  YModem,  Mo- 
dem7,  TeLink,  and  SEAlink  file  transfer 
protocols  with  concurrent  and  back¬ 
ground  transfers.  XON/XOFF,  DSR/ 
DTR,  CTS,  RTS,  as  well  as  Ctrl-C/Crtl-K 
handshaking  are  supported.  The  pack¬ 
age  includes  a  sample  terminal  pro¬ 
gram  with  source  code.  Supports  most 
popular  C,  C++,  and  Modula-2  compil¬ 
ers.  Solid  Link  for  C  and  Modula-2  is 
$199,  with  source  $498;  add  $50  for 
C++.  Reader  service  no.  27. 

Solid  Software 
227  West  Fourth  St. 

Cincinnati,  OH  45202-2645 
513-651-1133 

Microway  has  announced  NDP  C++, 
a  full  32-bit,  protected-mode  C++  com¬ 
piler  that  is  AT&T  Release  2.0-compat¬ 
ible.  It  runs  on  the  80386,  80486,  and 
i860,  under  DOS,  Unix,  Xenix,  and 
SunOS.  NDP  C++  utilizes  the  same  code 
generators  and  global  optimizing  tech¬ 
nologies  used  in  the  NDP  Fortran,  C, 
and  Pascal  compilers,  and  includes  ex¬ 
tensions  that  specifically  handle  C++ 
features,  such  as  function  inlining, 
classes,  constructors  and  destructors, 
single  and  multiple  inheritance,  and 
function  and  operator  overloading.  Mi¬ 
croway  integrated  C++  extensions  into 
their  ANSI  C  front  end  and  extended 


their  optimizer  and  code  generator  to 
handle  C++-specific  operations.  They 
claim  this  approach  increases  the  exe¬ 
cution  speed  of  the  compiler  and  im¬ 
proves  the  quality  of  the  generated  code. 
The  80386  version  is  $895,  the  80486 
version  is  $1,195,  and  the  i860  version 
is  $1,995.  All  include  one  year  of  free 
updates.  Reader  service  no.  28. 
Microway 
P.O.  Box  79 
Kingston,  MA  02364 
508-746-7341 

The  Multimedia  Expo,  held  in  San  Fran¬ 
cisco  in  early  October,  consisted  of 
seminars,  workshops,  corporate  pres¬ 
entations,  and  exhibits  in  the  field  of 
multimedia,  the  components  of  which 
are  based  on  digital  technology.  Semi¬ 
nar  topics  included  telecommunications 
and  networking,  desktop  video  work¬ 
stations,  voice  command,  multimedia 
engines  and  systems,  CD-ROM  XA  pro¬ 
duction,  full-motion  video  hardware  and 
software,  hypertext  and  hypermedia 
authoring,  visualization,  animation,  ar¬ 
tificial  reality,  and  multimedia  projects 
in  education.  The  professional  work¬ 
shops  covered  similar  topics,  but  in¬ 
cluded  hands-on  instruction  and  in- 
depth  information.  The  thrust  of  the 
Expo  was  on  the  business  applications 
of  multimedia  for  corporate  presenta¬ 
tions  and  information  systems.  Spon¬ 
sored  by  American  Expositions,  Mul 
timedia  Expo  will  be  held  in  New  York 
in  May  1991  and  again  in  San  Francisco 
in  October  1991.  Call  212-226-4141  for 
information. 

Communications  Formulas  and  Algo- 
rithmsby  C.  Britton  Rorabaugh  has  been 
published  by  McGraw-Hill.  Rorabaugh 
focuses  on  definitions,  formulas,  algo¬ 
rithms,  and  design  data  needed  by  com¬ 
munications  engineers,  programmers, 
and  technicians.  The  author  presents 
techniques  for  analyzing,  simulating, 
designing,  and  testing  communications 
systems.  Each  procedure,  method,  and 
algorithm  includes  the  relevant  mathe¬ 
matical  notation  and  pseudocode,  guide¬ 
lines  for  selection  and  use,  function 
plots,  graphs,  and  diagrams,  and  prac¬ 
tical  examples.  Topics  range  from  prob¬ 
ability  distributions  in  communications 
to  pulse  modulation  and  transmission, 
from  random  processes  to  signals  and 
spectra,  and  from  communication  chan¬ 
nels  to  phase  shift  keying.  The  book 
sells  for  $39.95.  ISBN:  0-07-053644-9- 
Reader  service  no.  29. 

McGraw-Hill  Publishing  Co. 

11  West  19th  St. 

New  York,  NY  10011 

212-337-5945 

800-262-4729 


Help!  is  a  help  system  for  creating  pop¬ 
up  help  and  menus,  from  Zaron  Soft¬ 
ware.  Help!  can  be  adapted  to  any  ap¬ 
plication  you  buy  or  write  yourself. 
Help!  can  be  used  with  standard  text 
files  to  create  a  custom  “flat”  help  sys¬ 
tem.  It  automatically  displays  the  cor¬ 
rect  help  file  for  the  program  you  are 
running,  returns  values  or  commands 
to  the  executing  program  or  to  DOS, 
provides  context-sensitive  help  at  ev¬ 
ery  point  in  each  program’s  operation, 
and  can  be  used  as  a  menu  system  as 
well.  Sample  help  files  and  programs 
are  included,  as  is  a  help  system  for 
commonly  used  DOS  commands.  Help! 
is  a  TSR,  requires  less  than  14K  of  mem¬ 
ory,  and  includes  mouse  support.  The 
price  is  $49-95.  Reader  service  no.  30. 
Zaron  Software 
13100  Dulaney  Valley  Rd. 

Glen  Arm,  MD  21057 
301-592-3334 

Objectworks\ Smalltalk,  Release  4,  is  a 
new  generation  object-oriented  program¬ 
ming  system  from  ParcPlace  Systems. 
It  is  designed  for  creating  customized, 
true  color,  graphic  applications  for  hetero¬ 
geneous  computing  environments  un¬ 
der  standard  windowing  systems.  Other 
new  features  include  the  Smalltalk  Port¬ 
able  Imaging  Model  (SPIM),  incremental 
garbage  collection,  and  support  for  in¬ 
ternational  applications.  Objectworks\ 
Smalltalk  is  designed  for  creating  interac¬ 
tive  business  and  technical  applications 
such  as  information  management  and 
decision  analysis,  systems  design  and 
simulation,  and  application-specific 
CASE  tools.  Objectworks\ Smalltalk  sells 
for  $3,500.  Reader  service  no.  32. 
ParcPlace  Systems 
1550  Plymouth  St. 

Mountain  View,  CA  94043 
415-691-6700 

C++/Views  from  CNS  is  fully  validated 
with  Zortech  C++  Version  2.1.  C++/ 
Views  is  an  application  development 
framework  for  Windows  3.0  develop¬ 
ment  that  provides  object  classes  and 
productivity  tools.  C++/Views  comes 
with  over  60  ready-made  C++  object 
classes  that  encapsulate  the  functional¬ 
ity  within  Windows.  C++/Views  also 
comes  with  a  C++  object  class  browser, 
which  manages  such  mechanics  as  build¬ 
ing  make  files.  An  interface  generator 
is  also  included  for  building  C++  dia¬ 
log  objects.  C++/Views  retails  for  $495. 
Reader  service  no.  36. 

CNS  Inc. 

Software  Products  Dept. 

7090  Shady  Oak  Rd.; 

Minneapolis,  MN  55344 
612-944-0170 
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A  Look  at  the  Latest  Videos 


S  WAIN  E'  S  FLAMES 


In  these  latter  days  of  the  20th  century,  the  format  of  choice  for  communicating  with 
Americans  is  VCR,  and  if  the  computer  industry  knows  anything,  it  knows  formats. 
Today,  software  documentation,  press  releases,  and  memoirs  of  computer  scientists  are 
all  making  the  move  to  video.  The  latest  collection  arrived  just  in  time  for  the  holidays. 
Here  are  the  best  of  the  lot. 

The  Dutch  Boy’s  Finger:  Edsgar  Dijkstra  in  Concert.  Rijksfilms,  90  min.  The  King  of  the 
Dutch  Computer  Science  Insult  Comics  takes  a  few  pokes  at  some  well-chosen  targets  and 
a  North  Sea  of  laughs  comes  pouring  in.  Among  the  pokees:  Americans  (too  anti¬ 
intellectual);  IBM  (too  big);  software  engineering  (the  20th-century  mania  for  cooperation 
in  everything);  universities  (their  degeneration  into  graduate  factories  a  threat  to  civilization); 
programming  languages  (Fortran  is  an  infantile  disorder,  PL/I  a  fatal  disease,  Basic  leaves 
students  mentally  mutilated  beyond  hope  of  regeneration,  APL  creates  a  new  generation 
of  coding  bums,  natural  language  programming  is  doomed  to  fail,  and  it’s  unscientific 
and  a  symptom  of  professional  immaturity  to  call  any  of  them  languages  at  all);  and  John 
von  Neumann  (as  the  villain  who  introduced  anthropomorphism  into  computer  science). 
Based  on  his  popular  treatise,  Selected  Writings  on  Computing:  A  Personal  Perspective, 
originally  distributed  in  copier-paper  format.  R,  strong  language,  adult  themes. 

Groupthink:  Getting  Ready  for  Groupware,  CoLabVideo,  104  min.  A  collection  of 
lectures,  interviews,  and  case  studies  on  the  Groupthink  model  and  its  implementation. 
Michael  Shrage  and  a  group  of  Lotus  groupware  specialists  discuss  how  all  great  discoveries 
are  really  collaborative  efforts,  a  group  of  Apple  Computer  Area  Associates  examines  the 
ways  in  which  workgroup  computing  has  helped  Apple  retain  its  technical  edge,  and,  in 
an  interview  with  a  group  of  Newsweek  reporters,  Alvin  Toffler  explains  how  to  detect  and 
suppress  individual  thinking  in  groups.  The  second  half  of  the  video  deals  with  legal  and 
technical  issues:  A  legal  firm  discusses  the  subtleties  of  the  shrinkware  group-license:  If 
any  of  the  group  breaks  the  seal,  is  the  entire  group  obligated  by  the  terms  and  conditions 
of  the  contract?  To  its  credit,  the  video  frankly  acknowledges  some  problems  yet  to  be 
resolved  in  groupware;  in  one  case  study  at  a  university  function,  a  group  of  philosophy 
professors  is  shown  failing  to  get  anything  to  eat  due  to  a  nondeterminancy  in  the 
groupware  algorithm.  G,  suitable  for  all  viewers. 

The  Face  Against  the  Glass.  Loving  Grace  Cybernetics,  120  min.  A  challenging  video, 
narrated  by  Mitch  Kapor.  Based  on  a  short  story  by  Franz  Kafka,  the  video  explores  the 
consequences  for  human  interface  design  of  the  fact  that  people  are  more  adaptable  than 
machines.  Kafka  himself  wrote  the  best  summation  of  the  story:  Leopards  break  into  the 
temple  and  drink  up  the  sacrificial  wine;  this  is  repeated  over  and  over  again;  eventually 
it  becomes  predictable,  and  is  incorporated  into  the  ceremony.  Many  questions  are  left 
unresolved  in  this  dark,  troubling  video:  Is  there  any  sequence  of  actions  that  will  not 
come  to  seem  to  users  the  normal  way  to  get  a  task  accomplished,  if  they  repeat  it  often 
enough?  Is  human  interface  design  an  art,  a  science,  or  religious  ritual?  NC-17,  ritual  acts, 
human  sacrifice,  desecration  of  icons. 

The  Apple/Claris  HyperCard  Announcement,  Apple  Computer  Multimedia  Lab,  38  min. 
A  taut,  white-knuckle  suspense  story  with  a  Peckinpah-like  burst  of  violence  at  the  climax. 
After  three  years,  Apple  releases  a  new  version  of  HyperCard.  The  tension  is  tangible,  and 
the  denouement  is  predictable  when  the  company  announces  that  the  product,  formerly 
bundled  with  all  Macintoshes,  will  henceforth  be  a  competitively-priced  Claris  product.  A 
thriller.  R,  strong  language,  graphic  violence. 

A  Tribute  to  Bill  Gates,  Microsoft  Press  Video  Division,  3  min.  All  of  Bill  Gates’s  industry 
friends  get  together  to  express  their  appreciation  and  fondness  for  the  great  man.  G, 
suitable  for  all  viewers. 

Our  Best  Marketing  Secrets,  Tandy/Radio  Shack  Videos,  ??  min.  This  video  could  not 
be  reviewed,  as  the  copy  received  was  blank. 


Michael  Swaine 
editor-at-large 
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The  Complete  Dr  Dobb’s  Journal  Bound  Volumes 

Each  bound  volume  contains  a  full  year’s  worth  of  useful  code  and  fascinating  history  from 
Dr.  Dobb’s  Journal.  DDJ  is  the  oldest  and  most  popular  programmer’s  magazine  today,  and 
many  back  issues  have  long  been  sold  out.  Most  of  the  practical  technical  information  contained 
in  these  volumes  is  not  available  from  any  other  source.  But  within  these  giant  volumes,  you’ll 
find  a  treasury  of  useful  source  code  and  programming  tips. 


Volume  1  —1976 

Chronicles  the  advent  of  the 
microcomputer  era  in  1976.  Always 
pertinent  for  bit  crunching  and  byte 
saving,  home-brew  computer  projects, 
and  the  technical  history  of  home 
computing.  Topics  include:  Tiny  BASIC, 
the  first  words  on  CP/M,  speech 
synthesis,  floating  point  routines,  the 
6502  disassembler  for  the  Apple,  and 
much  more.  364  pp. 

Volume  2  — 1977 

The  small  computer  emerges  as  a 
powerful  tool  for  the  modern  age  in  these 
issues  from  1977.  Topics  include: 
Lawrence  Livermore  Lab’s  BASIC, 

Dr.  Starweather’s  PILOT,  using  a 
modem,  string-handling  techniques, 
ciphers,  Turtle  graphics,  and  micro 
utilities.  498  pp. 

Volume  3  — 1978 

Explores  the  foundation  of  the  mass- 
market  computer  industry  in  1978.  Topics 
include:  programming  in  BASIC,  PILOT, 
and  Pascal;  RAM  memory  testers;  Apple 
utility  programs;  the  S-100  bus  standard; 
STRUBAL;  and  a  structured  BASIC 
compiler.  478  pp. 


Volume  4  — 1979 

Heralds  the  widespread  acceptance  of  the 
microcomputer  in  America.  Innovative 
ideas  and  articles  guide  the  reader 
through  the  age  of  discovery  in  1979. 
Topics  include:  selecting  business 
software,  microcomputer  speech  and 
music,  information  networks,  and 
interfacing  techniques.  467  pp. 

Volume  5  — 1980 

Focuses  on  the  technological  promise  of 
the  modern  microcomputer.  Topics 
include:  the  revolutionary  impact  of 
CP/M,  C  programming  and  the  UNIX 
operating  systems,  a  survey  of  computer 
networks,  software  portability, 
introduction  to  Forth,  and  compiler 
writing.  450  pp. 

Volume  6  — 1981 

The  microcomputer  enters  the 
mainstream.  These  issues  assess  the 
revolutionary  impact  of  microcomputers 
on  the  individual  and  on  society  in  1981. 
Topics  include:  computer  conferencing, 
the  power  of  Forth,  B-  and  16-bit 
technology,  Rubik’s  cube  simulator,  and 
an  adventure  game  development  systems. 
558  pp. 


Volume  7  — 1982 

Examines  the  potential  of  powerful 
1 6-bit  micros,  including  the  birth  of  the 
IBM  PC  in  1982.  Topics  include: 
in-depth  coverage  of  Forth,  68000,  8088 
programming,  C  software  tools,  utilities 
for  CP/M — including  a  spelling 
checker,  using  bulletin  boards,  and 
more.  568  pp. 

Volume  8  — 1983 

DDJ  turns  pro.  Some  of  the  most 
powerful  professional  programmer’s 
tools  ever  published  in  a  magazine  are 
in  this  1983  volume,  including  Small-C, 
the  RED  editor,  and  an  Ada  subset. 

798  pp. 

Volume  9  — 1984 

Shaping  things  to  come.  In  1984  DDJ 
examined  new  programming 
environments  including  Prolog,  expert 
systems,  Modula-2,  and  Pascal.  Other 
topics  include  GREP,  UNIX  internals, 
and  two  encryptions  systems.  982  pp. 
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Volume  10  — 1985 

The  year  of  living  dangerously.  In  1985  DDJ  added  more 
memory,  an  SCSI  port,  and  a  hard  disk  to  the  Macintosh; 
challenged  the  UNIX  establishment  with  plans  for  a  free 
UNIX.  Includes  software  tools  in  C,  Modula-2,  Forth,  Pascal, 
assembly  language,  and  Prolog.  942  pp. 

Volume  11  —1986 

The  promise  of  power.  Desktop  computers  began  to  rival 
minis  and  mainframes  in  power.  DDJ  covered  1986’s 
changes  with  issues  on  the  68000,  parallel  processing, 
artificial  intelligence,  the  80386,  and  multitasking.  DDJ  also 
supported  the  new  chips  with  assemblers,  translators,  and 
other  development  tools.  868  pp. 

Volume  12  —  1987 

Building  better  brains.  DDJ  broke  new  ground  in  1987  with  a 
neural  network  implementation,  monthly  coverage  of 
artificial  intelligence  and  object-oriented  programming 
techniques,  and  reviews  of  implementation  of  Prolog,  LISP, 
and  Smalltalk.  1015  pp. 
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The  new  frontier.  Database  technology,  Hyperanimation,  and 
much  more!  DDJ  talks  about  how  to  create  a  new  language, 
writing  real  time  programs  under  UNIX,  and  developing 
good  software.  Other  topics  on  object-oriented  programming, 
SQL  development  tools,  and  much  more  are  all  included. 

864  pp. 
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Wrapping  up  the  1980’s.  Highlights  include  complete 
coverage  of  object-oriented  programming,  windowing 
systems,  32-bit  programming,  memory  management, 
graphics  programming,  and  a  host  of  other  exciting  topics. 
DDJ  also  delivered  two  special  issues  —  Dr.  Dobb  ’s 
Macintosh  Journal  and  Dr.  Dobb’s  C  Sourcebook ,  both  are 
included  in  this  volume.  1051  pp. 
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DOS  5:  A  Developer’s  Guide 
Advanced  Programming  Guide  to  DOS 
by  Al  Williams 

This  complete  guide  to  programming  powerful,  professional  applications  for  all  versions 
of  MS-DOS  covers  such  advanced  topics  as  direct  access  techniques,  fundamentals  of 
graphics,  expanded  and  extended  memory,  TSR  programming,  protected  mode,  and  DOS 
extenders.  Packed  with  solid  examples  programmers  can  use,  study,  and  modify,  it  even 
includes  the  complete  source  code  for  an  80386  DOS  extender.  All  of  the  source  code  is 
available  on  disk  in  MS/PC-DOS  format.  914  pp. 

Book/Disk  (MS-DOS)  Item  #179-2  $39.95 

Book  only  Item  #177-6  $29.95 

DOS  5  User’s  Guide:  A  Comprehensive  Guide  for  Every  PC  User 
by  Dan  Gookin 

Take  control  of  the  MS-DOS®  operating  system  with  this  complete  guide  to  using  the 
world’s  most  popular  operating  system.  DOS  5  User’s  Guide  contains  clear,  concise 
explanations  of  every  feature,  function,  and  command  of  DOS  5.0.  Novice  PC  users  will 
gain  a  quick  start  on  using  DOS,  while  advanced  users  will  learn  savvy  tricks  and 
techniques  to  maneuver  their  way  quickly  and  easily  through  the  system.  Practical 
discussions  and  helpful  examples  teach  readers  how  to  edit  text  files,  use  directories, 
create  batch  files,  and  much  more.  Advanced  topics  include  using  EDLIN,  the  DOS  text 
editor;  configuring  the  system;  and  using  the  DOS  shell.  771  pp. 

Book  only  Item  #188-1  $24.95 

Clipper  5:  A  Developer’s  Guide 

by  Joseph  D.  Booth,  Greg  Lief,  and  Craig  Yellick 

(R) 

An  invaluable  guide  for  all  database  programmers  developing  applications  for  Clipper^ 
5.  Provides  a  quick  introduction  to  Clipper  5  basics  and  discusses  common  programming 
needs  such  as  designing  data  files,  user  interfaces,  reports,  and  more.  Advanced  topics 
include  networking,  debugging,  and  pop-up  programming.  Code  examples  are  used 
throughout  the  text,  providing  useful  functions  that  can  be  applied  immediately.  All 
source  code  is  available  on  disk  in  MS/PC-DOS  format.  1300  pp.  approx. 

Book  &  Disk  (MS-DOS)  Item  #242-X  $44.95 

Book  only  Item  #  240-3  $34.95 

Windows  3:  A  Developer’s  Guide 
by  Jeffrey  M.  Richter 

This  example-packed  guide  is  for  all  experienced  C  programmers  developing 
applications  for  Windows  3.0.  This  book  describes  every  feature,  function,  and 
component  of  the  Windows  Application  Programming  Interface,  teaching  programmers 
how  to  take  full  advantage  of  its  many  capabilities.  Diagrams  and  source  code  examples 
are  used  to  demonstrate  advanced  topics,  including  window  subclassing,  dynamic 
memory  management,  and  software  installation  techniques.  67 1  pp. 

Book/Disk  (MS-DOS)  Item  #164-4  $39.95 

Book  only  Item  #162-8  $29.95 
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Windows  3.0  By  Example 
by  Michael  Hearst 

Here  is  a  hands-on  guide  to  Windows  3.0.  Written  for  all  users  new  to  Windows,  this 
book  provides  thorough,  easy-to-follow  explanations  of  every  Windows  3.0  feature  and 
function.  Numerous  exercises  and  helpful  practice  sessions  help  readers  further  develop 
their  understanding  of  Windows  3.0.  398  pp. 

Book  only  Item  #180-6  $26.95 
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The  Complete  Memory  Manager 

Every  PC  User’s  Guide  to  Faster,  More  Efficient  Computing 

by  Phillip  Robinson 

Readers  will  learn  why  memory  is  important,  how  and  when  to  install  more,  and  how  to 
wring  the  most  out  of  their  memory.  Clear,  concise  instructions  teach  users  how  to 
manage  their  computer’s  memory  to  multiply  its  speed  and  ability  to  run  programs 
simultaneously.  Tips  and  techniques  also  show  users  how  to  conserve  memory  when 
working  with  popular  software  programs.  437  pp. 

Book  only  Item  #102-4  $24.95 


A  Small  C  Compiler,  Second  Edition 
by  James  Hendrix 

This  is  a  solid  resource  for  all  programmers  who  want  to  learn  to  program  in  C.  It 
thoroughly  explains  Small  C’s  structure,  syntax,  and  features.  It  succinctly  covers  the 
theory  of  compiler  operation  and  design,  discussing  Small  C’s  compatibility  with  C, 
explaining  how  to  modify  the  compiler  to  generate  new  versions  of  itself,  and  more.  A 
fully-working  Small  C  compiler,  plus  all  the  source  code  and  files  are  provided  on  disk 
in  MS/PC-DOS  format.  628  pp. 

Book/Disk  (MS-DOS)  Item  #124-5  $34.95 
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Turbo  C++  Techniques  and  Applications 
by  Scott  Robert  Ladd 

Turbo  C++  Techniques  and  Applications  is  a  complete  guide  and  tutorial  to  mastering 
Turbo  C++™ ,  an  object-oriented  extension  of  the  popular  C  language.  Written  for 
proficient  C  programmers,  this  book  takes  readers  from  the  fundamentals  of  Turbo  C++ 
to  the  inner  workings  of  the  language,  thoroughly  explaining  its  many  features. 
Programmers  will  discover  the  how,  what,  and  why  of  Turbo  C++  programming  and 
gain  hands-on  experience  through  a  series  of  entertaining  programming  examples. 
Comprehensive  discussions  and  numerous  tips,  tricks,  and  techniques  detail  Turbo 
C++’s  commands  and  functions,  teaching  programmers  how  to  write  efficient  code  that 
fully  utilizes  the  speed  and  energy  of  Turbo  C++.  All  source  code  is  available  on  disk  in 
MS/PC-DOS  format.  423  pp. 

Book/Disk  Item  #146-6  $39.95 

Book  only  Item  #147-4  $29.95 
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The  Tao  of  Objects: 

A  Beginner’s  Guide  to  Object-Oriented  Programming 
by  Gary  Entsminger 

The  Tao  of  Objects  is  a  clearly  written,  user-friendly  guide  to  object-oriented  program¬ 
ming  (OOP).  Easy-to-understand  discussions  detail  OOP  techniques  teaching 
programmers  who  are  new  to  OOP  where  and  how  to  use  them.  Useful  programming 
examples  in  C++  and  Turbo  Pascal  illustrate  the  concepts  discussed  in  real-life 
applications.  249  pp. 

Book  only  Item  #155-5  $26.95 


An  OPEN  LOOK  at  UNIX:  A  Developer’s  Guide  to  X 
by  John  David  Miller 

This  is  the  book  that  explores  the  look  and  feel  of  the  OPEN  LOOK  graphical  interface, 
discussing  its  basic  philosophy,  environment,  and  user-interface  elements.  It  includes  a 
detailed  summary  of  the  X  Window  System,  introduces  readers  to  object-oriented 
programming,  and  shows  how  to  develop  commercial-grade  X  applications.  Dozens  of 
OPEN  LOOK  program  examples  are  presented,  along  with  nearly  13,000  lines  of  C 
code.  All  source  code  is  available  on  disk  in  1 .2  MB  UNIX  cpio  format.  482  pp. 
Book/Disk  (UNIX  cpio)  Item  #058-3  $39.95 

Book  only  Item  #057-5  $29.95 
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Object-Oriented  Programming  for  Presentation  Manager 
by  William  G.  Wong 

Written  for  programmers  and  developers  interested  in  OS/2  Presentation  Manager  (PM), 
as  well  as  DOS  programmers  who  are  just  beginning  to  explore  Object-Oriented 
Programming  and  PM.  Topics  include  a  thorough  overview  of  Presentation  Manager  and 
Object-Oriented  Programming,  Object-Oriented  Programming  languages  and 
techniques,  developing  Presentation  Manager  applications  using  C  and  OOP  techniques, 
and  more.  423  pp. 

Book/Disk  (MS-DOS)  Item  #079-6  $39.95 

Book  only  Item  #074-5  $29.95 


SQL  and  Relational  Basics 
by  Fabian  Pascal 

SQL  arid  Relational  Basics  was  written  to  help  PC  users  apply  sound  and  general 
objectives  to  evaluating,  selecting,  and  using  database  management  systems. 
Misconceptions  about  relational  data  management  and  SQL  are  addressed  and  corrected. 
The  book  concentrates  on  the  practical  objectives  of  the  relational  approach  as  they 
pertain  to  the  micro  environment.  Users  will  be  able  to  design  and  correctly  implement 
relational  databases  and  applications,  and  work  around  product  deficiencies  to  minimize 
future  maintenance.  336  pp. 

Book  only  Item  #063-X  $28.95 
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Programming  in  3  Dimensions:  3-D  Graphics,  Ray  Tracing,  and  Animation 
by  Sandra  Bloomberg 

Programming  in  3  Dimensions  is  a  comprehensive,  hands-on  guide  to  computer 
graphics.  It  contains  a  detailed  look  at  3-D  graphics  plus  discussions  of  popular  ray 
tracing  methods  and  computer  animation.  Readers  will  find  techniques  for  creating  3-D 
graphics  and  breath-taking  ray-traced  images  as  well  as  explanations  of  how  animation 
works  and  ways  computers  help  produce  it  more  effectively.  Packed  with  examples  and 
C  source  code,  this  book  is  a  must  for  all  computer  graphics  enthusiasts !  All  source  code 
is  available  on  disk  in  MS/PC-DOS  format.  Includes  16  pages  of  full-color  graphics. 

500  pp.  approx. 

Book  /Disk  (MS-DOS)  Item  #218-7  $39.95 

Book  only  Item  #220-9  $29.95 


Fractal  Programming  and  Ray  Tracing  with  C++ 
by  Roger  T.  Stevens 

Finally,  a  book  for  C  and  C++  programmers  who  want  to  create  complex  and  intriguing 
graphic  designs.  By  the  author  of  three  best-selling  graphics  books,  this  new  title 
thoroughly  explains  ray  tracing,  discussing  how  rays  are  traced,  how  objects  are  used  to 
create  ray-traced  images,  and  how  to  create  ray  tracing  programs.  A  complete  ray  tracing 
program,  along  with  all  of  the  source  code,  is  included  on  disk  in  MS/PC-POS  format. 
Contains  16  pages  of  full-color  graphics.  44pp. 

Book  /Disk  (MS-DOS)  Item  #1 18-0  $39.95 

Book  only  Item  #134-2  $29.95 


Advanced  Fractal  Programming  in  C 
by  Roger  T.  Stevens 

Programmers  who  enjoyed  our  best-selling  Fractal  Programming  in  C  can  move  on  to 
the  next  level  of  fractal  programming  with  this  book.  Included  are  how-to  instructions 
for  creating  many  different  types  of  fractal  curves.  Contains  16  pages  of  full-color 
fractals.  All  the  source  code  to  generate  the  fractals  is  available  on  an  optional  disk  in 
MS/PC-DOS  format.  305  pp. 

Book/Disk  (MS-DOS)  Item  #097-4  $39.95 

Book  only  Item  #096-6  $29.95 


Advanced  Graphics  Programming  in  Turbo  Pascal 
by  Roger  T.  Stevens  and  Christopher  D.  Watkins 

This  new  book  is  must  reading  for  Turbo  Pascal  programmers  who  want  to  create 
impressive  graphic  designs  on  IBM  PCs  and  compatibles.  There  are  32  pages  of  full- 
color  graphic  displays  along  with  the  source  code  to  create  these  dramatic  pictures. 
Complete  explanations  are  provided  on  how  to  tailor  the  graphics  to  suit  the 
programmer’s  need.  Covered  are  algorithms  for  creating  complex  2-D  shapes,  including 
lines,  circles  and  squares;  advanced  3-D  shapes,  wire-frame  graphics,  and  solid  images; 
numerous  tips  and  techniques  for  varying  pixel  intensities  to  give  the  appearance  of 
roundness  to  an  object;  and  more.  540  pp. 

Book  /Disk  (MS-DOS)  Item  #132-6  $39.95 

Book  only  Item  #131-8  $29.95 
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Advanced  Graphics  Programming  in  C  and  C++ 
by  Roger  T.  Stevens  and  Christopher  D.  Watkins 

This  book  is  for  all  C  and  C++  programmers  who  want  to  create  impressive  graphic 
designs  on  their  IBM  PCs  or  compatibles.  Through  in-depth  discussions  and  numerous 
sample  programs,  readers  will  learn  how  to  create  advanced  3-D  shapes,  wire-frame 
graphics,  solid  images,  and  more.  All  source  code  is  available  on  disk  in  MS/PC-DOS 
format.  Contains  16  pages  of  full-color  graphics.  500  pp.  approx. 

Book  /Disk  (MS-DOS)  Item  #173-3  $39.95 

Book  only  Item  #171-7  $29.95 


Graphics  Programming  with  Microsoft  C  6 
by  Mark  Mallett 

Written  for  all  C  programmers,  this  book  explores  graphics  programming  with  Microsoft 
C’s  built-in  graphics  libraries.  Sample  programs  will  help  readers  learn  the  techniques 
needed  to  create  spectacular  graphic  designs,  including  3-D  figures,  solid  images,  and 
more.  All  source  code  in  the  book  is  available  on  disk  in  MS/PC-DOS  format.  Includes 
16  pages  of  full-color  graphics.  500  pp.  approx. 

Book/Disk  (MS-DOS)  Item  #167-9  $39.95 

Book  only  Item  #165-2  $29.95 


Fractal  Programming  in  C 
by  Roger  T.  Stevens 

If  you  are  a  programmer  wanting  to  learn  more  about  fractals,  this  book  is  for  you.  Learn 
how  to  create  pictures  that  have  both  beauty  and  an  underlying  mathematical  meaning. 
Included  are  over  50  black  and  white  pictures  and  32  full-color  fractals.  All  source  code 
to  reproduce  these  pictures  is  provided  on  disk  in  MS-DOS  format  requiring  an  IBM  PC 
or  clone  with  an  EGA  or  VGA  card,  a  color  monitor,  and  a  Turbo  C,  Quick  C,  or 
Microsoft  C  compiler.  580  pp. 

Book  /Disk  (MS-DOS)  Item  #038-9  $39.95 

Book  only  Item  #037-0  $29.95 


Fractal  Programming  in  Turbo  Pascal 
by  Roger  T.  Stevens 

This  book  equips  Turbo  Pascal  programmers  with  the  tools  needed  to  program  dynamic 
fractal  curves.  It  is  a  reference  that  gives  full  attention  to  developing  the  reader’s 
understanding  of  various  fractal  curves.  More  than  50  black  and  white  and  32  full-color 
fractals  are  illustrated  throughout  the  book.  All  source  code  to  reproduce  the  fractals  is 
available  on  disk  in  MS/PC-DOS  format  requiring  a  PC  or  clone  with  EGA  or  VGA, 
color  monitor,  and  Turbo  Pascal  4.0  or  later.  462  pp. 

Book  /Disk  (MS-DOS)  Item  #107-5  $39.95 

Book  only  Item  #106-7  $29.95 
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Graphics  Programming  in  C 
by  Roger  T.  Stevens 

All  the  information  you  need  to  program  graphics  in  C,  including  source  code,  is 
presented.  You’ll  find  complete  discussions  of  ROM  BIOS,  VGA,  EGA,  and  CGA 
inherent  capabilities;  improved,  faster  methods  of  displaying  points  on  a  screen; 
improved,  faster  algorithms  for  drawing  and  filling  lines,  rectangles,  rounded  polygons, 
ovals,  circles,  and  arcs;  graphic  cursors;  and  much  more!  Both  Turbo  C  and  Microsoft  C 
are  supported.  639  pp. 

Book/Disk  (MS-DOS)  Item  #019-2  $36.95 

Book  only  Item  #018-4  $26.95 


Running  WordPerfect  on  NetWare 
by  Greg  McMurdie  and  Joni  Taylor 

Written  by  NetWare  and  WordPerfect  experts,  this  book  contains  practical  information 
for  both  system  administrators  and  network  WordPerfect  users.  Administrators  will  learn 
how  to  install,  maintain,  and  troubleshoot  WordPerfect  on  the  network.  Users  will  find 
answers  to  everyday  questions  such  as  how  to  print  over  the  network,  how  to  handle  error 
messages,  and  how  to  use  WordPerfect’s  tutorial  on  NetWare.  246  pp. 

Book  only  Item  #145-8  $29.95 


Delivering  cc:Mail 

Installing,  Maintaining,  and  Troubleshooting  a  cc:Mail  System 
by  Eric  Arnum 

Delivering  cc:Mail  teaches  administrators  how  to  install,  troubleshoot,  and  maintain 
cc:Mail,  one  of  the  mot  popular  E-mail  applications  for  the  PC.  In-depth  discussions  and 
practical  examples  show  administrators  how  to  establish  and  maintain  the  program  and 
database  files;  how  to  create  and  modify  the  bulletin  boards,  mail  directory,  and  public 
mailing  lists;  and  how  to  diagnose  and  repair  potential  problems.  Information  on  using 
the  management  tools  included  with  the  package,  plus  tips  and  techniques  for  creating 
efficient  batch  files  are  also  included.  All  source  code  is  available  on  disk  in  MS/PC-DOS 
format.  450  pp. 

Book  /Disk  (MS-DOS)  Item  #187-3  $39.95 

Book  only  Item  #185-7  $29.95 

Publishing  1-2-3 
by  Mary  Campbell 

Publishing  1-2-3  teaches  users  how  to  apply  their  1-2-3  skill  to  create  winning  spread¬ 
sheets  and  presentations.  Written  for  users  at  all  levels,  it  outlines  basic  design  objectives 
and  describes  important  elements  to  consider  when  planning  a  1-2-3  spreadsheet.  In 
addition,  this  book  shows  readers  how  to  enhance  the  features  of  1-2-3  by  using  it  with 
different  graphics  and  word  processing  packages.  Readers  will  learn  how  to  use  graphics 
packages  such  as  Harvard  Graphics  and  Freelance  to  create  charts  and  graphs  beyond  the 
capabilities  of  1-2-3  and  how  to  import  1-2-3  spreadsheets,  charts,  and  graphs  into 
WordPerfect®  Covers  Lotus  1-2-3  versions  2.01  through  3.1.  369  pp. 

Book  only  Item  #199-7  $24.95 
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Using  QuarkXPress  3.0 
by  Tim  Meehan 

Written  in  an  enjoyable,  easy-to-read  style,  this  book  addresses  the  needs  of  both 
beginning  and  intermediate  users.  It  includes  numerous  illustrations  and  screen  shots  that 
guide  readers  through  comprehensive  explanations  of  QuarkXPress,  its  potential  and 
real-world  applications.  Using  QuarkXPress  contains  comprehensive  explanations  for 
the  concepts,  practices,  and  uses  of  QuarkXPress,  with  sample  assignments  of  increasing 
complexity  that  give  readers  actual  hands-on  experience  using  the  program.  Disk  in 
Macintosh  format  includes  exercises  and  templates.  340  pp. 

Book/Disk  (Macintosh)  Item  #129-6  $34.95 

Book  only  Item  #128-8  $24.95 

PageMaker  4  By  Example 
PC  Version 

by  Tony  Webster  and  Paul  Webster 

This  hands-on  tutorial  introduces  PC  users  to  the  new  and  enhanced  features  of 
PageMaker  4,  providing  them  with  a  detailed  look  at  this  powerful  and  versatile  desktop 
publishing  program.  It  progressively  covers  more  and  more  complex  PageMaker 
operations,  taking  readers  from  basic  functions  to  creating  customized  templates. 
Step-by-step  exercises  that  teach  readers  how  to  apply  the  concepts  learned  to  practical 
desktop  publishing  projects  accompany  each  chapter.  The  supplementary  disk  includes 
tips  and  techniques  for  creating  professional-looking  newsletters,  advertisements,  press 
releases,  and  more.  617  pp. 

Book /Disk  (MS-DOS)  Item  #151-2  $34.95 

Book  only  Item  #149-0  $24.95 

PageMaker  4  By  Example 

Macintosh  Version 

by  Tony  Webster  and  David  Webster 

A  self-paced,  hands-on  guide  to  learning  PageMaker  4.0,  the  premier  desktop  publishing 
program  in  the  micro-computer  market.  Includes  step-by-step  instructions  for  everything 
from  starting  a  new  document  to  creating  customized  style  sheets.  Hundreds  of  screen 
shots  lead  readers  though  the  concepts  discussed,  and  useful  exercises  reinforce  each 
chapter’s  material.  Readers  will  learn  how  to  load  files  into  PageMaker,  edit  and 
manipulate  text,  create  templates,  and  much  more.  The  exercise  disk  (Macintosh) 
supplements  the  book’s  exercises  and  teaches  readers  how  to  apply  its  concepts  to 
practical  desktop  publishing  projects.  It  includes  tips  on  creating  projects  such  as 
newsletters,  advertisements,  and  press  releases.  593  pp. 

Book/Disk  (Macintosh)  Item  #121-0  $34.95 

Book  only  Item  #105-9  $24.95 
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The  Verbum  Book  of  Digital  Typography 

by  Michael  Gosney,  Linnea  Dayton,  and  Jennifer  Ball 

The  Verbum  Book  of  Digital  Typography  combines  information  on  good  design 
principles  with  effective  typography  techniques,  showing  designers,  illustrators,  and 
desktop  publishers  how  to  create  attractive  printed  materials  that  communicate 
effectively.  Each  chapter  highlights  the  talents  of  a  professional  type  designer  as  he  or 
she  steps  readers  through  an  interesting  real-life  project.  Readers  will  learn  how  to 
develop  letterforms  and  typefaces,  modify  type  outlines,  and  create  special  effects. 
200  pp.  approx. 

Book  only  Item  #092-3  $29.95 


The  Verbum  Book  of  Postscript  Illustration 
by  Michael  Gosney,  Linnea  Dayton,  and  Janet  Ashford 

This  is  the  premier  instruction  book  for  designers,  illustrators,  and  desktop  publishers 
using  Postscript.  Each  chapter  highlights  the  talents  of  top  illustrators  who  demonstrate 
the  electronic  artmaking  process.  The  narrative  keys  readers  in  to  the  artist’s  conceptual 
vision,  providing  valuable  insight  into  the  creative  thought  processes  that  go  into  real- 
world  PostScript  illustration  projects.  213  pp. 

Book  only  Item  #089-3  $29.95 


The  Verbum  Book  of  Electronic  Page  Design 
by  Michael  Gosney  and  Linnea  Dayton 

This  particular  volume  introduces  designers,  illustrators,  and  desktop  publishers  to  the 
electronic  page  layout  medium  and  various  application  programs,  such  as  PageMaker, 
QuarkXPress,  Design  Studio,  and  Ventura  Publishing.  Each  chapter  highlights  the  talents 
of  a  top  designer  who  guides  readers  through  the  thinking  as  well  as  the  “mousing”  that 
leads  to  creating  various  projects.  These  projects  range  in  complexity  from  a  trifold  black 
and  white  brochure  to  a  catalog  produced  with  QuarkXPress.  More  than  100  illustrations, 
with  32  pages  in  full-color,  are  included.  211  pp. 

Book  only  Item  #088-5  $29.95 

The  Verbum  Book  of  Digital  Painting 

by  Michael  Gosney,  Linnea  Dayton,  and  Paul  Goethel 

Contained  herein  are  a  series  of  entertaining  projects  that  teach  readers  how  to  create 
compelling  designs  using  the  myriad  graphics  tools  available  in  commercial  painting 
programs.  Presented  by  professional  designers,  these  projects  range  from  a  simple 
greeting  card  to  a  complex  street  scene.  This  book  also  includes  portfolios  of  paintings 
created  by  the  featured  artists,  plus  an  extensive  gallery  of  works  from  other 
accomplished  artists  and  64  pages  of  full-color  paintings.  21 1  pp. 

Book  only  Item  #090-7  $29.95 
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Troubleshooting 
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NetWare  User’s  Guide 
by  Edward  Liebing 

Endorsed  by  Novell,  this  book  informs  NetWare  users  of  available  services  and  utilities, 
and  describes  how  to  put  them  to  use  effectively.  This  book  contains  a  complete  task- 
oriented  reference  that  introduces  users  to  NetWare  and  guides  them  through  the  basics 
of  NetWare  menu-driven  and  command-line  utilities.  Each  utility  is  illustrated,  thus 
providing  a  visual  frame  of  reference.  You  will  find  general  information  about  the 
utilities  and  for  performing  particular  tasks.  The  book  covers  NetWare  v2.1  through 
v2.15.  For  advanced  users,  a  workstation  troubleshooting  section  describes  common 
problems.  Two  appendices  cover  the  services  available  in  each  NetWare  menu  or 
command-line  utility.  520  pp.  approx. 

Book  only  Item  #071-0  $24.95 


NetWare  Supervisor’s  Guide 

by  John  T.  McCann,  Adam  T.  Ruef,  and  Steven  L.  Guengerich 

Written  for  network  administrators,  consultants,  installers,  and  power  users  of  all 
versions  of  NetWare,  including  NetWare  386.  While  other  books  provide  information  on 
using  NetWare  at  a  workstation  level,  this  definitive  reference  focuses  on  how  to 
administer  NetWare.  Contains  numerous  examples  which  address  understanding  and 
using  NetWare’s  undocumented  commands  and  utilities,  implementing  system  fault 
tolerant  LANs,  refining  installation  parameters  to  improve  network  performance,  and 
more.  510  pp. 

Book  only  Item  #111-3  $29.95 


NetWare  Programmer’s  Guide 
by  JohnT.  McCann 

Covered  are  all  aspects  of  programming  in  the  NetWare  environment — from  basic 
planning  to  complex  application  debugging.  This  book  offers  practical  tips  and  tricks  for 
creating  and  porting  applications  to  NetWare.  NetWare  programmers  developing  simple 
applications  for  a  single  LAN  or  intricate  programs  for  multi-site  internetworked  systems 
will  find  this  book  a  valuable  reference  to  have  on  hand.  All  source  code  is  available  on 
disk  in  MS-PC/DOS  format.  425  pp. 

Book/Disk  Item  #154-7  $44.95 

Book  only  Item  #152-0  $34.95 

Troubleshooting  NetWare  for  the  286 
by  Cheryl  Snapp 

The  ideal  reference  for  network  supervisors  responsible  for  the  installation  and 
maintenance  of  a  NetWare  286  network.  Contains  a  thorough  overview  of  the  NetWare 
286  operating  system  plus  step-by-step  instructions  for  troubleshooting  common  and  not- 
so-common  problems.  Detailed  chapters  emphasize  the  information  most  helpful  in 
maintaining  a  healthy  NetWare  286  LAN,  including  installation,  file  server  and 
workstation  diagnostics,  printing  utilities,  and  network  management  services.  Covers 
NetWare  286  v2.2.  350  pp. 

Book  only  Item  #169-5  $34.95 
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Building  Local  Area  Networks  with  Novell’s  NetWare 
by  Patrick  H.  Corrigan  and  Aisling  Guy 

From  the  basic  components  to  complete  network  installation,  here  is  the  practical  guide 
that  PC  system  integrators  will  need  to  build  and  implement  PC  LANs  in  this  rapidly 
growing  market.  The  specifics  of  building  and  maintaining  PC  LANs,  including 
hardware  configurations,  software  development,  cabling,  selection  criteria,  installation, 
and  on-going  management  are  described  in  a  clear  “how-to”  manner  with  numerous 
illustrations  and  sample  LAN  management  forms.  635  pp.  approx. 

Book/Disk  (MS-DOS)  Item  #025-7  $39.95 

Book  only  Item  #010-9  $29.95 


Internetworking:  A  Guide  to  Network  Communications 
LAN  to  LAN;  LAN  to  WAN 
by  Mark  E.  Miller,  P.E. 

This  book  addresses  all  aspects  of  LAN  and  WAN  (wide-area  network)  integrations, 
detailing  the  hardware,  software,  and  communication  products  available.  In-depth 
discussions  describe  the  functions,  design,  and  performance  of  repeaters,  bridges, 
routers,  and  gateways,  Communication  facilities  such  as  leased  lines,  T-l  circuits  and 
access  to  packed  switched  public  data  networks  (PSPDNs)  are  compared,  helping  LAN 
managers  decide  which  is  most  viable  for  their  internetwork.  Also  examined  are  the 
X.25,  TCP/IP,  and  XNS  protocols,  as  well  as  the  internetworking  capabilities  and 
interoperability  constraints  of  the  most  popular  networks,  including  NetWare,  LAN 
Server,  3+Open™,  VINES®,  and  AppleTalk.  425  pp. 

Book  only  Item  #143-1  $34.95 


LAN  Troubleshooting  Handbook 
by  Mark  A.  Miller,  P.E. 

This  book  is  specifically  for  users  and  administrators  who  need  to  identify  problems  and 
maintain  a  LAN  that  is  already  installed.  Topics  include  LAN  standards,  the  OSI  model, 
network  documentation,  LAN  text  equipment,  cable  system  testing,  and  more.  Addressed 
are  specific  issues  associated  with  troubleshooting  the  four  most  popular  LAN 
architectures:  ARCNET,  Token  Ring,  Ethernet,  and  StarLAN.  Each  is  closely  examined 
to  pinpoint  the  problems  unique  to  its  design  and  the  hardware.  Handy  checklists  to  assist 
in  solving  each  architecture’s  unique  network  difficulties  are  also  included.  309  pp. 
Book/Disk  (MS-DOS)  Item  #056-7  $39.95 

Book  only  Item  #054-0  $29.95 
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LAN  Protocol  Handbook 
by  Mark  A.  Miller,  P.E. 

Requisite  reading  for  all  network  administrators  and  software  developers  needing  in- 
depth  knowledge  of  the  internal  protocols  of  the  most  popular  network  software.  It 
illustrates  the  techniques  of  protocol  analysis  —  the  step-by-step  process  of  unraveling 
LAN  software  failures.  Detailed  is  how  Ethernet,  IEEE  802.3,  IEEE  802.5,  and 
ARCNET  networks  transmit  frames  of  information  between  workstations.  Individual 
chapters  thoroughly  discuss  Novell’s  NetWare,  3Com’s  3+  and  3+Open,  IBM  Token- 
Ring  related  protocols,  and  more!  324  pp. 

Book  only  Item  #099-0  $34.95 


LAN  Protocol  Handbook  Demonstration  Disks 


The  set  of  seven  demonstration  disks  is  for  those  who  wish  to  pursue  the  techniques  of 
protocol  analysis  or  consider  the  purchase  of  an  analysis  tool. 

The  analyzers  will  give  you  a  clear  view  of  your  network  so  that  you  can  better 
control  and  manage  your  LAN,  as  well  as  pinpoint  trouble  spots.  The  LAN  Protocol 
Handbook  demo  disks  are  packed  with  detailed  demonstration  programs  for 
LANanlyzer®,  LAN  Watch®,  The  Sniffer®,  for  Token-Ring  and  Ethernet, 
SpiderAnalyzer®  320-R  for  Token-Ring,  and  LANVista®.  By  surveying  the  demo 
programs,  you  will  receive  enough  information  to  choose  an  analyzer  that  best  suits  your 
specific  needs. 

Requirements:  IBM  PC/XT/AT  compatible  with  at  least  640K  after  booting.  Requires 
DOS  version  2.0  or  later.  Either  a  color  or  monochrome  display  may  be  used. 

Seven  Disks  Item  #114-8  $39.95 
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NetWare  386  User’s  Guide 
by  Christine  Milligan 

NetWare  386  User’s  Guide  is  a  complete  guide  to  using  and  understanding  Novell’s 
NetWare  386.  It  is  an  excellent  reference  for  386.  Detailed  tutorials  cover  tasks  such  as 
logging  in,  working  with  directories  and  files,  and  printing  over  a  network.  Complete 
explanations  of  the  basic  concepts  underlying  NetWare  386,  along  with  a  summary  of 
the  differences  between  NetWare  286  and  386,  are  included.  Advanced  users  will  benefit 
from  the  information  on  managing  workstation  environments  and  the  troubleshooting 
index  that  fully  examines  NetWare  386  error  messages.  450  pp. 

Book  only  Item  #101-6  $29.95 


NetWare  for  Macintosh  User’s  Guide 
by  Kelley  J.  P.  Lindberg 

NetWare  for  Macintosh  User’s  Guide  is  the  definitive  reference  to  using  Novell’s 
NetWare  on  Macintosh  computers.  Whether  you  are  a  novice  or  an  advanced  user,  this 
comprehensive  text  provides  the  information  readers  need  to  get  the  most  from  their 
NetWare  networks.  It  includes  an  overview  of  network  operations  and  detailed 
explanations  of  all  NetWare  for  Macintosh  menu  and  command  line  utilities.  Detailed 
tutorials  cover  such  tasks  as  logging  in,  working  with  directories  and  files  and  printing 
over  a  network.  Advanced  users  will  benefit  from  the  information  on  managing 
workstation  environments  and  troubleshooting.  280  pp. 

Book  only  Item  #126-1  $29.95 
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The  NetWare  Manual  Makers 

Complete  Kits  for  Creating  Customized  NetWare  Manuals 

Developed  to  meet  the  tremendous  demand  for  customized  manuals,  The  NetWare 
Manual  Makers  enable  the  NetWare  supervisor  and  administrator  to  create  network 
training  manuals  specific  to  their  individual  sites.  Administrators  simply  fill  in  the  blanks 
on  the  template  provided  on  disk  and  print  the  file  to  create  customized  manuals  and 
command  cards.  Included  is  general  “how-to”  information  on  using  a  network,  as  well  as 
fill-in-the-blank  sections  that  help  administrators  explain  and  document  procedures 
unique  to  a  particular  site.  This  disk  files  are  provided  in  WordPerfect  and  ASCII  format. 
The  WordPerfect  file  creates  a  manual  that  looks  exactly  like  the  one  in  the  book.  The 
ASCII  file  can  be  imported  into  any  desktop  publishing  or  word  processing  software. 

The  NetWare  286  Manual  Maker 

The  Complete  Kit  for  Creating  Customized  NetWare  286  Manuals 
by  Christine  Milligan 

Book  only  Item  #119-9  $49.95  314  pp. 

The  NetWare  386  Manual  Maker 

The  Complete  Kit  for  Creating  Customized  NetWare  386  Manuals 
by  Christine  Milligan 

Book  only  Item  #120-2  $49.95  314  pp. 

The  NetWare  for  Macintosh  Manual  Maker 

The  Complete  Kit  for  Creating  Customized  NetWare  for  Macintosh  Manuals 
by  Kelley  J.  P.  Llndberg 

Book  only  Item  #130-X  $49.95  314  pp. 


LAN  Primer 

An  Introduction  to  Local  Area  Networks 
by  Greg  Nunemacher 

A  complete  introduction  to  local  area  networks  (LANs),  this  book  is  a  must  for  anyone 
who  needs  to  know  basic  LAN  principles.  It  includes  a  complete  overview  of  LANs, 
clearly  defining  what  a  LAN  is,  the  functions  of  a  LAN,  and  how  LANs  fit  into  the  field 
of  telecommunications.  The  author  discusses  the  specifics  of  building  a  LAN,  including 
the  required  hardware  and  software,  an  overview  of  the  types  of  products  available, 
deciding  what  products  to  purchase,  and  assembling  the  pieces  into  a  working  LAN 
system.  LAN  Primer  also  includes  case  studies  that  illustrate  how  LAN  principles  work. 
Particular  focus  is  given  to  Ethernet  and  Token  Ring.  221  pp. 

Book  only  Item  #127-X  $24.95 
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Blueprint  of  a  LAN 
by  Craig  Chaiken 

For  programmers,  valuable  programming  techniques  are  detailed.  Network  adminis¬ 
trators  will  learn  how  to  build  and  install  LAN  communication  cables,  configure  and 
troubleshoot  network  hardware  and  more.  Addressed  are  a  very  inexpensive  zero-slot, 
star  topology  network,  remote  printer  and  file  sharing,  remote  command  execution, 
electronic  mail,  parallel  processing  support,  high-level  language  support,  and  more.  Also 
covered  is  the  complete  Intel  8086  assembly  language  source  code  that  will  help  you 
build  an  inexpensive-to-install  local  are  network.  An  optional  disk  containing  all  source 
code  is  available  in  MS/PC-DOS  format.  337  pp. 

Book/Disk  (MS-DOS)  Item  #066-4  $39.95 

Book  only  Item  #052-4  $29.95 


Troubleshooting  LAN  Manager  2 
by  Michael  Day 

The  ideal  reference  for  network  supervisors  responsible  for  the  maintenance  of  a  LAN 
Manager  2  network.  Troubleshooting  LAN  Manager  2  builds  a  functional  model  of  LAN 
Manager  from  the  ground  up,  beginning  with  OS/2  and  ending  with  fault  tolerance  and 
printer  setup.  Key  components  such  as  data  structures,  protocols,  services,  and 
applications  are  placed  in  a  troubleshooting  context,  examining  possible  problems  and 
providing  hands-on  solutions.  More  than  basic  hints  and  tips,  this  book  lays  a  solid 
foundation  upon  which  you  can  build  a  truly  outstanding  troubleshooting  methodology. 
337  pp. 

Book  only  Item#161-X  $34.95 
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Dr.  Dobb’s  Journal  Bound  Volume  15  - 1990 

The  new  decade  begins  and  DDJ  enters  its  15th  year  of  power  programming.  Every  1990  issue  of  Dr.  Dobb’s  Journal 
has  been  collected  and  bound  into  this  single  volume.  Included  are  the  popular  Annual  C  and  Annual  Operating 
Systems  issues.  Featured  are  well-known  contributors  such  as  Michael  Swaine,  AI  Stevens,  and  Jeff  Dunteniann. 
There’s  also  the  Dr.  Dobb’s  Journal  1989  index,  and  all  the  source  code  for  1990  (supplied  on  disk,  PC/MS-DOS  format). 
Some  of  the  1990  topics  include: 


Real-Time  Data  Acquisition.  Valuable  information  on  all  the  tools  you  need  (both  hardware 
and  software),  for  your  own  data  acquisition  system. 

Three-dimensional  Graphics  Using  The  X  Window  System.  3-1)  graphics  are  possible 

with  X  Window  systems!  Here’s  what  can  be  expected  from  porting  3-D  graphics  to  X,  plus 
solutions  to  some  thorny  problems. 

68040  Programming.  This  member  of  the  680x0  family  provides  challenges  for  programmers  at  all  levels. 

Neural  Nets,  ddj  presents  an  environment  that  dynamically  creates  neural  networks.  Also 
included  are  discussions  of  the  similarities  and  differences  of  various  neural  net  models. 

Memory  Management.  Everything  from  how  to  take  advantage  of  “handle  pointers”  to  object  swapping. 
Hypertext.  A  behind-the-scenes  look  at  the  DDJ  hypertext  project. 

Graphics.  From  Super  VGA  programming  to  drawing  character  shapes  with  Bezier  curves. 


C  Programming.  Porting  C  programs  to  80386  protected  mode,  encapsulating  C  memory 
allocation,  parallel  extensions  to  C,  and  much  more! 

Unraveling  Optimization.  Examined  are  the  practical  and  theoretical  aspects  of  code 
optimization  using  Microsoft  C  6.0. 


Communications  &  Connectivity.  Controlling  Unix  processes,  designing  for  OS1,  and 
programming  with  Mac  Comm  toolbox. 


